原生集成

要导入我们的 SDK，需要修改项目和应用程序的 build.gradle 文件。

添加到项目

在项目的 build.gradle 中添加我们的 Maven 仓库地址（在 Android Studio 中，该文件显示为："Project: {project_name}"），如下例所示。

buildscript {
    ...
}

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

添加到应用程序

之后，在应用程序的 build.gradle 中添加您要导入的库（在 Android Studio 中，该文件显示为："Module: {project_name}.app"），包含以下依赖项。

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

注意

自 2025 年 4 月起，Google Play 的新政策要求应用程序必须使用 Android API Level 35 才能在 Google Play Store 上发布或更新。因此，我们强烈建议至少使用 targetSdkVersion 35。

信息

使用 targetSdkVersion 35 意味着使用 compileSdkVersion 35，这对 Android 生态系统工具有一些最低要求：

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+

启动 SDK

重要提示！

从版本 5.0.0 起，认证系统已更新，使用 clientSessionKey 代替 mobileToken。此外，还添加了新的反馈屏幕配置选项。

获取 Client Session Key

在配置 SDK 之前，您必须通过服务器到服务器的请求向我们的人脸识别 API 生成一个临时的 clientSessionKey。

端点

环境	URL
沙盒	`https://api.sandbox.zaig.com.br/face_recognition/client_session`
生产	`https://api.zaig.com.br/face_recognition/client_session`

请求

Method: POST

Headers:

{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}

Body（可选，但推荐）：

{
  "user_id": "unique_user_identifier"
}

重要： user_id 字段强烈建议用于安全和反欺诈措施。请使用您应用程序中用户的唯一标识符。

响应

成功响应将包含需要传递给 SDK 配置的 client_session_key。

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

要将 SDK 嵌入到您的应用程序中，您必须通过 Builder 组件配置自定义采集应用程序，并通过 Intent Extra 作为参数提交给 FaceReconActivity。

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, "Para tirar uma boa foto:")
          .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
          .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire adereços e mostre bem o rosto")
          .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu rosto na moldura, aguardando que fique verde para realizar a captura");

  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

参数	功能	是否必填
clientSessionKey	客户密钥，用于标识收集的数据来源于您的应用程序。通过向 Face Recognition API 发送请求获取。	是。
.setSandboxEnvironment()	若在构造函数中使用此参数，库将配置为向沙盒环境发送数据。若不存在，请求将发送到生产环境。	否。
.showIntroductionScreens(Boolean showIntroductionScreens)	设置为 "false" 时，禁用向用户显示的照片采集介绍屏幕。	否。默认值为 "true"。
.setShowSuccessScreen(Boolean showSuccessScreen)	设置为 "false" 时，禁用照片采集后的成功屏幕。	否。默认值为 "true"。
.setShowInvalidTokenScreen(Boolean showSuccessScreen)	设置为 "false" 时，禁用认证失败屏幕。	否。默认值为 "true"。
.setBackgroundColor(String backgroundColor)	允许配置 SDK activities 的背景颜色。	否。默认值为 "#ffffff"。
.setFontColor(String fontColor)	允许配置 SDK activities 的字体和图标颜色。	否。默认值为 "#000000"。
.setFontFamily(FontFamily fontFamily)	允许配置 SDK activities 的字体。	否。若未指定，默认为 FontFamily.open_sans。可用字体：FontFamily.open_sans、FontFamily.futura、FontFamily.verdana、FontFamily.roboto、FontFamily.poppins 和 FontFamily.helvetica。
.activeFaceLiveness(Boolean activeFaceLiveness)	指示 SDK 是否执行用户自拍采集或主动活体检测程序。	否。默认值为 false。
.audioConfiguration(AudioConfiguration audioConfiguration)	指示 SDK 是否为用户播放提示音频。接受的配置为 AudioConfiguration.enable（播放提示音频）、AudioConfiguration.disable（不播放音频）和 AudioConfiguration.accessibility（当用户设备启用了无障碍配置时播放音频）。	否。默认值为 AudioConfiguration.disable。
.setVisualConfiguration(VisualConfiguration visualConfiguration)	用于自定义 SDK 执行过程中向用户显示的图片。	否。
.setTextConfiguration(TextConfiguration textConfiguration)	用于自定义 SDK 执行过程中向用户显示的引导屏幕上的文本。	否。
.setSessionId(String sessionId)	用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 FaceRecon 执行过程中的完整流程。此字段最多接受 255 个字符。	否。
.setLogLevel(FaceRecognition.LogLevel logLevel)	用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。默认为 LogLevel.debug。	否。
.setDocumentNumber(String documentNumber)	用于设置用户的文档号码。此字段接受 14 个字符。	仅适用于某次调用使用了 1:1 验证的情况。
.setValidation(Boolean validation)	用于定义 SDK 是否对用户的自拍照执行 1:1 验证。在用户的第一次会话中，此标志必须为 false。此功能需要填写 setDocumentNumber 方法。	否。默认值为 false。

VisualConfiguration 对象

参数	功能	是否必填
.setOnboardingDrawable(int onboarding_drawable, int onboarding_width)	用于配置在 SDK 引导屏幕上向用户显示的图片。参数 onboarding_drawable 应引用要显示的图片 ID，onboarding_width 是该图片的预期显示尺寸。	否。
.setButtonBorderSize(int border_size)	用于配置 SDK 按钮的边框宽度。	否。默认值为 1。
.setButtonShadow(boolean button_shadow)	设置为 false 时，移除 SDK 按钮使用的 Android 默认阴影效果。	否。默认值为 true。

TextConfiguration 对象

参数	功能	是否必填
.setCustomText(CustomLabel label, String text)	用于配置在 SDK 引导屏幕上向用户显示的文本	否。

旧版本

启动 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, "Para tirar uma boa foto:")
          .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
          .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire adereços e mostre bem o rosto")
          .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu rosto na moldura, aguardando que fique verde para realizar a captura");

  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);

我们使用 Mobile Token 来允许您的应用程序对我们的 API 进行认证访问。它可能已通过电子邮件发送给您。如果您尚未收到 token，请发送电子邮件至 suporte.caas@qitech.com.br。

我们的 API 期望在所有来自 SDK 的请求中接收 Mobile Token，因此必须通过上述方法将其作为配置参数包含在内。

注意

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。

FaceRecognition.Builder

参数	功能	是否必填
mobileToken	客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 mobile-token，请联系 suporte.caas@qitech.com.br。	是。
.setSandboxEnvironment()	若在构造函数中使用此参数，库将配置为向沙盒环境发送数据。若不存在，请求将发送到生产环境。	否。
.showIntroductionScreens(Boolean showIntroductionScreens)	设置为 "false" 时，禁用向用户显示的照片采集介绍屏幕。	否。默认值为 "true"。
.setShowSuccessScreen(Boolean showSuccessScreen)	设置为 "false" 时，禁用照片采集后的成功屏幕。	否。默认值为 "true"。
.setBackgroundColor(String backgroundColor)	允许配置 SDK activities 的背景颜色。	否。默认值为 "#ffffff"。
.setFontColor(String fontColor)	允许配置 SDK activities 的字体和图标颜色。	否。默认值为 "#000000"。
.setFontFamily(FontFamily fontFamily)	允许配置 SDK activities 的字体。	否。若未指定，默认为 FontFamily.open_sans。可用字体：FontFamily.open_sans、FontFamily.futura、FontFamily.verdana、FontFamily.roboto、FontFamily.poppins 和 FontFamily.helvetica。
.activeFaceLiveness(Boolean activeFaceLiveness)	指示 SDK 是否执行用户自拍采集或主动活体检测程序。	否。默认值为 false。
.audioConfiguration(AudioConfiguration audioConfiguration)	指示 SDK 是否为用户播放提示音频。接受的配置为 AudioConfiguration.enable（播放提示音频）、AudioConfiguration.disable（不播放音频）和 AudioConfiguration.accessibility（当用户设备启用了无障碍配置时播放音频）。	否。默认值为 AudioConfiguration.disable。
.setVisualConfiguration(VisualConfiguration visualConfiguration)	用于自定义 SDK 执行过程中向用户显示的图片。	否。
.setTextConfiguration(TextConfiguration textConfiguration)	用于自定义 SDK 执行过程中向用户显示的引导屏幕上的文本。	否。
.setSessionId(String sessionId)	用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 FaceRecon 执行过程中的完整流程。此字段最多接受 255 个字符。	否。
.setLogLevel(FaceRecognition.LogLevel logLevel)	用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。默认为 LogLevel.debug。	否。
.setDocumentNumber(String documentNumber)	用于设置用户的文档号码。此字段接受 14 个字符。	仅适用于某次调用使用了 1:1 验证的情况。
.setValidation(Boolean validation)	用于定义 SDK 是否对用户的自拍照执行 1:1 验证。在用户的第一次会话中，此标志必须为 false。此功能需要填写 setDocumentNumber 方法。	否。默认值为 false。

添加到项目​

添加到应用程序​

启动 SDK​

获取 Client Session Key​

端点​

请求​

响应​

SDK 初始化示例​

FaceRecognition.Builder​

VisualConfiguration 对象​

TextConfiguration 对象​

旧版本​

启动 SDK​

FaceRecognition.Builder​

添加到项目

添加到应用程序

启动 SDK

获取 Client Session Key

端点

请求

响应

SDK 初始化示例

FaceRecognition.Builder

VisualConfiguration 对象

TextConfiguration 对象

旧版本

启动 SDK

FaceRecognition.Builder