原生集成

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

添加到项目

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

buildscript {
    ...
}

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

添加到应用程序

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

android {
    ...
}
...
dependencies {
    ...
    implementation 'com.qitech.android:facerecon:v7.4.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.caas.qitech.app/face_recognition/client_session`
生产	`https://api.caas.qitech.app/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": "8f14e45f-ceea-467a-9a2e-4b1d0c6ba1f7",
  "expiration_date": "2026-09-22T18:40:57Z"
}

expiration_date 表示密钥的有效期。每个 client_session_key 仅服务于一次采集会话：每个流程请生成新的密钥，切勿在不同用户之间重复使用。

要将 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（显示按钮，当设备启用了无障碍功能时语音默认开启）。当 TalkBack 开启时，完整指引由屏幕阅读器本身播报。	否。默认值为 AudioConfiguration.disable。
.setLanguage(String language)	设置 SDK 界面、无障碍提示和语音引导的语言，格式为 BCP 47 语言标签（例如 `pt-BR`、`en`、`es` 或 `zh-Hans`）。支持的语言：葡萄牙语（`pt`、`pt-BR`）、英语（`en`、`en-US`）、通用西班牙语（`es`、`es-MX`、`es-419`）和简体中文（`zh`、`zh-Hans`、`zh-CN`）。标签不区分大小写，也接受 `_` 作为分隔符（`pt_BR`）。不支持的标签（如 `fr` 或 `zh-TW`）会以英语显示 SDK，并在日志中记录警告。SDK 不使用设备的系统语言。	否。未设置时默认为葡萄牙语。
.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 从不使用设备的系统语言，由您的集成代码决定。如需跟随应用的语言，请直接传入应用当前的语言标签，例如 Locale.getDefault().toLanguageTag()。
自定义的引导页文字（onboardingTextConfiguration）会按传入的内容原样显示，请传入已翻译成所选语言的文字。
当设备安装了所选语言的语音时，语音引导会使用该语言播报；否则，本次会话中 SDK 的语音播报将保持关闭。TalkBack 仍会以所选语言朗读操作提示。

Android App Bundle

以 Android App Bundle 形式发布应用时，Google Play 只会安装用户设备所设置的语言。如果您的应用选择了与设备不同的语言，请在应用模块的 build.gradle 中关闭按语言拆分：

android {
    bundle {
        language {
            enableSplit = false
        }
    }
}

如果所选语言的翻译未被安装，SDK 将以葡萄牙语显示，并在日志中记录警告。

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（显示按钮，当设备启用了无障碍功能时语音默认开启）。当 TalkBack 开启时，完整指引由屏幕阅读器本身播报。	否。默认值为 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