Liveness Integration
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.
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.
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.
5. Stop Liveness Detection
To stop the liveness detection process prematurely or upon completion, call stopDetection().
6. Release Resources
After the liveness process is complete, release the resources used by the SDK by calling 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.
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.
onSuccess
Triggered upon successful completion of the liveness flow. The response contains the final frame of the liveness flow and various scores, as applicable.
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.
VIDALivenessResponse
Returned on successful completion of the liveness flow. It contains the final frame and the scores below.
Accessor Methods
getImageBytes()
byte[]
The byte array representing the image used for liveness detection.
getLivenessScore()
double
Likelihood the image is of a live person, from 0.0 to 1.0. Returns -1 when the score is not applicable
or not relevant to the returned error code.
getManipulationScore()
double
Likelihood the image has been manipulated or altered.
getErrorDetails()
String
Details about any error that occurred, or null if no error occurred.
getSessionId()
String
Session ID of the liveness detection v1.6.7+
getTransactionId()
String
Transaction ID of the specific liveness API call. Can be null if no backend liveness call happened.
failedAttempts()
List<VidaFailedAttempt>
Details of all previous failed attempts (see below).
VidaFailedAttempt
Holds the information returned when a liveness attempt is unsuccessful. Each failed attempt provides the following details:
livenessScore
double
How closely the captured image or video resembles a real, live person.
manipulationScore
double
Likelihood of fraudulent activity or tampering detected during the check.
errorDetails
String
A description explaining why the attempt was unsuccessful.
errorCode
int
A specific code identifying the type of error, used for troubleshooting or support.
transactionId
String
A unique reference number for each attempt, used to track and identify the session for reporting or support inquiries.
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.10.0 — see Passive Liveness 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.
behavior_biometrics_enabled
Parent switch for all behavioral signals. When disabled, the two settings below have no effect.
clipboard_tracking
Clipboard and copy-paste events.
field_tracking
Typing, hesitation and field input events.
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 documentation.
Last updated