快速入门
快速入门
支持的系统和硬件版本：
| 项目 | 要求 |
|---|---|
| DevEco Studio | 5.0.0 及以上 |
| HarmonyOS SDK | API 12 及以上 |
| 编译 SDK | 5.0.0(12) |
| 目标设备 | phone |
| 运行系统 | HarmonyOS 5.0 及以上 |
开发包说明
1aip-ocr-harmonyos-sdk.zip // OCR SDK 包，包括文档、sample 工程、SDK 核心库
2|- sample/ // sample 示例工程
3|- libs/ // lib 库，包括 .har 包
4| |- ocr-core.har // 核心模块
5| |- ocr-online.har // 在线识别能力模块
6|- docs/ // 说明文档SDK 以 HAR 形式提供，可以通过 oh-package.json5 依赖引入，Sample 工程使用 DevEco Studio 打开。
为您自己的工程添加必要的依赖
在应用模块的 oh-package.json5 中添加：
1{
2 "dependencies": {
3 "@baidu/ocr-core": "file:./libs/ocr-core.har",
4 "@baidu/ocr-online": "file:./libs/ocr-online.har"
5 }
6}@baidu/ocr-online 通过副作用导入触发能力注册。使用识别接口前必须在任意入口执行一次 import '@baidu/ocr-online'，否则会得到 UNSUPPORTED_OCR_TYPE 错误。
为您自己的工程添加必要的权限
在 src/main/module.json5 中添加：
1"requestPermissions": [
2 {
3 "name": "ohos.permission.INTERNET"
4 },
5 {
6 "name": "ohos.permission.CAMERA",
7 "reason": "$string:permission_camera_reason",
8 "usedScene": {
9 "abilities": ["YourAbility"],
10 "when": "inuse"
11 }
12 }
13]各个权限的用途说明见下表：
| 名称 | 用途 |
|---|---|
ohos.permission.INTERNET |
应用联网，发送请求数据至服务器，获得识别结果 |
ohos.permission.CAMERA |
调用相机进行拍照（仅使用扫描模式时需要） |
ohos.permission.CAMERA 声明必须包含 reason 字段，否则系统不会弹出权限弹窗。SDK 不会主动申请相机权限，业务方需在调用扫描接口前自行调用 abilityAccessCtrl 完成权限申请。
放置资源文件（仅使用身份证识别时需要）
如果需要身份证自动采集质量检测，将以下文件放到 src/main/resources/rawfile/ 下：
- License 文件（如
ocr_license.ini） - 身份证质量检测模型目录（如
baiducard/）
不使用身份证识别的应用可跳过此步骤。License 用于身份证质量检测模型的离线鉴权，与在线 API 鉴权是两个独立体系。
Sample 使用说明
SDK 包中提供了一个可快速运行的 Sample 工程，位于 sample/ 目录，已经集成了 SDK 核心库、在线能力模块和默认采集 UI。使用 DevEco Studio 5.0+ 打开工程根目录即可导入。
| 项目 | 值 |
|---|---|
| 模块路径 | sample/entry/ |
| 入口页面 | DemoPage.ets |
| 入口 Ability | DemoAbility.ets |
| 最低 API 版本 | API 12 |
| 目标设备 | phone、tablet |
| IDE | DevEco Studio 5.0+ |
| 构建工具 | hvigor |
| 包管理器 | ohpm |
| 签名 | 需配置自动签名（Project Structure -> Signing Configs） |
| 鉴权方式 | access_token（从 rawfile 的 local.properties 读取） |
配置步骤
- 复制
sample/entry/src/main/resources/rawfile/local.properties.example为local.properties，填入真实 access_token：
1# 通过 API Key + Secret Key 换取的 token
2access_token=YOUR_REAL_ACCESS_TOKEN- 如需验证身份证自动采集，将 License 文件与模型目录放到
sample/entry/src/main/resources/rawfile/下：
| 资源 | 路径 |
|---|---|
| License 文件 | sample/entry/src/main/resources/rawfile/license.txt |
| 模型目录 | sample/entry/src/main/resources/rawfile/baiducard_models/ |
- 在 DevEco Studio 中配置自动签名：File -> Project Structure -> Signing Configs，勾选 Automatically generate signature，登录华为开发者账号完成签名。
- 选择目标设备（真机或模拟器），选择
entry模块作为运行目标，点击 Run 按钮。
首次运行成功标志：页面显示"初始化成功，支持 N 种类型"。
若运行提示身份验证错误，可能是您还未填写正确的 access_token，或者是还未在百度智能云控制台绑定 HarmonyOS 应用的 bundleName。如何绑定 bundleName 请参考 身份验证与安全 章节。
身份验证与安全
百度 AI 开放平台使用 OAuth2.0 授权调用开放 API，调用 API 时必须在请求中携带鉴权凭据。凭据可用 access_token、AK/SK、IAM API Key 或自定义 Token 提供器方式获得。HarmonyOS SDK 已经为您做了封装，当初始化完毕后，所有识别请求会自动携带鉴权信息，无需业务方在每次调用时手动传入。
OCR HarmonyOS SDK 提供了以下 4 种在线 API 鉴权方式，选其一即可。
| 方式 | 参数键 | 适用场景 | 安全性 | 优先级 |
|---|---|---|---|---|
| IAM API Key | IAM_API_KEY |
企业级权限管理 | 高 | 1（最高） |
| access_token | ACCESS_TOKEN |
快速验证、开发调试 | 中 | 2 |
| API Key + Secret Key | API_KEY + SECRET_KEY |
服务端中转下发 | 高 | 3 |
| 自定义 Token 提供器 | AUTH_TOKEN_PROVIDER |
企业自有鉴权中心，动态获取 token | 取决于实现 | 4（最低） |
优先级含义：当同时传入多种鉴权参数时，SDK 按上表从高到低选取第一个有效值。示例：同时设置了 IAM_API_KEY 和 ACCESS_TOKEN，SDK 使用 IAM_API_KEY 鉴权。
身份证质量检测能力 License（仅身份证需要）
除了包含远程API调用能力外，鸿蒙SDK中还集成了身份证识别的本地质量控制能力，提供给开发者本地检测身份证的功能。如果使用身份证正面/反面识别（ID_CARD_FRONT / ID_CARD_BACK），且需要自动采集质量检测功能，则还需配置 License 文件。License 用于身份证质量检测模型的离线鉴权，与在线 API 鉴权是两个独立体系，不参与上表的优先级判定。
| 项目 | 说明 |
|---|---|
| 是否必须 | 仅使用身份证识别且需要自动采集时必须。不使用身份证则完全不需要 |
| 配置位置 | 通过 OcrOptions.initParams 设置 |
| 文件位置 | 放置在 src/main/resources/rawfile/ 下 |
| 绑定方式 | 绑定应用 bundleName 和签名指纹 |
| 失败影响 | License 不可用时身份证退回手动拍照，不影响其他所有识别类型 |
方式 1：IAM API Key
使用百度智能云 IAM 体系的 API Key 进行鉴权，凭据以 Authorization: Bearer 头形式发送。
1const options = new OcrOptions();
2options.putParam(OnlineAuthParams.IAM_API_KEY, 'your_iam_api_key');
3
4await OnlineOcrClient.getInstance().initializeAsync(context, options);特点：
| 项目 | 说明 |
|---|---|
| 权限粒度 | 支持 IAM 策略精细控制 |
| 端侧刷新 | 有。SDK 内建缓存与后台刷新机制，长期驻留友好 |
| 适用场景 | 企业级多部门、多应用权限隔离 |
| 安全建议 | 通过 IAM 控制台管理密钥生命周期 |
方式 2：通过 access_token
此方案使用由 AK/SK 换取的短期 token，通常在服务端获取后下发到端侧。
1import common from '@ohos.app.ability.common';
2import {
3 OnlineOcrClient, OcrOptions, OcrInitResult,
4 OnlineAuthParams
5} from '@baidu/ocr-core';
6import '@baidu/ocr-online';
7
8async function initOcrSdk(context: common.Context, accessToken: string): Promise<void> {
9 const options = new OcrOptions();
10 options.putParam(OnlineAuthParams.ACCESS_TOKEN, accessToken);
11
12 const result: OcrInitResult = await OnlineOcrClient.getInstance()
13 .initializeAsync(context, options);
14
15 console.info(`OCR SDK 初始化完成，支持 ${result.getSupportedTypes().length} 种能力`);
16}特点：
| 项目 | 说明 |
|---|---|
| 有效期 | 30 天（以百度云实际策略为准） |
| 获取方式 | 服务端调用百度云鉴权接口，用 AK/SK 换取后下发 |
| 端侧刷新 | 无。SDK 不自动续期，过期后需重新 initializeAsync |
| 安全建议 | 由服务端获取后下发给端侧，不要在端侧直接存储 AK/SK |
方式 2：通过 API Key / Secret Key
直接传入 AK/SK，SDK 内部完成 token 换取并自动刷新。
1const options = new OcrOptions();
2options.putParam(OnlineAuthParams.API_KEY, 'your_api_key');
3options.putParam(OnlineAuthParams.SECRET_KEY, 'your_secret_key');
4
5await OnlineOcrClient.getInstance().initializeAsync(context, options);特点：
| 项目 | 说明 |
|---|---|
| 自动刷新 | SDK 内部管理 token 生命周期，临近过期自动续期 |
| 安全建议 | 密钥应存储在服务端，通过安全通道下发，不建议硬编码在端侧代码 |
方式 4：自定义 Token 提供器
当业务有特殊的 token 管理需求（如企业自有鉴权中心、动态切换鉴权通道），可通过自定义提供器接入。
1const options = new OcrOptions();
2options.putParam(OnlineAuthParams.AUTH_TOKEN_PROVIDER, 'your_provider_identifier');
3
4await OnlineOcrClient.getInstance().initializeAsync(context, options);身份证质量检测 License 配置
License 不属于在线 API 鉴权方式，而是身份证质量检测模型的独立离线授权。通过 OcrOptions.initParams 配置：
1import {
2 OcrInitParams, OnlineAuthParams, OnlineOcrTypes
3} from '@baidu/ocr-core';
4import { IdCardInitParams } from '@baidu/ocr-online';
5
6const options = new OcrOptions();
7// 先设置在线 API 鉴权（4 种方式选一）
8options.putParam(OnlineAuthParams.ACCESS_TOKEN, 'your_token');
9
10// 再设置身份证质量检测 License（仅使用身份证时需要）
11const idCardInit = new OcrInitParams();
12idCardInit.putParam(IdCardInitParams.LICENSE_KEY, 'your_license_key');
13idCardInit.putParam(IdCardInitParams.LICENSE_NAME, context.resourceDir + '/ocr_license.ini');
14idCardInit.params.set(IdCardInitParams.LICENSE_IS_REMOTE, true);
15idCardInit.putParam(IdCardInitParams.RESOURCE_DIR_PATH, context.resourceDir + '/baiducard');
16
17options.initParams.set(OnlineOcrTypes.ID_CARD_FRONT.value(), idCardInit);
18options.initParams.set(OnlineOcrTypes.ID_CARD_BACK.value(), idCardInit);
19
20await OnlineOcrClient.getInstance().initializeAsync(context, options);License 绑定应用 bundleName 和签名指纹，攻击者即使拦截了流量、盗取了授权文件，也难以盗用您的配额。不使用身份证识别的应用完全不需要配置以上 License 相关参数。
鉴权流程
1initializeAsync(context, options)
2 |
3 v
4按优先级选取在线 API 鉴权方式
5 |
6 +-> IAM_API_KEY 存在？使用 IAM Bearer 鉴权
7 |
8 +-> ACCESS_TOKEN 存在？直接使用该 token
9 |
10 +-> API_KEY + SECRET_KEY 存在？SDK 内部换取 token
11 |
12 +-> AUTH_TOKEN_PROVIDER 存在？调用自定义提供器
13 |
14 +-> 均未配置？抛出 AUTH_ERROR
15 |
16 v
17注册识别能力（身份证 License 在此阶段校验）
18 |
19 +-> initParams 中有身份证 License：初始化质量检测模型
20 | +-> 成功：身份证自动采集可用
21 | +-> 失败：身份证退回手动拍照（其他类型不受影响）
22 |
23 +-> 无身份证 License：跳过（其他类型正常可用）最小识别示例
初始化完成后，即可发起一次身份证识别：
1import {
2 OnlineOcrClient, OcrType, OcrError, OcrJSONCallback,
3 OcrCaptureOptions, CaptureMode
4} from '@baidu/ocr-core';
5import { OnlineOcrTypes, IdCardParams } from '@baidu/ocr-online';
6
7function scanIdCard(abilityContext: common.UIAbilityContext): void {
8 const captureOptions = new OcrCaptureOptions();
9 captureOptions.setCaptureMode(CaptureMode.AUTO);
10
11 const params = new IdCardParams();
12
13 OnlineOcrClient.getInstance().scanForJSON(
14 abilityContext,
15 OnlineOcrTypes.ID_CARD_FRONT,
16 captureOptions,
17 params,
18 {
19 onSuccess(responseJSON: string): void {
20 // responseJSON 为服务端完整 JSON 响应
21 console.info('识别成功: ' + responseJSON);
22 },
23 onFailure(error: OcrError): void {
24 console.error(`识别失败: code=${error.code}, message=${error.message}`);
25 },
26 onCanceled(): void {
27 console.info('用户取消');
28 }
29 } as OcrJSONCallback
30 );
31}页面销毁或不再使用时释放资源：
1OnlineOcrClient.getInstance().release();完成上述步骤后即可运行工程，跑通一次完整的采集识别流程。
评价此篇文章