更新记录

2.1.2（2026-10-19） 下载此版本

修复

• iOS 识别回包即崩溃（真机 SIGABRT）：SDK 回调参数声明为 ObjC id，运行时给的是原生 NSDictionary，而 result as UTSJSONObject 被 UTS 编成 Swift as!，动态转换失败直接 abort（崩溃栈 swift_dynamicCastFailure → unimoduleBinBdocr.handleIdCard）。身份证 / 银行卡 / 营业执照三处解析全部改为官方写法 new UTSJSONObject(result!) + getString(keyPath) 取值，插件内不再对 SDK 回调对象做 as 断言
• Android 系统权限框没有用途说明：相机权限改在 scan* 入口走 UTSAndroid.requestSystemPermission（识别时序变为 权限 → SDK 初始化 → 打开采集页）。百度 CameraActivity 内部那次裸 ActivityCompat.requestPermissions 不广播权限申请事件，宿主的权限用途说明浮层收不到这条链路，华为 / 应用宝合规审核会判「无说明弹系统框」

变更

• Android 授权与否不再采信 requestSystemPermission 回调的 allRight（它会把已授予的项从清单里剔除后回失败），统一以 ContextCompat.checkSelfPermission 为准
• 权限被永久拒绝（shouldShowRequestPermissionRationale 为 false）时 9030002 文案改为「相机权限已被禁止，请在系统设置中开启后重试」，指向设置页；系统还愿意再问时保持原文案
• iOS 字段取值兜底链补齐为 words_result.<key>.word → .words → .number → words_result.<key> → 顶层 <key>

文档

• readme 修正快速开始示例里与 2.1.1「模型常驻、orcRelease 只在页面退出时调一次」自相矛盾的写法（旧示例在识别回调里就 release）
• readme 补充：iOS 禁止 as UTSJSONObject 的硬约束、raw 的三端形态差异、Android 权限链路与判定口径、[bin-bdocr] 前缀日志的真机排查用法

1.0.0（2026-09-30） 下载此版本

首次发布。

• 三端统一 API：orcInit / orcRelease / scanIdFront / scanIdBack / scanBankCard / scanBusinessLicense
• 成功 code 固定 200；归一化字段 idFront / idBack / bankCard / license + raw + imgbase64
• 三端识别层均为百度 OCR 离线 SDK：
  • Android：官方 aip-ocr-android-sdk 2.4.0（ocrsdk.aar + ocr_ui CameraActivity + 身份证质量模型）
  • iOS：官方 aip-ocr-ios-sdk 3.1.1（AipOcrSdk.framework + AipCaptureCardVC / AipGeneralVC）
  • HarmonyOS：官方 aip-ocr-harmonyos-sdk V1.0.0（ocr_core.har + ocr_online.har，scanForJSON 内置采集 UI）
• 错误码 903xxxx，errMsg 为用户可读中文（不暴露 Activity / aar / SDK 术语）
• 鉴权：Android / iOS 用包内 license，不需要 accessToken；鸿蒙必须业务侧传 orcInit({ accessToken })（插件不内置 AK/SK，缺失回 9030004）
• 识别成功返回 imgbase64（无前缀），可直接传 uploadIdcardImageFront/Back 等后端接口
• Android 识别后建议调用 orcRelease 释放自动采集模型
• auto: true 自动识别 / false 手动拍照
• iOS PrivacyInfo.xcprivacy：相机拍摄证件（Name / OtherUserContent，App Functionality，无 Tracking）

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

百度离线 OCR（身份证 / 银行卡 / 营业执照）

面向 uni-app x（含蒸汽模式） 的三端 UTS 离线 OCR 插件。统一 orcInit / scan* API 与结果契约，三端识别层均为百度 OCR 离线 SDK，归一化字段与错误码一致。

功能特性

平台兼容性

• HBuilderX：^3.6.8
• uni-app x：App-Android / App-iOS / App-HarmonyOS（含蒸汽模式）

快速开始

import {
  orcRelease,
  scanIdFront, scanIdBack, scanBankCard, scanBusinessLicense
} from '@/uni_modules/bin-bdocr'
import { initOcr } from '@/utils/ocr-service.js' // 业务侧封装：仅鸿蒙先取 accessToken
import { uploadIdcardImageFront } from '@/api/servers.js'

onLoad(() => {
  // 统一走 initOcr()（utils/ocr-service.js）：Android / iOS 直接 orcInit；鸿蒙先 getVerifyToken 再带 accessToken
  // 返回 Promise 且不会 reject，失败以 { code, msg } 返回；鸿蒙要重取 token 时传 { force: true }
  initOcr()
})

// 身份证正面
scanIdFront({
  auto: true,
  // 采集页关闭后到识别结果返回之间是网络耗时（通常 1~10s），给个加载态
  captured: () => uni.showLoading({ title: '识别中...', mask: true }),
  success: async (res) => {
    uni.hideLoading()
    if (res.code != 200) {
      uni.showToast({ title: res.msg || '识别失败，请对准证件重新拍摄', icon: 'none' })
      return
    }
    const d = res.idFront
    name.value = d?.name
    idcard.value = d?.idNumber
  },
  fail: (err) => {
    uni.hideLoading()
    uni.showToast({ title: err.errMsg, icon: 'none' })
  }
})

// 银行卡
scanBankCard({
  auto: false,
  captured: () => uni.showLoading({ title: '识别中...', mask: true }),
  success: (res) => {
    uni.hideLoading()
    if (res.code != 200) {
      uni.showToast({ title: res.msg || '未识别到银行卡号，请重新拍摄', icon: 'none' })
      return
    }
    cardNo.value = res.bankCard?.bankCardNumber
    bankName.value = res.bankCard?.bankName
  },
  fail: (err) => {
    uni.hideLoading()
    uni.showToast({ title: err.errMsg, icon: 'none' })
  }
})

// 模型进程内常驻，只在页面退出时释放一次；不要在识别回调里 release
onUnload(() => orcRelease({}))

提交类入口建议配合防重复点击（如 throttle）再调用。

API

orcInit(options)

初始化 SDK。页面 onLoad 可调；扫描前也会懒初始化。

orcRelease(options)

释放自动采集模型与本地质量模型。只在页面退出（onUnload）时调一次，不要在每次识别的 success / fail 里调：三端的模型与 token 均为进程内常驻，提前释放会让下一次扫描重新加载模型并重发一次鉴权请求。三端一致：有识别进行中时拒绝释放并回 9030007，不会中断正在进行的识别（clearCache 清的是授权缓存，误清会让下一次识别直接授权失败）。

scanIdFront / scanIdBack / scanBankCard / scanBusinessLicense

打开对应证件采集页，回调触发一次后结束。

ScanOptions

Result

归一化字段

错误码

fail 参数继承 UniError，业务可读 err.errCode / err.errMsg。

接入配置（必读）

打包前确认：应用包名 / BundleId / 签名 MD5 与百度智能云控制台 OCR license 一致。

1. 申请百度 OCR 与 license

1. 开通 百度智能云 OCR，创建应用并申请身份证 / 银行卡 / 营业执照等离线识别能力。
2. 下载 license：Android 文件名须为 aip-ocr.license，iOS 为 aip.license。
3. 如需鸿蒙在线识别，由业务服务端换取 accessToken 后下发客户端（禁止把 AK/SK 打进 App）。

2. Android

• 鉴权用包内 license + initAccessToken，不需要 accessToken。
• 相机权限在 scan* 入口走 UTSAndroid.requestSystemPermission，不要退回采集页内部那次裸 ActivityCompat.requestPermissions：只有前者会广播权限申请事件，宿主的权限用途说明浮层（华为、应用宝上架合规要求）才收得到这条链路。
• 识别时序固定为 权限 → SDK 初始化 → 打开采集页，权限没过来就回 9030002，不再往下走。
• 授权与否一律以 ContextCompat.checkSelfPermission 为准，不要采信 requestSystemPermission 回调的 allRight：它会把已授予的项从申请清单里剔除后再回失败，据此判定会把已授权的相机读成拒绝。系统不再愿意展示说明（勾了「不再询问」）时，9030002 换成指引设置页的文案。
• 存储权限不可加 maxSdkVersion（XXPermissions / uni.chooseImage 要求全版本可声明）。
• 自定义基座或云打包后验证。

3. iOS

• 鉴权用 Bundle 内 license + auth(withLicenseFileData:)，不需要 accessToken。
• 结果解析只用 new UTSJSONObject(回调对象) 加 getString('words_result.姓名.word') 这类 keyPath 取值，禁止写 x as UTSJSONObject：SDK 回调参数声明为 ObjC id，运行时是原生 NSDictionary，该断言被 UTS 编成 Swift as!，动态转换失败直接 abort（真机 SIGABRT 落在 handleIdCard）。字段按 word → words → number → 字段本身 → 顶层键的顺序兜底。
• framework 仅 arm64 真机切片；模拟器用 hybrid.swift 空类满足链接。
• 隐私清单 PrivacyInfo.xcprivacy 已声明相机拍摄证件用途。
• 云打包 / macOS 编译；Windows 本机无法编 iOS。

4. HarmonyOS

• 必须 orcInit({ accessToken })；缺失回 9030004。
• token 来源示例：GET api/xyj/XyjFace/getVerifyToken → data.result.verify_token（由业务后端签发）。
• 推荐业务侧封装（如 utils/ocr-service.js 的 initOcr()）按平台分支，不要裸调 orcInit({})。

5. 三端鉴权差异

插件不内置 AK/SK（安全约束：禁止把百度密钥打进客户端）。

6. 权限

插件已在各端 Manifest / module.json5 声明；宿主商店隐私协议需写明相机拍摄证件用途。iOS 相机文案由宿主 manifest.json 提供（如 NSCameraUsageDescription）。

隐私与个人信息处理

插件本身（bin-bdocr 代码）

三方 SDK（百度 OCR 离线 SDK）

SDK 自身可能采集设备标识与运行日志并上报百度智能云，用于鉴权与服务诊断。详情与合规义务见 百度智能云 服务与隐私条款。

接入方义务

1. 宿主 App 隐私政策写明「相机用于拍摄并识别证件」及百度 OCR SDK 数据处理。
2. 自行申请并绑定包名 / 签名的 license，替换插件内占位文件。
3. 不要把 AK/SK 写进客户端；鸿蒙 token 走服务端换取。

市场申报可直接粘贴（declaration.data）

插件通过相机拍摄身份证、银行卡、营业执照等证件图像，在设备端完成文字识别后经回调返回业务方；识别图 base64 可由业务方自行上传，插件本身不落盘、不外传、不内置百度 AK/SK。三端内置百度 OCR 离线 SDK，SDK 可能采集设备标识与运行日志并上报百度智能云，用途为鉴权与服务诊断；鸿蒙端 accessToken 由业务方服务端签发后传入。详情见百度智能云服务与隐私条款。

目录结构

uni_modules/bin-bdocr/
  package.json
  readme.md
  changelog.md
  utssdk/
    interface.uts              # 类型与 API
    unierror.uts               # 903xxxx 错误码
    app-android/               # 百度 2.4.0：index.uts 直调 SDK + CameraActivity
      assets/aip-ocr.license
      assets/models/
      libs/ocrsdk.aar
      libs/bdocr-ui-release.aar
    app-ios/                   # 百度 3.1.1：index.uts 直调 AipOcrSdk.framework
      Frameworks/              # AipBase / AipOcrSdk / IdcardQuality
      Resources/aip.license
      PrivacyInfo.xcprivacy
    app-harmony/               # 百度 V1.0.0：scanForJSON 内置采集 UI
      libs/ocr_core.har
      libs/ocr_online.har

注意事项

• 仅 App（Android / iOS / HarmonyOS），不支持 Web / 小程序。
• 成功 code 固定 200；success 里仍可能收到非 200 的业务失败（如 9030006），需按 res.code 分支。
• 不要在每次识别成功 / 失败后调 orcRelease：Android 的本地质量模型与 token 都做成进程内常驻，释放后下一次扫描要重新加载模型并重发一次鉴权请求，白等一轮。正确用法是页面 onUnload 里释放一次（对齐 demo 的 onCreate init / onDestroy release）。识别进行中调用 orcRelease 会被拒绝并回 9030007。
• iOS 采集页以 UIModalPresentationStyle.fullScreen present（与 Android 全屏 CameraActivity 对齐；不设置时 iOS 13+ 默认走 pageSheet 卡片式、可下滑半退出）。
• iOS 识别完成 / 失败后由插件主动 dismiss 采集页（SDK 只在用户点关闭时自己关，识别成功后不会自动退出，对齐官方 demo AipOCRIDCardVC.m:117）。因此采集页不会在 OCR 回来后继续挂在页面上转圈。
• iOS 采集页（AipCaptureCardVC / AipGeneralVC）只有 handler(UIImage *)，用户直接退出采集页时 SDK 不会回调，插件收不到取消事件。旧会话由下一次 scan* 入口回收：采集页已消失且 handler 未触发过时，先回 9030009 已取消识别 给上一次调用，再开启新会话；否则仍按 9030007 拒绝。因此调用方不要把「已取消识别」当异常上报。
• Android 退出采集页走 RESULT_CANCELED，识别中另有 30s 超时兜底；iOS 无超时兜底，识别请求挂起时需用户再次点击才回收。
• Android 已把 SDK 的 HTTP 超时从默认 10s 抬到 socketTimeout = 25s（HttpUtil.getOptions()，connect 保持 10s）：百度在线身份证接口实测出现过 10.1s 才回包，贴着默认线会随机抛超时；25s 仍早于插件自身 30s 的识别兜底。
• 真机排查看 [bin-bdocr] 前缀日志：scan.click（iOS：场景 + 有无在途会话 + handler 是否触发过 + 采集页是否还挂着）、scan.stale / scan.blocked（残留会话回收 vs 被 9030007 拒）、camera.permission（Android：框架判定与 uni 判定并打，两者不一致即说明不能信 uni 回调）、recognize.start / recognize.http / recognize.timeout（发出请求到回包的耗时与 30s 兜底）、idcard.fields / bank.fields / license.fields / bank.number.empty（各字段取到的字符长度，「code 为 200 但字段为空」先看这行）。
• 用户可见文案禁止出现 Activity / aar / SDK 等开发向术语（见错误码表）。
• 自定义基座真机建议跑通：initOcr → 身份证正/反 → 银行卡 → 营业执照 → orcRelease。

FAQ

Q：鸿蒙为什么一定要 accessToken？
A：安全约束禁止把百度 AK/SK 打进客户端。鸿蒙走在线鉴权，由业务服务端换 token 后传入；Android / iOS 用包内 license 离线鉴权。

Q：iOS 模拟器编不过 / 识别页打不开？
A：framework 仅 arm64 真机切片，模拟器仅有链接空类。请用真机 + 云打包 / macOS 编译。

Q：识别成功但字段为空？
A：先看 res.raw 是否有值；仍为空按 9030006 / 9030009 引导用户对准证件重拍。检查包名 / 签名是否与 license 一致。

许可与免责

• 插件代码：MIT（驿家安自封）
• 内含百度 OCR Android AAR / iOS framework / 鸿蒙 har，版权归北京百度网讯科技有限公司，遵循百度智能云服务协议；商用请自行开通并合规使用
• 使用本插件产生的业务与合规责任由接入方自行承担