FaceLiveness

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

3.2.3

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

iProov Biometrics Android: Enables the integration of live facial verification technology.
Fingerprint Pro Android: Provides fingerprint authentication capabilities to enhance security features in your app.

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 'com.combateafraude.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

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

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 faceLivenessResult) {

    }

    @Override
    public void onError(SDKFailure sdkFailure) {

    }

    @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.

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.

FaceLivenessResult

Success

Return

Reason

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, based on this validation, the user can be guided to continue the flow or not. In case of isAlive: true, it would be able to continue with the journey. If isAlive: false, this user is not valid and should be prevented from continuing their journey.

Error

Return

Reason

String errorMessage

In case of any error, return the error.

SDKFailure sdkFailure

In case of a specific error, return the instance of the error.

SDKFailure

Return

Reason

String description

Error description.

ErrorType errorType

Return the type of the error.

ErrorType

type

Description

CAMERA_PERMISSION

Indicates that the device does not have permission to access the camera. This error typically occurs when the user denies access to the camera or if the app lacks the necessary permissions.

NETWORK_EXCEPTION

Indicates a network-related error occurred. This error may occur due to various network issues such as a lack of internet connection, server timeouts, or network congestion.

SERVER_EXCEPTION

Indicates an exception occurred on the server-side.<br. />This error is typically returned when there is an issue with the server processing the facial recognition request. This could include server-side errors, misconfigurations, or service interruptions.

TOKEN_EXCEPTION

Indicates an issue with the provided token. This error may occur if the provided authentication token is invalid, expired, or lacks the necessary permissions to perform facial recognition tasks.

UNSUPPORTED_DEVICE

Indicates that the device is not supported. This error may occur if the device hardware or software does not meet the minimum requirements for facial recognition functionality.

CERTIFICATE_EXCEPTION

Indicates an exception occurred on certificate pinning. This error may occur when the provided certificates on the reverse proxy implementation are not right.

Last updated 3 days ago