> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/android/standalone-modules/caffacelivenesslite.md).
# Face Liveness Lite
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
{% hint style="success" %}
The Lite SDK is approximately **85% smaller** (6.6x) than the full Face Liveness SDK.
{% endhint %}
## 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 `` tag:
{% code title="AndroidManifest.xml" %}
```xml
```
{% endcode %}
### 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:
{% hint style="info" %}
For Groovy-based projects, include the following repositories in the `settings.gradle` file.
{% endhint %}
{% tabs %}
{% tab title="Kotlin Script" %}
{% code title="settings.gradle.kts" %}
```kts
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
maven { url = uri("https://repo.combateafraude.com/android/release") }
}
}
```
{% endcode %}
{% endtab %}
{% tab title="Groovy" %}
{% code title="settings.gradle" %}
```groovy
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
maven { url "https://repo.combateafraude.com/android/release" }
}
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
### Adding dependencies
Add the Face Liveness Lite dependency to your module-level (app-level) `build.gradle.kts` file:
{% code title="build.gradle.kts" %}
```kts
dependencies {
implementation("io.caf.sdk:caf-face-liveness-lite:7.21.0")
}
```
{% endcode %}
## Starting Liveness
To start the Liveness flow, call `CafFaceLivenessLite.instance.startLiveness()` and pass a `CafLivenessConfig` object.
{% hint style="info" %}
This method accepts a callback to handle the results and events triggered during the Liveness flow.
{% endhint %}
{% tabs %}
{% tab title="Kotlin" %}
{% code expandable="true" %}
```kotlin
val livenessConfig = CafLivenessConfig(
mobileToken = "",
stage = CafStage.PROD,
personId = "",
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
}
}
}
```
{% endcode %}
{% endtab %}
{% tab title="Java" %}
```java
CafLivenessConfig livenessConfig = new CafLivenessConfig(
"", // mobileToken
CafStage.PROD, // stage
"", // 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
}
});
```
{% endtab %}
{% endtabs %}
### `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.
{% hint style="warning" %}
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.
{% endhint %}
#### **`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.
{% hint style="info" %}
To understand and handle the `type` of the failure, see Handling Failures.
{% endhint %}
#### **`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`:
{% tabs %}
{% tab title="Kotlin" %}
```kotlin
CafFaceLivenessLite.instance.release()
```
{% endtab %}
{% tab title="Java" %}
```java
CafFaceLivenessLite.Companion.getInstance().release();
```
{% endtab %}
{% endtabs %}
Links:
{% content-ref url="/pages/SWa4fYvXU4QHS0rTEBa7" %}
[Face Liveness Lite](/caf-sdk/android/standalone-modules/caffacelivenesslite.md)
{% endcontent-ref %}
{% content-ref url="/pages/kzUUoJkdkppda386DUZv" %}
[Handling Failures](/caf-sdk/android/getting-started-with-the-sdk/handling-failures.md)
{% endcontent-ref %}
{% content-ref url="/pages/CjjPANiCm0TOnbldUgeg" %}
[Ui Customization](/caf-sdk/android/standalone-modules/caffacelivenesslite/ui-customization.md)
{% endcontent-ref %}
{% content-ref url="/pages/vsdoZhkDbnAXRhPVlR18" %}
[Changelog](/caf-sdk/android/standalone-modules/caffacelivenesslite/changelog.md)
{% endcontent-ref %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.caf.io/caf-sdk/android/standalone-modules/caffacelivenesslite.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.