Video ID - VideoID

Introduction

Face Capture is performed with the VideoID Component.

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

• Internal management of cameras, mic and permissions.

• Connection with the services.

• Reading the OCR and document capture.

In the section of Simplified Launch the steps necessary for the basic integration of the SDK are detailed. In this section, information is added for launching this component.

---

Dependency

The specific dependency for the component is:

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

---

Available controllers

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

---

Simplified Launch

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:

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

---

Basic configuration

To launch the current component, an object must be created VideoIdConfigurationData which will be the configuration of the component controller.

The basic configuration required for it is as follows:

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

---

Receiving the result

The launch will return the information in SdkResult format. It can distinguish between a successful and unsuccessful launch:

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

Receiving errors

Errors will be returned as a 'VideoIdError' object.

List of errors:

• 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 cancellation of the SDK has been made

• VID_COMPONENT_LICENSE_ERROR: The component license is not correct

• VID_EMPTY_LICENSE: The license String is empty

• VID_FACE_DETECTION_TIMEOUT: No face has been detected

• VID_FETCH_DATA_ERROR: Error in collecting the result

• VID_FLOW_ERROR: Error in the flow process

• VID_INITIALIZATION_ERROR: Initialization error

• VID_MANAGER_NOT_INITIALIZED: The managers are null

• VID_NETWORK_CONNECTION: Error in the internet connection

• VID_NO_DATA_ERROR: The input data are null

• VID_OPERATION_NOT_CREATED: There is no operation in progress

• VID_PERMISSION_DENIED: The user has rejected the permissions

• VID_SOCKET_ERROR: Error in the services connection

• VID_TIMEOUT: Timeout in the process

• VID_VIDEO_ERROR: Error in video processing

• 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 response - data

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

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 as follows:

frontDocumentData

Data from the front of the document. Includes:

• documentImage: Document image

• documentFullImage: Captured full image

• documentFaceImage: If a face is found in the document, its image is returned.

• iqaOverExposure: Numeric value between 0 and 1 that indicates the image overexposure level; a high value suggests that the image is too bright, which may make it difficult to read the document.

• iqaReadable: Numeric value between 0 and 1 that indicates 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 that indicates the sharpness of the document image; high values reflect a more focused image, which improves the ability to extract data.

• documentFaceImageTokenized: If a face is found in the document, its encrypted image is returned.

backDocumentData

Data from the back of the document. Includes:

• documentImage: Document image

• documentFullImage: Captured full image

• documentFaceImage: If a face is found in the document, its image is returned.

• iqaOverExposure: Numeric value between 0 and 1 that indicates the image overexposure level; a high value suggests that the image is too bright, which may make it difficult to read the document.

• iqaReadable: Numeric value between 0 and 1 that indicates 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 that indicates the sharpness of the document image; high values reflect a more focused image, which improves the ability to extract data.

• documentFaceImageTokenized: If a face is found in the document, its encrypted image is returned.

faceImage

User image captured in the first section of the process.

ocrMap

Map of the OCR extracted from the document.

ocrDiagnostic

Dictionary with the OCR diagnosis of the document. The keys are the fields to validate and the values are instances of OcrDiagnostic.

OCR diagnosis 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 faces of the document (front and back).

documentType

Obtained document type.

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 pronounce during the video recording.

faceImageTokenized

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

---

Advanced information

This section expands the component information.

Advanced component configuration

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

The fields included in the configuration (url, apiKey, tenantId), normally do not need to be provided since they are completed internally through the license used.

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

url

Path to the video socket

apiKey

ApiKey needed for the connection with the video socket

tenantId

Identifier of the tenant referring to the current client, necessary for the connection with the video service.

sectionTime

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

mode

• ONLY_FACE: The process is carried out by capturing the user's face.

• FACE_DOCUMENT_FRONT: The process is carried out by capturing the user's face and the front of the Identity document.

• FACE_DOCUMENT_FRONT_BACK: The process is carried out 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 allowed time to complete a section (in ms).

autoFaceDetection

Turns automatic face detection on/off.

debug

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

countryFilter

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

documentFilter

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

• "IDC": Identity document (ID Card)

• "PSP": Passport (Passport)

• "DLI": 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 pronounce during the video recording.

ocrValidations

Dictionary with the OCR validations to be performed. The keys are the fields to validate and the values are instances of OcrValidationValue.

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 the OCR validation.

maxRetries

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

---

Component customization

Apart from the changes that can be made at the SDK level (which are explained in the document of SDK Customization), this particular component allows modification of its interface.

Texts

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

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

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

video_id_anim_doc_and_face.json
video_id_anim_face.json
video_id_anim_loading.json

External views

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

Error diagnostic screen:

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

Once the classes implementing the interfaces have been created, at component launch the "customViews" parameter can be added so they are used in the SDK.