JS SDK接入教程

2024.09.24 10:09:36

    行为式验证码是一种全新人机验证方式,能够高效拦截机器行为,构筑业务安全第一道防线。

    目前行为式验证码支持的类型有:智能无感知滑动拼图文字点选图标点选推理拼图短信上行语序点选空间推理障碍躲避语序选词、语音验证码。

    验证码类型和验证码ID(captchaId)绑定,可以登录管理后台灵活切换。

    验证码类型

    平台支持

    行为式验证码兼容市场主流浏览器,具体版本见下表:

    浏览器 最低支持版本
    IE 7
    Edge 44
    Chrome 44
    Firefox 71
    Mac Safari 13
    UC 9
    Android Chrome 7
    微信浏览器 7.1
    Opera 8
    iOS Safari 12

    SDK 接入

    包含降级方案接入(强烈推荐)

    该方案稳定性更有保障,可有效避免因网络质量问题引发的静态资源加载失败、接口不可用等问题。

    如果对稳定性有更高的要求,推荐使用降级方案中自定义降级逻辑,详细用法可以进一步咨询技术支持。

    • 降级脚本下载至本地项目中;
    • 在页面中引入上面的脚本,示例如下:
    • Script 引入
    <script src="/path/yidun-captcha.js"></script>
    
    • 模块引入
    import initNECaptchaWithFallback from '/path/yidun-captcha'
    

    注释: 当行为验证码所需静态资源或者接口不可用时,且请求验证码失败次数达到阈值(默认为 3 次,可根据需求配置),最后一次会触发降级逻辑,降级表现为:

    Web 端提示 前方拥堵,已自动跳过验证(智能无感知无该提示),验证码直接验证通过,用户可进行后续业务操作,免受行为验证码的影响。

    页面接入示例

    <!DOCTYPE html>
    <html lang="en">
    
    <head>
      <meta charset="UTF-8">
      <meta http-equiv="X-UA-Compatible" content="IE=edge">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>验证码接入示例</title>
      <script src="/path/yidun-captcha.js"></script>
    </head>
    
    <body>
      <div>
        <div id="captcha"></div>
        <button id="login">登录</button>
      </div>
      <script>
        (function () {
          var captchaIns;
          initNECaptchaWithFallback({
            element: '#captcha',
            captchaId: '<CAPTCHA_ID>',
            width: '320px',
            mode: 'popup',
            apiVersion: 2,
            popupStyles: {
              position: 'fixed',
              top: '20%'
            },
            onVerify: function (err, data) {
              /**
               * 第一个参数是err(Error的实例),验证失败才有err对象
               * 第二个参数是data对象,验证成功后的相关信息,data数据结构为key-value,如下:
               * {
               *   validate: 'xxxxx' // 二次验证信息
               * }
               **/
              if (err) return // 当验证失败时,内部会自动refresh方法,无需手动再调用一次
    
              // 点击登录按钮后可调用服务端接口,以下为伪代码,仅作示例用
              ajax('/login', {
                username: $('#username').val(),
                password: $('#password').val(),
                validate: data.validate
              }, function onsuccess(data) {
                // if (loginFail) {
                // 密码错误等原因导致登录失败,业务上若需要刷新验证码,可调用refresh方法
                //   captchaIns && captchaIns.refresh()
                // } else {
                // 登录成功后,相关处理逻辑
                // }
              })
            }
          }, function onload(instance) {
            captchaIns = instance
          }, function onerror(err) {
            console.warn(err)
          })
    
          var loginBtn = document.getElementById('login')
          loginBtn.addEventListener('click', function () {
            captchaIns && captchaIns.verify()
          })
        })();
      </script>
    </body>
    
    </html>
    

    更多使用场景,请参见DEMO

    查看主流框架的示例,请参见DEMO

    不含宕机方案接入

    通过 <script> 标签引入文件

    <!-- https示例如下: -->
    <script src="https://cstaticdun.126.net/load.min.js?t=<MINUTE_TIMESTAMP>"></script>
    
    <!-- http示例如下: -->
    <script src="http://cstaticdun.126.net/load.min.js?t=<MINUTE_TIMESTAMP>"></script>
    
    <!-- 地址中的t参数强烈建议设置为分钟级别时间戳, 避免该文件被浏览器长时间缓存 -->
    

    页面接入示例

    <!DOCTYPE html>
    <html lang="en">
    
    <head>
      <meta charset="UTF-8">
      <meta http-equiv="X-UA-Compatible" content="IE=edge">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>验证码接入示例</title>
      <script src="https://cstaticdun.126.net/load.min.js"></script>
    </head>
    
    <body>
      <div>
        <div id="captcha"></div>
        <button id="login">登录</button>
      </div>
      <script>
        (function () {
          var captchaIns;
          initNECaptcha({
            element: '#captcha',//popup 模式下,element 可以为空或者document.body
            captchaId: '<CAPTCHA_ID>',
            width: '320px',
            mode: 'popup',
            apiVersion: 2,
            popupStyles: {
              position: 'fixed',
              top: '20%'
            },
            onVerify: function (err, data) {
              /**
               * 第一个参数是err(Error的实例),验证失败才有err对象
               * 第二个参数是data对象,验证成功后的相关信息,data数据结构为key-value,如下:
               * {
               *   validate: 'xxxxx' // 二次验证信息
               * }
               **/
              if (err) return // 当验证失败时,内部会自动refresh方法,无需手动再调用一次
    
              // 点击登录按钮后可调用服务端接口,以下为伪代码,仅作示例用
              ajax('/login', {
                username: $('#username').val(),
                password: $('#password').val(),
                validate: data.validate
              }, function onsuccess(data) {
                // if (loginFail) {
                // 密码错误等原因导致登录失败,业务上若需要刷新验证码,可调用refresh方法
                //   captchaIns && captchaIns.refresh()
                // } else {
                // 登录成功后,相关处理逻辑
                // }
              })
            }
          }, function onload(instance) {
            captchaIns = instance
          }, function onerror(err) {
            console.warn(err)
          })
    
          var loginBtn = document.getElementById('login')
          loginBtn.addEventListener('click', function () {
            captchaIns && captchaIns.verify()
          })
        })();
      </script>
    </body>
    
    </html>
    

    方法说明

    以下示例都是以不含宕机方案接入,若接入方式为含宕机方案,只需将 initNECaptcha 替换成 initNECaptchaWithFallback 即可。

    初始化

    示例代码

    initNECaptcha(options, function onload (instance) {}, function onerror (error) {})
    

    参数说明:

    参数 类型 是否必填 默认值 描述
    captchaId String 验证码业务ID
    mode String PC 端默认 "float",移动端默认 "popup" 验证码模式,有三种模式可选:"float"(触发式)、"embed"(嵌入式)、"popup"(弹出式),其中智能无感知类型不支持 "embed" 模式。示例demo
    element String/HTMLElement 容器元素或容器元素选择器,popup 模式下,element 可以为空或者document.body
    width Number/String 'auto' 验证按钮宽度,推荐使用宽度 260px-400px。类型为 String 时,支持后缀 pxrem%,类型为 Number 时,内部会将其转换成 px 单位的值。当值为 "auto" 时,其宽度与容器元素宽度一致。mode 为 "popup" 时,百分比单位无效
    apiVersion Number SDK 版本,推荐设置为 2
    protocol String 与用户网站的网络协议一致 验证码传输数据使用的网络协议,可选:"http""https"
    lang String 'zh-CN' 验证码语言选项。支持 "zh-CN""zh-TW""en"等具体参考文档下方附录-lang枚举
    timeout Number 6000ms 内部每个请求的超时时间
    closeEnable Boolean false 是否由产品方控制验证码弹框关闭
    feedbackEnable Boolean true 是否开显示用户反馈入口(底图右上角问号图标)
    ipv6 Boolean false 是否支持 ipv6 网络,如果设置为 true ,验证码内部的所有请求都首先使用 ipv6 域名进行
    extraData String/Function 如果需要在 check 阶段透传业务数据,可以使用 extraData 配置,支持字符串和函数,函数可以解决动态数据问题。当调用二次校验结果接口时,会原样返回该字段,详见后端响应参数
    maxVerification Number 5 最大验证码失败次数,到达上限后会重置验证码,开始新的验证流程
    defaultFallback Boolean true 使用含宕机方案接入有效。是否启用默认降级方案,若设置 false,可搭配onFallback自定义降级方案
    errorFallbackCount Number 3 使用含宕机方案接入有效。触发降级的最大错误次数,当超过这个错误次数时,触发降级;降级产生的二次验证信息默认无法通过二次验证。大面积发生降级时,请联系客服
    enableAutoFocus Boolean 验证码弹框弹起时是否自动聚焦至弹框元素
    onFallback Function 使用含宕机方案接入有效。验证码触发降级的回调,仅 defaultFallback 为 false 时有效
    onReady Function 验证码所有工作准备就绪的回调函数
    onVerify Function 验证码一次验证结束回调函数
    onOpen Function 验证码弹框弹出前的回调
    onClose Function 验证码弹框关闭后的回调
    apiServer string/string[] 易盾默认域名 用于指定验证码接口域名,私有化部署、域名转发方式接入需要使用,常规接入不需要设置
    staticServer string/string[] 易盾默认域名 用于指定验证码静态资源域名,私有化部署、域名转发方式接入需要使用,常规接入不需要设置
    customStyles Object 高级定义功能-主界面自定义样式,请咨询客服
    popupStyles Object 高级定义功能-弹框界面自定义样式,请咨询客服
    customTexts Object 高级定义功能-文案自定义,请咨询客服

    回调参数说明:

    • onload(instance) 回调参数说明
    参数 类型 描述
    instance Object 初始化成功后的验证码实例
    • onerror(error) 回调参数说明
    参数 类型 描述
    error Error 初始化失败的错误信息,详细错误码请参考附录-错误码
    • onVerify(err, data) 回调参数说明
    参数 类型 描述
    err Error 验证失败的错误信息
    data Object 验证成功后的信息,格式为{ validate: '' },其中 validate 为二次验证信息

    显示验证码(可选)

    mode 配置成 popup 时,需要调用 verify 显示验证码;否则无需调用,用户直接操作界面进行验证

    代码说明

    instance.verify()  // instance 为行为式验证码实例
    

    关闭验证码(可选)

    closeEnable 设置为 true 时,产品方可获得主动关闭验证码弹框的权限。若需要关闭验证码弹框,可以调用 close 方法。

    代码说明

    instance.close() // instance 为行为式验证码实例
    

    刷新验证码(可选)

    当验证成功后,若产品方有场景需要刷新验证码,重新进行验证时,可以调用 refresh 方法:

    代码说明

    instance.refresh() // instance 为行为式验证码实例
    

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

    销毁验证码(可选)

    当业务不再需要验证码,需要销毁验证码时,可以调用 destroy 方法:

    代码说明

    instance.destroy() // instance 为行为式验证码实例
    

    特别说明

    onloadonReady 的区别:

    onloadonReady 触发时,均会返回验证码的实例,即传入的第一个参数;二者触发时机有所不同:

    onload 触发时,初始化函数结束和完成实例的生成,注意这并不代表验证码是可用的(比如验证码相关背景图片和信息并没有加载),此方法只触发一次;

    onReady 触发时,说明验证码准备就绪(比如背景图片等信息均已加载),onReady只触发一次;

    mode 模式演示

    closeEnable

    closeEnabletrue 时,将由产品方控制验证码弹框的关闭时机,验证码不会主动关闭弹框,且弹框右上角的关闭按钮隐藏。当业务方需要关闭验证码弹框时,可以调用 close 方法。使用示例如下:

    <!DOCTYPE html>
    <html lang="en">
    
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
      <meta http-equiv="X-UA-Compatible" content="ie=edge">
      <title>验证码示例-closeEnable</title>
      <script src="https://cstaticdun.126.net/load.min.js"></script>
    </head>
    
    <body>
      <button id="j-popup">点击弹出验证码</button>
      <div id="captcha"></div>
      <script>
        var captchaIns;
        initNECaptcha({
          element: '#captcha',
          captchaId: '<CAPTCHA_ID>',
          mode: 'popup',
          width: '320px',
          closeEnable: true,
          apiVersion: 2,
          popupStyles: {
            position: 'fixed',
            top: '20%'
          },
          onClose: function () {
            // 弹出关闭结束后将会触发该函数
          },
          onVerify: function (err, data) {
            if (!err) {
              // 验证成功后,调用 close 方法关闭弹框
              captchaIns.close()
              // TODO: 验证成功后继续进行业务逻辑
            }
          }
        }, function (instance) {
          // 初始化成功后得到验证实例 instance,可以调用实例的方法
          captchaIns = instance
        }, function (err) {
          // 初始化失败后触发该函数,err 对象描述当前错误信息
        })
    
        // 监听 button 的点击事件,弹出验证码
        document.getElementById('j-popup').addEventListener('click', function () {
          captchaIns && captchaIns.verify()
        })
      </script>
    </body>
    
    </html>
    

    form 表单进行二次验证

    通常业务方可以在 onVerify 中获取到二次校验信息后进行二次验证;但若产品方是使用表单提交的方式进行请求,可以参考如下示例:

    <!DOCTYPE html>
    <html lang="en">
    
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <meta http-equiv="X-UA-Compatible" content="ie=edge">
      <title>验证码示例</title>
      <script src="https://cstaticdun.126.net/load.min.js?t=201903281201"></script>
    </head>
    
    <body>
      <form action="/login" method="post">
        <input type="text" name="username" placeholder="用户名">
        <input type="password" name="password" placeholder="密码">
        <input type="hidden" name="captchaId" value="从易盾申请的captchaId">
        <div id="captcha"></div> <!-- 验证码容器元素 -->
        <button type="submit">登录</button>
      </form>
      <script>
        initNECaptcha({
          captchaId: '<CAPTCHA_ID>',
          element: '#captcha',
          width: '320px',
          apiVersion: 2,
          popupStyles: {
            position: 'fixed',
            top: '20%'
          }
        }, function onload(instance) {
          // 初始化成功后,用户输入对应用户名和密码,以及完成验证后,直接点击登录按钮即可
        }, function onerror(err) {
          // 验证码初始化失败处理逻辑,例如:提示用户点击按钮重新初始化
        })
      </script>
    </body>
    
    </html>
    

    附录

    错误码

    code 含义
    501 请求失败,包括网络原因等
    502 请求脚本资源失败
    432 非法业务ID,包含业务到期等
    1000 未知错误
    300 校验未通过,包含轨迹错误等
    200 校验未通过,是因为业务错误,包含超限

    lang 可选项

    验证码支持以下语言:

    语言标识 语种
    zh-CN 简体中文
    zh-TW 台湾繁体中文
    zh-HK 香港繁体中文
    en-US 美式英文
    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 维吾尔语
    Online Chat Tel:95163223 Free trial