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

The face capture is performed with the ***VideoID Component***.

This component is responsible for recording a user identifying themselves, showing their face and Identity document.

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

In the section on [Simplified Launch](/docs.facephi-en/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) the steps necessary for the basic integration of the SDK are detailed. In this section, information is added for launching this component.

***

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

The specific dependency for the component 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 Face Capture |

***

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

Once the SDK has started 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, an object must be created *VideoIdConfigurationData* which will be the configuration of the component controller.

The basic configuration needed is the following:

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

The different modes are:

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

***

## Receipt of 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, allowing distinction between a successful launch and an unsuccessful one:

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

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

Errors will be returned as a 'VideoIdError' object.

Error list:

* VID\_ACTIVITY\_RESULT\_MSG\_ERROR: The activity result is incorrect
* VID\_APPLICATION\_CONTEXT\_ERROR: The required application context is null
* VID\_CANCEL\_BY\_USER: The user has canceled the process
* VID\_CANCEL\_LAUNCH: A general SDK cancellation has been made
* VID\_COMPONENT\_LICENSE\_ERROR: The component License is incorrect
* VID\_EMPTY\_LICENSE: The License String is empty
* VID\_FACE\_DETECTION\_TIMEOUT: No face has been detected
* VID\_FETCH\_DATA\_ERROR: Error retrieving the result
* VID\_FLOW\_ERROR: Error in the flow process
* VID\_INITIALIZATION\_ERROR: Initialization error
* VID\_MANAGER\_NOT\_INITIALIZED: Managers are null
* VID\_NETWORK\_CONNECTION: Internet connection error
* VID\_NO\_DATA\_ERROR: Input data is null
* VID\_OPERATION\_NOT\_CREATED: There is no operation in progress
* VID\_PERMISSION\_DENIED: The user has rejected the permissions
* VID\_SOCKET\_ERROR: Error connecting to services
* VID\_TIMEOUT: Timeout in the process
* VID\_VIDEO\_ERROR: Error processing the video
* VID\_VIDEO\_CALL\_ACTIVE: Cannot start because there is already an active Video Call
* VID\_VIDEO\_RECORDING\_ACTIVE: Cannot start because the video recording process is active

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

In the SdkResult.Success part - *data*, the VideoIdResult class will be available.

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

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

The fields returned in the result are the following:

**frontDocumentData**

Document front-side data. Includes:

* documentImage: Document image
* documentFullImage: Full captured image
* documentFaceImage: If a face has been found in the document, its image is returned.
* iqaOverExposure: Numeric value between 0 and 1 indicating the image's overexposure level; a high value suggests the image is too brightly lit, which may make the document difficult to read.
* iqaReadable: Numeric value between 0 and 1 indicating the readability of the document text; higher values imply that the text is clearer and easier to recognize.
* iqaSharpness: Numeric value between 0 and 1 indicating the sharpness of the document image; high values reflect a more focused image, which improves data extraction capability.
* documentFaceImageTokenized: If a face has been found in the document, its encrypted image is returned.

**backDocumentData**

Document back-side data. Includes:

* documentImage: Document image
* documentFullImage: Full captured image
* documentFaceImage: If a face has been found in the document, its image is returned.
* iqaOverExposure: Numeric value between 0 and 1 indicating the image's overexposure level; a high value suggests the image is too brightly lit, which may make the document difficult to read.
* iqaReadable: Numeric value between 0 and 1 indicating the readability of the document text; higher values imply that the text is clearer and easier to recognize.
* iqaSharpness: Numeric value between 0 and 1 indicating the sharpness of the document image; high values reflect a more focused image, which improves data extraction capability.
* documentFaceImageTokenized: If a face has been found in the document, its encrypted image is returned.

**faceImage**

User image captured in the first section of the process.

**ocrMap**

OCR map extracted from the document.

**ocrDiagnostic**

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

OCR diagnostic extracted from the document.

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

**matchingSidesScore**

Numeric value between 0 and 1 that estimates the level of match between the document sides (front and back).

**documentType**

Type of document obtained.

**personalData**

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 that the user must say during video recording.

**faceImageTokenized**

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

***

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

This section expands on the information of the component.

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

To launch the current component, a \_VideoIdConfigurationData \_ object must be created, which will be the component controller configuration.

The fields included in the configuration (**url, apiKey, tenantId**) usually **do not need to be provided** as they are completed internally through the License used.

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

**url**

Path to the video socket

**apiKey**

ApiKey required for the connection to the video socket

**tenantId**

Tenant identifier referring to the current client, required for the connection to the video service.

**sectionTime**

Indicates the duration of sections with associated time (face capture and camera switching).

**mode**

* ONLY\_FACE: The process is performed by capturing the user's face.
* FACE\_DOCUMENT\_FRONT: The process is performed by capturing the user's face and the front of the Identity document.
* FACE\_DOCUMENT\_FRONT\_BACK: The process is performed by capturing the user's face and the complete 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 complete document.

**timeoutServerConnection**

Maximum wait time in ms for the server response.

**sectionTimeout**

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

**autoFaceDetection**

Enables/disables automatic face detection.

**debug**

Enables the display of additional information useful for diagnosing and monitoring internal behavior.

**countryFilter**

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

**documentFilter**

Allows restricting the types of documents accepted during capture. Possible values are:

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

**speechText**

Text that the user must say during 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.
  * STRICT: Strict validation.
  * LOW\_TOLERANCE: Low-tolerance validation.
  * MEDIUM\_TOLERANCE: Medium-tolerance validation.
  * HIGH\_TOLERANCE: High-tolerance validation.
* validationType: The type of validation to perform.
  * OPTIONAL: Optional validation.
  * REQUIRED: Mandatory validation.

**ocrMaxWarnings**

Maximum number of warnings allowed in OCR validation.

**maxRetries**

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

***

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

Apart from the changes that can be made at the SDK level (which are explained in the document of [SDK Customization](/docs.facephi-en/sdks/sdk-mobile/android-sdk/personalizacion.md)), this specific component allows modification of its interface.

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

Texts can be customized by adding an XML resource file in the client application and overwriting 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>

If you want to modify the SDK's animations (lottie), you would have to include the animations with the same name in the app's res/raw/ folder.

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

### External views <a href="#id-83-vistas-externas" id="id-83-vistas-externas"></a>

It is possible to completely customize the component screens while maintaining their functionality and navigation. To do so, the following interfaces must be implemented:

Error diagnostic screen:

```kts

interface IVideoIdErrorDiagnosticView {
    @Composable
    fun Content(
        error: VideoIdError,
        onRetry: () -> Unit,
        onClose: () -> Unit,
    )
}

```

Once the classes that implement the interfaces have been created, the component launch can include the "customViews" parameter so that they are used in the SDK.