# QI Tech — Risk Solutions › OCR Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 29 página(s). Índice: - 收集返回值 (/zh-Hans/documentation/caas/ocr/android/collecting_response) - DocumentDetectorStep (/zh-Hans/documentation/caas/ocr/android/document_step) - 简介 (/zh-Hans/documentation/caas/ocr/android/introduction) - 原生集成 (/zh-Hans/documentation/caas/ocr/android/native_java) - HTTP 状态码 (/zh-Hans/documentation/caas/ocr/api/http_status) - 简介 (/zh-Hans/documentation/caas/ocr/api/introduction) - 发送文档 (/zh-Hans/documentation/caas/ocr/api/send_image) - 获取返回结果 (/zh-Hans/documentation/caas/ocr/flutter/collecting_response) - 兼容性 (/zh-Hans/documentation/caas/ocr/flutter/compatibility) - 实现 (/zh-Hans/documentation/caas/ocr/flutter/example) - 安装 (/zh-Hans/documentation/caas/ocr/flutter/installation) - 简介 (/zh-Hans/documentation/caas/ocr/flutter/introduction) - OcrOptions 对象 (/zh-Hans/documentation/caas/ocr/flutter/ocr_options) - 收集返回值 (/zh-Hans/documentation/caas/ocr/ios/collecting_response) - QITechIosOcrConfiguration (/zh-Hans/documentation/caas/ocr/ios/configuration) - 简介 (/zh-Hans/documentation/caas/ocr/ios/introduction) - 导入 SDK (/zh-Hans/documentation/caas/ocr/ios/native_swift) - 获取返回结果 (/zh-Hans/documentation/caas/ocr/react_native/collecting_response) - 兼容性 (/zh-Hans/documentation/caas/ocr/react_native/compatibility) - 实现 (/zh-Hans/documentation/caas/ocr/react_native/example) - 安装 (/zh-Hans/documentation/caas/ocr/react_native/installation) - 简介 (/zh-Hans/documentation/caas/ocr/react_native/introduction) - OcrOptions 对象 (/zh-Hans/documentation/caas/ocr/react_native/ocr_options) - 收集返回值 (/zh-Hans/documentation/caas/ocr/web/collecting_results) - QiTechWebOCR.WebOCR() 构造函数 (/zh-Hans/documentation/caas/ocr/web/constructor_info) - 实现 (/zh-Hans/documentation/caas/ocr/web/example) - 导入库 (/zh-Hans/documentation/caas/ocr/web/import) - initialize() 函数 (/zh-Hans/documentation/caas/ocr/web/initialize_info) - 简介 (/zh-Hans/documentation/caas/ocr/web/introduction) --- # 收集返回值 URL: /zh-Hans/documentation/caas/ocr/android/collecting_response 要获取包含 SDK 采集结果的 **RequestResponseObject** 对象，请在启动 **DocumentRecognitionActivity** 的同一 *activity* 中覆盖 *onActivityResult* 方法： ```java @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); DocumentRecognition.RequestResponseObject result; if (requestCode == REQUEST_CODE){ if (resultCode == RESULT_OK && data != null){ DocumentRecognition.RequestResponseObject mRequestResponseObject = data.ParcelableExtra("result"); } } } ``` ### RequestResponseObject 对象属性说明 属性 | 描述 --------- | --------- ocr_key | 提供的图片标识密钥，可用于 QI Tech 系统的任何其他服务。 --- # DocumentDetectorStep URL: /zh-Hans/documentation/caas/ocr/android/document_step 用户将执行的文档采集流程通过一个 **DocumentRecognitionStep**（SDK 中提供）类型对象的数组来定义，其中每个元素是用户执行的采集步骤之一。 ```java DocumentSteps = new DocumentRecognitionStep[]{ new DocumentRecognitionStep(Document.cnh_front), new DocumentRecognitionStep(Document.cnh_back) }; ``` 上面实现了一个流程，将首先从用户处采集其驾照正面（cnh_front），在验证采集到高质量照片后，采集驾照背面。 DocumentRecognitionStep 对象可以取以下值： ```java public enum Document { cnh, // 巴西完整驾驶证 cnh_front, // 巴西驾驶证正面（照片面） cnh_back, // 巴西驾驶证背面（签名面） cnh_digital, // 巴西数字驾驶证的 PDF rg_cin_digital, // 由 gov.br 签发的数字 RG 或数字 CIN 的 PDF rg_front, // 巴西身份证正面（照片面） rg_back, // 巴西身份证背面（数据面） proof_of_address, // 居住证明 other // 其他身份证件 } ``` --- # 简介 URL: /zh-Hans/documentation/caas/ocr/android/introduction 欢迎使用 QI Tech Android OCR（光学字符识别）文档读取 SDK。此 SDK 执行文档采集并将其发送到 QI Tech OCR API 。您可以使用它通过您的应用程序采集客户文档的图像（如驾驶证或身份证），并通过密钥在 QI Tech 系统的其他产品中引用。 ## 遇到问题？ 我们不是一个躲在 API 背后的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！ ### 我们热爱反馈 即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！ :::danger 重要提示！ 不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。 ::: --- # 原生集成 URL: /zh-Hans/documentation/caas/ocr/android/native_java 要导入我们的 SDK，需要修改项目和应用程序的 _build.gradle_ 文件。 ## 添加到项目 在项目的 _build.gradle_ 中添加我们的 Maven 仓库地址（在 Android Studio 中，该文件显示为：**"Project: \{project_name\}"**），如下例所示。 ```java buildscript { ... } allprojects { repositories { ... maven { url 'https://sdks.qitech.com.br/' } } } ``` ## 添加到应用程序 之后，在应用程序的 build.gradle 中添加您要导入的库（在 Android Studio 中，该文件显示为：**"Module: \{project_name\}.app"**），包含以下依赖项。 ```java android { ... packagingOptions { pickFirst '**/*.so' } ... splits { abi { enable true universalApk true reset() include 'armeabi-v7a', 'x86', 'x86_64', 'arm64-v8a' } } } ... dependencies { ... implementation 'com.qitech.android:documentrecognition:v5.1.0' } ``` :::warning 自 **2025 年 4 月**起，Google Play 的新政策要求应用程序必须使用 **Android API Level 35** 才能在 Google Play Store 上发布或更新。因此，我们强烈建议至少使用 **targetSdkVersion 35**。 ::: :::info 使用 **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。 ```java 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，因此必须通过上述方法将其作为配置参数包含在内。 :::info **注意** 您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。 ::: ## DocumentRecognition.Builder | 参数 | 功能 | 是否必填 | |------------|--------------|--------------| |mobileToken |客户密钥，用于标识收集的数据来源于您的应用程序。如果尚未收到您的 mobile-token，请联系 suporte.caas@qitech.com.br。|是。| |.setDocumentSteps(DocumentRecognitionStep[] documentSteps)|定义用户进行的文档采集流程。更多信息请[点击这里](/documentation/caas/ocr/android/document_step)|是。| |.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。|否。| |.setAudioConfiguration(AudioConfiguration audioConfiguration)| 配置 SDK 的语音引导，实时朗读拍摄指引。接受的配置为 _AudioConfiguration.enable_（显示音频开关按钮，语音默认关闭）、_AudioConfiguration.disable_（关闭语音并隐藏按钮）和 _AudioConfiguration.accessibility_（显示按钮，当设备启用了无障碍功能时语音默认开启）。当 TalkBack 开启时，完整指引由屏幕阅读器本身播报。 |否。| ## 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 引导屏幕上向用户显示的文本 | 否。 | --- # HTTP 状态码 URL: /zh-Hans/documentation/caas/ocr/api/http_status 所有 QI Tech API 均按照 RFC 7231 使用以下 HTTP 返回状态标准化： HTTP 状态 | 含义 | 描述 ---------- | ------- | --------------------------------- 400 | Bad Request | 发送的请求存在格式错误。大多数情况下，我们会在消息正文中返回错误位置的说明。 401 | Unauthorized | 身份验证出现问题，请检查 API Key 是否正确以及是否在正确的头部中，详见 身份验证 部分。 403 | Forbidden | 访问的端点仅供内部使用，此 API Key 不可用。 404 | Not Found | 使用所提供的密钥未找到请求的数据。当请求无效端点时也会返回此状态。 405 | Method Not Allowed | 使用的 HTTP 方法不适用于所使用的端点。 406 | Not Acceptable | 请求正文中发送的数据无效。通常，这意味着发送的数据不是有效的 JSON。 409 | Conflict | 请求 ID 对应于之前已处理的 ID。当向服务器发送重复请求时会返回此状态。 500 | Internal Server Error | 处理此请求时出现问题，遇到此错误时，我们的专家会自动收到通知并立即开始分析和解决。 503 | Service Unavailable | 您遇到了我们服务器基础设施的计划内或计划外停机。 --- # 简介 URL: /zh-Hans/documentation/caas/ocr/api/introduction 欢迎使用 QI Tech OCR（光学字符识别）文档读取 API。您可以使用此 API 发送要识别的文档图像（如驾驶证或身份证），并通过密钥在 QI Tech 系统的其他产品中引用。 ## 遇到问题？ 我们不是一个躲在 API 背后的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！ ### 我们热爱反馈 即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！ ## 环境 我们为客户提供两个环境。API 的基础 URL 为： * 生产环境 - `https://api.caas.qitech.app/ocr/` * 沙盒环境 - `https://api.sandbox.caas.qitech.app/ocr/` :::danger 重要提示！ 不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。 ::: ## 仅限 HTTPS 出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS 进行。为避免因疏忽或其他原因进行 HTTP 调用，此服务器仅开放使用 TLS 1.2 通信的 443 端口。使用其他协议的调用将被自动拒绝。 ## 身份验证 > 要认证调用，请使用以下代码： ```shell # 在 shell 中，只需在每个请求中添加适当的头部 curl "api_endpoint_here" -H "Authorization: EXAMPLE_API_KEY" ``` > 将 API key 'EXAMPLE_API_KEY' 替换为您从我们的支持团队获取的密钥。 我们使用 API Key 来允许访问我们的 API。它可能已通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。 我们的 API 期望在所有向服务器发送的请求中，在如下头部中接收 API Key： `Authorization: EXAMPLE_API_KEY` :::info **注意** 您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。 ::: --- # 发送文档 URL: /zh-Hans/documentation/caas/ocr/api/send_image 使用 `/image` 端点发送文档，如下所示。此端点将返回文档的 GUID（全局唯一标识符），之后可在 QI Tech 系统的其他服务中引用。 ## 发送 要发送文档，只需通过 POST 方法以 JSON 格式将图片的 base64 代码发送至以下地址： `https://api.caas.qitech.app/ocr/image` Request Body ```json { "document_b64": "\", "template": "cnh", "file_type": "jpeg" } ``` 将您的文档 base64 代码替换占位符。 ### 发送属性说明 属性 | 描述 --------- | --------- document_b64 | 必填字段。以 base64 格式提交的待分析文档图片。 template | 必填字段。声明应用于图片分析的模板。 file_type | 可选字段。标识发送文件的格式，`jpeg` 或 `pdf`。如未提交，则默认值为 `jpeg`。 ### 可用模板 目前，QI Tech 提供以下可用于 OCR 分析的模板。如果您所需的文档不在此列表中，请发送电子邮件至 suporte.caas@qitech.com.br 了解此功能实施的详细信息。 模板 | 描述 --------- | --------- cnh | 完整的巴西国家驾驶执照。 cnh_front | 巴西国家驾驶执照正面（照片面）。 cnh_back | 巴西国家驾驶执照正面（签名面）。 cnh_digital | 巴西数字国家驾驶执照 PDF。 rg_front | 巴西身份证正面（照片面）。 rg_back | 巴西身份证背面（数据面）。 danfe | 电子发票辅助文档（NF-e）。 proof_of_address | 住址证明。 letter_of_attorney | 授予公司相关权限的授权书。 company_statute | 公司章程或合同。 ## 图片 为确保执行分析的可靠性，客户拍照时需遵循以下规则： * 从塑料袋中取出文档； * 确保文档在照片中居中； * 确保文档光线充足； * 确保文档的所有数据清晰、可见且可读； * 确保照片清晰可见。 ## 图片要求 为使 API 正常运行，请注意以下参数。 * 图片必须为 JPEG 或 PDF 格式； * 图片必须至少有 500 像素高和 500 像素宽； * API 不支持手写文档的识别； * 图片的最大大小根据所选格式而有所不同，遵循以下限制： 格式 | 最大支持大小 --------- | --------- .JPEG | 3MB .PNG | 10MB .PDF | 30MB ## 响应 如果您的文档读取请求处理成功，将返回 HTTP status 200 和包含指向已发送文档的标识符的 JSON 对象。 Response Body ```json { "ocr_key": "f1c0d2e1-f950-4360-896d-36588e443fc9" } ``` ### 响应属性说明 属性 | 描述 --------- | --------- ocr_key | 所提供图片的标识密钥，可用于 QI Tech 系统的任何其他服务。 ## 文档恢复 > 图片恢复 ```shell curl "https://api.caas.qitech.app/ocr/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \ -H "Authorization: EXAMPLE_API_KEY" ``` 任何时候都可以恢复已发送的图片。只需向以下端点发送经适当身份验证的 **GET** 请求： `https://api.caas.qitech.app/ocr/image/{image_key}/file` 其中 image_key 是发送图片时返回的值。 ## 图片质量验证 Response Body：无效图片情况 ```json { "title": "document_quality", "description": "A imagem enviada não pode ser processada com êxito." } ``` 在图片端点发送 POST 请求时，如果图片不足以进行验证，将返回 HTTP Status Code 400，如旁边示例所示。当文档不满足前面提到的图片要求时，也会返回 Status Code 400。 **注意 -** 还有其他原因会导致我们返回 400（均与无效数据相关）。只有 title 为 "document_quality" 的返回才是图片质量验证的结果，因此才应转达给用户。 ## 面部质量验证 图片质量验证**仅适用于包含面部的文档**，如 RG、CNH 和护照。当图片发送至系统时，如果被识别为以下类型之一，将**自动执行面部分析**： - `national_migration_registry_front` - `passport_front` - `ctps_front` - `regional_nursing_council_registry_front` - `regional_nursing_council_registry` - `national_registry_of_foreigners_back` - `passport` - `national_migration_registry` - `national_registry_of_foreigners` - `cnh_digital` - `rg_front` - `rg` - `cnh_front` - `cnh` 在此分析过程中，系统会验证图片中是否有**可见的面部**，并评估以下方面： - 适当的光照（亮度）； - 是否佩戴太阳镜等配件； - 面部过近或过远； - 图片中完全没有面部。 如果上述任一标准表明图片不合适，将返回 `title: "face_validation"` 的错误和相应的 `description`，详情如下。 ```json { "title": "face_validation", "description": "<错误代码>" } ``` ### 返回示例： **未检测到面部** ```json { "title": "face_validation", "description": "no_faces" } ``` --- ### 向用户显示消息的翻译表 | 错误代码（`description`） | 友好提示信息 | |-------------------------------|-------------------| | `close_face` | 图片拍摄时距离面部过近，请重新定位文档。 | | `distant_face` | 图片拍摄时距离面部过远，请重新定位文档。 | | `wearing_acessories` | 图片中的人佩戴了太阳镜或遮住眼睛的配件。 | | `brightness_problem` | 图片太暗，请在更充足的光线下重新发送。 | | `no_faces` | 无法在图片中检测到面部，请确认面部是否可见。 | --- # 获取返回结果 URL: /zh-Hans/documentation/caas/ocr/flutter/collecting_response `startOcr` 方法返回 `Future `。无需手动解析 JSON——插件已经提供带类型的 Dart 对象。 ## OcrReturnValues ```dart class OcrReturnValues { final List documentRecognitionResponse; } ``` | 属性 | 类型 | 说明 | |----------|------|-----------| |documentRecognitionResponse|List|列表，用户每完成一次采集对应一个条目。| ## DocumentRecognitionItem ```dart class DocumentRecognitionItem { final String? ocrKey; final String? ocrFrontKey; final String? ocrBackKey; final String documentType; } ``` | 属性 | 类型 | 说明 | |----------|------|-----------| |ocrKey|String?|图像识别密钥，出现在单次采集的证件中（`cnhFull`、`cnhDigital`、`address`、`rgCinDigital`）。可在 QI Tech 系统的任何其他服务中使用。| |ocrFrontKey|String?|正面图像的识别密钥，出现在双次采集的证件中（`cnh`、`rg`、`rne`、`crnm`）。| |ocrBackKey|String?|背面图像的识别密钥，出现在双次采集的证件中（`cnh`、`rg`、`rne`、`crnm`）。| |documentType|String|标识该密钥对应的证件（例如 `"cnh"`、`"rg"`、`"proof_of_address"`）。| :::info **重要** 请保存返回的密钥——它们是该图像在 QI Tech 系统其他产品（例如 Onboarding API）中的标识符。 ::: ## 读取返回结果的示例 ```dart final result = await plugin.startOcr( CaaSEnvironment.sandbox, '', CaaSDocumentType.cnh, ); for (final item in result.documentRecognitionResponse) { if (item.ocrKey != null) { print('Ocr key: ${item.ocrKey} document type: ${item.documentType}'); } if (item.ocrFrontKey != null) { print('Ocr front key: ${item.ocrFrontKey} document type: ${item.documentType}'); } if (item.ocrBackKey != null) { print('Ocr back key: ${item.ocrBackKey} document type: ${item.documentType}'); } } ``` ## 错误处理 :::warning 注意 与抛出带类型的 `FaceReconException` 的 `startFaceRecon` 不同，`startOcr` 方法抛出的是包含错误信息的 **String**。请使用通用的 `catch (e)`。 ::: ```dart try { final result = await plugin.startOcr( CaaSEnvironment.sandbox, '', CaaSDocumentType.cnh, ); // ... } catch (e) { print('Erro ao executar o OCR: $e'); } ``` ### 最常见的错误信息 | 错误信息 | 含义 | |----------|-------------| |`User canceled OCR`|用户在完成采集流程前中断了流程。| |`Error executing OCR: <详情>`|iOS 原生 SDK 以错误结束流程。| |`at startOcr: <详情>`|调用中缺少某个必填参数。| |`Activity is null`|在 Android 上，SDK 无法获取宿主 _activity_。| --- # 兼容性 URL: /zh-Hans/documentation/caas/ocr/flutter/compatibility `flutter_kyc_qitech` 插件要求以下最低版本： | 配置 | 最低版本 | |------------|--------------| |Flutter|3.3.0| |Dart SDK|3.2.3| |iOS|15.5| |Android API Level|35（Android 15 Vanilla Ice Cream）| |Gradle|8.6.0| |Android Gradle Plugin (AGP)|8.7| |Kotlin|2.0.21（推荐）| |原生 Datadog SDK（iOS，由插件引入）|3.x| |MLKit FaceDetection（iOS，如果您的应用已使用）|8.x| ## 当前插件版本 | 插件 | 版本 | |--------|--------| |`flutter_kyc_qitech`|`^5.3.0`| :::warning 注意 我们的 iOS SDK 不支持在 **arm64** 架构的机器（M1/M2/M3/M4 MacBook）上为模拟器构建，除非启用 **Rosetta** 将 x86_64 架构转译为 arm64。我们建议使用真机进行测试。 ::: --- # 实现 URL: /zh-Hans/documentation/caas/ocr/flutter/example `startOcr` 方法会打开原生的证件采集流程，将图像发送至 QI Tech 的 OCR API，并返回已处理图像的密钥。 ## Mobile Token 我们使用 Mobile Token 让您的应用以已认证的方式访问我们的 API。它通常已经通过邮件发送给您。如果您尚未收到您的 token，请发送邮件至 suporte.caas@qitech.com.br 。 :::info **注意** 每个环境（`sandbox` 和 `production`）需要不同的 Mobile Token。 ::: ## 方法签名 ```dart Future startOcr( CaaSEnvironment environment, String mobileToken, CaaSDocumentType document, { OcrOptions? options, }) ``` 前三个参数是位置参数且为必填。自定义项是可选的，通过命名参数 `options` 传入，详见 [OcrOptions 对象](/documentation/caas/ocr/flutter/ocr_options)。 ## 最小示例 ```dart import 'package:flutter_kyc_qitech/flutter_kyc_qitech.dart'; final _qitechFlutterKycPlugin = FlutterKycQitech(); final result = await _qitechFlutterKycPlugin.startOcr( CaaSEnvironment.sandbox, '', CaaSDocumentType.cnh, ); for (final item in result.documentRecognitionResponse) { print('${item.documentType}: ${item.ocrKey ?? item.ocrFrontKey ?? item.ocrBackKey}'); } ``` ## 完整示例 ```dart import 'package:flutter/material.dart'; import 'package:flutter_kyc_qitech/flutter_kyc_qitech.dart'; class OcrButton extends StatelessWidget { const OcrButton({super.key}); static const String _mobileToken = ''; Future _startOcr() async { final plugin = FlutterKycQitech(); try { final result = await plugin.startOcr( CaaSEnvironment.sandbox, _mobileToken, CaaSDocumentType.cnh, options: OcrOptions( sessionId: '', fontColor: '#FFFFFF', backgroundColor: '#000000', fontFamily: CaaSFontFamily.openSans, showIntroductionScreens: true, showSuccessScreen: false, audioConfiguration: FaceReconAudioConfiguration.enable, onboardingTextConfiguration: OnboardingTextConfiguration( onboardingTitle: 'Dicas Importantes', onboardingFirstLabel: 'Vá para um local iluminado', onboardingSecondLabel: 'Retire o documento do plástico', onboardingThirdLabel: 'Garanta que o documento está corretamente enquadrado', ), logLevel: CaaSLogLevel.debug, ), ); for (final item in result.documentRecognitionResponse) { if (item.ocrKey != null) { print('Ocr key: ${item.ocrKey} document type: ${item.documentType}'); } if (item.ocrFrontKey != null) { print('Ocr front key: ${item.ocrFrontKey} document type: ${item.documentType}'); } if (item.ocrBackKey != null) { print('Ocr back key: ${item.ocrBackKey} document type: ${item.documentType}'); } } } catch (e) { // startOcr 会抛出一个包含错误信息的 String print('Erro ao executar o OCR: $e'); } } @override Widget build(BuildContext context) { return ElevatedButton( onPressed: _startOcr, child: const Text('Capturar documento'), ); } } ``` :::info **注意** 请在您的应用中启用 _Portrait_ 和 _Landscape Right_ 方向支持，以保证 iOS 原生 SDK 正常工作。 ::: ## 按证件类型划分的采集流程 `document` 参数决定用户需要完成的采集次数，以及返回结果包含的条目数量。 | 证件类型 | 采集次数 | 返回结果 | |-------------------|----------|---------| |`CaaSDocumentType.cnhFull`|1（展开的 CNH）|1 个条目，含 `ocrKey`| |`CaaSDocumentType.cnhDigital`|1（电子 CNH 的 PDF）|1 个条目，含 `ocrKey`| |`CaaSDocumentType.address`|1（居住证明）|1 个条目，含 `ocrKey`| |`CaaSDocumentType.rgCinDigital`|1（电子 RG/CIN 的 PDF）|1 个条目，含 `ocrKey`| |`CaaSDocumentType.cnh`|2（正面和背面）|2 个条目：`ocrFrontKey` 和 `ocrBackKey`| |`CaaSDocumentType.rg`|2（正面和背面）|2 个条目：`ocrFrontKey` 和 `ocrBackKey`| |`CaaSDocumentType.rne`|2（正面和背面）|2 个条目：`ocrFrontKey` 和 `ocrBackKey`| |`CaaSDocumentType.crnm`|2（正面和背面）|2 个条目：`ocrFrontKey` 和 `ocrBackKey`| ## 示例应用 插件仓库在 `flutter_kyc_qitech/example` 下包含一个可直接运行的示例应用，演示了三个 SDK 的使用。运行前，请在 `example` 目录下创建 `.env` 文件并填入以下凭证，然后连接真机执行 `flutter pub get` 和 `flutter run`： ``` FACERECON_API_URL_SANDBOX='' FACERECON_API_KEY_SANDBOX='' OCR_MOBILE_TOKEN_SANDBOX='' DEVICE_SCAN_API_URL_SANDBOX='' DEVICE_SCAN_API_KEY_SANDBOX='' ``` 如果您尚未收到凭证，请联系 suporte.caas@qitech.com.br 。 --- # 安装 URL: /zh-Hans/documentation/caas/ocr/flutter/installation ## 安装插件 在 Flutter 项目根目录执行以下命令： ```bash flutter pub add flutter_kyc_qitech ``` 该命令会安装最新版本，并将依赖添加到 `pubspec.yaml`： ```yaml dependencies: flutter_kyc_qitech: ^5.3.0 ``` 然后拉取依赖： ```bash flutter pub get ``` ## 导入 ```dart import 'package:flutter_kyc_qitech/flutter_kyc_qitech.dart'; ``` 并实例化插件： ```dart final _qitechFlutterKycPlugin = FlutterKycQitech(); ``` ## Android 配置 ### 1. QI Tech Maven 仓库 在项目的 `build.gradle` 中添加 QI Tech 的 Android 仓库引用： ```gradle allprojects { repositories { maven { url 'https://sdks.qitech.com.br/' } ... } } ``` ### 2. AdMob 在 `AndroidManifest.xml` 中添加以下代码以初始化 AdMob 服务： ```xml ``` 如果您还没有 `ADMOB_APP_ID`，请联系 suporte.caas@qitech.com.br 。 ## iOS 配置 ### 1. 相机权限 在应用的 `Info.plist` 中添加 `NSCameraUsageDescription` 条目，说明应用需要访问相机的原因： ```xml NSCameraUsageDescription 我们需要使用相机拍摄您的证件照片 ``` ### 2. QI Tech iOS 仓库 source 在 `Podfile` 顶部添加以下 source： ```ruby source 'https://cdn.cocoapods.org/' source 'https://github.com/QITechSDKs/iOS.git' ``` ### 3. 静态 framework CocoaPods 默认构建静态库而非 framework。请在 `Podfile` 中添加： ```ruby use_frameworks! :linkage => :static ``` ### 4. 模块稳定性 QI Tech 的原生依赖要求为 Datadog 目标启用 `BUILD_LIBRARY_FOR_DISTRIBUTION`。请添加下面的 `post_install` 代码块（或合并到已有的 `post_install` 中）： ```ruby post_install do |installer| installer.pods_project.targets.each do |target| flutter_additional_ios_build_settings(target) target.build_configurations.each do |config| config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'NO' # 以下这行仅在模拟器上构建时需要（需启用 Rosetta） config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64" end if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name) target.build_configurations.each do |config| config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5' config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' end end end end ``` ### 5. 安装 pod 在 Flutter 应用的 `ios` 目录中执行： ```bash cd ios pod install ``` 或通过 Flutter 执行： ```bash flutter build ios ``` :::warning 注意 如果您的应用已使用 **Datadog**，请使用 `3.x` 主版本中的最新版本（`datadog_flutter_plugin` 3.x）。如果使用 **MLKit 的 FaceDetection**，请使用 `8.x` 主版本中的最新版本。 ::: --- # 简介 URL: /zh-Hans/documentation/caas/ocr/flutter/introduction 欢迎使用 QI Tech OCR（光学字符识别）SDK 的 Flutter 集成手册！`flutter_kyc_qitech` 插件通过 Dart 接口暴露 QI Tech 的 Android（Kotlin）和 iOS（Swift）原生 SDK。您可以使用它在应用中拍摄客户需要识别的证件图像，例如驾驶证或身份证，并通过一个密钥在 QI Tech 系统的其他产品中引用它。 :::info **三个 SDK 共用一个插件** `flutter_kyc_qitech` 在同一个包中提供三个 Risk Solutions SDK：`startFaceRecon`（人脸识别）、`startOcr`（OCR）和 `startDeviceScan`（设备扫描）。安装后，这三个方法均可使用，无需安装其他插件。 如果您**仅**需要设备扫描，请使用专用插件 `qitech_device_scan`，其文档见[设备扫描 Flutter 章节](/documentation/caas/device_scan/flutter/introduction)。 ::: ## 遇到问题？ 我们不是躲在 API 后面的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您需要快速回复，请随时致电我们！ ### 我们欢迎反馈 即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的不当排版），也请给我们发邮件——这样我们就能让文档越来越实用，下一个人也不必再经历您经历过的痛苦！ ## 环境 我们为客户提供两个环境。通过 `CaaSEnvironment` 枚举进行选择，该枚举作为 `startOcr` 方法的第一个参数传入。目前可用的环境如下： * 生产环境 - `CaaSEnvironment.production` * 沙盒环境 - `CaaSEnvironment.sandbox` 每个环境需要不同的 Mobile Token。 :::danger 重要提示！ 请勿在 QI Tech 的沙盒环境中使用真实的个人或企业数据。 ::: ## 后续步骤 1. [兼容性](/documentation/caas/ocr/flutter/compatibility) — Flutter、Dart、iOS 和 Android 的最低版本。 2. [安装](/documentation/caas/ocr/flutter/installation) — 插件安装以及 Android 和 iOS 原生配置。 3. [实现](/documentation/caas/ocr/flutter/example) — `startOcr` 的完整示例。 4. [OcrOptions 对象](/documentation/caas/ocr/flutter/ocr_options) — 所有自定义参数。 5. [获取返回结果](/documentation/caas/ocr/flutter/collecting_response) — 返回结构与错误处理。 --- # OcrOptions 对象 URL: /zh-Hans/documentation/caas/ocr/flutter/ocr_options ## startOcr 参数 | 参数 | 类型 | 作用 | 必填 | |------------|--------------|--------------|--------------| |environment|CaaSEnvironment|用于将运行环境设置为 `sandbox` 或 `production` 的枚举。|是。| |mobileToken|String|标识所采集数据来自您应用的客户端密钥。如果您尚未收到 mobile-token，请联系支持团队。每个环境需要不同的 token。|是。| |document|CaaSDocumentType|定义用户完成的证件采集流程的枚举。|是。| |options|OcrOptions?|包含 SDK 视觉、文案和行为自定义项的可选对象。|否。| ## OcrOptions 所有字段均为可选。未提供某个字段时，原生 SDK 会使用其默认值。 | 参数 | 类型 | 作用 | 默认值 | |------------|--------------|--------------|--------------| |sessionId|String?|标识 SDK 中启动的会话的密钥，用于通过日志追踪用户完成的完整流程。最多接受 255 个字符。|内部生成。| |fontColor|String?|SDK 界面的字体和图标颜色，十六进制格式（例如 `"#FFFFFF"`）。|`"#000000"`| |backgroundColor|String?|SDK 界面的背景颜色，十六进制格式（例如 `"#000000"`）。|`"#FFFFFF"`| |fontFamily|CaaSFontFamily?|SDK 界面使用的字体。|`CaaSFontFamily.openSans`| |showIntroductionScreens|bool?|设为 `false` 时，关闭证件采集前的介绍页。|`true`| |showSuccessScreen|bool?|设为 `false` 时，关闭采集完成后的成功页。|`true`| |audioConfiguration|FaceReconAudioConfiguration?|配置语音引导，实时播报采集指引。|`FaceReconAudioConfiguration.disable`| |onboardingTextConfiguration|OnboardingTextConfiguration?|自定义引导页文案。|SDK 默认文案。| |logLevel|CaaSLogLevel?|SDK 日志的详细级别。|`CaaSLogLevel.debug`| :::info **注意** `OcrOptions` 中的 `audioConfiguration` 参数自插件 **5.3.0** 版本起可用。 ::: ## OnboardingTextConfiguration | 参数 | 类型 | 作用 | |------------|--------------|--------------| |onboardingTitle|String?|引导页标题。| |onboardingFirstLabel|String?|展示给用户的第一条说明。| |onboardingSecondLabel|String?|展示给用户的第二条说明。| |onboardingThirdLabel|String?|展示给用户的第三条说明。| ```dart OnboardingTextConfiguration( onboardingTitle: 'Dicas Importantes', onboardingFirstLabel: 'Vá para um local iluminado', onboardingSecondLabel: 'Retire o documento do plástico', onboardingThirdLabel: 'Garanta que o documento está corretamente enquadrado', ) ``` ## 枚举 ### CaaSEnvironment ```dart enum CaaSEnvironment { production, sandbox, } ``` ### CaaSDocumentType ```dart enum CaaSDocumentType { cnhFull, // 巴西 CNH 驾驶证展开后的单张照片 cnhDigital, // 巴西电子 CNH 的 PDF cnh, // 巴西 CNH，正面和背面 rg, // 巴西 RG 身份证，正面和背面 address, // 居住证明 rne, // 巴西外国人国家登记证，正面和背面 crnm, // 巴西国家移民登记证，正面和背面 rgCinDigital, // 电子 RG/CIN 的 PDF } ``` :::info **注意** `rgCinDigital` 类型自插件 **5.3.0** 版本起可用。 ::: ### CaaSFontFamily ```dart enum CaaSFontFamily { jakarta, // 仅 iOS futura, // iOS 和 Android verdana, // iOS 和 Android trebuchetMs, // 仅 iOS tamilsangamMn, // 仅 iOS openSans, // iOS 和 Android helvetica, // 仅 Android poppins, // 仅 Android roboto, // 仅 Android systemFont, // 仅 iOS } ``` :::info **注意** 字体的可用性因平台而异。如果传入平台不支持的字体，将使用该平台的默认字体。为保证跨平台一致性，请使用 `futura`、`verdana` 或 `openSans`。 ::: ### FaceReconAudioConfiguration ```dart enum FaceReconAudioConfiguration { enable, // 显示音频开关，播报默认关闭 disable, // 关闭播报并隐藏开关 accessibility, // 当设备启用无障碍功能时，显示开关且播报默认开启 } ``` ### CaaSLogLevel ```dart enum CaaSLogLevel { trace, debug, log, info, warn, error, } ``` --- # 收集返回值 URL: /zh-Hans/documentation/caas/ocr/ios/collecting_response ```swift class ViewController: UIViewController, QITechIosOcrControllerDelegate { // Do something if QI Tech OCR's SDK succesfully collected document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults response: QITechIosOcrControllerResponse) { } // Do something if QI Tech OCR's SDK found any error when collecting document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) { } // Do something if the user canceled the picture collection on any steps func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) { } } ``` 要获取 SDK 的响应，您需要在 controller 中实现 **QITechIosOcrControllerDelegate** 委托，如旁边示例所示。 ## QITechIosOcrControllerResponse **QITechIosOcrControllerResponse** 类用于接收 QI Tech SDK 的响应。 下表详细列出了此类的所有属性： 名称 | 类型 | 描述 ---- | :----: | --------- OcrResponses | OcrResponse 列表 | 标识 ## OcrResponse 对象 名称 | 类型 | 描述 ---- | :----: | --------- OcrKey | string | QI Tech 中图片的唯一标识符。您必须存储此标识符，以便在执行验证的 QI Tech API 中发送（例如：Onboarding API） DocumentTemplate | QITechIosOcrDocumentTemplate | 标识该 OCR Key 对应照片的枚举值。 **QITechIosOcrDocumentTemplate** 枚举的可能值为： * `QITechIosOcrDocumentTemplate.CnhFull` - 标识完整 CNH 验证的结果。 * `QITechIosOcrDocumentTemplate.CnhFront` - 标识 CNH 正面验证的结果。 * `QITechIosOcrDocumentTemplate.CnhBack` - 标识 CNH 背面验证的结果。 * `QITechIosOcrDocumentTemplate.RgFront` - 标识 RG 正面验证的结果。 * `QITechIosOcrDocumentTemplate.RgBack` - 标识 RG 背面验证的结果。 * `QITechIosOcrDocumentTemplate.RgCinDigital` - 标识数字 RG 或数字 CIN 验证的结果。 * `QITechIosOcrDocumentTemplate.NationalRegistryOfForeignersFront` - 标识外国人国家登记证正面验证的结果。 * `QITechIosOcrDocumentTemplate.NationalRegistryOfForeignersBack` - 标识外国人国家登记证背面验证的结果。 ## QITechIosOcrControllerError **QITechIosOcrControllerError** 类在出现导致 SDK 终止的错误时触发。发生此情况时，QI Tech 将返回一个子类，其名称对应于导致 SDK 终止的错误，如下表所示： 类 | 描述 ---- | --------- InvalidMobileToken | 配置中发送的 MobileToken 无效。 MissingPermission | 验证所需的某些权限不足。 NetworkFailure | 用户在验证过程中失去了互联网连接。 ServerFailure | QI Tech 服务器向 SDK 返回了错误响应。 MissingStorage | 用户设备没有足够的存储空间进行图片采集。 LowImageQuality | 由于某种原因，采集的图片质量不足以进行验证。 要确定是哪个子类（即错误原因），请使用 Swift 的 *isKindOfClass()* 方法。 --- # QITechIosOcrConfiguration URL: /zh-Hans/documentation/caas/ocr/ios/configuration ```swift let visualConfiguration = VisualConfiguration() visualConfiguration.setOnboarding(onboardingFilePath: Bundle.main.path(forResource: "onboarding", ofType: "png")!, onboardingWidth: 200) let textConfiguration = TextConfiguration() textConfiguration.setCustomText(on: .onboardingTitle, text: "Vamos começar!") textConfiguration.setCustomText(on: .onboardingFirstLabel, text: "- Vá para um local com boa luminosidade") textConfiguration.setCustomText(on: .onboardingSecondLabel, text: "- Retire o documento do plástico") let ocrConfig = QITechIosOcrConfiguration(environment: QITechIosOcrEnvironment.Sandbox, mobileToken: "41fb4755-9bcf-4ae3-b981-b6009e51ce4a", sessionId: "288eb399-4936-4133-ab2c-5611d6e5bb7a", documentSteps: documentSteps, backgroundColor: "#C9CCD3", fontColor: "#337DFF", fontFamily: .open_sans, showIntroductionScreens: true, showSuccessScreen: false, logLevel: .debug ) ocrConfig.setVisualConfiguration(visualConfiguration: visualConfiguration) ocrConfig.setTextConfiguration(textConfiguration: textConfiguration) ``` **QITechIosOcrConfiguration** 类用于配置环境、凭证、视觉和文本方面，以及文档图片采集流程，即 SDK 个性化和运行所需的所有配置。 下表详细列出了实例化时需使用的所有参数： | 名称 | 类型 | 描述 | | ----------------------- | :--------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | environment | QITechIosOcrEnvironment | _（必填）_ 描述环境的枚举值。 | | mobileToken | string | _（必填）_ QI Tech 发送的用于 SDK 身份验证的 Token。 | | sessionId | string | _（可选）_ 用于通过日志跟踪用户在 OCR 执行过程中所经历的完整流程的唯一 ID。此字段最多接受 255 个字符。 | | documentSteps | QITechIosOcrDocumentFlow | _（必填）_ 描述将遵循的验证流程的枚举值，定义将采集的文档及图片采集顺序。 | | backgroundColor | string | _（可选）_ 界面背景色的十六进制值。如未提供，默认值为 #FFFFFF。 | | fontColor | string | _（可选）_ 字体颜色的十六进制值。如未提供，默认值为 #000000。 | | fontFamily | FontFamily | _（可选）_ 字体系列。如未提供，默认值为 .open_sans。可用字体：.open_sans、.futura、.verdana、.trebuchetms、.tamilsangammn 和 .system_font。 | | showIntroductionScreens | boolean | _（可选）_ 表示是否应显示介绍界面（包含照片拍摄说明）的标志。如未提供，默认值为 _true_。 | | showSuccessScreen | boolean | _（可选）_ 表示是否应显示成功界面（包含采集成功消息）的标志。如未提供，默认值为 _true_。 | | logLevel | LogLevel | _（可选）_ 用于自定义 SDK 日志详细程度级别。可用级别：LogLevel.debug、LogLevel.info、LogLevel.warn、LogLevel.error 和 LogLevel.trace。如未提供，默认值为 LogLevel.debug。 | | audioConfiguration | AudioConfiguration | _（可选）_ 配置 SDK 的语音引导，实时朗读拍摄指引。接受的配置为：_Enable_（显示音频开关按钮，语音默认关闭）、_Disable_（关闭语音并隐藏按钮）和 _Accessibility_（显示按钮，当设备启用了无障碍功能时语音默认开启）。当 VoiceOver 开启时，完整指引由屏幕阅读器本身播报。如未提供，默认值为 _Disable_。 | 下表列出了实例接受的所有配置方法： | 方法 | 参数 | 描述 | | ---------------------- | :-------------------------------------------------------------: | ---------------------------------------------------------------------------------------- | | setVisualConfiguration | visualConfiguration : VisualConfiguration | _（可选）_ 允许修改 SDK 执行过程中显示的图片的类； | | setTextConfiguration | textConfiguration : TextConfiguration | _（可选）_ 允许修改 SDK 执行过程中显示的文本的类； | --- # 简介 URL: /zh-Hans/documentation/caas/ocr/ios/introduction 欢迎使用 QI Tech iOS OCR（光学字符识别）文档读取 SDK。此 SDK 可采集文档并将其发送至 QI Tech OCR API 。您可以使用它通过您的应用采集客户文档图片（如驾驶执照或身份证）进行识别，并通过密钥在 QI Tech 系统的其他产品中引用。 ## 遇到问题？ 我们不是一个躲在 API 背后的公司！请联系我们的[支持团队](mailto:suporte.caas@qitech.com.br)，我们将尽快回复。如果您想要快速响应，也欢迎直接给我们打电话！ ### 我们热爱反馈 即使您已经解决了问题，或者问题非常简单（哪怕只是一个拼写错误或您已经理解的组织问题），也请给我们发送电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！ :::danger 重要提示！ 不得在 QI Tech 的沙盒环境中使用真实的个人和/或法人数据。 ::: --- # 导入 SDK URL: /zh-Hans/documentation/caas/ocr/ios/native_swift ## 远程方式 > 开始安装 ```shell pod init ``` 我们的 SDK 可使用 CocoaPods 导入。 | SDK | 当前版本 | | ---------- | ------------------------------ | | QITechIosOCR | `pod 'QITechIosOCR', '~> 8.2.0'` | :::info iOS Minimum Deployment Target 15.5 ::: :::danger 在搭载 arm64 芯片的 MacBook 上使用模拟器 目前，我们的 iOS OCR SDK 不幸不支持在搭载 **arm64 架构芯片**（M1/M2/M3/M4）的 MacBook 上运行的模拟器中编译，**除非使用 Rosetta**，它能将 x86_64 架构转换为 arm64。 ::: 要开始安装，请在您的项目根目录运行旁边的命令。 > 在 podfile 中添加 source ```ruby source 'https://github.com/QITechSDKs/iOS.git' ``` 下一步是在 `podfile` 文件中添加 QI Tech 的 source。 > 在 podfile 中添加 pod ```ruby pod 'QITechIosOCR', '~> ' ``` 最后，只需按照旁边的格式添加 `pod` 名称。 :::danger 注意： 架构变更（v6.0.0+）从 6.0.0 版本开始，SDK 改为仅以静态方式分发。在您的 Podfile 中，必须使用配置 :linkage => :static。 ::: > podfile 示例（6.0.0 或更高版本） ```ruby source 'https://github.com/QITechSDKs/iOS.git' source 'https://cdn.cocoapods.org/' target 'ExampleApp' do use_frameworks! :linkage => :static pod 'QITechIosOCR', '~> 8.2.0' end post_install do |installer| installer.pods_project.targets.each do |target| if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name) target.build_configurations.each do |config| config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0' config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' end end end end ``` > podfile 示例（早期版本） ```ruby source 'https://github.com/QITechSDKs/iOS.git' source 'https://cdn.cocoapods.org/' target 'ExampleApp' do use_frameworks! pod 'QITechIosOCR', '~> 4.0.0' end post_install do |installer| installer.pods_project.targets.each do |target| if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name) target.build_configurations.each do |config| config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0' config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES' end end end end ``` :::warning 注意 在 iOS 中集成依赖项时，可能需要对某些库使用静态链接，对其他库使用动态链接。此配置对于确保兼容性、避免构建错误和优化项目性能至关重要。 ::: ### 混合依赖链接（如有必要） 混合链接的需求源于某些库有特定要求：一些库需要静态链接以避免内部冲突和符号重复，而另一些依赖项可能需要动态链接，因为它们是为模块化和项目间共享而设计的。 静态链接与动态链接的区别 * 静态（static_framework）：库代码直接嵌入到最终二进制文件中，减少运行时加载时间，并消除执行期间的外部依赖。 * 动态（dynamic_framework）：库在运行时作为单独文件加载。这减少了最终二进制文件的大小，并便于独立更新/修改。 > 在 Podfile 中配置混合链接 ```ruby ... use_frameworks! :linkage => :dynamic # 将默认链接模式配置为动态 ... static_frameworks = ['framework_1', 'framework_2', ...] # 包含所有需要静态链接的依赖项 pre_install do |installer| installer.pod_targets.each do |pod| if static_frameworks.include?(pod.name) def pod.static_framework?; true end def pod.build_type; Pod::BuildType.static_framework end end end end ``` > 安装依赖项 ```shell pod install ``` 最后，执行 `pod install` 命令下载并安装依赖项。 ## 必要权限 为使 SDK 能够访问设备资源以采集照片，需要向用户请求权限。 在 **info.plist** 文件中，添加以下权限： | 权限 | 原因 | | ---------------------------------- | ---------------------------------------- | | Privacy - Camera Usage Description | 访问摄像头以采集文档照片。 | ## 启动 SDK ```swift import QITechIosOcr class ViewController: UIViewController, QITechIosOcrControllerDelegate { var qitechOcrConfiguration : QITechIosOcrConfiguration? override func viewDidLoad() { super.viewDidLoad() self.setupOcr() } func setupOcr() -> Void { // The environment can be 'Sandbox' ou 'Production' let environment = QITechIosOcrEnvironment.Sandbox // MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken. let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" // The documentFlow can be 'CnhFull', 'CnhFrontAndBack', 'RgFrontAndBack' or 'RgCinDigital' let documentFlow = QITechIosOcrDocumentFlow.CnhFrontAndBack self.ocrConfig = QITechIosOcrConfiguration(environment: environment, mobileToken: mobileToken, sessionId: "UNIQUE_SESSION_ID", documentFlow: documentFlow, backgroundColor: "#000000", fontColor: "#FFFFFF", fontFamily: .open_sans, showIntroductionScreens: true, logLevel: .debug ) } // Event where you intend to call QI Tech OCR View Controller - on this example, when the user press 'next' button @IBAction func pressNext(_ sender: Any) { let qitechOcrController = QITechIosOcrController(ocrConfiguration: self.ocrConfig) qitechOcrViewController.delegate = self let qitechOcrViewController = qitechOcrController.getViewController() present(qitechOcrViewController, animated: true, completion: nil) } // Do something if QI Tech OCR's SDK succesfully collected document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults results: QITechIosOcrControllerResponse) { } // Do something if QI Tech OCR's SDK found any error when collecting document picture func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) { } // Do something if the user canceled the picture collection on any steps func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) { } } ``` 要将 SDK 嵌入您的应用，需要通过 **QITechIosOcrConfiguration** 类配置自定义采集应用，然后将自定义配置作为参数实例化 **ViewController QITechIosOcrController**。 要启动文档分析流程，只需调用 _present_ 函数来调用 QI Tech 的 ViewController 进行图片采集。 重要的是实现 _Delegate_，负责在成功、错误或用户在验证的任何步骤中断流程时接收返回值。 旁边提供了完整的实现示例。 :::info **注意** 在您的应用中启用 _Portrait_ 和 _Landscape Right_ 方向支持，以确保 SDK 正常运行。 ::: ## Mobile Token 我们使用 Mobile Token 允许您的应用对我们的 API 进行身份验证访问。它可能已通过电子邮件发送给您。如果您尚未收到 Token，请发送电子邮件至 suporte.caas@qitech.com.br 。 我们的 API 期望在所有来自 SDK 的服务器请求中接收 Mobile Token，因此必须通过前面提到的方法将其作为配置参数必选包含。 :::info **注意** 您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。 ::: --- # 获取返回结果 URL: /zh-Hans/documentation/caas/ocr/react_native/collecting_response :::warning 注意 在 Android 和 iOS 上，`startOcr` 的 _Promise_ 解析出的都是 **JSON 字符串**。访问字段前必须调用 `JSON.parse()`。TypeScript 中声明的类型为 `OCR_RETURN_VALUES | string`。 ::: ## 返回结构 ```typescript type OCR_RETURN_VALUES = { DocumentRecognitionResponse: { ocr_key?: string; ocr_front_key?: string; ocr_back_key?: string; document_type: string; }[]; }; ``` | 属性 | 类型 | 说明 | |----------|------|-----------| |ocr_key|string|图像识别密钥，出现在单次采集的证件中（`cnh_full`、`cnh_digital`、`proof_of_address`、`rg_cin_digital`）。可在 QI Tech 系统的任何其他服务中使用。| |ocr_front_key|string|正面图像的识别密钥，出现在双次采集的证件中（`cnh`、`rg`、`rne`、`crnm`）。| |ocr_back_key|string|背面图像的识别密钥，出现在双次采集的证件中（`cnh`、`rg`、`rne`、`crnm`）。| |document_type|string|标识该密钥对应的证件（例如 `"cnh"`、`"rg"`、`"proof_of_address"`）。| :::info **重要** 请保存返回的密钥——它们是该图像在 QI Tech 系统其他产品（例如 Onboarding API）中的标识符。 ::: ### 单次采集的证件 ```json { "DocumentRecognitionResponse": [ { "ocr_key": "5d0f0e1c-8f9e-4b6c-9c3d-2f8a1b4e7c10", "document_type": "cnh_full" } ] } ``` ### 双次采集的证件 ```json { "DocumentRecognitionResponse": [ { "ocr_front_key": "5d0f0e1c-8f9e-4b6c-9c3d-2f8a1b4e7c10", "document_type": "cnh" }, { "ocr_back_key": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "document_type": "cnh" } ] } ``` ## 读取返回结果的示例 ```tsx startOcr(CAAS_ENVIRONMENT.SANDBOX, mobileToken, CAAS_DOCUMENT_TYPE.CNH) .then((response) => { const { DocumentRecognitionResponse } = JSON.parse(response as string); if (DocumentRecognitionResponse.length === 1) { const { ocr_key, document_type } = DocumentRecognitionResponse[0]; console.log('Ocr key: ' + ocr_key + ' document type: ' + document_type); } else if (DocumentRecognitionResponse.length === 2) { const { ocr_front_key } = DocumentRecognitionResponse[0]; const { ocr_back_key } = DocumentRecognitionResponse[1]; console.log('Ocr front key: ' + ocr_front_key + ' / Ocr back key: ' + ocr_back_key); } }) .catch((error) => { console.log('Error executing Ocr. Error: ' + error); }); ``` ## 错误处理 当用户中断流程或原生 SDK 发生错误时，_Promise_ 会被 reject。 | 场景 | 错误信息 | |----------|----------| |用户取消了流程|`User canceled OCR`| |iOS 原生 SDK 发生错误|`Error executing OCR: <详情>`| |原生模块未正确链接|`The package 'react-native-qi-tech-module' doesn't seem to be linked...`| :::info **注意** 如果遇到链接错误，请确认您在 iOS 上执行了 `pod install`、在安装包之后重新构建了应用，并且没有在未执行 `prebuild` 的 _Expo managed workflow_ 中运行。 ::: --- # 兼容性 URL: /zh-Hans/documentation/caas/ocr/react_native/compatibility `@qitech/react-native-caas` 模块要求以下最低版本： | 配置 | 最低版本 | |------------|--------------| |React Native|0.74| |React|18.2.0| |iOS|15.5| |Android API Level|35（Android 15）| |原生 Datadog SDK（iOS，由模块引入）|3.x| |MLKit FaceDetection（iOS，如果您的应用已使用）|8.x| ## 当前包版本 | 包 | 版本 | |--------|--------| |`@qitech/react-native-caas`|`11.3.0`| |`@qitech/react-native-device-scan`|`1.2.0`| :::warning 注意 我们的 iOS SDK 仅支持在启用 **Rosetta**（转译 x86_64 架构）的 **arm64** 架构机器（M1/M2/M3/M4）上运行模拟器。我们建议使用真机进行测试。 ::: ## Expo 该包内置了 Expo _config plugin_，可自动应用 iOS 和 Android 的原生配置。参见[安装](/documentation/caas/ocr/react_native/installation)。 :::info **注意** 该模块无法在未执行 `prebuild` 的 _Expo managed workflow_ 中工作——必须使用 `npx expo prebuild` 生成原生工程。 ::: --- # 实现 URL: /zh-Hans/documentation/caas/ocr/react_native/example `startOcr` 函数会打开原生的证件采集流程，将图像发送至 QI Tech 的 OCR API，并返回已处理图像的密钥。 ## Mobile Token 我们使用 Mobile Token 让您的应用以已认证的方式访问我们的 API。它通常已经通过邮件发送给您。如果您尚未收到您的 token，请发送邮件至 suporte.caas@qitech.com.br 。 :::info **注意** 每个环境（`SANDBOX` 和 `PRODUCTION`）需要不同的 Mobile Token。 ::: ## 函数签名 ```javascript const result = await startOcr( environment, // CAAS_ENVIRONMENT mobile_token, // string document, // CAAS_DOCUMENT_TYPE options // OcrOptions（可选） ); ``` 自定义项是可选的，通过 `options` 对象传入，详见 [OcrOptions 对象](/documentation/caas/ocr/react_native/ocr_options)。 ## 最小示例 ```tsx import { CAAS_ENVIRONMENT, CAAS_DOCUMENT_TYPE, startOcr } from '@qitech/react-native-caas'; const response = await startOcr( CAAS_ENVIRONMENT.SANDBOX, '', CAAS_DOCUMENT_TYPE.CNH ); const { DocumentRecognitionResponse } = JSON.parse(response); console.log(DocumentRecognitionResponse); ``` :::warning 注意 `startOcr` 的 _Promise_ 解析出的是 **JSON 字符串**，而不是对象。必须对返回值调用 `JSON.parse()`。参见[获取返回结果](/documentation/caas/ocr/react_native/collecting_response)。 ::: ## 完整示例 ```tsx import * as React from 'react'; import { View, Button } from 'react-native'; import { CAAS_ENVIRONMENT, CAAS_DOCUMENT_TYPE, CAAS_FONT_FAMILY, CAAS_LOG_LEVEL, startOcr, } from '@qitech/react-native-caas'; const config = { ocrMobileToken: '', environment: CAAS_ENVIRONMENT.SANDBOX, sessionId: '', fontColor: '#5dcfe3', backgroundColor: '#f5f3f0', fontFamily: CAAS_FONT_FAMILY.VERDANA, showIntroductionScreens: true, showSuccessScreen: true, logLevel: CAAS_LOG_LEVEL.DEBUG, }; export default function App() { const [documentType] = React.useState(CAAS_DOCUMENT_TYPE.CNH); const startDocumentOcr = () => { startOcr(config.environment, config.ocrMobileToken, documentType, { session_id: config.sessionId, font_color: config.fontColor, background_color: config.backgroundColor, font_family: config.fontFamily, show_introduction_screens: config.showIntroductionScreens, show_success_screen: config.showSuccessScreen, onboarding_text_configuration: { onboarding_title: 'Dicas Importantes', onboarding_first_label: 'Vá para um local iluminado', onboarding_second_label: 'Retire o documento do plástico', onboarding_third_label: 'Garanta que o documento está corretamente enquadrado', }, log_level: config.logLevel, }) .then((response) => { const { DocumentRecognitionResponse } = JSON.parse(response as string); if (DocumentRecognitionResponse.length === 1) { const { ocr_key, document_type } = DocumentRecognitionResponse[0]; console.log('Ocr key: ' + ocr_key + ' document type: ' + document_type); } else if (DocumentRecognitionResponse.length === 2) { // 正反面流程返回两个密钥，每张照片各一个 const { ocr_front_key } = DocumentRecognitionResponse[0]; const { ocr_back_key } = DocumentRecognitionResponse[1]; console.log('Ocr front key: ' + ocr_front_key + ' / Ocr back key: ' + ocr_back_key); } }) .catch((error) => { console.log('Error executing Ocr. Error: ' + error); }); }; return (