uni-app x 鸿蒙HarmonyOS原生工程集成一键登录uni-verify模块实战指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本文以 uni-app 开源仓库中的 鸿蒙一键登录模块文档 为核心骨架系统讲解如何将 uni-app x 的 App 一键登录能力uni-verify模块接入鸿蒙原生工程。内容涵盖 har 依赖包的获取与声明、index.generated.ets入口注册含 VDOM / 蒸汽两种运行时、uni.getUniVerifyManager()客户端 API 的完整用法预登录、标准登录、自定义页面登录、关闭授权页、预登录有效性判断以及运营商合规规范与错误码排查体系。读完本文你将能够在鸿蒙原生项目中独立完成一键登录模块的集成、注册与联调。一、模块概述一键登录在鸿蒙平台的形态App 一键登录是 uni-app x 提供的能力它封装了个推的一键登录 SDK其内部再次封装了中国移动、中国联通、中国电信三大运营商提供的 SDK。在手机 SIM 卡信号正常的情况下通过运营商云端接口即可获取当前用户的手机号实现点一下直接以当前手机号登录无需短信验证码详见 uni.getUniVerifyManager() API 文档。在鸿蒙平台上该能力以独立模块uni_modules/uni-verify形式存在。与 Android/iOS 通过 Gradle/CocoaPods 依赖不同鸿蒙侧的模块以har 包Harmony Archive为载体需要开发者从 uni-app x 项目的编译产物中获取后手动集成到鸿蒙原生工程中。从仓库源码看鸿蒙平台一键登录 API 的兼容版本为HarmonyOS 4.61| 方法 | Web | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | |uni.getUniVerifyManager()| x | 4.42 | 4.42 | 4.61 | |preLogin| x | 3.99 | 4.18 | 4.61 | |login| x | 3.99 | 4.18 | 4.61 | |customLogin| x | 4.41 | 4.41 | 4.71 | |close| x | 3.99 | 4.18 | 4.61 | |isPreLoginValid| x | 3.99 | 4.18 | 4.61 |该 API 不支持 Web 平台请将示例工程运行到 App 平台体验。二、配置依赖获取并声明 uni-verify 的 har 包2.1 依赖包来源鸿蒙一键登录依赖的 har 包为uni_modules/uni-verify。需要注意该 har 包未发布到鸿蒙官方包管理仓库 ohpm无法直接通过ohpm install安装需要自行到任意 uni-app x 项目编译到鸿蒙的产物中拷贝典型产物路径为unpackage/dist/dev/app-harmony/libs/uni_modules__uni_verify.har将上述 har 文件拷贝到鸿蒙原生项目中惯例放置于工程的libs/目录。2.2 在 oh-package.json5 中声明依赖在鸿蒙原生项目根目录的oh-package.json5文件的dependencies字段下添加本地依赖声明uni_modules/uni-verify: ./libs/uni_modules__uni_verify.har完整片段示意{ dependencies: { uni_modules/uni-verify: ./libs/uni_modules__uni_verify.har } }同样的集成思路可参考鸿蒙平台的 Push 模块uni-push、地图模块、三方登录uni-oauth、实人认证、支付uni-pay、定位 等文档——它们均遵循har 拷贝 oh-package.json5 声明的统一范式。三、注册模块在 index.generated.ets 中注册一键登录 API3.1 入口文件约定按照 鸿蒙平台 modules 总览文档 的约定index.generated.ets鸿蒙原生工程内的 uni_modules 入口文件位于/entry/src/main/ets/uni_modules/index.generated.ets如果没有请自行创建在 uni-app 项目manifest.json内已勾选对应鸿蒙模块时编译产物unpackage/dist/dev/app-harmony/uni_modules目录下会生成对应的index.generated.ets和oh-package.json5可参考相关文档将这两个文件集成进鸿蒙项目还需要在鸿蒙项目的entry/src/main/ets/entryability/EntryAbility.ets文件中调用入口初始化函数import { initUniModules } from ../uni_modules/index.generated initUniModules()3.2 注册代码两种运行模式在index.generated.ets内注册一键登录 API。uni-app x 鸿蒙端存在两套运行时注册代码略有差异VDOM 模式默认运行时依赖dcloudio/uni-app-x-runtimeimport { registerUniProvider, uni } from dcloudio/uni-app-x-runtime; import { getUniVerifyManager } from uni_modules/uni-verify export function initUniModules() { initUniExtApi() } function initUniExtApi() { uni.getUniVerifyManager getUniVerifyManager }蒸汽模式Vapor 模式依赖dcloudio/uni-app-x-vapor-runtimeimport { registerUniProvider, uni } from dcloudio/uni-app-x-vapor-runtime; import { getUniVerifyManager } from uni_modules/uni-verify export function initUniModules() { initUniExtApi() } function initUniExtApi() { uni.getUniVerifyManager getUniVerifyManager }两种模式的差异仅在运行时导入来源VDOM 模式从dcloudio/uni-app-x-runtime导入蒸汽Vapor模式从dcloudio/uni-app-x-vapor-runtime导入其余逻辑完全一致——通过initUniExtApi()将uni_modules/uni-verify导出的getUniVerifyManager挂载到全局uni对象上从而在业务代码中可通过uni.getUniVerifyManager()调用。四、客户端 APIuni.getUniVerifyManager() 完整用法模块注册完成后业务代码即可使用 uni.getUniVerifyManager() 获取一键登录管理对象UniVerifyManager。4.1 命名规范变更HBuilderX 4.41从 HBuilderX 4.41 起该 API 及类型命名做了规范化调整旧的uni.getUniverifyManager()已废弃请改用uni.getUniVerifyManager()参数类型统一增加UniVerifyManager前缀如PreLoginOptions→UniVerifyManagerPreLoginOptionsLoginOptions→UniVerifyManagerLoginOptionsCustomLoginOptions→UniVerifyManagerCustomLoginOptions以及PreLoginSuccess/PreLoginFail/PreLoginComplete/LoginSuccess/LoginFail/LoginComplete等回调类型均同步改名调整原因是未来会增加更多登录方式一键登录的参数类型占用通用名称LoginOptions不合适注意在 4.41 以前的版本仍需使用无前缀的老类型名称一般情况下开发者无需手动as返回值类型uni-app x 会自动推导类型。4.2 UniVerifyManager 的方法一览| 方法 | 说明 | HarmonyOS 兼容版本 | | :- | :- | :- | |preLogin(options)| 预登录提前获取脱敏手机号等运营商信息 | 4.61 | |login(options)| 标准登录拉起框架预置的授权页 | 4.61 | |customLogin(options)| 自定义授权页登录开发者自绘登录界面 | 4.71 | |close()| 关闭授权页仅支持标准登录 | 4.61 | |isPreLoginValid()| 预登录是否有效返回boolean| 4.61 |4.3 预登录 preLogin预登录用于在真正登录前提前与运营商网关建立会话并获取展示信息。参数UniVerifyManagerPreLoginOptions支持三个回调success成功回调结果UniVerifyManagerPreLoginSuccess包含number手机号脱敏显示slogan运营商 slogan如移动中国移动提供认证服务、联通认证服务由联通统一认证提供、电信天翼账号提供认证服务privacyName运营商隐私协议名称HarmonyOS 4.71如中国移动认证服务条款等privacyUrl运营商隐私协议 url 地址HarmonyOS 4.71。fail失败回调错误对象UniVerifyManagerPreLoginFail含errCode、errSubject、data、cause、errMsgcomplete无论成败均触发的完成回调。4.4 标准登录 loginlogin(options)使用 uni-app 框架预置的授权页全屏/半屏两种模板页面已遵守运营商规范。参数UniVerifyManagerLoginOptions核心字段uniVerifyStyle登录页样式UniVerifyManagerLoginStyle包含fullScreen是否全屏logoPathlogo 路径backgroundColor登录页背景色HarmonyOS 4.71loginBtnText登录按钮文字。success/fail/complete回调旧字段univerifyStyleUniVerifyManagerLoginStyle已废弃建议使用uniVerifyStyle。登录成功回调UniVerifyManagerLoginSuccess返回openId登录授权唯一标识accessTokentoken。4.5 自定义页面登录 customLogincustomLogin(options)HBuilderX 4.41HarmonyOS 4.71允许开发者自绘授权页。参数UniVerifyManagerCustomLoginOptions要求传入五个 UI 元素的UniElement对象| 参数 | 组件要求 | 说明 | | :- | :- | :- | |numberTextElement| text 组件 | 号码栏展示含掩码的手机号 | |sloganTextElement| text 组件 | 品牌露出运营商 slogan | |loginButtonElement| button 组件 | 登录按钮 | |privacyCheckBoxElement| checkbox 组件 | 隐私确认 | |privacyTextElement| text 组件 | 隐私标题协议名称 |关于五个 UI 要素的运营商合规规范详见本文第六节。4.6 关闭与状态判断close()关闭授权页仅支持标准登录isPreLoginValid()判断预登录是否仍有效返回boolean。典型流程是先判断预登录是否有效无效则先preLogin成功后再执行login。五、实战流程从预登录到取号登录结合 hello uni-app x 的一键登录示例 中的完整 uvue 代码该 API 不支持 Web请运行到 App 平台体验一个规范的鸿蒙端一键登录流程如下const uniVerifyManager ref(null as UniVerifyManager | null) // 预登录 const preLogin (callback: (() void)) { uniVerifyManager.value?.preLogin({ success: (res) { phone.value res.number; slogan.value res.slogan; privacyName.value res.privacyName; privacyUrl.value res.privacyUrl; callback(); }, fail: (err) { // 读取 cause 链中的详细错误描述 const hasCauseMessage (err.cause?.cause?.message ?? ).length 0 uni.showModal({ title: 预登录失败, content: hasCauseMessage ? JSON.parseObject(err.cause?.cause?.message ?? )?.getString(errorDesc) : err.errMsg, showCancel: false }); } }); } // 标准登录 const login (fullScreen: boolean) { uniVerifyManager.value?.login({ uniVerifyStyle:{ fullScreen: fullScreen, loginBtnText: 一键登录, logoPath: /static/logo.png }, success: (res) { // 用 openId accessToken 到服务端换取手机号 takePhoneNumber(res.accessToken, res.openId); }, fail: (err) { // 处理失败 } }); } const verify (fullScreen: boolean) { // 校验预登录是否有效 const isPreLoginValid uniVerifyManager.value?.isPreLoginValid() ?? false; if (isPreLoginValid) { login(fullScreen); } else { preLogin(() { login(fullScreen); }) } } onLoad(() { uniVerifyManager.value uni.getUniVerifyManager(); preLogin(() { }); })登录成功后客户端拿到的是openId与accessToken注意手机号不会直接返回给客户端需要调用云函数如uniCloud.callFunction携带这两个凭证在服务端换取真实手机号完成登录闭环const takePhoneNumber (accessToken: string, openId: string) { uniCloud.callFunction({ name: univerify, data: { access_token: accessToken, // 客户端一键登录接口返回的access_token openid: openId // 客户端一键登录接口返回的openid } }).then(res { uniVerifyManager.value?.close(); // 关闭登录页 // 从 res.result 中读取 phoneNumber }).catch(err { uniVerifyManager.value?.close(); }); }六、标准登录与自定义登录运营商合规规范三大电信运营商对一键登录在 App 端的使用有一套强制规范开发者必须遵守否则会被停止认证取号服务。uni-app x 提供两种合规使用方式6.1 标准登录loginuni-app 框架预置了全屏和半屏的界面模板该页面已遵守运营商规范流程先调用预登录成功后调用login拉起授权页登录成功后通过close关闭页面优点方便快捷、无需开发界面 UI缺点预置页面无法自定义。6.2 自定义页面登录customLogin预登录成功后返回 4 项内容number带掩码的手机号、slogan运营商品牌、privacyName运营商协议名称、privacyUrl运营商协议在线地址。开发者必须根据运营商规范在自己页面上呈现这些信息。运营商规范要求授权页面必须有 5 个 UI 要素含掩码的手机号码numberTextElement从预登录接口获取必须使用 text 组件 呈现运营商品牌sloganTextElement从预登录接口获取必须使用 text 组件 呈现同意协议的 checkboxprivacyCheckBoxElement自行使用 checkbox 组件 构造不可默认勾选必须由终端用户手动勾选协议名称privacyTextElement从预登录接口获取必须使用 text 组件 呈现放置在privacyCheckBoxElement后面样式需有可点击效果点击后需通过 webview 打开运营商的在线协议地址privacyUrl登录按钮loginButtonElement自行使用 button 组件 实现必须包含登录或注册等文字不得诱导用户授权必须由终端用户手动点击不可自动发起。红线要求开发者不得通过任何技术手段将上述五个必要元素内容隐藏、覆盖或动态变更对已上线应用运营商会对授权页面做审查若发现未按要求弹出或设计授权页面将关闭应用的认证取号服务在登录按钮点击事件内调用customLogin入参传入上述五个 UI 元素的UniElement对象uni-app x 框架会校验这些元素是否遵守运营商规范不符合规范会抛出错误见错误码表符合规范才继续调用运营商接口若使用三方 UI 库的 checkbox 和 button 组件可能无法获取正确的UniCheckboxElement和UniButtonElement建议改用 uni-app x 的标准内置组件登录成功后通过uni.navigateBack()或uni.closeDialogPage()等方式关闭授权页。自定义页面可配合 dialogPage 弹出。七、错误处理与错误码体系7.1 统一错误对象与 cause 链无论预登录还是登录失败时返回的 uni Error 错误对象都含有一个cause属性它表示底层错误来源包含了个推 SDK 和运营商 SDK 的详细信息如没有 SIM 卡、未开启蜂窝网络等。开发时应把这些详细错误提示给用户引导其正确使用一键登录const hasCauseMessage (err.cause?.cause?.message ?? ).length 0 content: hasCauseMessage ? JSON.parseObject(err.cause?.cause?.message ?? )?.getString(errorDesc) : err.errMsg7.2 uni 层 errCode 错误码| 错误码 | 说明 | | :- | :- | | 1000 | 当前应用 appid 尚未开通 uni 一键登录 | | 1001 | 应用所有者账号信息异常请检查账号一键登录服务是否正常 | | 1002 | 应用所有者账号信息异常请检查账号余额是否充足 | | 1004 | uni 一键登录应用不存在 | | 4001 | 参数异常 | | 30001 | 取消登录Android/iOS 4.51HarmonyOS 4.61 | | 30004 | 其他错误 | | 30005 | 预登录失败 | | 30006 | 一键登录失败 | | 30007 | 预登录失效 | | 30008 | 上一个请求正在进行中请稍后重试 | | 40001 | 自定义授权页面未同意隐私条款HarmonyOS 4.71 | | 40002 | 自定义授权页不合规请参考文档修改HarmonyOS 4.71 |7.3 个推 SDK 错误码cause 中的 getui 层错误码错误信息-10000sdk 没有初始化请先初始化 sdk-10001sdk 初始化失败详见整体 msg 内容-10003接口请求超时请稍后重试、加大超时时间或者检查网络-10006上一个请求正在进行中请稍后重试-10009其他错误详见整体 msg 内容-20100传入参数错误-20101appid 为空请检查 GETUI_APPID 配置-20102appid 无效或者签名无效-20104预登录无效请先进行预登录-20200无网络可用请检查手机网络、或者稍后重试-20201未插手机电话卡-20202未开启蜂窝网络-20203不支持的运营商-20301登录授权页退出-20500获取运营商 APPID 失败请重启应用重试、或者联系技术支持-30001服务器返回的其他错误-40001运营商返回的其他错误更多明细错误码移动 102101200087、联通 1003066、电信 -6480801可在 uni.getUniVerifyManager() 文档 中查阅完整表格。常见问题包括手机没有 SIM 卡-20201 / 200002 / 200010、蜂窝网络未开启-20202 / 102103 / 200027、卡欠费导致数据解析异常102223 / 200021、取号限额105021、余量不足105312等。八、鸿蒙平台权限与模块摇树说明8.1 隐私合规权限鸿蒙端一键登录涉及用户隐私需在鸿蒙工程的module.json5中配置ohos.permission.APP_TRACKING_CONSENT权限具体权限声明以鸿蒙工程实际配置为准。8.2 模块与摇树treeShaking从 modules 模块配置文档 可知uni-verify是 uni-app x 的内置模块HBuilderX 3.99对应 API 为uni.getUniverifyManager()、UniverifyManager.preLogin、UniverifyManager.login无额外依赖模块HBuilderX 4.63 之前鸿蒙平台不支持根据使用情况自动添加模块4.63 及之后版本支持摇树代码中没有引用一键登录 API 时模块会被剔除打包自定义基座时若工程代码未调用一键登录相关 API打出的自定义基座将不包含该模块功能在这些基座上运行时调用会报错。此时需要在工程中写入相关调用代码后重新打包自定义基座注意uni-verify 属于provider机制之外的普通内置模块不涉及三方 provider 手动配置与 uni-location、uni-payment、uni-oauth 等需要手动配置 provider 的模块不同。8.3 与其他平台的对照参考若需在Android 原生工程中集成同一能力可参考 Android 平台 uni-verify 文档其依赖本地 aaruni-verify-release.aar、GY-3.1.6.3-release.aar与个推线上依赖com.getui:gtc-dcloud:3.2.16.7并通过build.gradle的GETUI_APPID、GY_APP_ID占位符配置一键登录应用 ID再按 VDOM / 蒸汽模式分别注册UTSMethodRegister或UTSEasyCom插件。鸿蒙与 Android 的差异本质在于Android 通过 Gradle 依赖 manifest 占位符鸿蒙通过 har 包 oh-package.json5 声明 index.generated.ets注册。九、常见问题与使用建议一键登录并非 100% 成功手机没有 SIM 卡、蜂窝网络未开启、当时没有蜂窝网信号是最常见原因详见上方错误码列表。无法使用时建议转为短信验证码登录兜底相关降级逻辑可参考 uni-id 体系的完整实现。收费与基座一键登录涉及业务开通和付费支持标准基座真机运行费用扣除开发者的费用无需自定义基座。隐私合规自定义授权页必须让用户手动勾选隐私协议、手动点击登录按钮不可默认勾选、不可自动发起否则面临运营商停服风险。调试提示遇到失败时优先读取err.cause?.cause?.message中的errorDesc字段它包含了个推 SDK 与运营商 SDK 的详细原因比 uni 层 errMsg 更能定位问题。版本注意HarmonyOS 平台customLogin、privacyName/privacyUrl等能力需要 HBuilderX 4.714.41 之前的 API 与类型命名不同请按实际 HBuilderX 版本查阅对应文档。十、延伸阅读鸿蒙平台 modules 总览含 index.generated.ets 与 oh-package.json5 约定uni.getUniVerifyManager() API 完整文档含全部错误码与示例代码modules 模块配置与摇树说明鸿蒙平台 manifest 模块配置Android 平台 uni-verify 集成对照文档鸿蒙平台 Push 模块har 集成同范式【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考