> 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/video-identificacion.md).

# Video identification - VideoID

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

Video identification is performed using the ***VideoID Component***.

This component records a user identifying themselves, showing their face and identity document.

* Internal management of cameras, microphone, and permissions.
* Connection to the services.
* OCR reading and document capture.

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

***

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

The component’s specific dependency is:

```kotlin
implementation "com.facephi.androidsdk:video_id_component:$version"
```

***

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

| **Controller**             | **Description**                                 |
| -------------------------- | ----------------------------------------------- |
| VideoIdController          | Main video identification controller            |
| SignatureVideoIdController | Controller for signing a process with a Capture |

***

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

Launch:

```kotlin
val response = SDKController.launch(
    VideoIdController(VideoIdConfigurationData(...))
)
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>

To launch the current component, you must create a *VideoIdConfigurationData* object, which will configure the component controller.

The basic configuration required is as follows:

```kotlin
VideoIdConfigurationData(
    mode = VideoIdMode.DOCUMENT_FRONT_BACK,
)
```

The available modes are:

* VideoIdMode.ONLY\_FACE
* VideoIdMode.FACE\_DOCUMENT\_FRONT
* VideoIdMode.FACE\_DOCUMENT\_FRONT\_BACK
* VideoIdMode.DOCUMENT\_FRONT
* VideoIdMode.DOCUMENT\_FRONT\_BACK

***

## 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 'VideoIdError' object.

List of errors:

* `ACTIVITY_RESULT_MSG_ERROR` (`VID_408`): The activity result is incorrect
* `APPLICATION_CONTEXT_ERROR` (`VID_409`): The required application context is null
* `CANCEL_BY_USER` (`VID_000`): The user canceled the process
* `CANCEL_LAUNCH` (`VID_007`): A general SDK cancellation has occurred
* `COMPONENT_LICENSE_ERROR` (`VID_002`): The component license is invalid
* `EMPTY_LICENSE` (`VID_003`): The license string is empty
* `FACE_DETECTION_TIMEOUT` (`VID_400`): No face was detected
* `FETCH_DATA_ERROR` (`VID_410`): Error retrieving the result
* `FLOW_ERROR` (`VID_416`): Error in the flow process
* `INITIALIZATION_ERROR` (`VID_004`): Initialization error
* `INTERNAL_ERROR` (`VID_415`): Internal error
* `MANAGER_NOT_INITIALIZED` (`VID_411`): Managers are null
* `NETWORK_CONNECTION` (`VID_401`): Internet connection error
* `NO_DATA_ERROR` (`VID_005`): Input data is null
* `OCR_ERROR` (`VID_402`): Error in the document's OCR validation. Includes the field `ocrDiagnostic` (`Map<String, OcrDiagnostic>?`) with the diagnosis for each validated field
* `OPERATION_NOT_CREATED` (`VID_006`): There is no operation in progress
* `PERMISSION_DENIED` (`VID_403`): The user denied permissions
* `SOCKET_ERROR` (`VID_404`): Error connecting to the services
* `TIMEOUT` (`VID_001`): Timeout during the process
* `TRACKING_STEP_ERROR` (`VID_414`): Error creating the tracking step
* `VIDEO_ERROR` (`VID_406`): Error processing the video
* `VIDEO_CALL_ACTIVE` (`VID_405`): Cannot start because a Video Call is already active
* `VIDEO_RECORDING_ACTIVE` (`VID_407`): Cannot start because the video recording process is active

### Successful execution response - *data* <a href="#id-62-recepcion-de-ejecucion-correcta-data" id="id-62-recepcion-de-ejecucion-correcta-data"></a>

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

The result returns the images in **SdkImage**format; you can extract the bitmap by accessing *image.bitmap*. To convert it to base64, you can use the function:

`Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP)`

The fields returned in the result are as follows:

**frontDocumentData**

Front-side document data. Includes:

* documentImage: Document image
* documentFullImage: Full image captured
* documentFaceImage: If a face is detected in the document, its image is returned.
* iqaOverExposure: A numeric value between 0 and 1 indicating the image's overexposure level; a high value suggests that the image is too bright, which may make the document difficult to read.
* iqaReadable: A numeric value between 0 and 1 indicating the legibility of the document text; higher values mean the text is clearer and easier to recognize.
* iqaSharpness: A numeric value between 0 and 1 indicating the sharpness of the document image; higher values reflect a more focused image, which improves data extraction.
* documentFaceImageTokenized: If a face is detected in the document, its encrypted image is returned.
* documentFaceImageMapTokenized: If a face is found in the document, the tokenized map of its image is returned.

**backDocumentData**

Back-side document data. Includes:

* documentImage: Document image
* documentFullImage: Full image captured
* documentFaceImage: If a face is detected in the document, its image is returned.
* iqaOverExposure: A numeric value between 0 and 1 indicating the image's overexposure level; a high value suggests that the image is too bright, which may make the document difficult to read.
* iqaReadable: A numeric value between 0 and 1 indicating the legibility of the document text; higher values mean the text is clearer and easier to recognize.
* iqaSharpness: A numeric value between 0 and 1 indicating the sharpness of the document image; higher values reflect a more focused image, which improves data extraction.
* documentFaceImageTokenized: If a face is detected in the document, its encrypted image is returned.
* documentFaceImageMapTokenized: If a face is found in the document, the tokenized map of its image is returned.

**faceImage**

Image of the user captured in the first section of the process.

**ocrMap**

OCR map extracted from the document.

**ocrDiagnostic**

Dictionary containing the document's OCR diagnostics. The keys are the fields to validate, and the values are OcrDiagnostic instances.

OCR diagnostics extracted from the document.

* OK: OCR is correct.
* NOT\_FOUND: The OCR key was not found.
* TOLERANCE\_ERROR: OCR is incorrect.
* WARNING: OCR is incorrect, but this is only a warning because the field is optional.

**matchingSidesScore**

A numeric value between 0 and 1 that estimates the degree of similarity between the front and back of the document.

**documentType**

Document type obtained.

**personalData**

A reduced set of data obtained from the user:

* issuer
* documentNumber
* issueDate
* expiryDate
* name
* surname
* fullName
* gender
* birthDate
* birthPlace
* nationality
* address
* nfcKey
* numSupport
* mrz

**speechText**

Text the user must speak during the video recording.

**faceImageTokenized**

Encrypted image of the user captured in the first section of the process.

***

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

To launch the current component, you must create a \_VideoIdConfigurationData \_ object, which will be the component controller's configuration.

The fields included in the configuration (**url, apiKey, tenantId**), usually **do not need to be provided** because they are populated internally using the license in use.

These fields are usually provided **only** when the **server** is **On-Premise**.

**url**

Path to the video socket

**apiKey**

ApiKey required to connect to the video socket

**tenantId**

Tenant identifier that refers to the current client, required to connect to the video service.

**sectionTime**

Specifies the duration of sections with an associated time (face capture and camera switch). Default: 5000 ms.

**mode**

Default `FACE_DOCUMENT_FRONT_BACK`.

* ONLY\_FACE: The process captures the user's face.
* FACE\_DOCUMENT\_FRONT: The process captures the user's face and the front of the Identity document.
* FACE\_DOCUMENT\_FRONT\_BACK: The process captures the user's face and the entire Identity document.
* DOCUMENT\_FRONT: The process extracts information only from the front of the document.
* DOCUMENT\_FRONT\_BACK: The process extracts information only from the entire document.

**timeoutServerConnection**

Maximum wait time in ms for the server response. Default: 10000 ms.

**sectionTimeout**

Maximum time allowed to complete a section (in ms). Default: 15000 ms.

**autoFaceDetection**

Enables/disables automatic face detection. Default: `true`.

**countryFilter**

Allows processing to be restricted to a specific set of countries by accepting an array of strings representing aliases in ISO3 format (3-letter code according to the ISO 3166-1 standard).

**documentFilter**

Allows the types of documents accepted during capture to be restricted. Possible values are:

* "IDC": Identity document (ID Card)
* "PSP": Passport
* "DLI": License (Driver License)
* "VIS": Visa
* "FOC": Foreign Card
* "INV": Invoice
* "CUS": Custom Document

**documentQualityThreshold**

Minimum document quality threshold (`Double`). Default is 0.7.

**speechText**

Text the user must speak during the video recording.

**ocrValidations**

Dictionary containing the OCR validations to perform. The keys are the fields to validate, and the values are OcrValidationValue instances.

OcrValidationValue has the following fields:

* value: The value to validate.
* tolerance: The tolerance level for validation (default `HIGH_TOLERANCE`).
  * STRICT: Strict validation.
  * LOW\_TOLERANCE: Validation with low tolerance.
  * MEDIUM\_TOLERANCE: Validation with medium tolerance.
  * HIGH\_TOLERANCE: Validation with high tolerance.
* validationType: The type of validation to perform (default `OPTIONAL`).
  * OPTIONAL: Optional validation.
  * REQUIRED: Required validation.

**ocrMaxWarnings**

Maximum number of warnings allowed during OCR validation. By default, the number of entries in `ocrValidations`.

**maxRetries**

Maximum number of retries allowed for OCR validation. The default value is 2.

***

## 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 on [SDK Customization](https://docs.facephi.com/docs.facephi-en/sdks/sdk-mobile/android-sdk/personalizacion.md)), this particular component also allows its interface to be modified.

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

Text can be customized by adding an XML resource file to the client application and overriding the default values.

```kotlin

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- Waiting -->
    <string name="video_widget_id_text_waiting_agent_title">Video ID</string>

    <!-- Process -->
    <string name="video_widget_id_document_front_message">Place the front of your document on the markers</string>
    <string name="video_widget_id_document_front_message_readable">Keep the front of your document on the markers</string>
    <string name="video_widget_id_document_front_message_not_readable">Bring the front of your document closer to the markers</string>
    <string name="video_widget_id_document_back_message">Now place the back of your document</string>
    <string name="video_widget_id_document_back_message_readable">Keep the back of your document on the markers</string>
    <string name="video_widget_id_document_back_message_not_readable">Bring the back of your document closer to the markers</string>
    <string name="video_widget_id_switch_camera_message">Get the document ready while we switch the camera</string>
    <string name="video_widget_id_finish_button">FINISH</string>
    <string name="video_widget_id_ready_button">CONTINUE</string>
    <string name="video_widget_id_exit_alert_cancel">Cancel</string>
    <string name="video_widget_id_exit_alert_question">Are you sure you want to finish the process?</string>
    <string name="video_widget_id_exit_alert_finish">Finish</string>
    <string name="video_widget_id_exit_alert_accept">Accept</string>
    <string name="video_widget_id_close_button_alt">Close</string>
    <string name="video_widget_id_back_button_alt">Back</string>
    <string name="video_widget_id_logo_alt">Logo</string>
    <string name="video_widget_id_face_message">Place your face inside the frame.</string>
    <string name="video_widget_id_multiple_face_message">Multiple faces detected. Place only your face inside the frame</string>
    <string name="video_widget_id_speech_message">Say out loud: "I (name and surname) accept the terms and conditions".</string>
    <string name="video_widget_id_front_document_captured_message">Front of the document captured successfully</string>
    <string name="video_widget_id_document_back_finish_message">Back of the document captured successfully</string>

    <!-- Diagnostic -->
    <string name="video_widget_id_restart_button">RECORD AGAIN</string>
    <string name="video_widget_id_timeout_title">Time exceeded</string>
    <string name="video_widget_id_timeout_desc">We couldn't complete the recording in time. Let's try again.</string>
    <string name="video_widget_id_face_timeout_title">We couldn't detect your face</string>
    <string name="video_widget_id_face_timeout_desc">Place your face on the marker to start the process</string>
    <string name="video_widget_id_internal_error_title">There was a technical problem</string>
    <string name="video_widget_id_internal_error_desc">We apologize. An unexpected error occurred. Try again.</string>
    <string name="video_widget_id_ocr_error_desc">The document could not be read. Please check the lighting and the distance to the camera</string>
    <string name="video_widget_id_finish_message">Video recording 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.

```
video_id_anim_doc_and_face.json
video_id_anim_face.json
video_id_anim_loading.json
```
