帮助中心

JS SDK接入教程

2024.04.15 16:46: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',
        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	是	无
width	Number/String	否	'auto'	验证按钮宽度，推荐使用宽度 260px-400px。类型为 String 时，支持后缀 `px`、`rem`、`%`，类型为 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	否	无
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	否	无	验证码弹框关闭后的回调
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 为行为式验证码实例

特别说明

onload 和 onReady 的区别：

onload 和 onReady 触发时，均会返回验证码的实例，即传入的第一个参数；二者触发时机有所不同：

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

onReady 触发时，说明验证码准备就绪（比如背景图片等信息均已加载），onReady只触发一次；

mode 模式演示

popup，验证码交互模式为弹出式，效果见 popup演示DEMO
float，验证码交互模式为触发式，效果见 float演示DEMO
embed，验证码交互模式为嵌入式，效果见 embed演示DEMO

closeEnable

当 closeEnable 为 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>验证码示例-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	维吾尔语

上一篇：验证码更新动态下一篇：Android接入

对文档做个评价吧：

如果遇到产品相关问题，您可提交工单或在线咨询寻求帮助。

在线咨询电话咨询：95163223 免费试用