> 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/ios-sdk/modulos/subida-de-ficheros-y-gestion-de-qr.md).

# File upload and QR management - Capture

This component requires a minimum of iOS 14

## Introduction

File uploading and QR code reading and generation are handled by the ***Capture Component***.

This component lets you upload documents by taking a photo with the device camera or selecting one from the gallery. FileUploader, QR Reader, and QR Generator use the KMP widget **FPHICaptureWidget** (there is no native UI). Its main features are:

* Upload documents using the camera or gallery.
* Read QR codes.
* Generate QR codes.

The [Simplified Launch](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/ios-sdk/inicializacion/lanzamiento-simplificado.md) section describes the steps required for basic SDK integration. This section provides information on launching this component.

***

## Dependencies

To avoid conflicts and compatibility issues, if you want to install the component in a project that contains an older version of the Facephi libraries (Widgets), you must completely remove them before installing the **SDKMobile**.

### **CocoaPods**

* Facephi libraries are currently distributed remotely through various dependency managers, in this case CocoaPods. The **required** dependencies that must be installed beforehand (by adding them to the project's Podfile) are:

```swift
pod 'FPHISDKMainComponent', '~> $VERSION'
```

* To install the Capture component, add the following entry to the application's Podfile:

```swift
pod 'FPHISDKCaptureComponent', '~> $VERSION'
```

### **SPM**

* The required dependencies that must be installed beforehand are:

```swift
//HTTPS
https://github.com/facephi-clienters/SDK-SdkPackage-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-SdkPackage-SPM.git
```

* To install the SelphID component, add it to the project's modules:

<pre class="language-swift"><code class="lang-swift"><strong>//HTTPS
</strong>https://github.com/facephi-clienters/SDK-CapturePackage-SPM.git
//SSH
git@github.com:facephi-clienters/SDK-CapturePackage-SPM.git
</code></pre>

***

## Info.plist configuration (KMP widget)

{% hint style="warning" %}
**IMPORTANT:** The **Capture** component uses the KMP widget **FPHICaptureWidget** and resource files. You must add the following key to the application's **Info.plist** to prevent a runtime crash (**EXC\_BAD\_ACCESS**).
{% endhint %}

```xml
<key>CADisableMinimumFrameDurationOnPhone</key>
<true/>
```

***

## 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, you can launch the component. You can use any of its controllers to run its functionality.

Launching document capture:

```swift
let controller = FileUploaderController(data: fileUploaderConfigurationData, , output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
SDKController.shared.launch(controller: controller)
```

Launching QR capture:

```swift
let controller = QrReaderController(data: qrReaderConfigurationData, , output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
SDKController.shared.launch(controller: controller)
```

Launching QR generation:

```swift
let controller = QrGeneratorController(data: qrGeneratorConfigurationData, , output: { sdkResult in
        // Do whatever with the result
        ...
    }, viewController: viewController)
SDKController.shared.launch(controller: controller)
```

***

## 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, you will need to provide the text to use:

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

***

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

The launch will return the information in SdkResult format.

* errorType
* finishStatus
* data

### Error handling <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

Errors are returned as a CaptureError object.

List of errors:

* CAP\_ACTIVITY\_RESULT\_MSG\_ERROR: The result returned by the activity is incorrect or does not contain the information required to continue.
* CAP\_APPLICATION\_CONTEXT\_ERROR: The required application context is null or invalid, preventing the capture module from being initialized correctly.
* CAP\_CAMERA\_ERROR: An internal error related to the device camera has occurred (opening, initialization, or capture failure).
* CAP\_CAMERA\_PERMISSION\_DENIED: The user denied the permissions required to access the camera.
* CAP\_CANCEL\_BY\_USER: The user manually canceled the capture process.
* CAP\_CANCEL\_LAUNCH: The process was canceled in general by the SDK or by an external action.
* CAP\_COMPONENT\_LICENSE\_ERROR: The component license is invalid, has expired, or does not match the required configuration.
* CAP\_EMPTY\_LICENSE: The license string is empty or has not been provided.
* CAP\_FETCH\_DATA\_ERROR: An error occurred while retrieving or processing the data required to run the flow. *(Includes additional information in the `error`.)*
* CAP\_FLOW\_ERROR: An internal error occurred while running the capture flow. *(Includes additional information in the `error`.)*
* CAP\_INITIALIZATION\_ERROR: An error occurred while initializing the SDK components required. *(Includes detailed information in the `error`.)*
* CAP\_FILE\_UPLOADER\_CAPTURE\_ERROR: An error occurred while uploading the files generated during capture.
* CAP\_MANAGER\_NOT\_INITIALIZED: The managers required to run the process have not been initialized correctly.
* CAP\_NO\_DATA\_ERROR: The required input data is null, missing, or insufficient to continue the process.
* CAP\_OPERATION\_NOT\_CREATED: An active operation required to continue could not be created or retrieved. *(Includes detailed information in the `error`.)*
* CAP\_QR\_CAPTURE\_ERROR: An error occurred while capturing or reading the QR code.
* CAP\_QR\_GENERATION\_ERROR: An error occurred while generating the requested QR code.
* CAP\_TIMEOUT: The maximum time allowed for one of the process stages has been reached.
* CAP\_FLOW\_VIDEO\_RECORDING\_ERROR: An error occurred during Video Recording within the specified flow.
* CAP\_FLOW\_TRACKING\_ERROR: An error occurred while performing the Tracking required to complete the capture flow.

### Successful result received - *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 can be images or PDFs. The fields returned for each are:

* mimeType
* timestampMillis
* content: FileContent -> indicates whether it is an image or a PDF document. If it is an image, it also indicates whether it was captured with the camera or from the gallery.

```
public enum FileContent {
    case uploaderImage(UploaderImage)
    case uploaderDocument(UploaderDocument)
    
    // MARK: - Nested types
    public struct UploaderImage {
        public let image: UIImage
        public let rotationDegrees: Int
        public let source: FileUploaderSource
    }
    
    public struct UploaderDocument {
        public let frontPageImage: UIImage?
        public let bytes: Data
    }
}

public enum FileUploaderSource: String {
    case CAMERA
    case GALLERY
}
```

For example, to read the first element of the array:

```
(..., output: { fileUploaderResult in
    guard fileUploaderResult.errorType == .NO_ERROR else {
        print("\(fileUploaderResult.errorType)")
        return
    }
    ...
    let firstElement = fileUploaderResult.data?.documentImages.first
    
    switch firstElement?.content {
    case .uploaderDocument(let doc):
        // Do something with the file
        break
    case .uploaderImage(let image):
        // Do something with the image
        break
    case .none:
        break
    }
})
```

#### **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 created QR code.

***

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

This section provides additional 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 the current component, you must create an object *FileUploaderConfigurationData* that will serve as the component controller's configuration.

All the fields that are part of this class are described below.

* `vibrationEnabled`: Indicates whether vibration is enabled when the Widget completes successfully.
* `extractionTimeout`: Sets the maximum time allowed for capture.
* `showDiagnostic`: Show diagnostic screens at the end of the process.
* `showPreviousTip`: Shows a screen before capture starts with information about the process and a button to start it.
* `maxScannedDocs`: Maximum number of documents that can be captured
* `allowGallery`: Enables access to the gallery to retrieve images or PDFs
* `onlyGalleryMode`: Opens the flow directly in gallery mode, without showing camera capture. By default, `true`.
* `maxGalleryImageSizeKb`: Maximum allowed size, in KB, for images selected from the gallery. By default `2048`. If an image exceeds this limit, the component returns `CAP_IMAGE_TOO_LARGE`.

#### **QR capture configuration**

To launch the current component, you must create an object *QrCaptureConfigurationData* that will serve as the component controller's configuration.

All the fields that are part of this class are described below.

* `vibrationEnabled`: Indicates whether vibration is enabled when the Widget completes successfully.
* `extractionTimeout`: Sets the maximum time allowed for capture.
* `showDiagnostic`: Show diagnostic screens at the end of the process.
* `showPreviousTip`: Shows a screen before capture starts with information about the process and a button to start it.
* `showTutorial`: Indicates whether the component displays the tutorial screen. This view intuitively explains how to capture.
* `cameraShape`: Lets you choose between a square and a circular mask.

***

## 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 (which are explained in the document on *SDK Customization*), this particular component also allows its interface to be modified.

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

The text can be customized by overriding the values of the following keys in a **Localizable.strings**. Keys with the suffix ***\_alt*** are the strings used in accessibility labels required for ***VoiceOver***.

```xml
<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; Point &lt;/b&gt; the camera at 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">An animation of a mobile phone taking a photo of a QR Code. A frame appears on the phone screen. When the QR Code fits inside the frame, the app takes a photo.</string>
    <string name="capture_component_qr_tutorial_1_anim_desc">A QR Code appears against a white background. The edges of the QR Code are not clearly distinguishable. 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 it.</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 centered</string>
    <string name="capture_component_button_message">Capture</string>
    <!-- Diagnostic -->
    <string name="capture_component_timeout_title">Time limit exceeded</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 picture of a document. A frame appears on the phone screen. When the document fits inside the frame, the app takes a picture.</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">Is all the information 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">Once you delete this document, you won't be able to recover it. You'll 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>
```

This way, if you want to change, for example, the text “*Start*” for the key `capture_widget_tip_button` for the language **es**, go to the file **Localizable.strings** in the **es.lproj** folder, if it exists (if not, create it), and add:

`"capture_widget_tip_button"="Start";`

If a message is not specified in the language file, the default message will be used.

### 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
```
