Help Center

智能无感知

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参数强烈建议设置为分钟级别时间戳，避免该文件被浏览器长时间缓存 -->

方案二：含宕机方案版引入

将宕机方案脚本下载至本地项目中

在页面中引入该脚本，示例如下

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 时，支持后缀 `px`、`rem`，类型为 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 时，支持后缀 `px`、`rem`，类型为 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	否	无	高级定义功能-文案自定义，请咨询客服

特别说明

onload和onReady的区别：
onload和onReady触发时，均会返回验证码的实例，即传入的第一个参数。二者触发时机有所不同，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	校验未通过，是因为业务错误，包含超限

Comment On The Document:

If you encounter product-related problems, you can Submit a ticket 或Online ChatSeek help.

Online Chat Tel：95163223