> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/componentes-modulos/subida-de-ficheros-y-gestion-de-qr.md).

# File upload and QR management - Capture

## Introduction <a href="#id-1-introduccion" id="id-1-introduccion"></a>

Document capture and QR reading and generation are performed with the ***CaptureComponent***.

This component allows documents to be uploaded by taking a photo with the device camera or selecting one from the gallery.

***

## Dependency <a href="#id-2-dependencia" id="id-2-dependencia"></a>

The component’s specific dependency is:

```
implementation "com.facephi.androidsdk:capture_component:$version"
```

***

## Available controllers <a href="#id-3-controladores-disponibles" id="id-3-controladores-disponibles"></a>

| **Controller**         | **Description**                 |
| ---------------------- | ------------------------------- |
| FileUploaderController | Controller for document capture |
| QrReaderController     | Controller for QR capture       |
| QrGeneratorController  | Controller for QR generation    |

***

## Simplified Launch <a href="#id-4-lanzamiento-simplificado" id="id-4-lanzamiento-simplificado"></a>

Once the SDK has been initialized and a new operation has been created, the component can be launched. Any of its controllers can be used to execute its functionality.

Launching document capture:

```kotlin
val response = SDKController.launch(
    FileUploaderController(FileUploaderConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}
```

Launching QR capture:

```kotlin
val response = SDKController.launch(
    QrReaderController(QrCaptureConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}
```

Launching QR generation:

```kotlin
val response = SDKController.launch(
    QrGeneratorController(QrGeneratorConfiguration(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}
```

***

## Basic configuration <a href="#id-5-configuracion-basica" id="id-5-configuracion-basica"></a>

For the component capture and QR capture controllers, the configuration can be generated using the default parameters. For QR generation, the text to be used must be provided:

```
QrGeneratorConfiguration(source = "QR text")
```

***

## Receiving the result <a href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

Launching the component returns the information in SdkResult format. The result can be either a successful or an unsuccessful launch:

```kotlin
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error}")
    is SdkResult.Success -> response.data
}
```

### Receiving errors <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

Errors are returned as a 'CaptureError' object.

List of errors:

* `ACTIVITY_RESULT_MSG_ERROR` (`CAP_855`): The result returned by the activity is incorrect or does not contain the information needed to continue.
* `APPLICATION_CONTEXT_ERROR` (`CAP_856`): The required application context is null or invalid, preventing the capture module from being initialized correctly.
* `CAMERA_ERROR` (`CAP_853`): An internal error related to the device camera has occurred (opening, initialization, or capture failure).
* `CAMERA_PERMISSION_DENIED` (`CAP_852`): The user denied the permissions required to access the camera.
* `CANCEL_BY_USER` (`CAP_000`): The user manually canceled the capture process.
* `CANCEL_LAUNCH` (`CAP_007`): The process was canceled generally by the SDK or by an external action.
* `COMPONENT_LICENSE_ERROR` (`CAP_002`): The component license is invalid, has expired, or does not match the required configuration.
* `EMPTY_LICENSE` (`CAP_003`): The license string is empty or was not provided.
* `FETCH_DATA_ERROR` (`CAP_858`): An error occurred while fetching or processing the data required to execute the flow. *(Includes additional information in the `error`.)*
* `FLOW_ERROR` (`CAP_863`): An internal error occurred during the execution of the capture flow. *(Includes additional information in the `error`.)*
* `INITIALIZATION_ERROR` (`CAP_004`): Error initializing the SDK components required. *(Includes detailed information in the `error`.)*
* `FILE_UPLOADER_CAPTURE_ERROR` (`CAP_850`): Error during the upload of files generated during capture.
* `INTERNAL_ERROR` (`CAP_861`): Unexpected internal error during execution. *(Includes additional information in the `error`.)*
* `IMAGE_TOO_LARGE` (`CAP_862`): The image selected from the gallery exceeds the maximum size configured in `maxGalleryImageSizeKb`.
* `MANAGER_NOT_INITIALIZED` (`CAP_857`): The managers required to execute the process have not been initialized correctly.
* `NO_DATA_ERROR` (`CAP_005`): The required input data is null, missing, or insufficient to continue the process.
* `OPERATION_NOT_CREATED` (`CAP_006`): Could not create or retrieve an active operation required to continue. *(Includes detailed information in the `error`.)*
* `QR_CAPTURE_ERROR` (`CAP_851`): Error during QR Code capture or scanning.
* `QR_GENERATION_ERROR` (`CAP_854`): Error generating the requested QR Code.
* `TIMEOUT` (`CAP_001`): The maximum allowed time was reached during one of the process stages.
* `FLOW_VIDEO_RECORDING_ERROR` (`CAP_859`): Error during Video Recording within the established flow.
* `FLOW_TRACKING_ERROR` (`CAP_860`): Error performing the tracking required to complete the capture flow.

### Receiving the successful result - *data* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

#### **Receiving the document capture result**

In the SdkResult.Success section - *data*, we will have the *FileUploaderResult*.

The fields returned in the result are as follows:

***capturedDocumentList***

List of captured files. These may be images or PDFs. The fields returned for each are:

* mimeType: `String`
* timestampMillis: `Long`
* content: `FileContent`. Document content. This differs depending on whether it is an image or a PDF document. To distinguish between them:

```kotlin
capturedDocumentList.forEach { documentData ->
                            when (val content = documentData.content) {
                                is FileContent.UploaderImage -> {
                                    // Uploader: New image found
                                    // content.image
                                }

                                is FileContent.UploaderDocument -> {
                                    // Uploader: New document found
                                    // content.bytes
                                }
                            }
                        }
```

Fields for each content type:

* `FileContent.UploaderImage`:
  * `image`: `SdkImage`. Captured image.
  * `rotationDegrees`: `Int`. Image rotation in degrees.
  * `source`: `FileUploaderSource`. Image source. Possible values: `CAMERA`, `GALLERY`.
* `FileContent.UploaderDocument`:
  * `frontPageImage`: `SdkImage?`. Image of the first page of the PDF (may be null).
  * `bytes`: `ByteArray`. PDF content.

#### **Receiving the QR capture result**

In the SdkResult.Success section - *data*, we will have the *QrResult*.

The fields returned in the result are as follows:

***qrText***

Text obtained from the QR code

#### **Receiving the QR generation result**

In the SdkResult.Success section - *data*, we will have an `SdkImage` with the generated QR code.

***

## Advanced information <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

This section provides more information about the component.

### Advanced component configuration <a href="#id-71-configuracion-avanzada-del-componente" id="id-71-configuracion-avanzada-del-componente"></a>

#### **Document capture configuration**

To launch this component, you must create a *FileUploaderConfigurationData* object, which will be the component controller's configuration.

All the fields that make up this class are detailed below.

* `vibrationEnabled`: `Boolean`. Indicates whether vibration is enabled when the widget completes successfully. Defaults to `true`.
* `extractionTimeout`: `Long`. Sets the maximum time allowed for capture, in milliseconds. Defaults to `60000`.
* `showDiagnostic`: `Boolean`. Show diagnostic screens at the end of the process. Defaults to `true`.
* `showPreviousTip`: `Boolean`. Shows a screen before capture starts, with information about the process to be carried out and a button to start it. Defaults to `true`.
* `maxScannedDocs`: `Int`. Maximum number of documents that can be captured. Defaults to `2`.
* `allowGallery`: `Boolean`. Enables access to the gallery to retrieve images or PDFs. Defaults to `true`.
* `onlyGalleryMode`: `Boolean`. If enabled, the flow opens directly in gallery mode and does not show camera capture. Defaults to `true`.
* `maxGalleryImageSizeKb`: `Int`. Maximum allowed size for images selected from the gallery, in KB. Defaults to `2048`; if this limit is exceeded, `CAP_IMAGE_TOO_LARGE`.

#### **QR capture configuration**

To launch this component, you must create a *QrCaptureConfigurationData* object, which will be the component controller's configuration.

All the fields that make up this class are detailed below.

* `vibrationEnabled`: `Boolean`. Indicates whether vibration is enabled when the widget completes successfully. Defaults to `true`.
* `extractionTimeout`: `Long`. Sets the maximum time allowed for capture, in milliseconds. Defaults to `60000`.
* `showDiagnostic`: `Boolean`. Show diagnostic screens at the end of the process. Defaults to `true`.
* `showPreviousTip`: `Boolean`. Shows a screen before capture starts, with information about the process to be carried out and a button to start it. Defaults to `true`.
* `showTutorial`: `Boolean`. Indicates whether the component displays the tutorial screen. This screen intuitively explains how to capture an image. By default `true`.
* `cameraPreferred`: `Camera`. Camera used for capture. Possible values: `FRONT`, `BACK`. By default `BACK`.
* `cameraShape`: `CameraShape`. Lets you choose the shape of the camera mask. Possible values: `SQUARE`, `CIRCULAR`, `RECTANGLE_TALL`. By default `SQUARE`.
* `showStroke`: `Boolean`. Displays the border of the camera mask. By default `false`.
* `transparentBackground`: `Boolean`. Indicates whether the background of the capture screen is transparent. By default `false`.

#### **QR generation configuration**

To launch the current component, you must create a *QrGeneratorConfiguration* object, which will serve as the component controller's configuration.

All the fields that make up this class are detailed below.

* `source`: `String`. Text used to generate the QR Code. Required.
* `width`: `Int`. Width of the generated image in pixels. By default `200`.
* `height`: `Int`. Height of the generated image in pixels. By default `200`.

***

## Component customization <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

In addition to the changes that can be made at the SDK level (explained in the document ([SDK Customization](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/personalizacion.md)), this specific component also allows its interface to be modified.

### Text <a href="#id-81-textos" id="id-81-textos"></a>

To modify the SDK text, include the following XML file in the client application and change the value of each *String* to the desired text.

```
<resources>
    <!-- Previous Tip -->
    <string name="capture_component_qr_tip_title">Scan the QR Code</string>
    <string name="capture_component_qr_tip_message">&lt;b&gt; Aim &lt;/b&gt; the QR Code &lt;b&gt; inside the frame &lt;/b&gt;</string>
    <string name="capture_component_qr_tip_button">Start</string>
    <string name="capture_component_qr_tip_anim_desc">Animation of a mobile phone taking a picture of a QR Code. A frame appears on the phone screen. When the QR Code fits inside the frame, the application takes a picture.</string>
    <string name="capture_component_qr_tutorial_1_anim_desc">A QR Code is shown against a white background. The edges of the QR Code are not clearly visible. The background changes color in an animation.</string>
    <string name="capture_component_qr_tutorial_2_anim_desc">A mobile phone takes a photo of a QR Code. The QR Code is horizontal, and the phone is vertical. A frame appears on the phone screen. When the QR Code fits inside the frame, the app takes a photo.</string>
    <!-- Tutorial -->
    <string name="capture_component_qr_tutorial_1">Make sure the QR Code has &lt;b&gt; enough light &lt;/b&gt; and &lt;b&gt; there are no reflections &lt;/b&gt; or glare on the code.</string>
    <string name="capture_component_qr_tutorial_2">Fit the edges of the QR Code inside the frame.</string>
    <!-- Process -->
    <string name="capture_component_qr_camera_message">Keep the QR Code in the center</string>
    <string name="capture_component_button_message">Capture</string>
    <!-- Diagnostic -->
    <string name="capture_component_timeout_title">Timeout</string>
    <string name="capture_component_timeout_desc">We apologize. The capture could not be completed.</string>
    <string name="capture_component_internal_error_title">A technical problem occurred</string>
    <string name="capture_component_internal_error_desc">We apologize. The capture could not be completed.</string>

    <!-- WIDGET -->
    <!-- Previous Tip -->
    <string name="capture_widget_tip_title">Scan documents</string>
    <string name="capture_widget_tip_message">Take a photo of the document or upload an image.&lt;br&gt;&lt;br&gt; You can scan multiple documents before finishing.</string>
    <string name="capture_widget_tip_message_alt">Take a photo of the document or upload an image. You can scan multiple documents before finishing.</string>
    <string name="capture_widget_tip_button">Start</string>
    <string name="capture_widget_tip_button_alt">Start document capture</string>
    <string name="capture_widget_tip_close_button_alt">Back</string>
    <string name="capture_widget_tip_info_button_alt">View tips</string>
    <string name="capture_widget_tip_anim_desc">Animation of a mobile phone taking a photo of a document. A frame appears on the phone screen. When the document fits inside the frame, the app takes a photo.</string>
    <!-- Camera -->
    <string name="capture_widget_document_camera_button_gallery">Gallery</string>
    <string name="capture_widget_document_camera_button_capture">Capture</string>
    <string name="capture_widget_document_camera_button_cancel">Cancel capture</string>
    <string name="capture_widget_document_camera_button_finish">Finish</string>
    <!-- Gallery -->
    <string name="capture_widget_gallery_images">Images</string>
    <string name="capture_widget_gallery_pdf">Select PDF</string>
    <string name="capture_widget_gallery_cancel">Cancel</string>
    <!-- Confirmation -->
    <string name="capture_widget_image_captured">Image captured</string>
    <string name="capture_widget_confirmation_message">Are all the details clear and legible?</string>
    <string name="capture_widget_confirmation_retry">NO, I WANT TO RETAKE THE PHOTOS</string>
    <string name="capture_widget_confirmation_continue">Yes, finish</string>
    <string name="capture_widget_confirmation_delete">Delete photo</string>
    <string name="capture_widget_confirmation_image_unavailable">Preview unavailable</string>
    <string name="capture_widget_confirmation_no_images">No captures available</string>
    <string name="capture_widget_confirmation_delete_dialog_title">Do you want to delete this document?</string>
    <string name="capture_widget_confirmation_delete_dialog_message">You won't be able to recover this document after deleting it. You will need to take a new photo.</string>
    <string name="capture_widget_confirmation_delete_dialog_cancel">CANCEL</string>
    <string name="capture_widget_confirmation_delete_dialog_confirm">DELETE DOCUMENT</string>
    <!-- Diagnostic -->
    <string name="capture_widget_timeout_title">Timeout</string>
    <string name="capture_widget_timeout_desc">We apologize. The capture could not be completed.</string>
    <string name="capture_widget_internal_error_title">A technical problem occurred</string>
    <string name="capture_widget_internal_error_desc">We apologize. The capture could not be completed.</string>

</resources>

```

### Animations <a href="#id-82-animaciones" id="id-82-animaciones"></a>

To modify the SDK animations (Lottie), include animations with the same names in the application's res/raw/ folder.

```
qr_anim_tip_1.json
qr_anim_tip_2.json
capture_anim_tip.json
```
