帮助中心

常规验证码

2022.06.28 10:23:17

全新人机验证方式，高效拦截机器行为，业务安全第一道防线。常规验证码包括：滑动拼图、文字点选、图标点选、推理拼图、短信上行、语序点选、空间推理、语音验证码。

平台支持

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

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

资源引入

方案一：含宕机方案版引入
本方案稳定性更高，可有效避免因网络故障引发的服务中断，推荐接入!

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

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

script 引入

    <script src="/path/yidun-captcha.js"></script>

模块引入

    import initNECaptchaWithFallback from '/path/yidun-captcha'

注释： 当易盾服务器宕机了，请求验证码失败超过一定次数（示例代码中默认为 3 次，可配置），最后一次会触发宕机逻辑，宕机表现为：web 端提示“前方拥堵，已自动跳过验证”，验证码直接验证通过，用户可进行后续业务操作，免受宕机影响。

方案二：简单脚本引入

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

快速调用示例

<!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: 'popup',
                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) {
                console.warn(err)
            })

            var loginBtn = document.getElementById('login')
            loginBtn.addEventListener('click', function () {
                captchaIns && captchaIns.popUp()
            })
        })();
    </script>
</body>
</html>

更多使用场景，见 DEMO

SDK方法说明

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

1. 初始化

代码说明

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

参数说明：

options 基础参数

参数	类型	是否必填	默认值	描述
captchaId	String	是	无	验证码业务ID
mode	String	否	PC 端默认 `"float"`，移动端默认 `"popup"`	验证码模式，有三种模式可选：`"float"`（触发式）、`"embed"`（嵌入式）、`"popup"`（弹出式），示例demo
element	String\|HTMLElement	*	无	容器元素或容器元素选择器。当 mode 是`"popup"` 且用户使用表单提交时，必填；mode 是 `"float"` 或 `"embed"` 时均是必填
width	Number \|String	否	'auto'	验证按钮宽度，推荐使用宽度 260px-400px。类型为 String 时，支持后缀 `px`、`rem`、`%`，类型为 Number 时，内部会将其转换成 px 单位的值。当值为 `"auto"` 时，其宽度与容器元素宽度一致。mode 为 `"popup"` 时，百分比单位无效
onVerify	Function	否	无	验证码一次验证结束回调函数

更多详细参数见参数详情

onload: 验证码初始化成功回调
onerror: 验证码初始化失败回调

回调参数说明：

onload(instance) 回调参数说明

参数	类型	描述
instance	Object	初始化成功后的验证码实例

onerror(error) 回调参数说明

参数	类型	描述
error	Error	初始化失败的错误信息

onVerify(err, data) 回调参数说明

参数	类型	描述
err	Error	验证失败的错误信息
data	Object	验证成功后的信息，格式为`{ validate: 'xxx' }`，其中 validate 为二次验证信息

2. 进行验证码验证（可选）

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

代码说明

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

3. 关闭验证码（可选）

当 enableClose 设置为 true，即开启业务方控制弹框关闭时，若需要关闭验证码弹框，可以调用下述方法：

代码说明

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

4. 刷新验证码（可选）

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

代码说明

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

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

5. 销毁验证码（可选）

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

代码说明

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

参数详情

初始化（initNECaptcha）options 参数详解：

参数	类型	是否必填	默认值	描述
captchaId	String	是	无	验证码业务ID
mode	String	否	PC端默认 `"float"`，移动端默认 `"popup"`	验证码模式，有三种模式可选：`"float"`、`"embed"`、`"popup"`，详见下述 mode 部分
element	String\|HTMLElement	*	无	容器元素或容器元素选择器。当 mode 是 `"popup"` 且用户使用表单提交时，必填；mode 是 `"float"` 或 `"embed"` 时均是必填
width	Number \|String	否	'auto'	验证按钮宽度，推荐使用宽度 260px-400px。类型为 String 时，支持后缀 `px`、`rem`、`%`，类型为 Number 时，内部会将其转换成 `px` 单位的值。当值为 `"auto"` 时，其宽度与容器元素宽度一致。mode 为 `"popup"` 时，百分比单位无效
protocol	String	否	与用户网站的网络协议一致	验证码传输数据使用的网络协议，可选：`"http"`、`"https"`
lang	String	否	'zh-CN'	验证码语言选项。支持 `"zh-CN"`、`"zh-TW"`、`"en"`等
timeout	Number	否	6000ms	内部每个请求的超时时间
appendTo	String\|HTMLElement	否	无	验证码弹框的指定区域元素或者指定区域元素选择器。该配置仅在 popup 模式有效，请注意，指定区域的元素必须为非静态定位
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：模式

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

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	维吾尔语

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-popup">点击弹出验证码</button>
<div id="captcha"></div>
<script>
    var captchaIns;
    initNECaptcha({
        element: '#captcha',
        captchaId: '从易盾申请的captchaId',
        mode: 'popup',
        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-popup').addEventListener('click', function () {
        captchaIns && captchaIns.popUp()
    })
</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" id="appendWrap">
    <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: 'popup',
      width: '320px',
      appendTo: '#appendWrap',
      onVerify: function () {
        // TODO：处理验证码验证结果
      }
    }, function onload (instance) {
      // 初始化成功
      captchaIns = instance
    }, function onerror (err) {
      // 验证码初始化失败处理逻辑，例如：提示用户点击按钮重新初始化
    })
    
    // 监听button的点击事件，弹出验证码
    document.getElementById('j-bind').addEventListener('click', function () {
      captchaIns && captchaIns.popUp()
    })
  </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	含义
200	校验未通过，是因为业务错误，包含超限
300	校验未通过，包含轨迹错误等
432	非法业务ID，包含业务到期等
501	请求失败，包括网络原因等
502	请求脚本资源失败
503	请求图片资源失败
505	请求音频资源失败
1000	未知错误

下一篇：开通服务流程

对文档做个评价吧：

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

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