更新记录

1.0.0（2026-11-10）

• 初始版本

当前版本 1.0.0（2026-11-10），内置阿里云金融级实人认证 SDK 2.3.54。

• 支持 Android / iOS / HarmonyOS 三端，三端 SDK 二进制已随插件内置
• init：初始化 SDK（IPv4 / IPv6），返回 SDK 版本号
• getMetaInfo：获取设备 metaInfo，交业务服务端换取 certifyId
• verify：用 certifyId 拉起刷脸认证页，回调 code / subCode / message / videoFilePath / faceImage
• 证件 OCR 三端一致：Android / iOS 由 SDK 内置，鸿蒙初始化时自动注册 OcrFeature
• 扩展参数：活体视频、进度颜色、OCR 按钮颜色、语言、取景框大小、水波纹样式、屏幕方向、extraJson 透传
• 统一错误码 9290001~9290008，认证失败时保留 SDK 原始结果码

平台兼容性

uni-app(4.72)

uni-app x(4.72)

zy-aliyun-verify 阿里云金融级实人认证

支持的功能

阿里云「金融级实人认证（ID Verification）」客户端 SDK 的 UTS 封装，三端 SDK 二进制（2.3.54）已内置在插件目录中，开箱可用。

提供的能力：

• SDK 初始化 init：支持 IPv4 / IPv6，返回 SDK 版本号；须在用户同意隐私政策后调用
• 获取设备信息 getMetaInfo：返回 metaInfo（JSON 字符串），交给业务服务端换取 certifyId
• 发起刷脸认证 verify：用服务端下发的 certifyId 拉起 SDK 认证页
• 证件 OCR：三端均已集成（鸿蒙端初始化时自动 OcrFeature.install() 注册），业务侧无需额外调用
• 扩展参数：活体视频、进度条颜色、OCR 按钮颜色、显示语言、取景框大小、水波纹样式、屏幕方向，另支持 extraJson 原样透传原生参数
• 统一结果：code / subCode / message / certifyId / videoFilePath / faceImage / rawJson
• 统一错误码：9290001~9290008，认证失败时仍保留 SDK 原始 code、subCode

使用方法

1. 引入

import { init, getMetaInfo, verify } from '@/uni_modules/zy-aliyun-verify'

2. 整体流程

App                         业务服务端                    阿里云
 |-- init() -------------------|                            |
 |-- getMetaInfo() ----------->|                            |
 |                             |-- InitFaceVerify(metaInfo, 姓名, 证件号) -->|
 |<-------- certifyId ---------|                            |
 |-- verify(certifyId) -----------------------------------> |  刷脸页
 |<------------- code / subCode --------------------------- |
 |                             |-- DescribeFaceVerify -----> |  最终结果

姓名、证件号、AccessKey、服务端签名参数等敏感信息严禁放在客户端。

3. init(options)

init({
  ipv6: false,
  success: (res) => console.log('初始化成功', res.sdkVersion),
  fail: (err) => console.error(err.errCode, err.errMsg)
})

4. getMetaInfo(options)

getMetaInfo({
  autoInit: true,
  success: (res) => {
    // res.metaInfo 上传到业务服务端，换取 certifyId
  },
  fail: (err) => console.error(err.errCode, err.errMsg)
})

5. verify(options)

verify({
  certifyId: '服务端返回的 certifyId',
  useMessageBox: true,
  extParams: { useVideo: true, faceCircleSize: 'M' },
  success: (res) => {
    // 仅代表采集流程成功，最终结果需服务端查询
    console.log(res.code, res.subCode, res.videoFilePath)
  },
  fail: (err) => {
    console.error(err.errCode, err.code, err.subCode, err.errMsg)
  }
})

extParams

成功结果

6. 错误码

SDK 常见结果码：1000 采集成功（仅供参考，是否计费：是）、1001 系统错误、1003 验证中断、2002 网络错误、2003 设备时间错误、2006 认证未通过。 常用子码：Z1008 用户退出、Z1013 活体不通过、Z1019 摄像头权限未赋予、Z1036 未调用 install、Z1037 certifyId 为空、Z5120 认证通过、Z5128 认证未通过。

7. 使用注意

1. certifyId 一次性使用，每次认证前必须由服务端重新获取；
2. success 的 1000 只代表采集成功，最终结论以服务端 DescribeFaceVerify 为准；
3. metaInfo 必须用真机真实数据，禁止硬编码或跨设备复用；
4. Android 拉起认证前需已授予 CAMERA 权限；iOS 首次由系统弹窗申请；
5. 三端均不支持模拟器，必须用自定义基座调试；
6. iOS 自定义基座 / 云打包需带 -ObjC 链接参数；
7. 三端 OCR 能力一致：Android / iOS 由 SDK 内置模块提供，鸿蒙在初始化时自动调用 OcrFeature.install() 注册，业务侧都无需额外调用；若删除 utssdk/app-harmony/libs/ocrverify.har，鸿蒙端将无法走证件识别流程；
8. screenOrientation、ocrButtonColor 在 iOS 端不生效（iOS SDK 未提供对应参数），其余扩展参数三端一致；
9. NFC 读卡能力仅 Android（aliyun-nfc）与 iOS（DTFNFCIdentityManager）具备，鸿蒙 SDK 未提供 NFC har，认证方案里若配置 NFC 采集，鸿蒙端不支持。