MÓDULO NATIVO

Liveness (Android)

The DicioLivenessSdk SDK is designed to perform liveness verifications. It allows developers to integrate facial verification functionality into their Android mobile applications. The SDK handles the creation of a liveness session, captures images, and provides callbacks to handle the verification results.

Regresar

ANDROIDNATIVEv1.5.0-rc1

Compatibilidad y Requisitos

Lenguaje

Kotlin / Java

OS Min

Android 7+

API / Target

API 24+

IDE

Jellyfish+

1. Project Setup

Configure your project dependencies by adding the library to your Gradle files and version catalog.

libs.versions.toml

[versions]
dicioLiveness = "1.5.0-rc1"

[libraries]
dicio-sdkliveness = { group = "io.bitbucket.juarezsdco", name = "sdkliveness", version.ref = "dicioLiveness" }

build.gradle

dependencies {
    implementation(libs.dicio.sdkliveness)
}

2. Customization (optional)

Add the following function to your code and call it before launching the SDK, and modify the colors according to your flow:

ConfigStyle.kt

private fun setConfigStyle() {
    // Customize the SDK colors here according to your flow
    Config.backgroundColorCustom = "#121212"
    Config.outerBackgroundColorCustom = "#000000"
    Config.frameColorCustom = "#1E1E1E"
    Config.borderColorCustom = "#3700B3"
    Config.ovalColorCustom = "#03DAC6"
    Config.dualSpinnerColorCustom = "#03DAC6"
    Config.textColorCustom = "#FFFFFF"
    Config.buttonAndFeedbackBarColorCustom = "#6200EE"
    Config.buttonAndFeedbackBarTextColorCustom = "#ffffff"
    Config.buttonColorHighlightCustom = "#3700B3"
    Config.buttonColorDisabledCustom = "#424242"
    Config.showCancelButton = true
    Config.applyAllCustomizations()
}

3. Text Customization (optional)

To customize the texts displayed by the DicioLivenessSdk SDK, you must add an XML file values-en.xml in the res/values-en/ folder of your project. This file will allow you to overwrite the SDK's default text strings with your own custom versions in English.

values-en.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="FaceTec_accessibility_cancel_button">Cancel</string>
    <string name="FaceTec_accessibility_feedback_face_not_on_camera">Face not visible on camera or too far away</string>
    <string name="FaceTec_accessibility_feedback_face_pointing_too_far_left">Your face is pointing too far left</string>
    <string name="FaceTec_accessibility_feedback_face_pointing_too_far_right">Your face is pointing too far right</string>
    <string name="FaceTec_accessibility_feedback_face_rotated_too_far_left">Your face is rotated too far left</string>
    <string name="FaceTec_accessibility_feedback_face_rotated_too_far_right">Your face is rotated too far right</string>
    <string name="FaceTec_accessibility_feedback_face_too_far_left">Your face is too far left</string>
    <string name="FaceTec_accessibility_feedback_face_too_far_right">Your face is too far right</string>
    <string name="FaceTec_accessibility_feedback_face_too_high">Your face is too high</string>
    <string name="FaceTec_accessibility_feedback_face_too_low">Your face is too low</string>
    <string name="FaceTec_accessibility_feedback_hold_device_to_eye_level">Hold the device at eye level</string>
    <string name="FaceTec_accessibility_feedback_move_phone_away">Your face is too close</string>
    <string name="FaceTec_accessibility_feedback_move_phone_closer">Your face is too far away</string>
    <string name="FaceTec_accessibility_tap_guidance">Double tap anywhere on the screen for face alignment guidance.</string>
    <string name="FaceTec_accessibility_torch_button">Lighting switch</string>
    <string name="FaceTec_action_accept_photo">ACCEPT</string>
    <string name="FaceTec_action_confirm">CONFIRM INFORMATION</string>
    <string name="FaceTec_action_continue">CONTINUE</string>
    <string name="FaceTec_action_im_ready">I\\'M READY</string>
    <string name="FaceTec_action_ok">OK</string>
    <string name="FaceTec_action_retake_photo">RETAKE</string>
    <string name="FaceTec_action_scan_nfc">RESCAN</string>
    <string name="FaceTec_action_scan_nfc_card">RESCAN</string>
    <string name="FaceTec_action_skip_nfc">SKIP THIS STEP</string>
    <string name="FaceTec_action_take_photo">TAKE PHOTO</string>
    <string name="FaceTec_action_try_again">TRY AGAIN</string>
    <string name="FaceTec_camera_permission_enable_camera">ENABLE CAMERA</string>
    <string name="FaceTec_camera_permission_header">Enable camera</string>
    <string name="FaceTec_camera_permission_launch_settings">OPEN SETTINGS</string>
    <string name="FaceTec_camera_permission_message_auth">The camera is disabled. Tap below to edit your settings.</string>
    <string name="FaceTec_camera_permission_message_enroll">Please tap the button below to enable your selfie camera.</string>
    <string name="FaceTec_feedback_center_face">Center your face</string>
    <string name="FaceTec_feedback_face_not_found">Frame your face in the oval</string>
    <string name="FaceTec_feedback_face_not_looking_straight_ahead">Look straight ahead</string>
    <string name="FaceTec_feedback_face_not_upright">Keep your head straight</string>
    <string name="FaceTec_feedback_hold_steady">Hold steady</string>
    <string name="FaceTec_feedback_move_phone_away">Move away</string>
    <string name="FaceTec_feedback_move_phone_closer">Move closer</string>
    <string name="FaceTec_feedback_move_phone_to_eye_level">Place the camera at eye level</string>
    <string name="FaceTec_feedback_use_even_lighting">Light your face more evenly</string>
    <string name="FaceTec_idscan_additional_review_message">Additional review\\nis required</string>
    <string name="FaceTec_idscan_capture_hold_steady_message">Hold steady</string>
    <string name="FaceTec_idscan_capture_id_back_instruction_message">Back of your ID</string>
    <string name="FaceTec_idscan_capture_id_front_instruction_message">Front of your ID</string>
    <string name="FaceTec_idscan_capture_tap_to_focus_message">Tap screen to focus</string>
    <string name="FaceTec_idscan_nfc_card_status_finished_with_error_message">Unable to read\\nID chip</string>
    <string name="FaceTec_idscan_nfc_card_status_ready_message">Get ready to scan\\nyour ID chip</string>
    <string name="FaceTec_idscan_nfc_card_status_starting_message">Hold your phone near your ID\\nto scan the NFC chip</string>
    <string name="FaceTec_idscan_nfc_status_disabled_message">Enable NFC\\nin your device settings\\nto continue</string>
    <string name="FaceTec_idscan_nfc_status_finished_with_error_message">Unable to read\\nthe ePassport chip</string>
    <string name="FaceTec_idscan_nfc_status_finished_with_success_message">Document scanning\\ncompleted</string>
    <string name="FaceTec_idscan_nfc_status_ready_message">Get ready to scan\\nyour ePassport chip</string>
    <string name="FaceTec_idscan_nfc_status_scanning_message">Hold steady,\\nscanning NFC chip</string>
    <string name="FaceTec_idscan_nfc_status_skipped_message">NFC scan\\nskipped</string>
    <string name="FaceTec_idscan_nfc_status_starting_message">Bring the phone close to the\\nback of the ePassport\\nto scan the NFC chip</string>
    <string name="FaceTec_idscan_nfc_status_weak_connection_message">Let\\'s try\\nanother scan</string>
    <string name="FaceTec_idscan_ocr_confirmation_main_header">Review and confirm</string>
    <string name="FaceTec_idscan_ocr_confirmation_scroll_message">Scroll down</string>
    <string name="FaceTec_idscan_review_id_back_instruction_message">Verify it is clear and legible</string>
    <string name="FaceTec_idscan_review_id_front_instruction_message">Verify it is clear and legible</string>
    <string name="FaceTec_idscan_type_selection_header">Get ready to scan\\nyour ID</string>
    <string name="FaceTec_initializing_camera">Securing connection</string>
    <string name="FaceTec_instructions_header_ready_1">Get ready for</string>
    <string name="FaceTec_instructions_header_ready_2">your video selfie</string>
    <string name="FaceTec_instructions_message_ready_1">Frame your face in the oval</string>
    <string name="FaceTec_instructions_message_ready_2">Press "I\\'m ready" and move closer</string>
    <string name="FaceTec_presession_brighten_your_environment">Brighten your environment</string>
    <string name="FaceTec_presession_conditions_too_bright">Too bright</string>
    <string name="FaceTec_presession_frame_your_face">Frame your face in the oval</string>
    <string name="FaceTec_presession_hold_steady_1">Hold steady for: 1</string>
    <string name="FaceTec_presession_hold_steady_2">Hold steady for: 2</string>
    <string name="FaceTec_presession_hold_steady_3">Hold steady for: 3</string>
    <string name="FaceTec_presession_neutral_expression">Neutral expression, no smiling</string>
    <string name="FaceTec_presession_position_face_straight_in_oval">Look straight ahead</string>
    <string name="FaceTec_presession_remove_dark_glasses">Remove dark glasses</string>
    <string name="FaceTec_result_facescan_upload_message">Uploading\\nencrypted 3D\\nface scan</string>
    <string name="FaceTec_result_idscan_retry_barcode_not_read_message">Barcode could not be scanned\\nPlease try again</string>
    <string name="FaceTec_result_idscan_retry_face_did_not_match_message">Face does not match\\nenough</string>
    <string name="FaceTec_result_idscan_retry_id_not_fully_visible_message">The ID\\nis not fully visible</string>
    <string name="FaceTec_result_idscan_retry_id_type_not_supported_message">This ID type is not supported\\nPlease use a different ID</string>
    <string name="FaceTec_result_idscan_retry_ocr_results_not_good_enough_message">ID text is not legible</string>
    <string name="FaceTec_result_idscan_skip_or_error_nfc_message">ID info\\nuploaded</string>
    <string name="FaceTec_result_idscan_success_additional_review_message">ID photo capture\\ncompleted</string>
    <string name="FaceTec_result_idscan_success_back_side_message">ID scan completed</string>
    <string name="FaceTec_result_idscan_success_back_side_nfc_next_message">Back of ID\\nscanned</string>
    <string name="FaceTec_result_idscan_success_front_side_back_next_message">Front of ID\\nscanned</string>
    <string name="FaceTec_result_idscan_success_front_side_message">ID scan completed</string>
    <string name="FaceTec_result_idscan_success_front_side_nfc_next_message">Front of ID\\nscanned</string>
    <string name="FaceTec_result_idscan_success_nfc_message">ID scan completed</string>
    <string name="FaceTec_result_idscan_success_passport_message">Passport scan completed</string>
    <string name="FaceTec_result_idscan_success_passport_nfc_next_message">Passport scanned</string>
    <string name="FaceTec_result_idscan_success_user_confirmation_message">Photo ID scan\\ncompleted</string>
    <string name="FaceTec_result_idscan_unsuccess_message">ID photo\\ndoes not match\\nuser\\'s face</string>
    <string name="FaceTec_result_idscan_upload_message">Uploading\\nencrypted ID scan</string>
    <string name="FaceTec_result_nfc_upload_message">Uploading\\nencrypted NFC info</string>
    <string name="FaceTec_result_success_message">Done</string>
    <string name="FaceTec_retry_header">Let\\'s try again</string>
    <string name="FaceTec_retry_ideal_image_label">Ideal pose</string>
    <string name="FaceTec_retry_instruction_message_1">Neutral expression, no smiling</string>
    <string name="FaceTec_retry_instruction_message_2">No glare or extreme lighting</string>
    <string name="FaceTec_retry_instruction_message_3">Too blurry, clean your camera</string>
    <string name="FaceTec_retry_subheader_message">We need a clearer video selfie</string>
    <string name="FaceTec_retry_your_image_label">Your selfie</string>
</resources>

4. Starting the Liveness Process

To start the liveness verification process, the developer must call the startLivenessActivity function from the DicioLivenessSdk class.

Syntax

DicioLivenessSdk.startLivenessActivity(
    context: Context,
    token: String,
    retries: Int,
    playOnSound: Boolean,
    urlBase: String,
    callback: DicioLivenessCallback
)

• Context: The context of the application or activity that will call the SDK.
• Token: An authentication token required to initialize the verification.
• retries: The maximum number of attempts the user can make before failing the verification.
• playOnSound: Enables or disables the voice-guided system.
• urlBase: URL for token validation and obtaining licenses.
• Callback: Implementation of the DicioLivenessCallback interface that will handle the results.

Usage Example

LivenessScreen.kt

private fun initDicioLivenes(token: String, retries: Int, urlBase: String){
    // Invoke the SDK passing the necessary parameters
    DicioLivenessSdk.startLivenessActivity(this, token, retries, true, urlBase, object : DicioLivenessCallback
        {
            override fun DicioLvOnSuccess(resultData: String, image: String, retries: Int) {
                // Successful verification. Process the received data.
                println("resultDataSuccess: $resultData")
                println("imageFACE: $image")
                println("retries: $retries")
                // Here you can proceed with your flow
            }
            override fun DicioLvResReceived(resultData: String, image: String, retries: Int) {
                // Invoked every time an attempt is made
                println("resultData: $resultData")
                println("imageFACE: $image")
                println("retries: $retries")
            }
            override fun DicioLvonFailure(errorMessage: String) {
                // An error occurred during the process
                println("errorMessage: $errorMessage")
                // Here you can handle other errors or log them
            }
            override fun DicioLvonCancel(cancelMessage: String, retries: Int) {
                // The process was canceled (by the user or max retries reached)
                println("cancelMessage: $cancelMessage")
                println("attempts: $retries")
                // Here you can navigate back
            }
        })
}

DicioLivenessCallback Interface

This interface handles the results of the liveness verification.

Methods:

1. DicioLvOnSuccess:

• Description: Invoked when the liveness verification is successful.
• Parameters:
  • resultData: Verification result in JSON format.
  • image: Image captured during the liveness process in b64.
  • retries: Number of attempts.

1. DicioLvOnResReceived:

• Description: Invoked every time an attempt is made.
• Parameters:
  • resultData: Verification result in JSON format.
  • image: Image captured during the liveness process in b64.
  • retries: Number of attempts.

1. DicioLvonFailure:

• Description: Invoked when there is an error during the process.
• Parameter:
  • errorMessage: Error message in JSON format.

1. DicioLvonCancel:

• Description: Invoked when the user cancels the verification.
• Parameter:
  • cancelMessage: Message explaining why the process was canceled.
  • retries: Number of attempts.

Error Handling

The SDK handles different types of errors, which are returned through the DicioLvonFailure method. Error messages are in JSON format and contain the keys:

• "Code": Cancellation code.
• "Message": Cancellation description.

Similarly, it returns the number of attempts made at the time of cancellation:

• "Retries": Number of attempts.

Error Handling and Response Codes

The SDK returns different status codes and messages that will allow you to understand what happened during the verification.

Success messages:

• "Liveness confirmed" : The liveness was successful and the verification is complete.

Error messages:

Error code	Description
NETWORK_ERROR	Network error during the request.
SESSION_TOKEN_ERROR	Error retrieving the session token.
SDK_INITIALIZATION_FAILED	SDK initialization failed.
TOKEN_NOT_VALID	The provided token is invalid.
NO_INTERNET	No internet connection available.
TOKEN_EMPTY	The token is empty or missing.
RETRIES_INVALID	The number of attempts must be greater than 0.
UNEXPECTED_API_RESPONSE	Unexpected response from the API.
JSON_PARSE_ERROR	Error parsing the JSON response.
TOKEN_NOT_VALID	Invalid token.

Cancellation messages:

Cancellation code	Description
USER_CANCEL	The session was successfully canceled.
MAX_RETRIES_REACHED	The maximum number of allowed retries was reached.