LogoLogo
Useful links
  • Home
  • Product guides
  • API
  • SDKs
  • Overview
  • First steps
  • ANDROID
    • Getting Started with the SDK
    • Standalone Modules
      • Document Detector
        • Release Notes
        • Current Version
        • Requirements
        • Gradle Dependencies
        • Gradle Source Code
        • Setting up the SDK
          • Setting properties
          • Capture Stages
          • Messages Settings
          • Customization
          • Security Settings
          • Detection Steps
          • Upload Mode
          • Advanced Settings
            • Proxy configuration
            • Preview configuration
        • Start Document Detection
        • Source Code
        • Google security form
        • Reduce SDKs size
        • SDKs response
        • References
        • FAQ
      • Face Liveness
        • Release Notes
        • Current Version
        • Requirements
        • Gradle Dependencies
        • Gradle Source Code
        • SDK Lifecycle
        • Building the SDK
        • Start Liveness Verification
        • Source Code
        • References
        • Advanced Features
        • FAQ
      • Face Authenticator
        • Release Notes
      • Smart Auth
        • Release Notes
        • Current Version
        • Requirements
        • Gradle Dependencies
        • Gradle Source Code
        • Permissions
        • SDK Lifecycle
        • Building the SDK
        • Start Smart Authentication
        • Source Code
        • References
        • FAQ
      • Face Liveness (deprecated)
        • Release Notes
  • iOS
    • Getting Started with the SDK
    • Standalone Modules
      • Document Detector
        • Release Notes
        • Current Version
        • Requirements
        • Installing the SDK
        • Setting up the SDK
          • Setting properties
          • Messages Settings
          • Customization
          • Detection Steps
          • Upload Mode
          • Advanced Settings
            • Proxy configuration
            • Preview configuration
        • Start Document Detection
        • References
        • FAQ
      • Face Liveness
        • Release Notes
        • Installation
        • Current Version
        • Requirements
        • SDK Lifecycle
        • Building the SDK
        • Start Liveness Verification
        • Source Code
        • References
        • FAQ
      • Face Authenticator
        • Release Notes
        • Installation
        • Current Version
        • Requirements
        • Building the SDK
        • Start the SDK
        • References
        • FAQ
      • Smart Auth
        • Release Notes
        • Installation
        • Current Version
        • Requirements
        • SDK Lifecycle
        • Building the SDK
        • Start Smart Authentication
        • Source Code
        • References
        • FAQ
      • Face Liveness (deprecated)
        • Release Notes
  • REACT NATIVE
    • Standalone Modules
      • Document Detector
        • Release Notes
        • Current Version
        • Requirements
        • Installation
        • Hooks
        • Start Document Verification
        • Source Code
        • TypeScript References
        • Customizing Style
        • FAQ
      • Face Liveness
        • Release Notes
        • Current Version
        • Requirements
        • Installation
        • Hooks
        • Start Liveness Verification
        • Source Code
        • TypeScript References
        • FAQ
      • Face Authenticator
        • Release Notes
        • Current Version
        • Requirements
        • Installation
        • Hooks
        • Start Authentication Verification
        • Source Code
        • TypeScript References
        • FAQ
      • Smart Auth
        • Getting started
        • Release notes
        • Using Native Modules
          • Requirements
          • Gradle Source Code
          • Podfile Source Code
          • Native Module Android
          • Native Module iOS
          • Import Native Modules
          • Source Code
          • TypeScript References
          • FAQ
        • Using Expo Modules
          • Requirements
          • Create Local Expo Module
          • Gradle Source Code
          • Podspec Source Code
          • Native Module Android
          • Native Module iOS
          • Import Expo Modules
          • Source Code
          • TypeScript References
          • FAQ
  • WEB (JAVASCRIPT)
    • Standalone Modules
      • Document Detector
        • Getting started
        • SDK builder options
          • Analytics
          • Appearance
          • Messages
        • SDK methods
        • Event listeners
        • Customization
        • Release notes
      • Face Liveness
        • Customization
        • Release notes
      • Face Authenticator
        • Customization
        • Release notes
      • Smart Auth
        • SDK errors
        • Customization
        • Release notes
LogoLogo

2025 © Caf. - All rights reserved

On this page
  • Current Version
  • Requirements
  • SDK Dependencies
  • Runtime permissions
  • Installation
  • Instantiating the SDK
  • Builder method
  • Reverse proxy
  • FaceLiveness reverse proxy
  • Authentication reverse proxy
  • Consulting a policy
  • Parameters
  • Example
  • VerifyLivenessListener options
  • SDK Results
  • Success cases
  • Error cases
  • Failure cases
  1. ANDROID
  2. Standalone Modules

Face Liveness (deprecated)

Enables you to integrate live facial verification and fingerprint authentication technology into your Android applications, offering a seamless and secure way to authenticate users.

Current Version

Name
Version

FaceLiveness

4.1.1

Requirements

  • Minimum Android SDK API version: minSdk 26 (Android 8 Oreo)

  • Android SDK API version to compile: compileSdk 34

To publish your app on the Google Play Store, you must complete a data safety form. Since we integrate with the FingerPrintJS SDK, you'll need to provide the following information:

Question in Google Play Console's data safety form
Response

Does your app collect or share any of the required user data types?

Yes.

What type of data is collected?

Device or other identifiers.

Is this data collected, shared, or both?

Collected.

Is this data processed ephemerally?

Yes.

Why is this user data collected?

Fraud Prevention, Security, and Compliance.

versionName and versionCode are mandatory for the SDK to work correctly.

SDK Dependencies

FaceLiveness leverages the following external SDKs:

SDK
Version

iProov Biometrics Android

9.1.2

Fingerprint Pro Android

2.7.0

These dependencies are easily managed through Gradle and are bundled with the SDK for ease of installation.

Runtime permissions

Permission
Reason
Required

CAMERA

Capturing the selfie in live facial verification policies

Yes

Installation

If your version of Gradle is earlier than 7, add these lines to your build.gradle.

allprojects {
  repositories {
  ...
  maven { url 'https://repo.combateafraude.com/android/release' }
  maven { url 'https://raw.githubusercontent.com/iProov/android/patch912/maven/' }
  maven { url 'https://maven.fpregistry.io/releases' }
  maven { url 'https://jitpack.io' }

}}

If your version of Gradle is 7 or newer, add these lines to your settings.gradle.

dependencyResolutionManagement {
    repositories {
        ...
        maven { url 'https://repo.combateafraude.com/android/release' }
        maven { url 'https://raw.githubusercontent.com/iProov/android/patch912/maven/' }
        maven { url 'https://maven.fpregistry.io/releases' }
        maven { url 'https://jitpack.io' }
    }
}

Add support for Java 8 to your build.gradle file. Skip this step if Java 8 is enabled.

android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

Add the SDK version to the dependencies section in your build.gradle file

dependencies {
    implementation 'io.caf.sdk:new-face-liveness:{version}'
}

Instantiating the SDK

First, create an object of type FaceLiveness. This object is for you to configure all your business rules:

FaceLiveness faceLiveness = new FaceLiveness.Builder(String mobileToken)
    //see table below
    .build();

Builder method

Parameter
Required

String mobileToken

Yes

.setStage(CAFStage stage)

Used to redirect the SDK to the desired stage in caf api. The method takes as parameter an enum CafStage to select the environment:

  • CAFStage.PROD set production environment.

  • CAFStage.BETA set beta environment.

No. The default is CAFStage.PROD

.setFilter(Filter filter)

Used to change the SDK filter, that has the following options:

  • Filter.NATURAL

  • Filter.LINE_DRAWING

No, the default is LINE_DRAWING

.setEnableScreenshots(boolean bool)

Used to enable screenshots during the SDK scan. Disabled by default for security reasons.

No, the default is false

.setLoadingScreen(boolean bool)

Used to enable a default loading progressbar during loading events. You can set your customized loading screen instead, using the onLoading method below.

No, the default is false

.setImageUrlExpirationTime(Time time)

Used to customize the image URL expiration time, that has the following options:

  • Time.THREE_HOURS

  • Time.THIRTY_DAYS

No, the default is null

.setFaceLivenessBaseUrl(String baseURL)

Used to enable the use of reverse proxy to execute face liveness. If used, the certificates must be set with the setCertificates method.

No, the default is the original IProov URL

.setCertificates(String[] certificates)

Used to set pinned certificates for reverse proxy implementation.

No, the default is an empty list

.setAuthenticationBaseUrl(String baseURL)

Used to enable the use of reverse proxy to execute SDK's authentications.

No, the default is the original Caf's URL

Reverse proxy

In order to implement reverse proxy settings, you must follow these instructions:

FaceLiveness reverse proxy

  • Set your proxy to communicate with `wss://us.rp.secure.iproov.me/ws´.

  • Use the method .setFaceLivenessBaseUrl to set the URL on which the FaceLiveness must run.

    • The URL's protocol must be WSS.

  • Use the method .setCertificates method to set the certificates, which are base64-encoded SHA-256 hash of certificate' Subject Public Key Info.

    • Certificates are needed in order to make Faceliveness reverse proxy work.

FaceLiveness faceLiveness = new FaceLiveness.Builder(usersToken)
        .setFaceLivenessBaseUrl("wss://my.proxy.io/ws/")
        .setCertificates(new String[]{
                "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
                "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
                "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="
        })
        .build();

Authentication reverse proxy

  • Set your proxy to communicate with the URL that corresponds the CAFStage you are using:

    • CAFStage.PROD -> https://api.public.caf.io/v1/sdks/faces/

    • CAFStage.BETA -> https://api.public.beta.caf.io/v1/sdks/faces/

    • CAFStage.DEV -> https://api.public.dev.caf.io/v1/sdks/faces/

  • Use the method .setAuthenticationBaseUrl to set the URL on which the authorization requests must run.

    • The URL's protocol must be HTTPS.

FaceLiveness faceLiveness = new FaceLiveness.Builder(usersToken)
        .setAuthenticationBaseUrl("https://my.proxy.io/v1/faces/")
        .build();

Consulting a policy

To authenticate a user, use the .startSDK() method. You must enter the personId, your app's Context and a VerifyLivenessListener object.

Parameters

Parameter
Required

String personId

Identifier of the user who will perform the face liveness verification. It's recommended to use the user's identification document in this field, such as their CPF (Brazilian document ID), but it could be any other value.

Yes

Context context

Your app Context

Yes

VerifyLivenessListener listener

Response Listener

Yes

Example

faceLiveness.startSDK(Context context, String personId, new VerifyLivenessListener() {
    @Override
    public void onSuccess(FaceLivenessResult result) {

    }

    @Override
    public void onFailure(FaceLivenessFailureResult result) {

    }

    @Override
    public void onError(SDKError sdkerror) {

    }

    @Override
    public void onCancel() {

    }

    @Override
    public void onLoading() {

    }

    @Override
    public void onLoaded() {

    }
});

VerifyLivenessListener options

Method
Description

onSuccess

The execution has ended with success, you have to use the faceLivenessResult and check for the results of the SDK.

onFailure

The execution has ended with failure, you have to use the faceLivenessFailureResult and check for the results of the SDK.

onError

The execution has ended with error, you have to use the sdkFailure and check for the error results of the SDK.

onCancel

The execution has been cancelled by the user.

onLoading

The SDK is loading, you can use this method to set a action in your app, for example a loading.

onLoaded

The SDK is not loading anymore, you can use this method to set a action in your app, for example, you can stop your previous loading.

SDK Results

Success cases

  livenessResult.getSignedResponse()

FaceLivenessResult (Class)

Property
Description

String signedResponse

Signed response from the CAF server confirming that the captured selfie has a real face. This parameter is used to get an extra layer of security, checking that the signature of the response is not broken, or caused by request interception. If it is broken, there is a strong indication of request interception.

SignedResponse params

Event
Description

requestId

Request identifier.

isAlive

Validation of a living person, identifies whether the user passed successfully or not.

token

Request token.

userId

User identifier provided for the request.

imageUrl

Temporary link to the image, generated by our API.

personId

User identifier provided for the SDK.

sdkVersion

Sdk version in use.

iat

Token expiration.

The isAlive parameter is VERY IMPORTANT, as it dictates whether the validation process proceeds or halts. When isAlive: true, the user gains passage to continue their journey; conversely, if isAlive: false, the user is deemed invalid and access to further stages of the journey should be denied. This parameter plays a pivotal role in guiding the flow of operations.

Error cases

In the event of execution errors, you will receive an object of type SDKError. This object encompasses an enum containing the errorType, and a description.

SDKError (Class)

Property
Description

String description

Error description.

ErrorType errorType

Return the type of the error.

ErrorType (Enum class)

Error
Description

CAMERA_PERMISSION

Indicates that the device does not have permission to access the camera, either due to user denial or missing app permissions.

NETWORK_EXCEPTION

Indicates a network-related error, such as no internet connection, server timeouts, or network congestion.

SERVER_EXCEPTION

Indicates a server-side error, which may include server misconfigurations, processing failures, or service interruptions.

TOKEN_EXCEPTION

Indicates an issue with the provided authentication token, such as being invalid, expired, or lacking necessary permissions.

UNSUPPORTED_DEVICE

Indicates that the device hardware or software does not meet the minimum requirements for facial recognition.

MULTI_WINDOW_UNSUPPORTED_EXCEPTION

Indicates that the user attempted to use facial recognition in split-screen or multi-screen mode, which is not supported.

CAPTURE_ALREADY_ACTIVE_EXCEPTION

Indicates that a facial recognition capture is already in progress. A new capture cannot start until the current one completes.

CAMERA_EXCEPTION

Indicates an error occurred while acquiring or using the camera, typically when using external camera support.

FACE_DETECTOR_EXCEPTION

Indicates an error occurred with the face detector during the facial recognition process.

UNEXPECTED_ERROR_EXCEPTION

Indicates an unrecoverable error occurred during the facial recognition transaction.

INVALID_OPTIONS_EXCEPTION

Indicates an error occurred when applying the specified options for facial recognition.

CERTIFICATE_EXCEPTION

Indicates that there are no valid certificates for the proxy URL, preventing secure communication.

IMAGE_NOT_FOUND_EXCEPTION

Indicates that the image that has been captured couldn’t be found to be validated.

TOO_MANY_REQUESTS_EXCEPTION

Indicates that the server has received more requests than it’s prepared to handle.

Failure cases

In the event of execution failures, you will receive an object of type SDKFailure. This object encompasses an enum containing the failureType, description and a signedResponse.

FaceLivenessFailureResult (Class)

Property
Description

String signedResponse

Signed response from the CAF server confirming that the captured selfie has a real face. This parameter is used to get an extra layer of security, checking that the signature of the response is not broken, or caused by request interception. If it is broken, there is a strong indication of request interception.

String failureType

In case of a specific failure, return the error type.

String failureMessage

In case of a specific failure, return the instructions to avoid the error.

Failure Types

All failure reasons are exclusively returned in GPA liveness validation flows. In LA (Liveness Assurance) flows, any failure will consistently return the generic UNKNOWN error, regardless of the specific issue encountered.

FailureReason Value
Description (English)
LA
GPA

UNKNOWN

Try again

✅

✅

TOO_MUCH_MOVEMENT

Keep still

❌

✅

TOO_BRIGHT

Move somewhere darker

❌

✅

TOO_DARK

Move somewhere brighter

❌

✅

MISALIGNED_FACE

Keep your face in the oval

❌

✅

EYES_CLOSED

Keep your eyes open

❌

✅

FACE_TOO_FAR

Move your face closer to the screen

❌

✅

FACE_TOO_CLOSE

Move your face farther from the screen

❌

✅

SUNGLASSES

Remove sunglasses

❌

✅

OBSCURED_FACE

Remove any face coverings

❌

✅

MULTIPLE_FACES

Ensure only one person is visible

❌

✅

Last updated 14 hours ago

: Enables the integration of live facial verification technology.

: Provides fingerprint authentication capabilities to enhance security features in your app.

Usage token associated with your Identity account (see how to get it ).

At the end of a successful execution, you will receive an object of type . This object carries a signedResponse property containing a JWT token with the execution result. This token should be decrypted to obtain the execution results details.

Within the signedResponse, the parameter isAlive defines the execution of liveness, where true is approved and false is rejected ( will be returned).

iProov Biometrics Android
Fingerprint Pro Android
FaceLivenessResult
Failure case
here