Face Liveness Lite

Lightweight face liveness verification SDK for Android. Provides a streamlined flow to verify that a captured face is live, with simple integration and minimal footprint.

The Face Liveness Lite SDK is a lightweight alternative to the Face Liveness SDK. It delivers the same passive liveness verification with a minimal footprint, making it ideal for apps where download size is a priority.

Size Comparison

SDK	Size
Face Liveness (caf-face-liveness)	~25.6 MB
Face Liveness Lite (caf-face-liveness-lite)	~3.9 MB

The Lite SDK is approximately 85% smaller (6.6x) than the full Face Liveness SDK.

Installation

Requirements

Before integrating, ensure your environment meets the minimum requirements for the Face Liveness Lite SDK:

Requirement	Version
Min SDK Version (minSdk)	26
Android Compile version (compileSDK)	34
Min Kotlin version	1.9.10
Gradle version	8.4
Android Gradle Plugin (AGP)	8.3.2

Permissions

To enable the required network and camera functionality, declare the appropriate permissions and hardware features in your project's AndroidManifest.xml file.

Add the following lines within your <manifest> tag:

AndroidManifest.xml

<uses-feature android:name="android.hardware.camera" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

Adding repositories

To download the Face Liveness Lite SDK, add the required repository URL to the dependencyResolutionManagement block located in your project's root settings.gradle.kts file:

For Groovy-based projects, include the following repositories in the settings.gradle file.

Kotlin Script

settings.gradle.kts

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url = uri("https://repo.combateafraude.com/android/release") }
    }
}

Groovy

settings.gradle

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url "https://repo.combateafraude.com/android/release" }
    }
}

Adding dependencies

Add the Face Liveness Lite dependency to your module-level (app-level) build.gradle.kts file:

build.gradle.kts

dependencies {
    implementation("io.caf.sdk:caf-face-liveness-lite:7.21.0")
}

Starting Liveness

To start the Liveness flow, call CafFaceLivenessLite.instance.startLiveness() and pass a CafLivenessConfig object.

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

Kotlin

val livenessConfig = CafLivenessConfig(
    mobileToken = "<YOUR_MOBILE_TOKEN>",
    stage = CafStage.PROD,
    personId = "<PERSON_ID>",
    showLoading = true,
    enableSecurity = true
)
CafFaceLivenessLite.instance.startLiveness(context, livenessConfig) { event ->
    when (event) {
        is LivenessLiteEvent.Success -> {
            // Handle Success
        }
        is LivenessLiteEvent.Failure -> {
            // Handle Failure
        }
        is LivenessLiteEvent.Error -> {
            // Handle Error
        }
        LivenessLiteEvent.Cancelled -> {
            // The user abandoned the flow
        }
        LivenessLiteEvent.Loading -> {
            // Show a loading indicator
        }
        LivenessLiteEvent.Loaded -> {
            // Hide the loading indicator
        }
    }
}

Java

CafLivenessConfig livenessConfig = new CafLivenessConfig(
    "<YOUR_MOBILE_TOKEN>",  // mobileToken
    CafStage.PROD,          // stage
    "<PERSON_ID>",          // personId
    true,                   // loading
    true                    // enableSecurity
);
CafFaceLivenessLite.Companion.getInstance().startLiveness(context, livenessConfig, event -> {
    if (event instanceof LivenessLiteEvent.Success) {
        // Handle Success
    } else if (event instanceof LivenessLiteEvent.Failure) {
        // Handle Failure
    } else if (event instanceof LivenessLiteEvent.Error) {
        // Handle Error
    } else if (event instanceof LivenessLiteEvent.Cancelled) {
        // The user abandoned the flow
    } else if (event instanceof LivenessLiteEvent.Loading) {
        // Show a loading indicator
    } else if (event instanceof LivenessLiteEvent.Loaded) {
        // Hide the loading indicator
    }
});

CafLivenessConfig Parameters

Parameter	Default	Description
mobileToken	—	Required. Mobile authentication token used for backend authentication.
stage	—	Required. Target environment: PROD, BETA, or DEV.
personId	—	Required. Identifies the user for the liveness process.
showLoading	true	Shows loading indicators during processing when true.
enableSecurity	true	When enabled, runs device security validation before and during liveness.

Understanding Liveness Events & Results

To handle the outcome of the Liveness flow, pass a callback to the CafFaceLivenessLite.instance.startLiveness() 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.

LivenessLiteEvent.Success(signedResponse: String)

The capture and liveness pipeline succeeded. signedResponse 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.

LivenessLiteEvent.Failure(signedResponse: String, type: CafFailureType, description: String)

Liveness ran, but the outcome is a business failure:

1. signedResponse: The signed payload returned by the server. May be empty for capture-level failures.
2. type: A CafFailureType enum value identifying exactly why the process was unsuccessful, such as environment issues, timeout, no face detected, or a rejected face authentication.
3. description: A human-readable description intended for diagnostics or UX messaging.

To understand and handle the type of the failure, see Handling Failures.

LivenessLiteEvent.Error(type: CafLivenessErrorType, description: Stringm cause: Throwable)

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.

CafLivenessErrorType	Typical cause
CONFIGURATION_EXCEPTION	mobileToken or personId not provided.
TOKEN_EXCEPTION	Invalid mobileToken detected.
CAMERA_PERMISSION	Camera (or related) permission denied.
NETWORK_EXCEPTION	Connectivity issues surfaced as network class errors.
SERVER_EXCEPTION	Server-side issues while creating or validating the session.
LIVENESS_EXCEPTION	The liveness capture engine failed to initialize or run.
SECURITY_EXCEPTION	Security checks failed.
UNSUPPORTED_DEVICE	Device does not meet the hardware requirements.
GENERIC_EXCEPTION	Other failures not mapped to a specific case.

LivenessLiteEvent.Cancelled

Occurs when the user abandons the flow before completion, such as by pressing the back button or sending the app to the background.

LivenessLiteEvent.Loading / LivenessLiteEvent.Loaded

Lifecycle events emitted while the session is being prepared. Use them to show or hide a loading indicator in your UI.

Releasing Resources

Call release() when the SDK is no longer needed or before starting a new session with a different CafLivenessConfig:

Kotlin

CafFaceLivenessLite.instance.release()

Java

CafFaceLivenessLite.Companion.getInstance().release();

Links:

Face Liveness LiteHandling FailuresUi CustomizationChangelog