Links

PassiveFaceLiveness

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
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
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
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
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
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
Allows you to customize the messages displayed in the "status" balloon during the capture and analysis process.
No. The pattern is this
.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

MessageSettings

To use it, simply instantiate a MessageSettings object and use the methods as needed to customize the messages.
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."
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
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
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