> 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 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
SDKSize
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) | 36 | | 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.25.0") } ``` {% endcode %} ## Starting Liveness The Liveness flow has three steps: 1. **`configure()`** — give the SDK your credentials, once. 2. **`prewarm()`** — fetch the liveness session while the user is still on the previous screen. 3. **`startLiveness()`** — open the camera and receive the result. {% hint style="info" %} Splitting the work this way lets the network request happen before the user asks for the camera, so the camera opens noticeably faster. {% endhint %} ### Configure Create a `CafLivenessConfig` and pass it to `configure()`. This only stores the context and configuration. {% code title="MainActivity.kt" %} ```kotlin val livenessConfig = CafLivenessConfig( mobileToken = "", stage = CafStage.PROD, personId = "", showLoading = true, enableSecurity = true ) CafFaceLivenessLite.instance.configure(context, livenessConfig) ``` {% endcode %} #### `CafLivenessConfig` Parameters | Parameter | Default | Description | | ---------------- | ------- | ----------------------------------------------------------------------------- | | `mobileToken` | — | **Required.** Mobile authentication token used for backend authentication. | | `stage` | `PROD` | **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. | ### Pre-warm Call `prewarm()` as soon as you know Liveness is coming — when the user reaches the screen before it, or when the "Start" button becomes visible. The SDK creates the Liveness session in the background so `startLiveness()` does not have to wait for it. ```kotlin CafFaceLivenessLite.instance.prewarm() ``` `prewarm()` takes no parameters, returns immediately and reports nothing — the work continues in the background. It requires `configure()` to have been called first. {% hint style="info" %} `prewarm()` is optional. If you skip it, `startLiveness()` creates the session itself and everything works exactly the same — just without the speed gain. {% endhint %} {% hint style="warning" %} The pre-warmed session is valid for 90 seconds and is used at most once. If the window passes, or the session was already used by a previous `startLiveness()`, a fresh one is fetched automatically. {% endhint %} ### Start Liveness Call `startLiveness()` with a callback to handle the results and events triggered during the Liveness flow. ```kotlin CafFaceLivenessLite.instance.startLiveness { 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 } } } ``` {% hint style="info" %} If a pre-warm is still running when `startLiveness()` is called, the SDK waits for it rather than starting a second request — so calling `prewarm()` shortly before is never wasted. {% endhint %} ### Complete example ```kotlin class SelfieIntroFragment : Fragment() { private val livenessConfig = CafLivenessConfig( mobileToken = "", stage = CafStage.PROD, personId = "", showLoading = true, enableSecurity = true ) override fun onViewCreated(view: View, savedInstanceState: Bundle?) { super.onViewCreated(view, savedInstanceState) // The user is on the screen before Liveness: prepare the session now. CafFaceLivenessLite.instance.configure(requireContext(), livenessConfig) CafFaceLivenessLite.instance.prewarm() startButton.setOnClickListener { CafFaceLivenessLite.instance.startLiveness { event -> // Handle events } } } } ``` ## 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. ## Changing the user or credentials If you call `configure()` again with a different `mobileToken` or `personId`, any pre-warmed session is discarded, since it belongs to the previous user. Call `prewarm()` again after reconfiguring. ## Releasing the SDK `release()` cancels the Liveness in progress and discards any pre-warmed session. The configuration from `configure()` is kept, so you can call `prewarm()` or `startLiveness()` again without reconfiguring. ```kotlin CafFaceLivenessLite.instance.release() ``` 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.