uni-app x 鸿蒙原生工程集成实人认证（uni-facialverify）完整指南

uni-app x 鸿蒙原生工程集成实人认证uni-facialverify完整指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-app x 的实人认证模块uni_modules/uni-facialverify提供金融级实人认证能力通过对比人脸、活体检测、姓名和身份证号确认用户身份。本篇指南面向需要在HarmonyOS 原生工程中手动集成该模块的开发者讲解 har 依赖配置、uni_modules 入口注册的完整步骤含 VDOM 模式与蒸汽模式两种写法并结合仓库源码补充 API 参数、错误码与端到端调用示例帮助你在鸿蒙 App 中原生接入实人认证能力。一、模块背景实人认证与两个核心 API在 uni-app x 中实人认证由两个客户端 API 组成对应的鸿蒙实现位于uni_modules/uni-facialverifyhar 包内uni.getFacialRecognitionMetaInfo()获取阿里云实人认证 meta info供服务端换取 certifyId 使用uni.startFacialRecognitionVerify(faceStyle)携带 certifyId 启动人脸识别活体检测页面。在标准 uni-app x 编译流程中只要在manifest.json内勾选了对应鸿蒙模块编译产物unpackage/dist/dev/app-harmony/libs/uni_modules__uni_facialverify.har会自动生成并且产物目录会生成对应的index.generated.ets与oh-package.json5。本指南针对手动把鸿蒙原生工程与编译产物合并的场景需要自行完成 har 拷贝、依赖声明与 API 注册三步。相关背景可参考 鸿蒙模块集成总览。二、配置依赖har 包的获取与声明2.1 获取 har 产物uni_modules/uni-facialverify未发布到鸿蒙官方 ohpm 仓库需要自行从任意 uni-app x 项目编译到鸿蒙的产物中拷贝产物路径unpackage/dist/dev/app-harmony/libs/uni_modules__uni_facialverify.har目标位置鸿蒙原生项目的libs目录与oh-package.json5同级的libs目录2.2 声明依赖在鸿蒙原生工程根目录的oh-package.json5文件dependencies字段下添加uni_modules/uni-facialverify: ./libs/uni_modules__uni_facialverify.har./libs/...为相对工程根目录的路径请确保拷贝后 har 文件实际存在于该位置。此处oh-package.json5即鸿蒙原生工程根目录的/oh-package.json5约定同 modules.md。三、注册模块在 uni_modules 入口注册 API实人认证 API 需要注册到 uni 全局对象上才能在页面中通过uni.startFacialRecognitionVerify/uni.getFacialRecognitionMetaInfo调用。注册位置为鸿蒙原生工程内的 uni_modules 入口文件index.generated.ets位于/entry/src/main/ets/uni_modules/index.generated.ets如果文件不存在请自行创建见 modules.md。原文档提供了两种渲染模式下的注册写法二者仅导入的 runtime 包不同注册逻辑一致。3.1 VDOM 模式注册import { registerUniProvider, uni } from dcloudio/uni-app-x-runtime; import { startFacialRecognitionVerify, getFacialRecognitionMetaInfo } from uni_modules/uni-facialverify export function initUniModules() { initUniExtApi(); } function initUniExtApi() { uni.startFacialRecognitionVerify startFacialRecognitionVerify uni.getFacialRecognitionMetaInfo getFacialRecognitionMetaInfo }3.2 蒸汽模式Vapor注册import { registerUniProvider, uni } from dcloudio/uni-app-x-vapor-runtime; import { startFacialRecognitionVerify, getFacialRecognitionMetaInfo } from uni_modules/uni-facialverify export function initUniModules() { initUniExtApi(); } function initUniExtApi() { uni.startFacialRecognitionVerify startFacialRecognitionVerify uni.getFacialRecognitionMetaInfo getFacialRecognitionMetaInfo }3.3 入口调用注册函数需要在应用启动时被调用。在鸿蒙工程的entry/src/main/ets/entryability/EntryAbility.ets中添加import { initUniModules } from ../uni_modules/index.generated initUniModules()这是鸿蒙 uni_modules 的统一接入约定其他模块地图、推送、三方登录等同样通过initUniModules()完成注册详见 modules.md。四、API 详解与参数说明注册完成后即可在页面中调用实人认证 API。以下参数与错误码信息来自 docs/api/facial-recognition-meta-info.md。4.1 uni.getFacialRecognitionMetaInfo()获取阿里云实人认证 meta info用于服务端换取 certifyId。该 API 在 Web 端需 4.84、Android 3.9、iOS 4.11、HarmonyOS 4.61 及以上版本支持。4.2 uni.startFacialRecognitionVerify(faceStyle)启动人脸识别活体检测。参数faceStyle类型为StartFacialRecognitionVerifyOptions属性如下| 名称 | 类型 | 必填 | 默认值 | 描述 | | :- | :- | :- | :- | :- | | certifyId | string | 是 | - | 调用实人认证的 id由服务端下发 | | progressBarColor | string | 否 | - | 活体检测页面的进度条颜色HarmonyOS 暂不支持 | | screenOrientation | string | 否 | port | 认证时屏幕方向HarmonyOS 暂不支持 | | success | (res) void | 否 | - | 成功回调 | | fail | (res) void | 否 | - | 失败回调 | | complete | (res: any) void | 否 | - | 完成回调 |screenOrientation合法值land横屏、port竖屏。4.3 错误码 errCode认证失败时通过 fail 回调返回常见错误码| 错误码 | 含义 | | :- | :- | | 10001 | certifyId 不能为空 | | 10002 | 当前设备不支持 | | 10010 | 刷脸异常 | | 10011 | 验证中断 | | 10012 | 网络异常 | | 10013 | 刷脸验证失败 | | 10020 | 设备设置时间异常 |五、端到端调用示例客户端 云端以下完整示例来自仓库演示工程 src/pages/API/facial-recognition-meta-info/facial-recognition-meta-info.uvue展示了「获取 metaInfo → 云端换 certifyId → 本地刷脸 → 云端取认证结果」的完整链路template !-- #ifdef APP -- scroll-view classpage-scroll-view !-- #endif -- view page-head :titletitle/page-head view classuni-padding-wrap uni-common-mt view classuni-btn-v uni-common-mt input classuni-input typetext v-modelrealName namereal-name placeholder姓名 / /view view classuni-btn-v uni-common-mt input classuni-input typetext v-modelidCard nameid-card placeholder身份证号 / /view view classuni-btn-v uni-common-mt button typeprimary clickfacialRecognition开始人脸识别/button /view /view /view !-- #ifdef APP -- /scroll-view !-- #endif -- /template script setup languts const title ref(实人认证) const realName ref() const idCard ref() const facialRecognition () { const realNameValue realName.value.trim() const idCardValue idCard.value.trim() if (realNameValue || idCardValue ) { uni.showModal({ title: 错误, content: 姓名和身份证号不可为空, showCancel: false }) return } if (production process.env.NODE_ENV __UNI__HelloUniAppX uni.getAppBaseInfo().appId) { uni.showModal({ title: 提示, content: 实人认证为收费功能当前环境暂不支持。请在HBuilderX中新建Hello uni-app x项目真机运行体验, showCancel: false }) return } const testFacialCo uniCloud.importObject(facial-recognition-co) let metaInfo uni.getFacialRecognitionMetaInfo(); testFacialCo.getCertifyId({ realName: realNameValue, idCard: idCardValue, metaInfo }) .then((res : UTSJSONObject) : Promisestring { const certifyId res[certifyId] as string return new Promise(( resolve : (res : string) void, reject : (err : Error) void ) { uni.startFacialRecognitionVerify({ certifyId, success() { resolve(certifyId) }, fail(err) { reject(new Error(err.errMsg)) } }) }) }) .then((certifyId : string) : PromiseUTSJSONObject { return testFacialCo.getAuthResult(certifyId) }) .then((res : UTSJSONObject) { console.log(res, res) }) .catch((err : any | null) { console.error(error, err) }) } /script调用链路要点客户端调用uni.getFacialRecognitionMetaInfo()拿到 metaInfo通过uniCloud.importObject(facial-recognition-co)调用云端对象方法getCertifyId传入姓名、身份证号与 metaInfo换取certifyId客户端调用uni.startFacialRecognitionVerify({ certifyId })启动活体检测在 success 回调中 resolve刷脸成功后调用云端getAuthResult(certifyId)获取最终认证结果。六、使用注意事项实人认证为收费功能涉及业务开通与付费同时涉及客户端和服务端交互业务开通、流程与付费详见 uniCloud 侧实人认证介绍文档见 facial-recognition-meta-info.md 开篇说明。检查手机端摄像头权限请使用uni.getAppAuthorizeSetting相关说明见 get-app-authorize-setting.md。从 HBuilderX 3.99 起标准基座真机运行可直接体验实人认证涉及扣除开发者费用无需自定义基座。Android 端实人认证仅支持armeabi-v7a与arm64-v8aCPU 类型其他 CPU 类型设备调用uni.getFacialRecognitionMetaInfo()会返回空字符串调用uni.startFacialRecognitionVerify()会触发错误码10002当前设备不支持的回调集成时建议做兼容降级处理。在manifest.json勾选模块的对应关系可参考 manifest-modules.md模块名为uni-facialRecognitionVerify即包含上述两个 API。七、小结在鸿蒙原生工程中集成实人认证核心步骤可归纳为三步拷贝 har 产物并声明依赖 → 在index.generated.ets注册 API → 在EntryAbility.ets调用initUniModules()。完成注册后即可按照「metaInfo → certifyId → 刷脸 → 取结果」的链路调用uni.getFacialRecognitionMetaInfo与uni.startFacialRecognitionVerify完成完整的实人认证流程。若使用编译产物自动生成的index.generated.ets与oh-package.json5则无需手动处理依赖与注册可直接参考鸿蒙模块集成总览modules.md完成工程合并。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考