鸿蒙 SDK 接入教程
2024.08.08 17:28:18
全新人机验证方式，高效拦截机器行为，业务安全第一道防线。搭载风险感知引擎，智能切换验证难度，安全性高，极致用户体验。读屏软件深度适配，视障群体也可轻松使用，符合工信部无障碍适配要求
兼容性
| 条目 | 说明 |
|---|---|
| 适配版本 | HarmonyOS 11 及以上版本 |
资源引入
远程仓库依赖
验证码共享包 HAR 发布在 OpenHarmony 三方库中心仓，需要从 OpenHarmony三方中心仓引用。
方式一
在Terminal窗口中，执行如下命令安装三方包，DevEco Studio 会自动在工程的 oh-package.json5 中自动添加三方包依赖
ohpm install @yidun/captcha
方式二
在工程的 oh-package.json5 中设置三方包依赖
"dependencies": {
"@yidun/captcha": "^1.0.2"
}
快速调用示例
@Component
export default struct Test {
private dialogController?: CustomDialogController;
private listener: CaptchaListener = {
onValidate: (result: string, validate: string, _msg: string) => {
if (result === "true") {
AlertDialog.show(
{
title: "验证成功",
message: `校验码为：${validate}`,
alignment: DialogAlignment.Center
}
)
}
},
onError: (code: number, msg: string) => {
AlertDialog.show(
{
title: "验证码报错",
message: `错误code为${code} 错误信息为${msg}`,
alignment: DialogAlignment.Center
}
)
},
onCaptchaShow: () => {
},
onClose:(closeType:CloseType)=>{
}
}
showCaptcha() {
let configuration = new CaptchaConfiguration();
configuration.setCaptchaId("易盾验证码业务id");
configuration.setListener(this.listener);
this.dialogController = new CustomDialogController({
builder: CaptchaDialog({
configuration: configuration
}),
alignment: DialogAlignment.Center,
customStyle: true
})
this.dialogController.open();
}
build() {
Column() {
Text("易盾行为式验证码")
.fontSize("35fp")
.fontWeight(FontWeight.Bold)
Button("显示验证码")
.width("50%")
.height($r('app.float.default_48'))
.backgroundColor($r('app.color.blueColor'))
.type(ButtonType.Capsule)
.stateEffect(true)
.margin({
top: 64
})
.onClick(() => {
this.showCaptcha();
})
}
.width("100%")
.height("100%")
.justifyContent(FlexAlign.Center)
}
}
共享包方法说明
1. 创建验证码自定义弹窗 CaptchaDialog
代码说明
let dialogController: CustomDialogController = new CustomDialogController(
{
builder: CaptchaDialog({
configuration: configuration
})
}
)
CaptchaDialog 接收一个类型为 CaptchaConfiguration 的必要参数作为配置。CaptchaConfiguration具体的可配置项如下
| 配置项 | 参数/类型 | 是否必须 | 默认值 | 描述 |
|---|---|---|---|---|
| setCaptchaId | captchaId:string | 是 | 无 | 业务id |
| setListener | listener:CaptchaListener | 是 | 无 | 回调监听 |
| setMobileTimeout | mobileTimeout:number | 否 | 10s | 超时时间，单位ms |
| setLangType | langType:LangType | 否 | 系统语言 | 语言类型：枚举值 |
| setTheme | theme:Theme | 否 | Theme.LIGHT | 主题：枚举值 |
| setDefaultFallback | defaultFallback:boolean | 否 | true | 是否采用默认降级 |
| setErrorFallBackCount | errorFallBackCount:number | 否 | 3 | 触发降级的最大错误次数，当超过这个错误次数时触发降级 |
| setHideCloseButton | hideCloseButton:boolean | 否 | false | 是否隐藏关闭按钮 |
| setProtocol | protocol:string | 否 | https | 资源加载协议: http 或 https |
| setIpv6 | ipv6:boolean | 否 | false | 网络是否ipv6 |
| setExtraData | extraData:string | 否 | 无 | 额外参数，在二次校验result返回/3.3.3版本加入 |
| setApiServer | apiServer:string | 否 | 无 | 私有化接口域名，私有化部署必须，协议需要和protocol对应 |
| setStaticServer | staticServer:string | 否 | 无 | 私有化资源域名，私有化部署必须，协议需要和protocol对应 |
| setShowInnerClose | showInnerClose:boolean | 否 | false | 是否显示验证码内部关闭按钮 |
| setRadius | radius:number | 否 | 0 | 验证码弹窗圆角弧度 |
| setRefreshInterval | refreshInterval:number | 否 | 300 | 错误提示时长/ms |
| setIsDebug | isDebug:boolean | 否 | true | 是否打开debug日志开关 |
高级 ui 配置
| 配置项 | 参数/类型 | 是否必须 | 默认值 | 描述 |
|---|---|---|---|---|
| setUiParamsJson | uiParamsJson:string | 否 | 无 | 高级 ui json字符串 |
json 字段支持范围如下
{
"customStyles":{
"imagePanel":{
"align":"top", // 仅在 float 模式下有效，可选项为 top 和 bottom，指定 imagePanel 出现在 controlBar 上方还是下方
"borderRadius":"2px", // 边框圆角大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"loadBackgroundImage":"xxx", // 加载中时的背景图片地址，v2.21.4 后新增，需要填入一个 url
"loadBackgroundColor" :"#f00" // 加载中时的背景颜色，v2.21.4 后新增，支持 CSS 所有颜色值
},
"controlBar":{
"height": "40px", // 高度，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em，不支持 %，会影响功能
"borderRadius": "20px", // 边框圆角大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"paddingLeft": "40px", // 左边距，如果相对于整个 bar 居中提示文字，设为 0； v2.21.4 后新增，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、%，不支持 em，会影响功能
"borderColor": "transparent", // 边框颜色，支持 CSS 所有颜色值
"background": "#e1c1ff", // 背景颜色，占满整个 controlBar，支持 CSS 所有颜色值
"borderColorMoving": "#0000ff", // 滑动时已滑动区域边框、滑块颜色，仅在滑动类型验证码下有效，支持 CSS 所有颜色值
"backgroundMoving": "rgba(0, 0, 255, 0.1)", // 滑动时已滑动区域背景颜色，仅在滑动类型验证码下有效，支持 CSS 所有颜色值
"borderColorSuccess": "#00ff00", // 验证成功时边框、文字、滑块背景颜色，如果是滑动，已滑动区域有效，支持 CSS 所有颜色值
"backgroundSuccess": "rgba(0, 255, 0, 0.1)", // 验证成功时背景颜色，如果是滑动，已滑动区域有效，支持 CSS 所有颜色值
"borderColorError": "#ff0000", // 验证失败时边框、文字、滑块背景颜色，如果是滑动，已滑动区域有效，支持 CSS 所有颜色值
"backgroundError": "rgba(255, 0, 0, 0.1)", // 验证失败时背景颜色，如果是滑动，已滑动区域有效，支持 CSS 所有颜色值
"slideBackground": "#fff", // 滑块滑动前背景颜色，支持 CSS 所有颜色值
"textSize": "14px", // 滑块内文本大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem，不支持 em、%，会影响功能
"textColor": "orange", // 滑块内文本颜色（滑块滑动前、失败、成功前的颜色），支持 CSS 所有颜色值
"slideIcon": "", // 滑块滑动前 iocn，需要是一个 url，如果未提供则按照默认icon显示
"slideIconMoving": "", // 滑块滑动过程 iocn，需要一个 url，如果未提供则按照默认 icon 显示
"slideIconSuccess": "", // 滑块验证成功时 iocn，需要一个 url，如果未提供则按照默认 icon 显示
"slideIconError": "" // 滑块验证失败时 iocn，需要一个 url，如果未提供则按照默认 icon 显示
},
"icon": {
"intellisenseLogo": "" // 智能无感知的 icon，需要一个 url，如果未提供则按照默认 icon 显示
},
"gap": "30px", // imagePanel 相对 controlBar 的间距大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"executeBorderRadius": "4px", // imagePanel 右边顶部的操作按钮最外层容器圆角大小，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"executeBackground": "rgba(0, 0, 0, 0.2)", // imagePanel 右边顶部的操作按钮最外层容器背景颜色，支持 CSS 所有颜色值
"executeTop": "4px", // imagePanel 右边顶部的操作按钮最外层容器顶部距离，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
"executeRight": "4px" // imagePanel 右边顶部的操作按钮最外层容器右侧距离，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、rem、em、%
}，
"popupStyles":{
"width": "350px", // 宽度，当传入数字时，默认单位 px；当传入字符串时，支持单位 px、%，v2.21.4 后支持 rem、em
"capBarHeight": "50px", // 弹框头部标题所在容器高度，当传入数字时，默认单位 px；当传入字符串时，支持单位 px，v2.21.4 后支持 rem；不支持 %、em，会影响功能
"capBarTextAlign": "left", // 弹框头部标题文字对齐方式，可选值为 left、center、right
"capBarBorderColor": "#fff", // 弹框头部标题下边框颜色，想要去掉的话可取 transparent 或者与背景色同色，支持 CSS 所有颜色值
"capBarTextColor": "#333", // 弹框头部标题文字颜色，支持 CSS 所有颜色值
"capBarTextSize": 14, // 弹框头部标题文字字体大小，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px、rem；不支持 %、em，会影响功能
"capBarTextWeight": 600, // 弹框头部标题文字字体体重，可设置粗细，也就是 css 样式的 font-weight 属性
"capPadding": 15, // 弹框 imagePanel 与外边框距离，相当于总体设置 capPaddingTop，capPaddingRight，capPaddingBottom，capPaddingLeft，当传入数字时，默认单位 px；当传入字符串时，支持单位 px；不支持 %、rem，em，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"capPaddingTop": 0, // 弹框 imagePanel 与上外边框距离，会覆盖 capPadding 上边距，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"capPaddingRight": 15, // 弹框 imagePanel 与右外边框距离，会覆盖 capPadding 右边距，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"capPaddingBottom": 0, // 弹框 imagePanel 与下外边框距离，会覆盖 capPadding 下边距，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"capPaddingLeft": 15, // 弹框 imagePanel 与左外边框距离，会覆盖 capPadding 左边距，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px，如果传入的单位是 %、rem、em 时，保留数字并强转为 px 单位
"opacity": 0.1, // 弹框遮罩层透明度,0 ~ 1 之间的数字
"radius": 20, // 弹框最外层容器圆角，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px、%、rem，em
"borderColor": "transparent", // 弹框最外层容器边框颜色，想要去掉的话可取 transparent 或者与背景色同色，支持 CSS 所有颜色值
"paddingTop": 20, // 弹框最外层容器上内边距，实践时可与 capPaddingTop 配合，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px、%、rem，em
"paddingBottom": 40, // 弹框最外层容器下内边距，实践时候可与 capPaddingBottom 配合，当传入数字时，默认单位 px；v2.21.4 后支持字符串，单位 px、%、rem，em
"position": "absolute", // 弹框的 css 定位，可填 absolute、fixed、static 等，默认时 absolute
"top": "20%" // 弹框相对顶部的位置，也就是 css 样式的 top 属性
}，
"customTexts":{
"slideTip": "向右拖动滑块填充拼图" // 滑动模块文案
}
}
Theme 枚举类说明
// 主题
enum Theme {
// 正常
LIGHT,
// 暗黑
DARK
}
LangType 枚举值说明
enum LangType {
LANG_AM,// 阿姆哈拉语
LANG_AR,//阿拉伯语
LANG_AS,//阿萨姆语
LANG_AZ,//阿塞拜疆语
LANG_BE,//白俄罗斯语
LANG_BG,//保加利亚语
LANG_BN,//孟加拉语
LANG_BO,//藏语
LANG_BS,//波斯尼亚语
LANG_CA,//加泰罗尼亚语
LANG_CS,//捷克语
LANG_DA,//丹麦语
LANG_DE,//德语
LANG_EL,//希腊语
LANG_EN,//英文
LANG_EN_US,//英语/美国
LANG_ES,//西班牙语
LANG_ES_LA,//西班牙语/拉美
LANG_ET,//爱沙尼亚语
LANG_EU,//巴斯克语
LANG_FA,//波斯语
LANG_FI,//芬兰语
LANG_FR,//法语
LANG_GL,//加利西亚语
LANG_GU,//古吉拉特语
LANG_HI,//印地语
LANG_HR,//克罗地亚
LANG_HU,//匈牙利语
LANG_ID,//印尼语
LANG_IT,//意大利语
LANG_HE,//希伯来语
LANG_JA,//日文
LANG_JV,//爪哇语
LANG_KA,//格鲁吉亚语
LANG_KK,//哈萨克语
LANG_KM,//高棉语
LANG_KN,//卡纳达语
LANG_KO,//韩文
LANG_LO,//老挝语
LANG_LT,//立陶宛语
LANG_LV,//拉脱维亚语
LANG_MAI,//迈蒂利语
LANG_MI,//毛利语
LANG_MK,//马其顿语
LANG_ML,//马拉亚拉姆语
LANG_MN,//蒙古语
LANG_MR,//马拉地语
LANG_MS,//马来西亚语
LANG_MY,//缅甸语
LANG_NO,//挪威语
LANG_NE,//尼泊尔语
LANG_NL,//荷兰语
LANG_OR,//欧里亚语
LANG_PA,//旁遮普语
LANG_PL,//波兰语
LANG_PT,//葡萄牙语
LANG_PT_BR,//葡萄牙语/巴西
LANG_RO,//罗马西亚语
LANG_RU,//俄语
LANG_SI,//僧加罗语
LANG_SK,//斯洛伐克语
LANG_SL,//斯洛文尼亚语
LANG_SR,//塞尔维亚语
LANG_SV,//瑞典语
LANG_SW,//斯瓦希里语
LANG_TA,//泰米尔语
LANG_TE,//泰卢固语
LANG_TH,//泰语
LANG_FIL,//菲律宾语
LANG_TR,//土耳其语
LANG_UG,//维吾尔语
LANG_UK,//乌克兰语
LANG_UR,//乌尔都语
LANG_UZ,//乌兹别克语
LANG_VI,//越南语
LANG_ZH_CN,//中文简体
LANG_ZH_HK,//中国香港
LANG_ZH_TW,//中国台湾
}
CaptchaListener 接口说明
interface CaptchaListener {
/**
* 验证之后结果回调
* @param result 结果（true表示验证通过)
* @param validate 检验码
* @param msg 结果信息，包括验证错误信息
*/
onValidate(result:string, validate:string, msg:string):void;
/**
* 异常回调
* @param code 异常码
* @param msg 异常信息
*/
onError(code:number,msg:string):void;
/**
* 验证码弹窗显示回调
*/
onCaptchaShow():void;
/**
* 验证码弹窗关闭回调
* 共两种类型 CloseType.USER_CLOSE(用户主动关闭) VERIFY_SUCCESS_CLOSE(流程结束自动关闭)
*/
onClose(closeType: CloseType):void;
}
2. 弹出验证码弹窗
代码说明
dialogController.open()
3. 关闭验证码弹窗
代码说明
dialogController.close()
错误码
| code | 含义 |
|---|---|
| 200 | 校验未通过，是因为业务错误，包含超限 |
| 300 | 校验未通过，包含轨迹错误等 |
| 432 | 非法业务ID，包含业务到期等 |
| 501 | 请求失败，包括网络原因等 |
| 502 | 请求脚本资源失败 |
| 503 | 请求图片资源失败 |
| 505 | 请求音频资源失败 |
| 1000 | 未知错误 |
| 1004 | 初始化失败，接口超时 |
| 2000 | json解析异常 |
| 2001 | 网络未连接 |
