智能无感知

2021.10.19 15:54:13

    智能无感知验证码拥有极致用户体验,多维度收集环境信息,安全用户只需轻点即可通过验证;可疑用户根据疑似程度弹出不同难度的验证码进行二次验证

    平台支持

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

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

    资源引入

    • 方案一:简单脚本引入
     <!-- https示例如下: -->
      <script src="https://cstaticdun.126.net/load.min.js?t=201903281201"></script>
    
      <!-- http示例如下: -->
      <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
    
      <!-- 地址中的t参数强烈建议设置为分钟级别时间戳,避免该文件被浏览器长时间缓存 -->
    
    • 方案二:含宕机方案版引入
    1. 宕机方案脚本下载至本地项目中
    2. 在页面中引入该脚本,示例如下
      • 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="https://cstaticdun.126.net/load.min.js?t=201903281201"></script>
        <!-- 地址中的t参数强烈建议设置为分钟级别时间戳,避免该文件被浏览器长时间缓存 -->
    </head>
    <body>
        <div>
            <div id="captcha"></div>
            <button id="login">验证</button>
        </div>
        <script>
            (function () {
                var captchaIns;
                initNECaptcha({
                    element: '#captcha',
                    captchaId: '从易盾申请的captchaId',
                    width: '320px',
                    mode: 'bind'
                }, 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

    SDK方法说明

    以下方法及示例都是以简单脚本引入为前提,若引入方式为宕机方案引入,则将所有 initNECaptcha 替换成 initNECaptchaWithFallback

    1. 初始化

    代码说明

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

    参数说明:

    • options基础参数
    参数 类型 是否必填 默认值 描述
    captchaId String 验证码业务ID
    mode String 按钮模式 验证码模式,可设置 "bind" 模式,绑定自有按钮模式;若不设置,则为验证按钮模式,示例demo
    element String|HTMLElement * 容器元素或容器元素选择器
    width Number |String 'auto' 常规验证码宽度,推荐使用宽度 260px - 400px。类型为 String 时,支持后缀 pxrem,类型为 Number 时,内部会将其转换成 px 单位的值。当 mode 非 "bind" 时,width 无效,宽度取决于容器的宽度
    onVerify Function 验证码一次验证结束回调函数
    更多详细参数见参数详情
    • onload: 验证码初始化成功回调
    • onerror: 验证码初始化失败回调

    回调参数说明:

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

    2. 进行验证码验证(可选)

    当 mode 配置成 "bind" 时,需要调用以下方法弹出验证码;否则无需调用,用户直接操作界面进行验证。

    代码说明

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

    3. 关闭验证码弹框(可选)

    当智能无感知验证码第一次校验不通过时,会进行常规验证码验证。当常规验证码为弹框形式出现且 enableClose 设置为 true,即开启业务方控制弹框关闭时,若需要关闭验证码弹框,可以调用下述方法:

    代码说明

        instance.close()
    

    4. 刷新验证码(可选)

    当上一轮验证成功后,若业务需要刷新验证码,重新进行验证时,可以调用下述方法:

    代码说明

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

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

    5. 销毁验证码(可选)

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

    代码说明

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

    参数详解

    初始化(initNECaptcha)options 参数详解:

    参数 类型 是否必填 默认值 描述
    captchaId String 验证码业务ID
    mode String 按钮模式 验证码模式,可设置 "bind" 模式,绑定自有按钮模式;若不设置,则为验证按钮模式,示例 demo
    element String|HTMLElement * 容器元素或容器元素选择器
    width Number |String 'auto' 常规验证码宽度,推荐使用宽度 260px - 400px。类型为 String 时,支持后缀 pxrem,类型为 Number 时,内部会将其转换成 px 单位的值。当 mode 非 "bind" 时, width 无效,宽度取决于容器的宽度
    protocol String 与用户网站的网络协议一致 验证码传输数据使用的网络协议,可选:"http""https"
    lang String 'zh-CN' 验证码语言选项。支持 "zh-CN""zh-TW""en"
    timeout Number 6000ms 内部每个请求的超时时间
    appendTo String|HTMLElement 验证码弹框的指定区域元素或者指定区域元素选择器。该配置仅适用于验证码弹框,请注意,指定区域的元素必须为非静态定位
    enableClose Boolean false 由业务方控制验证码弹框关闭
    feedbackEnable Boolean true 是否开启用户反馈入口(底图右上角问号图标)
    extraData String|Function 如果需要在 check 阶段透传业务数据,可以使用 extraData 配置,支持字符串和函数,函数可以解决动态数据问题。当调用二次校验结果接口时,会原样返回该字段,详见后端响应参数
    group String 验证码分组,作用于统计
    scene String 验证码使用场景,作用于统计
    maxVerification Number 最大验证码失败次数,到达上线后会重置验证码,开始新的验证流程
    defaultFallback Boolean true 使用方案二接入有效。是否启用默认降级方案,若设置 false,可搭配onFallback自定义降级方案
    errorFallbackCount Number 3 使用方案二接入有效。触发降级的最大错误次数,当超过这个错误次数时,触发降级;降级产生的二次验证信息默认无法通过二次验证。大面积发生降级时,请联系客服
    onFallback Function 使用方案二接入有效。验证码触发降级的回调,仅 defaultFallback 为 false 时有效
    onReady Function 验证码所有工作准备就绪的回调函数
    onVerify Function 验证码一次验证结束回调函数
    onClose Function 验证码弹框关闭后的回调
    customStyles Object 高级定义功能-主界面自定义样式,请咨询客服
    popupStyles Object 高级定义功能-弹框界面自定义样式,请咨询客服
    customTexts Object 高级定义功能-文案自定义,请咨询客服

    特别说明

    • onloadonReady的区别:
      onloadonReady触发时,均会返回验证码的实例,即传入的第一个参数。二者触发时机有所不同,onload触发时,初始化函数结束和完成实例的生成,注意这并不代表验证码是可用的(比如验证码相关背景图片和信息并没有加载),此方法只触发一次。onReady触发时,说明验证码准备就绪(比如背景图片等信息均已加载),onReady只触发一次。

    mode:模式

    • bind,默认无界面,由业务方调用 verify 发起,效果见 bind演示DEMO
    • 按钮模式(不设置),验证码界面为按钮条,效果见 无感知演示DEMO

    lang:语言

    验证码支持如下多种语言:

    语种 简体中文 英语 繁体中文 日语 韩语 泰语 越南语 法语 俄语 阿拉伯语 德语 意大利语 希伯来语 印地语 印尼语 缅甸语 老挝语 马来语 波兰语 葡萄牙语 西班牙语 土耳其语
    lang zh-CN en zh-TW ja ko th vi fr ru ar de it he hi id my lo ms pl pt es tr

    enableClose

    当 enableClose 为 true 时,将由业务方控制验证码弹框的关闭时机,验证码不会主动关闭弹框,且弹框右上角的关闭按钮隐藏。当业务方需要关闭验证码弹框时,可以调用 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>验证码示例-enableClose</title>
      <script src="https://cstaticdun.126.net/load.min.js?t=201903281201"></script>
    </head>
    <body>
    <button id="j-bind">点击进行验证</button>
    <div id="captcha"></div>
    <script>
        var captchaIns;
        initNECaptcha({
            element: '#captcha',
            captchaId: '从易盾申请的captchaId',
            mode: 'bind',
            width: '320px',
            enableClose: true,
            onClose: function () {
                // 弹出关闭结束后将会触发该函数
            },
            onVerify: function (err, data) {
                if (!err) {
                    // 验证成功后,调用 close 方法关闭弹框
                    captchaIns.close()
                    // TODO: 验证成功后继续进行业务逻辑
                }
            }
        }, function (instance) {
            // 初始化成功后得到验证实例 instance,可以调用实例的方法
            captchaIns = instance
        }, function (err) {
            // 初始化失败后触发该函数,err 对象描述当前错误信息
        })
    
        // 监听 button 的点击事件,弹出验证码
        document.getElementById('j-bind').addEventListener('click', function () {
            captchaIns && captchaIns.verify()
        })
    </script>
    </body>
    </html>
    

    appendTo

    appendTo用于指定弹框区域

    <!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">
      验证码示例
    
      <style type="text/css">
        #appendWrap {
          position: relative;
        }
      </style>
    </head>
    <body>
      <div class="form-container">
        <button id="j-bind">点击弹出验证码</button>
        <div id="captcha"></div>
      </div>
      <script src="http://cstaticdun.126.net/load.min.js?t=201903281201"></script>
      <!-- 地址中的t参数强烈建议设置为分钟级别时间戳,避免该文件被浏览器长时间缓存 -->
      <script>
        initNECaptcha({
          captchaId: '从易盾申请的captchaId',
          element: '#captcha',
          mode: 'bind',
          width: '320px',
          onVerify: function (err, data) {
            /**
             * 第一个参数是err(Error的实例),验证失败才有err对象
             * 第二个参数是data对象,验证成功后的相关信息,data数据结构为key-value,如下:
             * {
             *   validate: 'xxxxx' // 二次验证信息
             * }
            **/
            if (err) return  // 当验证失败时,内部会自动refresh方法,无需手动再调用一次
            // 点击登录按钮后可调用服务端接口,以下为伪代码,仅作示例用
            ajax('/login', {
              captchaId: '从易盾申请的captchaId',
              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) {
          // 验证码初始化失败处理逻辑,例如:提示用户点击按钮重新初始化
        })
        
        // 监听button的点击事件,弹出验证码
        document.getElementById('j-bind').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: '从易盾申请的captchaId',
                element: '#captcha',
                width: '320px'
            }, function onload (instance) {
            // 初始化成功后,用户输入对应用户名和密码,以及完成验证后,直接点击登录按钮即可
            }, function onerror (err) {
            // 验证码初始化失败处理逻辑,例如:提示用户点击按钮重新初始化
            })
        </script>
    </body>
    </html>
    

    错误码

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