PassiveFaceLiveness (Deprecated)

Smart camera that captures a reliable selfie of your user using artificial intelligence, capable of detecting and disapproving snapshots and recordings. Ideal for your onboarding.

SDK size

A maximum of about 3.5 MB, which may decrease because of these elements.

Analytics

Our SDKs by default collect information about the user and running environment to better map fraudsters and understand their behaviors. We recommend keeping this collection active as the only purpose of this data is for fraud reduction, but if you wish, you can disable it by .setAnalyticsSettings(boolean useAnalytics) parameter.

Runtime permissions

Permission Reason Required

Permission	Reason	Required
`CAMERA`	To capture the user selfie	Yes

CAMERA

To capture the user selfie

Yes

Instantiating the SDK

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

PassiveFaceLiveness mPassiveFaceLiveness = new PassiveFaceLiveness.Builder(String mobileToken)
    // see table below
    .build();

All parameters annotated with @Nullable can be given null values, useful if you want to set only one of the parameters of a single method.

Builder method

Parameter Required

Parameter	Required
`String mobileToken` Usage token associated with your CAF account.	Yes
`.setPersonId(String personId)` User identifier for the purpose of identifying fraudulent profiles and assisting in the identification of Analytics logs in cases of errors and bugs.	No, used for analytics
`.setAnalyticsSettings(boolean useAnalytics)` Enables/disables data collection for analytics.	No, the default is `true`
`.setStabilitySensorSettings(@Nullable SensorStabilitySettings sensorStabilitySettings)` Changes the default settings of the stability sensor, Apply null if you don't want to use this sensor.	No. The default time is 1500 ms and the default threshold is 0.7 m/s².
`.setLuminositySensorSettings(@Nullable SensorLuminositySettings sensorLuminositySettings)` Changes the default settings for the brightness sensor, Apply null if you don't want to use this sensor.	No. The default threshold is 3 lx
`.setOrientationSensorSettings(@Nullable SensorOrientationSettings sensorOrientationSettings)` Changes the default settings for the orientation sensor, Apply null if you don't want to use this sensor.	No. The standard threshold is 3 m/s².
`.setCaptureSettings(@Nullable CaptureSettings captureSettings)` Defines the capture settings. The method accepts instances of the ImageCapture and VideoCapture classes.	No. The default is `ImageCapture`
`.setShowButtonTime(int showButtonTime)` Changes the waiting time until the manual capture button is displayed.	No. The default is 15000 (milliseconds)
`.setLayout(@Nullable @LayoutRes Integer layoutId)` Replaces the default SDK layout. Create a file in your project's layout folder, copy this template and make the desired changes.	No. The pattern is this
`.setMask(MaskType type)` Defines the type of mask used in the captures. There are two types: `MaskType.DEFAULT`, with the dotted pattern on the face shape; `MaskType.NONE`, which completely removes the mask.	No. The defalut is `MaskType.DEFAULT`
`.setMask(@DrawableRes Integer greenMask, @DrawableRes Integer whiteMask, @DrawableRes Integer redMask)` Changes the face capture masks: SUCCESS, NORMAL, and FAIL, in that order. If you use this option, use masks with the same detection area as the face, this region is very important for the algorithm to capture.	No. The mask patterns are: Normal Success Failure
`.setStyle(@StyleRes int styleResourceId)` Replaces the SDK's default style. In your project's styles.xml file, copy this template and edit it.	No. The pattern is that.
`.setNetworkSettings(int requestTimeout)` Sets the timeout interval for SDK requests.	No. The default is 60 (seconds)
`.setProxySettings(@Nullable ProxySettings proxySettings)` Sets the proxy settings, as explained here.	No. The default is `null`
`.setPreviewSettings(@NonNull PreviewSettings previewSettings)` Habilita/desabilita e permite a configuração da visualização da captura realizada, solicitando a confirmação do usuário para prosseguir.	No. The default is disabled
`.setCurrentStepDoneDelay(boolean showDelay, int delay)` Delay the activity after the completion of each step. This method can be used to display a success message on the screen itself after the capture, for example.	No. The default is `false`
`.setMessageSettings(MessageSettings messageSettings)` Allows you to customize the messages displayed in the "status" balloon during the capture and analysis process.	No.
`.setPersonCPF(String personCPF)` It links an attempt at a proof of life to a CPF.	No, the default is `null`
`.setPersonName(String personName)` It ties an attempt at a proof of life to a name.	No, the default is `null`
`.enableSwitchCameraButton(boolean enable)` Enables/disables the button for the user to switch between the front and rear camera.	No, the default is `true`
`.enableGoogleServices(boolean enable)` Allows you to enable/disable features of the SDK that consume GoogleServices in the SDK, we do not recommend disabling the services because of the loss of security.	No, the default is `true`
`.setUseEmulator(boolean use)` Enables the use of emulators when `true`. When `true`, ADB mode is enabled together for the emulator to work correctly. It is not recommended to enable this option, use it for testing purposes only.	No, the default is `false`
`.setUseRoot(boolean use)` Allows the use of root devices when `true`.	No, the default is `false`
`.setUseDeveloperMode(boolean use)` Enables the use of developer mode when `true`. It is not recommended to enable this option, use it only for testing purposes.	No, the default is `false`
`.setUseAdb(boolean use)` Enables Android Debug Bridge (ADB) debugging mode when `true`. It is not recommended to enable this option, use it only for testing purposes.	No, the default is `false`
`.setUseDebug(boolean use)` Allows you to use the app in debug mode when `true`. It is not recommended to enable this option, use it only for testing purposes.	No, the default is `false`
`.setResolutionSettings(Resolution resolution)` Allows you to set the capture resolution. The method expects as parameter a `Resolution` that has the following options: `qHD`: 540x960 `HD`: 720x1280 `FULL_HD`: 1080x1920 `QUAD_HD`: 1440x2560 `ULTRA_HD`: 2160x3840	No. The default is `Resolution.ULTRA_HD`
`.setGetImageUrlExpireTime (String expireTime)` Sets the time the image URL will last on the server until it is expired. Expect to receive a time interval between "30m" to "30d". Examples: `setGetImageUrlExpireTime("30m")`: To set minutes only `setGetImageUrlExpireTime("24h")`: To set only hour(s) `setGetImageUrlExpireTime("1h 10m")`: To set hour(s) and minute(s) `setGetImageUrlExpireTime("10d")`: To set day(s)	No. The default is `3h`
`.setAudioSettings(boolean use)` Enables/disables playback of SDK audios.	No. The default is `true`
`.setAudioSettings(Integer audioResId)` It allows you to customize the audio used by the SDK.	No. The default is `"Registro Facial"`
`.enableBrightnessIncrease(boolean enable)` Enables/disables device brightness boost on opening the SDK. This feature increases proof-of-life security by reflecting screen captures and also aids in better detection and capture quality.	No. The default is `true`
`.setEyesClosedSettings(boolean enable, double threshold)` Allows you to customize the SDK's open-eye validation settings. The method expects a parameter `enable` to enable or disable validation, and `threshold`, a value between 0.0 and 1.0	No. The default is `true` and `0.5`
`.setStage(CafStage stage)` Allows you to choose the environment in wich the SDK will run (production, beta). The method takes as parameter an enum `CafStage` to select the environment:	No. The default is `CafStage.PROD`
Enum	Description
`CafStage.PROD`	Will use the Trust Platform production environment to register the SDK executions.
`CafStage.BETA`	Will use the Trust Platform beta environment to register the SDK executions.

String mobileToken

Usage token associated with your CAF account.

Yes

.setPersonId(String personId)

User identifier for the purpose of identifying fraudulent profiles and assisting in the identification of Analytics logs in cases of errors and bugs.

No, used for analytics

.setAnalyticsSettings(boolean useAnalytics)

Enables/disables data collection for analytics.

No, the default is true

.setStabilitySensorSettings(@Nullable SensorStabilitySettings sensorStabilitySettings)

Changes the default settings of the stability sensor, Apply null if you don't want to use this sensor.

No. The default time is 1500 ms and the default threshold is 0.7 m/s².

.setLuminositySensorSettings(@Nullable SensorLuminositySettings sensorLuminositySettings)

Changes the default settings for the brightness sensor, Apply null if you don't want to use this sensor.

No. The default threshold is 3 lx

.setOrientationSensorSettings(@Nullable SensorOrientationSettings sensorOrientationSettings)

Changes the default settings for the orientation sensor, Apply null if you don't want to use this sensor.

No. The standard threshold is 3 m/s².

.setCaptureSettings(@Nullable CaptureSettings captureSettings)

Defines the capture settings. The method accepts instances of the ImageCapture and VideoCapture classes.

No. The default is ImageCapture

.setShowButtonTime(int showButtonTime)

Changes the waiting time until the manual capture button is displayed.

No. The default is 15000 (milliseconds)

.setLayout(@Nullable @LayoutRes Integer layoutId)

Replaces the default SDK layout. Create a file in your project's layout folder, copy this template and make the desired changes.

No. The pattern is this

.setMask(MaskType type)

Defines the type of mask used in the captures. There are two types:

MaskType.DEFAULT, with the dotted pattern on the face shape;
MaskType.NONE, which completely removes the mask.

No. The defalut is MaskType.DEFAULT

.setMask(@DrawableRes Integer greenMask, @DrawableRes Integer whiteMask, @DrawableRes Integer redMask)

Changes the face capture masks: SUCCESS, NORMAL, and FAIL, in that order. If you use this option, use masks with the same detection area as the face, this region is very important for the algorithm to capture.

No. The mask patterns are:

Normal

Success

Failure

.setStyle(@StyleRes int styleResourceId)

Replaces the SDK's default style. In your project's styles.xml file, copy this template and edit it.

No. The pattern is that.

.setNetworkSettings(int requestTimeout)

Sets the timeout interval for SDK requests.

No. The default is 60 (seconds)

.setProxySettings(@Nullable ProxySettings proxySettings)

Sets the proxy settings, as explained here.

No. The default is null

.setPreviewSettings(@NonNull PreviewSettings previewSettings)

Habilita/desabilita e permite a configuração da visualização da captura realizada, solicitando a confirmação do usuário para prosseguir.

No. The default is disabled

.setCurrentStepDoneDelay(boolean showDelay, int delay)

Delay the activity after the completion of each step. This method can be used to display a success message on the screen itself after the capture, for example.

No. The default is false

.setMessageSettings(MessageSettings messageSettings)

Allows you to customize the messages displayed in the "status" balloon during the capture and analysis process.

No.

.setPersonCPF(String personCPF)

It links an attempt at a proof of life to a CPF.

No, the default is null

.setPersonName(String personName)

It ties an attempt at a proof of life to a name.

No, the default is null

.enableSwitchCameraButton(boolean enable)

Enables/disables the button for the user to switch between the front and rear camera.

No, the default is true

.enableGoogleServices(boolean enable)

Allows you to enable/disable features of the SDK that consume GoogleServices in the SDK, we do not recommend disabling the services because of the loss of security.

No, the default is true

.setUseEmulator(boolean use)

Enables the use of emulators when true. When true, ADB mode is enabled together for the emulator to work correctly. It is not recommended to enable this option, use it for testing purposes only.

No, the default is false

.setUseRoot(boolean use)

Allows the use of root devices when true.

No, the default is false

.setUseDeveloperMode(boolean use)

Enables the use of developer mode when true. It is not recommended to enable this option, use it only for testing purposes.

No, the default is false

.setUseAdb(boolean use)

Enables Android Debug Bridge (ADB) debugging mode when true. It is not recommended to enable this option, use it only for testing purposes.

No, the default is false

.setUseDebug(boolean use)

Allows you to use the app in debug mode when true. It is not recommended to enable this option, use it only for testing purposes.

No, the default is false

.setResolutionSettings(Resolution resolution)

Allows you to set the capture resolution. The method expects as parameter a Resolution that has the following options:

qHD: 540x960
HD: 720x1280
FULL_HD: 1080x1920
QUAD_HD: 1440x2560
ULTRA_HD: 2160x3840

No. The default is Resolution.ULTRA_HD

.setGetImageUrlExpireTime (String expireTime)

Sets the time the image URL will last on the server until it is expired. Expect to receive a time interval between "30m" to "30d".

Examples:

setGetImageUrlExpireTime("30m"): To set minutes only
setGetImageUrlExpireTime("24h"): To set only hour(s)
setGetImageUrlExpireTime("1h 10m"): To set hour(s) and minute(s)
setGetImageUrlExpireTime("10d"): To set day(s)

No. The default is 3h

.setAudioSettings(boolean use)

Enables/disables playback of SDK audios.

No. The default is true

.setAudioSettings(Integer audioResId)

It allows you to customize the audio used by the SDK.

No. The default is "Registro Facial"

.enableBrightnessIncrease(boolean enable)

Enables/disables device brightness boost on opening the SDK. This feature increases proof-of-life security by reflecting screen captures and also aids in better detection and capture quality.

No. The default is true

.setEyesClosedSettings(boolean enable, double threshold)

Allows you to customize the SDK's open-eye validation settings. The method expects a parameter enable to enable or disable validation, and threshold, a value between 0.0 and 1.0

No. The default is true and 0.5

.setStage(CafStage stage)

Allows you to choose the environment in wich the SDK will run (production, beta). The method takes as parameter an enum CafStage to select the environment:

No. The default is CafStage.PROD

Enum

Description

CafStage.PROD

Will use the Trust Platform production environment to register the SDK executions.

CafStage.BETA

Will use the Trust Platform beta environment to register the SDK executions.

Each environment (beta and production) requires its own specific mobileToken, generated in the Trust platform of the respective environment.

MessageSettings

To use it, simply instantiate a MessageSettings object and use the methods as needed to customize the messages.

Method Default value

Method	Default value
`.setFaceNotFoundMessage(@NonNull @StringRes Integer message)` Message displayed when the algorithm does not recognize a face.	"Não encontramos nenhum rosto"
`.setFaceNotFittedMessage(@NonNull @StringRes Integer message)` Message displayed when the face is not fitted correctly to the mask.	"Encaixe seu rosto"
`.setFaceTooFarMessage(@NonNull @StringRes Integer message)` Message displayed when the user's face is too far away.	"Aproxime o rosto"
`.setFaceTooCloseMessage(@NonNull @StringRes Integer message)` Message displayed when the user's face is too close to the camera.	"Afaste o rosto"
`.setMultipleFaceDetectedMessage(@NonNull @StringRes Integer message)` Message displayed when more than one face is detected.	"Mais de um rosto detectado"
`.setHoldItMessage(@NonNull @StringRes Integer message)` Message displayed when the user is in the correct position for capture.	"Segure assim"
`.setVerifyingLivenessMessage(@NonNull @StringRes Integer message)` Message displayed during proof-of-life check.	"Verificando selfie…"
`.setInvalidFaceMessage(@NonNull @StringRes Integer message)` Message displayed when the proof-of-life check refuses the selfie.	"Não conseguimos capturar seu rosto. Tente novamente."
`.setEyesClosedMessage(@NonNull @StringRes Integer message)` Message displayed when both eyes are closed.	"Não use óculos escuros e mantenha os olhos abertos"
`.setNotCenterXMessage(@NonNull @StringRes Integer message)` Message displayed when the face is tilted to the X-axis (up or down).	"Centralize seu rosto na vertical"
`.setNotCenterYMessage(@NonNull @StringRes Integer message)` Message displayed when the face is tilted to the X-axis (left or right side).	"Centralize seu rosto na horizontal"
`.setNotCenterZMessage(@NonNull @StringRes Integer message)` Message displayed when the face is tilted to the Z-axis (rotated face).	"Ajuste seu rosto à mascara"
`.setWaitMessage(boolean show, @Nullable Integer message)` Message displayed when you start the camera.	"Aguarde..."
`.setSensorLuminosityMessage(@NonNull @StringRes Integer message)` Message displayed when the brightness threshold is lower than expected.	"Ambiente muito escuro"
`.setSensorOrientationMessage(@NonNull @StringRes Integer message)` Message displayed when the orientation threshold is lower than expected.	"Celular não está na vertical"
`.setSensorStabilityMessage(@NonNull @StringRes Integer message)` Message displayed when the orientation threshold is lower than expected.	"Mantenha o celular parado"
`.setCaptureProcessingErrorMessage(@NonNull @StringRes Integer message)` Message displayed when there is a processing problem or error in the API response.	"Ops, tivemos um problema ao processar sua imagem. Tente novamente."

.setFaceNotFoundMessage(@NonNull @StringRes Integer message)

Message displayed when the algorithm does not recognize a face.

"Não encontramos nenhum rosto"

.setFaceNotFittedMessage(@NonNull @StringRes Integer message)

Message displayed when the face is not fitted correctly to the mask.

"Encaixe seu rosto"

.setFaceTooFarMessage(@NonNull @StringRes Integer message)

Message displayed when the user's face is too far away.

"Aproxime o rosto"

.setFaceTooCloseMessage(@NonNull @StringRes Integer message)

Message displayed when the user's face is too close to the camera.

"Afaste o rosto"

.setMultipleFaceDetectedMessage(@NonNull @StringRes Integer message)

Message displayed when more than one face is detected.

"Mais de um rosto detectado"

.setHoldItMessage(@NonNull @StringRes Integer message)

Message displayed when the user is in the correct position for capture.

"Segure assim"

.setVerifyingLivenessMessage(@NonNull @StringRes Integer message)

Message displayed during proof-of-life check.

"Verificando selfie…"

.setInvalidFaceMessage(@NonNull @StringRes Integer message)

Message displayed when the proof-of-life check refuses the selfie.

"Não conseguimos capturar seu rosto. Tente novamente."

.setEyesClosedMessage(@NonNull @StringRes Integer message)

Message displayed when both eyes are closed.

"Não use óculos escuros e mantenha os olhos abertos"

.setNotCenterXMessage(@NonNull @StringRes Integer message)

Message displayed when the face is tilted to the X-axis (up or down).

"Centralize seu rosto na vertical"

.setNotCenterYMessage(@NonNull @StringRes Integer message)

Message displayed when the face is tilted to the X-axis (left or right side).

"Centralize seu rosto na horizontal"

.setNotCenterZMessage(@NonNull @StringRes Integer message)

Message displayed when the face is tilted to the Z-axis (rotated face).

"Ajuste seu rosto à mascara"

.setWaitMessage(boolean show, @Nullable Integer message)

Message displayed when you start the camera.

"Aguarde..."

.setSensorLuminosityMessage(@NonNull @StringRes Integer message)

Message displayed when the brightness threshold is lower than expected.

"Ambiente muito escuro"

.setSensorOrientationMessage(@NonNull @StringRes Integer message)

Message displayed when the orientation threshold is lower than expected.

"Celular não está na vertical"

.setSensorStabilityMessage(@NonNull @StringRes Integer message)

Message displayed when the orientation threshold is lower than expected.

"Mantenha o celular parado"

.setCaptureProcessingErrorMessage(@NonNull @StringRes Integer message)

Message displayed when there is a processing problem or error in the API response.

"Ops, tivemos um problema ao processar sua imagem. Tente novamente."

Example

MessageSettings messageSettings = new MessageSetings()
.setFaceNotFoundMessage(R.string.exempleFacenoajatFound)
.setFaceTooFarMessage(R.string.exempleFaceTooFar);

Security validations

We are constantly taking actions to make the product more and more secure, mitigating a number of attacks observed in the capture process and, consequently, reducing as many possible identity frauds as possible. The SDK has some blocks that may prevent its execution in certain contexts. To disable them, you can use the methods as shown in the example below:

PassiveFaceLiveness.Builder("mobileToken")
    .setUseEmulator(true)
    .setUseRoot(true)
    .setUseDeveloperMode(true)
    .setUseAdb(true)
    .setUseDebug(true)
    .build();

Disabling security validations is recommended for testing purposes only. For publishing your application in production, we recommend using the default settings.

Starting Activity

After creating the PassiveFaceLiveness, start the PassiveFaceLivenessActivity by passing this object as a parameter via extra intent:

Intent mIntent = new Intent(context, PassiveFaceLivenessActivity.class);
mIntent.putExtra(PassiveFaceLiveness.PARAMETER_NAME, mPassiveFaceLiveness);
startActivityForResult(mIntent, REQUEST_CODE);

Getting the result

To get the PassiveFaceLivenessResult object, which contains the captures taken by the SDK, override the onActivityResult method in the same activity that you started the PassiveFaceLivenessActivity:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == REQUEST_CODE){
        if (resultCode == RESULT_OK && data != null) {
            PassiveFaceLivenessResult mPassiveFaceLivenessResult = (PassiveFaceLivenessResult) data.getSerializableExtra(PassiveFaceLivenessResult.PARAMETER_NAME);
            // verifique mPassiveFaceLivenessResult.getSDKFailure() para descobrir qual foi o motivo da finalização do SDK
        } else {
            // o usuário fechou a activity
        }
    }
    super.onActivityResult(requestCode, resultCode, data);
}

PassiveFaceLivenessResult

Parameter Allow null

Parameter	Allow null
`String capturePath` Full path of the image or video on the user's device.	Yes, in case of error
`String imagePath` Full path of the image on the user's device.	Yes, in case of error
`String imageUrl` URL of the selfie on the CAF server.	Yes, in case of error
`String signedResponse` Signed response from the CAF server confirming that the captured selfie has a real face (not a photo or video). Use this parameter if you want 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.	Yes, in case of error or server unavailability
`String trackingId` Identifier of this execution on our servers. If possible, save this field and send it along to our API. This way we will have more data on how the user behaved during the execution.	Yes, if the user sets `useAnalytics = false` or the analytics calls do not work
`SDKFailure sdkFailure` Object that tells you the reason for the SDK shutdown. For more information, see here	Yes, in case of success
`lensFacing: Int` Defines the face of the camera that was used. Use `PassiveFaceLivenessResult.LENS_FACING_FRONT` or `PassiveFaceLivenessResult.LENS_FACING_FRONT` to validate.	No

String capturePath

Full path of the image or video on the user's device.

Yes, in case of error

String imagePath

Full path of the image on the user's device.

Yes, in case of error

String imageUrl

URL of the selfie on the CAF server.

Yes, in case of error

String signedResponse

Signed response from the CAF server confirming that the captured selfie has a real face (not a photo or video). Use this parameter if you want 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.

Yes, in case of error or server unavailability

String trackingId

Identifier of this execution on our servers. If possible, save this field and send it along to our API. This way we will have more data on how the user behaved during the execution.

Yes, if the user sets useAnalytics = false or the analytics calls do not work

SDKFailure sdkFailure

Object that tells you the reason for the SDK shutdown. For more information, see here

Yes, in case of success

lensFacing: Int

Defines the face of the camera that was used. Use PassiveFaceLivenessResult.LENS_FACING_FRONT or PassiveFaceLivenessResult.LENS_FACING_FRONT to validate.

Last updated 7 months ago