HarmonyOS 接入
更新时间:2026-10-09
HarmonyOS 接入
1. 接入流程
- 开通验证码服务后,在控制台添加验证场景,获取该场景分配的业务
ak(AccessKey); - 在 HarmonyOS 应用中集成验证码 SDK;
- 在业务页面中调用验证码 SDK 拉起验证,SDK 通过回调返回验证令牌(token,即
stk); - 应用将 token 传入验证码服务端进行验签。
2. 接入方式
HarmonyOS 端支持两种接入方式,请根据业务形态选择:
| 接入方式 | 说明 | 适用场景 | 参考文档 |
|---|---|---|---|
| ① Web 组件加载 H5 页面 | 在应用内通过 Web 组件加载验证码 H5 页面,通过 JS 桥接获取验证结果 | 已有 Web 组件业务页面、希望复用 H5 接入逻辑 | 见《Web/H5 接入》 |
| ② 原生客户端集成 | 集成验证码 HarmonyOS SDK(HAR 包),通过 YMGCaptchaDialogClass 拉起验证 |
原生应用、需要原生交互体验 | 见本文档以下内容 |
- 两种方式的验证结果(
stk)与服务端验签流程完全一致,均参见《服务端接入》。
3. SDK 方案说明
验证码 HarmonyOS SDK(HarmonyOS NEXT)本质上是对 H5 验证码能力的原生封装,在保留 Web 端安全对抗能力的同时,提供原生调用体验。
- 通过 Web 组件承载验证页面,监听并拦截验证成功的回调,完成与 H5 验证逻辑的双向通信;
- 技术选型:ArkTS + Web 组件 + 不依赖 UI 组件的全局自定义弹出框;
- 以 HAR 包形式交付,支持滑块、数字点选、文字点选、轨迹绘制等多种验证形态;
- 验证逻辑与对抗策略基于 SaaS 架构在云端统一维护、自动更新。
4. SDK 集成方式
1. 添加 SDK 依赖
将产物 BehaviorVerifyStaticLibrary_xxx.har 放到模块目录下(如 libs),然后在项目的 oh-package.json5 中的 dependencies 节点下添加 SDK 依赖:
Plain Text
1"@antibot/ymgbehaviorverify": "file:./libs/BehaviorVerifyStaticLibrary_xxx.har",
2. 配置权限
验证码服务需要网络访问,如宿主工程尚未声明网络权限,请在 entry/src/main/module.json5 中添加:
Plain Text
1{ "module": {
2 "requestPermissions": [
3 { "name": "ohos.permission.INTERNET" }
4 ]
5} }
3. 混淆配置
如工程开启了代码混淆(ArkGuard),请保留 SDK 相关类与资源。
5. SDK 控件接口说明
验证码 Dialog 实现类:
TSX
1/**
2 验证码 Dialog 实现类
3 */
4class YMGCaptchaDialogClass{
5 /** 开启验证码dialog方法
6 @param context : 页面 UI 上下文(UIContext),通过 this.getUIContext() 获取
7 @param handleCaptchaToken: 验证成功后,验证码token通过该函数回调。
8 @param handleDismiss: 点击返回键,返回手势,点击对话框外蒙层导致验证码对话框消失的事件通过该函数回调,reason取值见官方文档:
9 https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-promptaction#dismissreason12%E6%9E%9A%E4%B8%BE%E8%AF%B4%E6%98%8E
10 @param ak: 验证码业务 ak
11 @param ext: 与服务器约定的额外信息,可为空
12 @param ctype: 验证码类型,可为空
13 @param subid:业务场景ID,即子渠道号,若需要子渠道号维度报表,则需要配置此项
14 */
15 static openDialog(context: UIContext,
16 handleCaptchaToken: ((token: string) => void),handleDismiss: ((reason: number) => void)|null, ak: string,
17 ext: string | null, ctype: string | null, subid: string | null)
18
19 /**
20 关闭验证码dialog方法
21 */
22 static closeDialog()
23}
openDialog 参数说明:
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| context | UIContext | 是 | 页面 UI 上下文,通过组件的 this.getUIContext() 获取 |
| handleCaptchaToken | (token: string) => void | 是 | 验证成功回调,入参为验证码令牌(即《服务端接入》文档中的 stk),业务需将其提交至服务端二次校验 |
| handleDismiss | (reason: number) => void | null | 否 |
| ak | string | 是 | 控制台为验证场景分配的业务 AccessKey |
| ext | string | null | 否 |
| ctype | string | null | 否 |
| subid | string | null | 否 |
6. SDK 集成代码参考
TSX
1import { YMGCaptchaDialogClass } from '@antibot/ymgbehaviorverify';
2import { hilog } from '@kit.PerformanceAnalysisKit';
3
4@Entry
5@Component
6struct Index {
7 @State message: string = '触发验证码';
8 @State token: string = 'token';
9 private ak = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
10
11 handleCaptchaToken(tokenstr: string): void {
12 this.token = tokenstr;
13 this.message = '触发验证码';
14 }
15
16 handleDismiss(dismissReason: number): void {
17 hilog.info(0x0000, 'testTag', 'handleDismiss dismissReason:' + dismissReason);
18 }
19
20 build() {
21 RelativeContainer() {
22 Text(this.message)
23 .id('ShowDialog')
24 .fontSize($r('app.float.page_text_font_size'))
25 .fontWeight(FontWeight.Bold)
26 .alignRules({
27 center: { anchor: '__container__', align: VerticalAlign.Center },
28 middle: { anchor: '__container__', align: HorizontalAlign.Center }
29 })
30 .onClick(() => {
31 this.message = '验证码触发成功';
32 YMGCaptchaDialogClass.openDialog(this.getUIContext(), this.handleCaptchaToken.bind(this),
33 this.handleDismiss.bind(this), this.ak, "", "", "");
34 })
35 Text(this.token)
36 .id('token')
37 .fontSize($r('app.float.token_font_size'))
38 .fontWeight(FontWeight.Bold)
39 .alignRules({
40 middle: { anchor: '__container__', align: HorizontalAlign.Center },
41 top: { anchor: 'ShowDialog', align: VerticalAlign.Bottom }
42 })
43 .onClick(() => {
44 this.message = this.message + "_";
45 this.token = this.token + "_";
46 })
47 }
48 .height('100%')
49 .width('100%')
50 }
51}
7. Token 与服务端验签
- 验证成功后,
handleCaptchaToken回调返回验证码令牌 token(即《服务端接入》文档中的stk); - 应用将 token 提交至业务服务端(传输方式由业务自定义,如请求体字段);
- 业务服务端调用验证码服务端
/v1/webapi/verint/verifystk接口完成二次校验,具体加解密流程与请求/响应格式见《服务端接入》; - 仅当服务端验签返回
pass == true时,才允许放行业务流程(注册、登录、领券等)。
安全提示:客户端回调结果不可作为最终放行依据,必须以服务端验签结果为准。
评价此篇文章
