字节跳动小程序

2024.03.13 19:19:06

    字节跳动小程序支持四种验证码类型:

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

    平台支持

    字节跳动小程序支持最低基础库版本为 1.90.0,对应的抖音版本为 13.5,头条的版本为 7.9.6。

    环境准备

    开发环境

    • 申请字节跳动开发者账号
    • 安装字节跳动开发者工具

    项目开发配置

    请在开发设置-服务器域名白名单添加如下域名: c.dun.163.com、c.dun.163yun.com

    资源集成

    • 下载资源 请将下载组件,将解压后的组件放置在 components 或其他目录下(字节跳动小程序暂不支持 npm 引入第三方包)

    • 在使用页对应的 json 中引入验证码组件

    {
      "usingComponents": {
        "ne-captcha": "path-to-component/ne-captcha/index"
      }
    }
    

    快速调用示例

    在 index 页面集成验证码:

    • index.json

      {
        "usingComponents": {
          "ne-captcha": "path-to-component/ne-captcha/index"
        }
      }
      
    • index.ttml

      <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', res => {
                  res && res.popup()
              })
          },
          handleCaptchaVerify (ev) {
              const [err, validate] = ev.detail
              if (!err) {
                  // TODO
                  // 验证成功,进行后续的业务逻辑,如登录等
                  // validate 用于服务端二次验证
              }
          }
      })
      

    SDK方法说明

    使用组件

    字节跳动小程序验证码提供验证码组件,在使用的页面引入即可。

    代码说明

    • ttml
        <ne-captcha id="captcha" captcha-id="业务ID"></ne-captcha>
    
    • 获取组件实例
        this.selectComponent('#captcha', res => {
            this.captchaIns = res
        }) // 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 支持语音种类见下表:
    语种 简体中文 英语 繁体中文 日语 韩语 泰语 越南语 法语 俄语
    lang zh-CN en zh-TW ja ko th vi fr ru

    事件参数说明:

    • bindverify - 事件对象(event)说明:
    - event (Object)
        - detail (Array)
            - error (Error): 验证失败的错误信息
            - validate (String): 二次验证信息
    

    进行验证码验证

    验证需区分验证码的类型,若验证码为常规类型,则调用 popup 方法进行验证;若验证码为智能无感知,则调用 verify 方法进行验证。

    代码说明

    • 常规验证码
        this.captchaIns.popup()  // this.captchaIns 为验证码组件实例
    
    • 智能无感知
        this.captchaIns.verify() // this.captchaIns 为验证码组件实例
    

    刷新验证码(可选)

    当上一轮验证成功后,若业务需要重置验证码,重新进行验证时,可以调用 reset 方法。

    注意:请不要在验证失败时调用,失败时验证码会自动刷新。

    代码说明

        this.captchaIns.reset() // this.captchaIns 为验证码组件实例
    

    错误码

    code 含义
    200 校验未通过,是因为业务错误,包括超限
    501 接口请求失败,包括网络原因等
    503 图片请求失败
    1000 未知错误
    在线咨询 电话咨询:95163223 免费试用