常规验证码
全新人机验证方式,高效拦截机器行为,业务安全第一道防线。 常规验证码包括:滑动拼图、文字点选、图标点选、推理拼图、短信上行、语序点选、空间推理、语音验证码。
平台支持
验证码兼容市场主流浏览器,具体版本见下表:
浏览器 | 最低版本 |
---|---|
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 | 未知错误 |