Native Integration

To import our SDKs, it is necessary to make changes to the Project and Application build.gradle.

Adding to Project

Add our maven repository address to the project's build.gradle (in Android Studio this file appears as: "Project: {project_name}"), as shown in the example below.

buildscript {
    ...
}

allprojects {
    repositories {
        ...
        maven { url 'https://sdks.zaig.com.br/' }
    }
}

Adding to Application

After that, add the library you want to import to your app's build.gradle (in Android Studio this file appears as: "Module: {project_name}.app"), including the dependency shown below.

android {
    ...
}
...
dependencies {
    ...
    implementation 'com.zaig.android:facerecon:v5.2.1'
}

warning

Since April 2025, new Google Play policies require Android API Level 35 for applications to be published or updated on the Google Play Store. Therefore, we strongly recommend using targetSdkVersion version 35 at least.

info

Using targetSdkVersion 35 implies using compileSdkVersion 35, which triggers some minimum requirements for tools in the Android ecosystem:

compileSdkVersion 35 --> AGP 8.6.0
AGP 8.6.0 --> Gradle 8.7
AGP 8.6.0 --> Java 17 (JDK 17)
AGP 8.6.0 --> Kotlin 2+

Starting the SDK

Important Warning!

Starting from version 5.0.0, the authentication system has been updated to use clientSessionKey instead of mobileToken. In addition, new configuration options have been added for feedback screens.

Obtaining the Client Session Key

Before configuring the SDK, you must generate a temporary clientSessionKey through a server-to-server request to our face recognition API.

Endpoint

Environment	URL
Sandbox	`https://api.sandbox.zaig.com.br/face_recognition/client_session`
Production	`https://api.zaig.com.br/face_recognition/client_session`

Request

Method: POST

Headers:

{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}

Body (Optional, but recommended):

{
  "user_id": "unique_user_identifier"
}

Important: The user_id field is highly recommended for security and anti-fraud measures. Use a unique identifier for your application's user.

Response

The successful response will contain the client_session_key that should be passed to the SDK configuration.

{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

To incorporate the SDK into your application, you must configure your custom capture application through a Builder component and submit it as a parameter via Intent Extra to FaceReconActivity.

SDK initialization example

  Intent intent = new Intent(getApplicationContext(), FaceReconActivity.class);

  VisualConfiguration visualConfiguration = new VisualConfiguration()
          .setOnboardingDrawable(R.drawable.introscreen,500);

  TextConfiguration textConfiguration = new TextConfiguration()
          .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "To take a good photo:")
          .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Go to a well-lit place")
          .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Remove accessories and show your face clearly")
          .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insert your face into the frame, waiting for it to turn green to capture");

  FaceRecognition mFaceRecognition = new FaceRecognition.Builder(clientSessionKey)
          .showIntroductionScreens(true)
          .setVisualConfiguration(visualConfiguration)
          .setTextConfiguration(textConfiguration)
          .setBackgroundColor("#000000")
          .setFontColor("#FFFFFF")
          .setFontFamily(FaceRecognition.FontFamily.futura)
          .setSessionId("SESSION_ID")
          .setLogLevel(FaceRecognition.LogLevel.debug)
          .setShowSuccessScreen(false)
          .build();
  intent.putExtra("settings", mFaceRecognition);
  startActivityForResult(intent, REQUEST_CODE);

FaceRecognition.Builder

Parameter	Function	Required
clientSessionKey	Client key that identifies that the collected data comes from your application. Obtained through a request to the Face Recognition API	Yes.
.setSandboxEnvironment()	If this parameter is used in the constructor, the library will be configured to send data to the sandbox environment. If absent, requests are sent to the production environment.	No.
.showIntroductionScreens(Boolean showIntroductionScreens)	When "false" disables the introduction screens for photo capture that appear to the user.	No. Default is "true".
.setShowSuccessScreen(Boolean showSuccessScreen)	When "false" disables the success screen after photo capture.	No. Default is "true".
.setShowInvalidTokenScreen(Boolean showSuccessScreen)	When "false" disables the authentication failure screen.	No. Default is "true".
.setBackgroundColor(String backgroundColor)	Allows configuration of the background color of the SDK activities.	No. Default is "#ffffff".
.setFontColor(String fontColor)	Allows configuration of the font and icon color of the SDK activities.	No. Default is "#000000".
.setFontFamily(FontFamily fontFamily)	Allows configuration of the font of the SDK activities.	No. If not specified, the default is FontFamily.open_sans. Available fonts: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins and FontFamily.helvetica.
.activeFaceLiveness(Boolean activeFaceLiveness)	Indicates whether the SDK should perform a user selfie capture procedure or active proof of life.	No. Default is false.
.audioConfiguration(AudioConfiguration audioConfiguration)	Indicates whether the SDK should or should not execute indication audios for the user. Accepted configurations are AudioConfiguration.enable which executes indication audios, AudioConfiguration.disable which does not execute these audios and AudioConfiguration.accessibility which executes audios if the user's device has accessibility settings enabled.	No. Default is AudioConfiguration.disable.
.setVisualConfiguration(VisualConfiguration visualConfiguration)	Used to customize the images shown to the user throughout the SDK execution.	No.
.setTextConfiguration(TextConfiguration textConfiguration)	Used to customize the introductory onboarding screen texts shown to the user throughout the SDK execution.	No.
.setSessionId(String sessionId)	Used to define the key that identifies the session started in the SDK. It is used to track the entire flow taken by the user in the FaceRecon execution through logs. This field accepts up to 255 characters.	No.
.setLogLevel(FaceRecognition.LogLevel logLevel)	Used to customize the verbosity level of the SDK logs. Available levels: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error and LogLevel.trace. Default is LogLevel.debug.	No.
.setDocumentNumber(String documentNumber)	Used to define the user's document number. This field accepts 14 characters.	Only for calls that use 1:1 validation at some point.
.setValidation(Boolean validation)	Used to define whether the SDK should or should not perform 1:1 validation with the user's selfie. In the user's first session this flag must be, mandatorily, false. This function requires the setDocumentNumber method to be filled.	No. Default is false.

The VisualConfiguration Object

Parameter	Function	Required
.setOnboardingDrawable(int onboarding_drawable, int onboarding_width)	Used to configure the image shown to the user on the SDK onboarding screen. The onboarding_drawable parameter should reference the id of the image to be shown and onboarding_width is the desired display size of this image.	No.
.setButtonBorderSize(int border_size)	Used to configure the border width of the SDK buttons.	No. Default is 1.
.setButtonShadow(boolean button_shadow)	When set to false removes the shadow effect, default on android, used by the SDK buttons.	No. Default is true.

The TextConfiguration Object

Parameter	Function	Required
.setCustomText(CustomLabel label, String text)	Used to configure the texts shown to the user on the SDK onboarding screen	No.

Previous Versions

Starting the SDK

  Intent intent = new Intent(getApplicationContext(), FaceReconActivity.class);

  VisualConfiguration visualConfiguration = new VisualConfiguration()
          .setOnboardingDrawable(R.drawable.introscreen,500);

  TextConfiguration textConfiguration = new TextConfiguration()
          .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "To take a good photo:")
          .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Go to a well-lit place")
          .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Remove accessories and show your face clearly")
          .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insert your face into the frame, waiting for it to turn green to capture");

  FaceRecognition mFaceRecognition = new FaceRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
          .showIntroductionScreens(true)
          .setVisualConfiguration(visualConfiguration)
          .setTextConfiguration(textConfiguration)
          .setBackgroundColor("#000000")
          .setFontColor("#FFFFFF")
          .setFontFamily(FaceRecognition.FontFamily.futura)
          .setSessionId("SESSION_ID")
          .setLogLevel(FaceRecognition.LogLevel.debug)
          .setShowSuccessScreen(false)
          .build();
  intent.putExtra("settings", mFaceRecognition);
  startActivityForResult(intent, REQUEST_CODE);

We use a Mobile Token to allow authenticated access from your application to our API. It has probably already been sent to you by email. If you have not yet received your token, send an email to suporte.caas@qitech.com.br.

Our API expects to receive the Mobile Token in all requests to our server from the SDK, therefore, it must be included as a configuration parameter through the method mentioned above.

Attention

You must replace"YOUR_MOBILE_TOKEN_SENT_BY_QITECH" with the Mobile Token received from support.

FaceRecognition.Builder

Parameter	Function	Required
mobileToken	Client key that identifies that the collected data comes from your application. If you have not yet received your mobile-token, contact suporte.caas@qitech.com.br.	Yes.
.setSandboxEnvironment()	If this parameter is used in the constructor, the library will be configured to send data to the sandbox environment. If absent, requests are sent to the production environment.	No.
.showIntroductionScreens(Boolean showIntroductionScreens)	When "false" disables the introduction screens for photo capture that appear to the user.	No. Default is "true".
.setShowSuccessScreen(Boolean showSuccessScreen)	When "false" disables the success screen after photo capture.	No. Default is "true".
.setBackgroundColor(String backgroundColor)	Allows configuration of the background color of the SDK activities.	No. Default is "#ffffff".
.setFontColor(String fontColor)	Allows configuration of the font and icon color of the SDK activities.	No. Default is "#000000".
.setFontFamily(FontFamily fontFamily)	Allows configuration of the font of the SDK activities.	No. If not specified, the default is FontFamily.open_sans. Available fonts: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins and FontFamily.helvetica.
.activeFaceLiveness(Boolean activeFaceLiveness)	Indicates whether the SDK should perform a user selfie capture procedure or active proof of life.	No. Default is false.
.audioConfiguration(AudioConfiguration audioConfiguration)	Indicates whether the SDK should or should not execute indication audios for the user. Accepted configurations are AudioConfiguration.enable which executes indication audios, AudioConfiguration.disable which does not execute these audios and AudioConfiguration.accessibility which executes audios if the user's device has accessibility settings enabled.	No. Default is AudioConfiguration.disable.
.setVisualConfiguration(VisualConfiguration visualConfiguration)	Used to customize the images shown to the user throughout the SDK execution.	No.
.setTextConfiguration(TextConfiguration textConfiguration)	Used to customize the introductory onboarding screen texts shown to the user throughout the SDK execution.	No.
.setSessionId(String sessionId)	Used to define the key that identifies the session started in the SDK. It is used to track the entire flow taken by the user in the FaceRecon execution through logs. This field accepts up to 255 characters.	No.
.setLogLevel(FaceRecognition.LogLevel logLevel)	Used to customize the verbosity level of the SDK logs. Available levels: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error and LogLevel.trace. Default is LogLevel.debug.	No.
.setDocumentNumber(String documentNumber)	Used to define the user's document number. This field accepts 14 characters.	Only for calls that use 1:1 validation at some point.
.setValidation(Boolean validation)	Used to define whether the SDK should or should not perform 1:1 validation with the user's selfie. In the user's first session this flag must be, mandatorily, false. This function requires the setDocumentNumber method to be filled.	No. Default is false.

Native Integration

Adding to Project​

Adding to Application​

Starting the SDK​

Obtaining the Client Session Key​

Endpoint​

Request​

Response​

SDK initialization example​

FaceRecognition.Builder​

The VisualConfiguration Object​

The TextConfiguration Object​

Previous Versions​

Starting the SDK​

FaceRecognition.Builder​

Adding to Project

Adding to Application

Starting the SDK

Obtaining the Client Session Key

Endpoint

Request

Response

SDK initialization example

FaceRecognition.Builder

The VisualConfiguration Object

The TextConfiguration Object

Previous Versions

Starting the SDK

FaceRecognition.Builder