> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/verify/liveness/integration/liveness-sdk/android-sdk/liveness-integration.md).

# Liveness Integration

<figure><img src="/files/WxrsutMHAZ768HfirKxs" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**Using ID Fraud Shield?** It runs as a complementary library inside this same liveness flow. The integration steps below stay the same. See ID Fraud Shield at the end of this page.
{% endhint %}

## Liveness Detection Flow

Follow these steps to integrate liveness checks into your Android application, from creating the detector through running detection and releasing resources.

### 1. Import VidaLivenessDetector

Start by importing the `VidaLiveness` class into your application’s activity.

### 2. Create the detector instance

Use the `VidaLivenessBuilder` class to create an instance of the `VidaLiveness` class. You can specify the detection configurations through the builder.

```java
VidaLiveness detector = VidaLiveness.VidaLivenessBuilder
.newInstance(/* ...config params... */) // include userId when ID Fraud Shield is enabled
.build();
```

### 3. Initialize the detector

Call the `initialize()` API to initialize the liveness detection engine. When initialization succeeds, the `onInitialized()` callback of the `VidaLivenessListener` interface is\
invoked - make any subsequent liveness API calls only after that callback fires.

```java
detector.initialize();
```

### 4. Start Liveness Detection

Once the detector is initialized, call `startDetection()` to begin. This API starts the camera and the liveness detection process, capturing image frames and analyzing them to\
determine whether the detected face is live or a spoof.

```java
detector.startDetection();
```

### 5. Stop Liveness Detection

To stop the liveness detection process prematurely or upon completion, call `stopDetection()`.

```java
detector.stopDetection();
```

### 6. Release Resources

After the liveness process is complete, release the resources used by the SDK by calling `release()`.

```java
detector.release();
```

### 7. Retrieve full liveness details (backend)

Once you have the `transactionId` from `getTransactionId()`, your backend can fetch the complete liveness transaction record (scores, status, and metadata). Using the [Liveness Transaction Details API.](/identity-stack/verify/liveness/integration/api/api-reference/liveness-transaction-details-api.md)

## Handling Results - VIDALivenessListener

The `VidaLivenessListener` interface delivers the lifecycle events and results of the liveness flow.

#### onInitialized

Called when `VidaLiveness` has been successfully initialized, after `initialize()` is called with the necessary parameters. Any subsequent liveness API calls should be made only\
after this method is triggered.

```java
void onInitialized()
```

#### onSuccess

Triggered upon successful completion of the liveness flow. The response contains the final frame of the liveness flow and various scores, as applicable.

```java
void onSuccess(VidaLivenessResponse response)
```

#### onError

Invoked when an error occurs during the liveness flow. It provides an error code, an error message detailing the error, and a response containing the final frame, various scores as\
applicable, and error details if available.

```java
void onError(int errorCode, @NonNull String errorMessage, VidaLivenessResponse response)
```

## VIDALivenessResponse

Returned on successful completion of the liveness flow. It contains the final frame and the scores below.

```java
public VidaLivenessResponse(byte[] imageBytes,
 double livenessScore,
 double manipulationScore,
 String errorDetails,
 String transactionId,
 private String sessionId;
 private List<VidaFailedAttempt> failedAttempts; // All previous failed attempt details 
 List<byte[]> images, 
 String sessionId ) 
```

#### Accessor Methods

<table><thead><tr><th width="207.33984375">Method</th><th width="218.0625">Returns</th><th>Description</th></tr></thead><tbody><tr><td>getImageBytes()</td><td>byte[]</td><td>The byte array representing the image used for liveness detection.</td></tr><tr><td>getLivenessScore()</td><td>double</td><td><p>Likelihood the image is of a live person, from 0.0 to 1.0. Returns -1 when the score is not applicable</p><p>or not relevant to the returned error code.</p></td></tr><tr><td>getManipulationScore()</td><td>double</td><td>Likelihood the image has been manipulated or altered.</td></tr><tr><td>getErrorDetails()</td><td>String</td><td>Details about any error that occurred, or null if no error occurred.</td></tr><tr><td>getSessionId()</td><td>String</td><td>Session ID of the liveness detection v1.6.7+</td></tr><tr><td>getTransactionId()</td><td>String</td><td>Transaction ID of the specific liveness API call. Can be null if no backend liveness call happened.</td></tr><tr><td>failedAttempts()</td><td>List&#x3C;VidaFailedAttempt></td><td>Details of all previous failed attempts (see below).</td></tr></tbody></table>

### VidaFailedAttempt

Holds the information returned when a liveness attempt is unsuccessful. Each failed attempt provides the following details:

```java
public final class VidaFailedAttempt {
    private double livenessScore;
    private double manipulationScore;
    private String errorDetails;
    private int errorCode;
    private String transactionId;
```

<table><thead><tr><th width="206.03515625">Field</th><th width="144.52734375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>livenessScore</code></td><td>double</td><td>How closely the captured image or video resembles a real, live person.</td></tr><tr><td><code>manipulationScore</code></td><td>double</td><td>Likelihood of fraudulent activity or tampering detected during the check.</td></tr><tr><td><code>errorDetails</code></td><td>String</td><td>A description explaining why the attempt was unsuccessful.</td></tr><tr><td><code>errorCode</code></td><td>int</td><td>A specific code identifying the type of error, used for troubleshooting or support.</td></tr><tr><td><code>transactionId</code></td><td>String</td><td>A unique reference number for each attempt, used to track and identify the session for reporting or support inquiries.</td></tr></tbody></table>

## Backend-Managed Configurations

These features are configured per client by the VIDA team through OSS (our backend system). They require **no changes to your application code**, please continue using your existing SDK integration as-is. The SDK reads the configuration when it initializes.

To enable or change any of them, contact the VIDA support team.

#### Color Flash

An alternative liveness capture mode. Enabling or disabling it is handled entirely on the VIDA backend.

#### Video Liveness

**Available from:** Android Liveness SDK v1.9.7 — see [Passive Liveness](/identity-stack/verify/liveness/overview/passive-liveness.md) for how it works.

Cannot be enabled together with Color Flash. If both are switched on, Color Flash takes precedence. The review screen is not supported for this liveness type.

#### Behavioral Biometrics

**Available from:** Android Liveness SDK v1.9.8

Part of ID Fraud Shield. Collects clipboard, copy-paste and typing signals during the flow.

<table><thead><tr><th width="295.78125">Setting</th><th>Description</th></tr></thead><tbody><tr><td><code>behavior_biometrics_enabled</code></td><td>Parent switch for all behavioral signals. When disabled, the two settings below have no effect.</td></tr><tr><td><code>clipboard_tracking</code></td><td>Clipboard and copy-paste events.</td></tr><tr><td><code>field_tracking</code></td><td>Typing, hesitation and field input events.</td></tr></tbody></table>

All three are **disabled by default on the SDK side**. If nothing is configured for your account, no behavioral signals are collected.

Enable these only for flows that contain input fields, such as name or date of birth. The liveness screen has no input fields, so these signals add no value there.

A configuration change takes effect at the **next SDK initialization**. It never changes behaviour in the middle of an active session.

## ID Fraud Shield

When ID Fraud Shield is enabled for your account, it runs as a complementary library within the liveness flow. It is not part of the Liveness SDK, and the integration steps above stay the same.

**To use it:** add the ID Fraud Shield dependency and provide a `userId` in the detector configuration. See Getting Started for the dependency and the `VidaLivenessRequest` parameters.

**About `userId`:** optional from Liveness SDK v1.9.6 onwards. If you do not provide one, the SDK uses a default value. We recommend setting your own so fraud rules can be applied per user. On earlier versions it is required when ID Fraud Shield is enabled.

For details about the library, see the [ID Fraud Shield SDK](/identity-stack/verify/id-fraud-shield-sdk.md) documentation.