原生集成

要导入我们的 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 {
    ...
    packagingOptions {
        pickFirst '**/*.so'
    }
    ...
    splits {
        abi {
            enable true
            universalApk true
            reset()
            include 'armeabi-v7a', 'x86', 'x86_64', 'arm64-v8a'
        }
    }
}
...
dependencies {
    ...
    implementation 'com.zaig.android:documentrecognition:v3.1.3'
}

注意

自 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

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

  Intent intent = new Intent(context, DocumentRecognitionActivity.class);

  VisualConfiguration visualConfiguration = new VisualConfiguration()
          .setOnboardingDrawable(R.drawable.introscreen,500)
          .setDocumentFrontDrawable(R.drawable.documentfront, 500)
          .setDocumentBackDrawable(R.drawable.documentback, 500);

  TextConfiguration textConfiguration = new TextConfiguration()
           .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Vamos começar!")
           .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
           .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire o documento do plástico")
           .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu documento na moldura, aguardando que fique verde para realizar a captura.");

  DocumentRecognition mDocumentRecognition = new DocumentRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
          .setDocumentSteps(DocumentSteps)
          .setVisualConfiguration(visualConfiguration)
          .setTextConfiguration(textConfiguration)
          .showIntroductionScreens(true)
          .setShowSuccessScreen(false)
          .setBackgroundColor("#000000")
          .setFontColor("#FFFFFF")
          .setFontFamily(DocumentRecognition.FontFamily.open_sans)
          .setSessionId("SESSION_ID")
          .setLogLevel(DocumentRecognition.LogLevel.debug)
          .build();
  intent.putExtra("settings", mDocumentRecognition);
  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。

DocumentRecognition.Builder

参数	功能	是否必填
mobileToken	客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 mobile-token，请联系 suporte.caas@qitech.com.br。	是。
.setDocumentSteps(DocumentRecognitionStep[] documentSteps)	定义用户进行的文档采集流程。更多信息请点击这里	是。
.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。
.setVisualConfiguration(VisualConfiguration visualConfiguration)	用于自定义 SDK 执行过程中向用户显示的图片。	否。
.setTextConfiguration(TextConfiguration textConfiguration)	用于自定义 SDK 执行过程中向用户显示的引导屏幕上的文本。	否。
.setSessionId(String sessionId)	用于设置标识 SDK 启动会话的密钥。用于通过日志跟踪用户在 OCR 执行过程中的完整流程。此字段最多接受 255 个字符。	否。
.setLogLevel(DocumentRecognition.LogLevel logLevel)	用于自定义 SDK 日志的详细级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。默认为 LogLevel.debug。	否。

VisualConfiguration 对象

参数	功能	是否必填
.setOnboardingDrawable(int onboarding_drawable, int onboarding_width)	用于配置在 SDK 引导屏幕上向用户显示的图片。参数 onboarding_drawable 应引用要显示的图片 ID，onboarding_width 是该图片的预期显示尺寸。	否。
.setDocumentFullDrawable(int documentfull_drawable, int documentfull_width)	用于配置在 SDK 完整驾照采集屏幕上向用户显示的图片。参数 documentfull_drawable 应引用要显示的图片 ID，documentfull_width 是该图片的预期显示尺寸。	否。
.setDocumentFrontDrawable(int documentfront_drawable, int documentfront_width)	用于配置在 SDK 驾照和身份证正面采集屏幕上向用户显示的图片。参数 documentfront_drawable 应引用要显示的图片 ID，documentfront_width 是该图片的预期显示尺寸。	否。
.setDocumentBackDrawable(int documentback_drawable, int documentback_width)	用于配置在 SDK 驾照和身份证背面采集屏幕上向用户显示的图片。参数 documentback_drawable 应引用要显示的图片 ID，documentback_width 是该图片的预期显示尺寸。	否。
.setButtonBorderSize(int border_size)	用于配置 SDK 按钮的边框宽度。	否。默认值为 1。
.setButtonShadow(boolean button_shadow)	设置为 false 时，移除 SDK 按钮使用的 Android 默认阴影效果。	否。默认值为 true。

TextConfiguration 对象

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

添加到项目​

添加到应用程序​

启动 SDK​

DocumentRecognition.Builder​

VisualConfiguration 对象​

TextConfiguration 对象​