微信小程序

2024.11.01 11:59:35

    微信小程序支持四种验证码类型:

    • 智能无感知
    • 滑块拼图
    • 文字点选
    • 图标点选

    平台支持

    微信版验证码是一个微信小程序插件,兼容2.2.4以上的基础库。

    环境准备

    • 申请微信开发者账号
    • 安装微信开发者工具

    域名加白

    使用公众号账号登录微信公众平台,在管理员首页的左侧栏,可以找到 开发 - 开发管理 菜单,点击页面上“开发设置”,需要将小程序 SDK 的服务器域名 c.dun.163.com、c.dun.163yun.com 加入服务器域名白名单。

    资源集成

    • 添加插件:用管理员身份登录微信公众平台,请使用需要接入小程序的相关账号,依次点击:设置-第三方设置-添加插件,然后输入关键字“网易易盾验证码”并搜索,点击确认,如下图所示: image

    • 在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 时,支持后缀 rpxpxrem;类型为 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.jsonShow 中添加以下代码,来捕获验证结果。

    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
          // ...
        }
      },
      // ...
    })
    
    Online Chat Tel:95163223 Free trial