更新记录

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()：Android/iOS 直接 orcInit；鸿蒙 getVerifyToken 后 orcInit({ accessToken })
  initOcr()
})

// 身份证正面
scanIdFront({
  auto: true,
  success: async (res) => {
    if (res.code != 200) {
      uni.showToast({ title: res.msg || '识别失败，请对准证件重新拍摄', icon: 'none' })
      return
    }
    const d = res.idFront
    name.value = d?.name
    idcard.value = d?.idNumber
    await uploadIdcardImageFront({ image: res.imgbase64 })
    orcRelease({})
  },
  fail: (err) => {
    uni.showToast({ title: err.errMsg, icon: 'none' })
    orcRelease({})
  }
})

// 银行卡
scanBankCard({
  auto: false,
  success: (res) => {
    const bankCard = res.bankCard?.bankCardNumber
    const bankName = res.bankCard?.bankName
    orcRelease({})
  },
  fail: (err) => {
    uni.showToast({ title: err.errMsg, icon: 'none' })
    orcRelease({})
  }
})

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

API

orcInit(options)

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

orcRelease(options)

释放自动采集模型。Android 识别后建议调用（防个别机型无法释放）；iOS / 鸿蒙可作幂等清理。

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。
• 存储权限不可加 maxSdkVersion（XXPermissions / uni.chooseImage 要求全版本可声明）。
• 自定义基座或云打包后验证。

3. iOS

• 鉴权用 Bundle 内 license + auth(withLicenseFileData:)，不需要 accessToken。
• 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 分支。
• Android 识别后建议 orcRelease；识别失败 / 取消分支也建议调用，避免模型占用。
• 用户可见文案禁止出现 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，版权归北京百度网讯科技有限公司，遵循百度智能云服务协议；商用请自行开通并合规使用
• 使用本插件产生的业务与合规责任由接入方自行承担