微信小程序
2024.04.15 16:46:36
微信小程序支持四种验证码类型：
- 智能无感知
- 滑块拼图
- 文字点选
- 图标点选
平台支持
微信版验证码是一个微信小程序插件，兼容2.2.4以上的基础库。
环境准备
- 申请微信开发者账号
- 安装微信开发者工具
资源集成
-
添加插件：用管理员身份登录微信公众平台，请使用需要接入小程序的相关账号，依次点击：设置-第三方设置-添加插件，然后输入关键字“网易易盾验证码”并搜索，点击确认，如下图所示：
-
在app.json中声明验证码插件，如下：
{
"plugins": {
"captcha": {
"version": "1.3.0",
"provider": "wxb7c8f9ea9ceb4663"
}
}
}
- 在使用页面对应的 JSON 中引入验证码组件。
{
"usingComponents": {
"ne-captcha": "plugin://captcha/ne-captcha"
}
}
快速调用示例
在index页面集成验证码：
-
index.json
{ "usingComponents": { "ne-captcha": "plugin://captcha/ne-captcha" } } -
index.wxml
<view> <ne-captcha id="captcha" captcha-id="业务ID" width="640rpx" bindverify="handleCaptchaVerify"></ne-captcha> <button bindtap="tryToVerify">点击验证</button> </view> -
index.js
Page({ tryToVerify () { this.selectComponent('#captcha').popup() }, handleCaptchaVerify (ev) { const [err, validate] = ev.detail if (!err) { // TODO // 验证成功，进行后续的业务逻辑，如登录等 // validate 用于服务端二次验证 } } })
SDK方法说明
使用组件
微信小程序验证码提供验证码组件，在使用的页面引入即可。
代码说明
- wxml
<ne-captcha id="captcha" captcha-id="业务ID"></ne-captcha>
- 获取组件实例
instance = this.selectComponent('#captcha') // captcha为元素id
组件属性说明
| 属性 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
| captchaId | String | 是 | 无 | 验证码业务ID |
| width | Number |String | 否 | 'auto' | 验证按钮宽度；类型为 String 时，支持后缀 rpx、px、rem；类型为 Number 时，内部会将其转换成 rpx 单位的值 |
| lang | String | 否 | zh-CN | 验证码使用的语言 |
| timeout | Number | 否 | 6000 | 请求超时时间，单位为毫秒 |
| customStyles | Object | 否 | null | 自定义样式，详见自定义样式配置 |
| customTexts | Object | 否 | null | 自定义文本，用户可指定文本使用自定义，详见自定义文案配置 |
| extraData | String | 否 | 无 | 如果需要在 check 阶段透传业务数据，可以使用 extraData 配置。当调用二次校验结果接口时，会原样返回该字段，详见后端响应参数 |
| bindinit | Eventhandle | 否 | 无 | 验证码配置（初始化）成功触发的事件 |
| binderror | Eventhandle | 否 | 无 | 验证码配置失败触发的事件 |
| bindready | Eventhandle | 否 | 无 | 验证码准备就绪（可进行验证）触发的事件 |
| bindverify | Eventhandle | 否 | 无 | 验证码一次验证完成触发的事件 |
| bindclose | Eventhandle | 否 | 无 | 验证码弹出关闭触发的事件 |
注意：自定义功能仅高版本套餐支持，详情请咨询客服
- 自定义样式：customStyles
为更好地理解自定义样式相关内容，请先了解我们对易盾验证码弹框界面组成部分的定义
自定义样式数据结构如下：
- customStyles (Object)
- imagePanel (Object)
- borderRadius (String): imagePanel 的圆角大小
- controlBar (Object)
- borderRadius (String): controlBar 的圆角大小
- height (String): controlBar 的高度
- gap (String): imagePanel 和 controlBar 的间隔
- popTitle (Object)
- height (String): 弹框头部高度
- popPadding (String): 弹框体内边距
使用示例：
<ne-captcha
captcha-id="业务ID"
width="640rpx"
custom-styles="{{customStyles}}"></ne-captcha>
Page({
data: {
customStyles: {
imagePanel: {
borderRadius: '2rpx'
},
controlBar: {
height: '80rpx'
}
}
}
})
- 自定义文案：customTexts
| 属性 | 原文案（简体中文） |
|---|---|
| LOADING | 加载中... |
| LOAD_FAIL | 加载失败 |
| VERIFY_SUCCESS | 验证成功 |
| VERIFY_ERROR | 验证失败，请重试 |
| VERIFY_OUT_OF_LIMIT | 失败过多，点此重试 |
| CLICK_BUTTON | 点此进行验证 |
| CLICK_IN_TURN | 请依次点击 |
| SLIDE_TIP | 向右拖动滑块填充拼图 |
| POPUP_TITLE | 请完成安全验证 |
使用示例：
<ne-captcha
captcha-id="业务ID"
width="640rpx"
custom-texts="{{customTexts}}"></ne-captcha>
Page({
data: {
customTexts: {
LOADING: '加载中，请耐心等待',
LOAD_FAIL: '加载失败，刷新重试'
}
}
})
lang 可选项
验证码支持以下语言：
| 语言标识 | 语种 |
|---|---|
| zh-CN | 简体中文 |
| zh-TW | 台湾繁体中文 |
| zh-HK | 香港繁体中文 |
| en | 美式英文 |
| en-GB | 英式英文 |
| es | 西班牙语（欧洲） |
| pt | 葡萄牙语（欧洲） |
| fr | 法语 |
| de | 德语 |
| ru | 俄语 |
| it | 意大利语 |
| ja | 日语 |
| es-la | 拉美西语 |
| pt-br | 巴西葡语 |
| sv | 瑞典语 |
| no | 挪威语 |
| da | 丹麦语 |
| cs | 捷克语 |
| hu | 匈牙利语 |
| sk | 斯洛伐克语 |
| pl | 波兰语 |
| ro | 罗马尼亚语 |
| el | 希腊语 |
| sr | 塞尔维亚语（拉丁文） |
| bs | 波斯尼亚语 |
| mk | 马其顿语 |
| bg | 保加利亚语 |
| fi | 芬兰语 |
| et | 爱沙尼亚语 |
| lv | 拉脱维亚语 |
| lt | 立陶宛语 |
| sl | 斯洛文尼亚语 |
| hr | 克罗地亚语 |
| uk | 乌克兰语 |
| tr | 土耳其语 |
| vi | 越南语 |
| id | 印尼语 |
| ar | 阿拉伯语 |
| fa | 波斯语 |
| nl | 荷兰语 |
| th | 泰语 |
| ms | 马来西亚语 |
| ca | 加泰罗尼亚语 |
| hi | 印地语 |
| my | 缅甸语 |
| ko | 韩语 |
| he | 希伯来语 |
| gl | 加利西亚语 |
| eu | 巴斯克语 |
| ka | 格鲁吉亚语 |
| az | 阿塞拜疆语 |
| uz | 乌孜别克语 |
| km | 高棉语 |
| si | 僧伽罗语 |
| ur | 乌尔都语 |
| bo | 藏语 |
| be | 白俄罗斯语 |
| kk | 哈萨克语（西里尔文） |
| bn | 孟加拉语 |
| lo | 老挝语 |
| fil | 菲律宾语 |
| jv | 爪哇语 |
| ne | 尼泊尔语 |
| sw | 斯瓦西里语 |
| mi | 毛利语 |
| am | 阿姆哈拉语 |
| te | 泰卢固语 |
| mr | 马拉地语 |
| ta | 泰米尔语 |
| gu | 古吉拉特语 |
| kn | 卡纳达语 |
| ml | 马来亚拉姆语 |
| or | 欧里亚语 |
| pa | 旁遮普语 |
| as | 阿萨姆语 |
| mai | 迈蒂利语 |
| mn | 蒙古语（西里尔文） |
| ug | 维吾尔语 |
事件参数说明：
- bindverify - 事件对象（event）说明：
- event (Object)
- detail (Array)
- error (Error): 验证失败的错误信息
- validate (String): 二次验证信息
进行验证码验证
验证需区分验证码的类型，若验证码为常规类型，则调用 popUp 方法进行验证；若验证码为智能无感知，则调用 verify 方法进行验证。
代码说明
- 常规验证码
instance.popUp() // instance 为验证码组件实例
- 智能无感知
instance.verify() // instance 为验证码组件实例
刷新验证码（可选）
当上一轮验证成功后，若业务需要重置验证码，重新进行验证时，可以调用 reset 方法。 注意：请不要在验证失败时调用，失败时验证码会自动刷新。
代码说明
instance.reset() // instance 为验证码组件实例
错误码
| code | 含义 |
|---|---|
| 200 | 校验未通过，是因为业务错误，包含超限 |
| 501 | 接口请求失败，包括网络原因等 |
| 503 | 图片请求失败 |
| 1000 | 未知错误 |
跳转式接入
小程序使用限制
需要用户确认跳转，从小程序 2.3.0 版本开始，在跳转至其他小程序前，将统一增加弹窗，询问是否跳转，用户确认后才可以跳转其他小程序。如果用户点击取消，则回调 fail cancel。
每个小程序可跳转的其他小程序数量限制为不超过 10 个，从 2.4.0 版本以及指定日期（具体待定）开始，开发者提交新版小程序代码时，如使用了跳转其他小程序功能，则需要在代码配置中声明将要跳转的小程序名单，限定不超过10个，否则将无法通过审核。该名单可在发布新版时更新，不支持动态修改。配置方法详见配置。调用此接口时，所跳转的 appId 必须在配置列表中，否则回调 fail appId "${appId}" is not in navigateToMiniProgramAppIdList。
详见小程序说明地址：https://developers.weixin.qq.com/miniprogram/dev/component/navigator.html
小程序唤起验证码
通过 navigator 组件跳转至验证码小程序。用户完成或关闭验证码后，将返回至调用方的小程序。
<!-- 由于小程序限制，只能通过navigator跳转到验证码的小程序 -->
<!-- 如果跳转前需要校验表单，请先将button的disabled属性设为true，
同时表单中使用bind:input事件校验合法性，
完成后再将button的disabled属性设为false
captchaId替换成申请到的验证码captchaId -->
<navigator target="miniProgram"
app-id="wxb7c8f9ea9ceb4663"
path="/pages/captcha/index"
extra-data="{{ { captchaId: 'captchaId' } }}">
<button>验证</button>
</navigator>
在 app.js 获取验证结果
在网易易盾验证码中验证。
验证成功后，验证码小程序页面关闭，验证结果会返回给调用验证码的小程序页面。由于小程序间相互跳转过程中产生的数据仅能在 app.js 中获取到，故需要在 app.js 的 onShow 中添加以下代码，来捕获验证结果。
App({
// ...
onShow: function(options) {
// 解决各类回调的兼容问题
if (!this.captchaValidateExpire) this.captchaValidateExpire = {}
if (options.scene === 1038 && options.referrerInfo.appId === 'wxb7c8f9ea9ceb4663') {
const result = options.referrerInfo.extraData;
if (result.ret === 0) {
const validate = result.validate
if (!this.captchaValidateExpire[validate]) {
this.globalData.captchaResult = result
this.captchaValidateExpire[validate] = true
}
} else {
// 验证失败
}
}
},
// ...
})
验证结果（result）参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| ret | Number | 0为验证成功，1为验证失败 |
| validate | String | 仅验证成功时会有，验证成功的code，用于后台校验验证合法性 |
服务端校验
在小程序页面的onShow阶段将验证结果及待提交的表单数据一起提交到服务器，进行校验。
const app = getApp()
Page({
data: {
// ...
},
onShow() {
const captchaResult = app.globalData.captchaResult
app.globalData.captchaResult = null // 验证码的验证code是一次性的，取完需要置空
if (captchaResult && captchaResult.ret === 0) {
// 将验证码的结果返回至服务端校验
// const validate = captchaResult.validate
// ...
}
},
// ...
})
