Face Liveness

Install and launch Face Liveness for Android. Learn prerequisites, LivenessConfiguration options, callback events, success and failure results, and error handling.

This guide covers version 7.14.0 and above. For versions below 7.14.0, please see the legacy documentation.

Prerequisites

Before proceeding, ensure the Certta SDK is properly installed. If you haven't done this yet, please refer to our Installation Guide.

Installation Guide

Starting Liveness

To start the Liveness flow, call CerttaLiveness.instance.open() and pass a LivenessConfiguration object.

This method accepts a callback to handle the results and events triggered during the Liveness flow.

Kotlin

val livenessConfig = LivenessConfiguration(
    maxRetryAttempts = 3,
    faceAuthEnabled = false,
    showLoading = true,
    useFaceLivenessUi = true
)
CerttaLiveness.instance.open(livenessConfig) { event ->
    when (event) {
        is LivenessEvent.Completed -> {
            when (val result = event.result) {
                is LivenessResult.Success -> {
                    // Handle Success
                }
                is LivenessResult.Failed -> {
                    // Handle Failed
                }
            }
        }
        is LivenessEvent.Error -> {
            // Handle Error
        }
    }
}

Java

LivenessConfiguration livenessConfiguration = new LivenessConfiguration(
    3,      // maxRetryAttempts
    false,  // faceAuthEnabled
    true,   // showLoading
    true    // useFaceLivenessUi
);
CerttaLiveness.getInstance().open(livenessConfiguration, new CerttaLivenessListener() {
    @Override
    public void onEvent(@NotNull LivenessEvent event) {
        if (event instanceof LivenessEvent.Completed) {
            LivenessResult result = ((LivenessEvent.Completed) event).getResult();    
            if (result instanceof LivenessResult.Success) {
                // Handle Success
            } else if (result instanceof LivenessResult.Failed) {
                // Handle Failed
            }    
        } else if (event instanceof LivenessEvent.Error) {
            // Handle Error    
        }
    }
});

LivenessConfiguration Parameters

Parameter	Default	Description
maxRetryAttempts	3	Maximum retries after a failed capture attempt.
faceAuthEnabled	false	When enabled, the SDK performs face authentication.
showLoading	true	Shows loading indicators during processing when true.
useFaceLivenessUi	false	If enabled, the SDK uses the built-in Certta UI.

Understanding Liveness Events & Results

To handle the outcome of the Liveness flow, pass a callback to the CerttaLiveness.instance.open() method to listen for success, failure, or error events.

Ensure the JWT response is evaluated on the backend. This process must include validating the token's signature and verifying the isAlive and isMatch fields. Do not perform these validations on the client side.

LivenessEvent.Completed(result: LivenessResult)

This event indicates that the UI flow has finished. It contains a LivenessResult which you must evaluate:

1. LivenessResult.Success(response: String): The capture and liveness pipeline succeeded. response is a JWT containing the result data obtained during the Liveness execution. This data may include information relevant to the process, such as captured images or validation results.
2. LivenessResult.Failed(failure: LivenessFailure): Liveness ran, but the outcome is a business failure. See LivenessFailure below.

LivenessFailure

Indicates that the liveness check concluded with a failure. There are two variants:

1. LivenessFailure.imageCaptureFailure(cause: String): Problems during capture, such as environment issues, timeout, no face detected, or provider-specific failure. The cause is intended for diagnostics or UX messaging.
2. LivenessFailure.faceRecognitionFailure(result: String, cause: String): Capture succeeded, but face recognition / backend did not accept the result. cause explains the rejection, and result is the signed payload.

To undestand and handle the cause of the failure, see Liveness Error

LivenessEvent.Error(error: CerttaError)

Triggered when a technical blocker prevents the SDK from starting or finishing the process, such as denied camera permissions, no internet connection, or hardware initialization failures.

Event	Typical cause
initializationError	configure not called, empty token or user ID, or invalid maxRetryAttempts.
permissionError	Camera (or related) permission denied.
networkError	Connectivity or server-side issues surfaced as network class errors.
securityError	Security checks failed.
unknownError	Other failures not mapped to a specific case.
cancelled	Occurs when the user abandons the flow before completion, such as by pressing the back button or sending the app to the background.