配置参数

这里说的配置参数,是指初始化验证时传入的 config 对象(key-value 结构),也就是调用初始化函数 initGeetest4 时所传入的第一个参数的可选参数配置,必需参数请参考部署文档,demo参考4.0适应性验证码demo

除了captchaId,其它均为可选配置参数(以下配置参数除非您知道如何去使用,否则不要去设置(可能在不同的场景下带来副作用)):

参数 必填 类型 说明 默认值 可选值
captchaId
Y
string 验证 id,极验后台申请得到
product N string 设置下一步验证的展现形式 float float、popup、bind
btnWidth N string 设置按钮的长度 260px 单位可以是 px,%,em,rem,pt
btnHeight N string 设置按钮的宽度 50px 单位可以是 px,%,em,rem,pt
rem N number 设置验证码整体的缩放比例 1 可以根据不同设备传入不同比例值
language N string 设置验证界面文字的语言, 如不传默认取浏览器设置的语言,不在支持的列表内,默认使用中文 zh zh、en、zh-tw、zh-hk、ja、id、ko、ru、ar、es、pt、fr、de
protocol N string 协议头 默认去当前页面的协议头(本地或者混合开发一定要手动设置,否则一般会自动取到file协议) http://、https://、file://
timeout N number 设置验证过程中单个请求超时时间 30000(ms) 大于0的整数
outside N boolean 点击验证码区域外关闭验证 true false
bgColor N string 弹窗背景色 #0000004d 任意合法的css颜色单位都可以
apiServers N array 控制api请求的地址 [‘gcaptcha4.geetest.com’]
nextWidth N string 验证码弹窗的宽度(此参数设置后,验证码弹窗将不会自动根据网页内容宽度调整)
riskType N string 结合风控融合,指定验证形式
offlineCb N function 宕机模式处理函数,默认为极验的宕机,设置了此函数代表想自定义宕机逻辑(不会再执行默认的宕机模式)
onError N function 初始化验证码之前的错误捕获

product

在行为验证中,配置了ai模式的绝大多数真实用户仅需点击一下即可通过验证。但是考虑到实际风险情况,被行为验证判定为有风险的请求,会进入下个阶段的验证。此时,行为验证提供了弹出二级验证的交互样式,方便用户兼容自己本身的界面。

目前提供三种展现形式

  • popup(弹出式)

  • float(浮动式)

  • bind(隐藏按钮类型)

对于popupbind类型,可设置以下参数:

参数 类型 作用 说明
bgColor string 设置弹出背景的颜色 默认为黑色,可设置任何一种合法的颜色值

各展现形式效果如下。

popup,弹出式:

initGeetest4({
// 省略必须的配置参数

product: 'popup'
}, function (captchaObj) {
captchaObj.appendTo("#captchaBox"); //将验证按钮插入到宿主页面中captchaBox元素内
captchaObj.onReady(function(){
//your code
}).onSuccess(function(){
//your code
}).onError(function(){
//your code
})
})

float,浮动式:

initGeetest4({
// 省略必须的配置参数

product: 'float'
}, function (captchaObj) {
captchaObj.appendTo("#captchaBox"); //将验证按钮插入到宿主页面中captchaBox元素内
captchaObj.onReady(function(){
//your code
}).onSuccess(function(){
//your code
}).onError(function(){
//your code
})
});

bind,隐藏按钮式:

对于bind类型,需要注意此时appendTo接口调用将无效,验证时调用showBox实例方法进行验证。

initGeetest4({
// 省略必须的配置参数

product: 'bind'
}, function(captchaObj){
captchaObj.onReady(function(){
//验证码ready之后才能调用showBox方法显示验证码
}).onSuccess(function(){
//your code
}).onError(function(){
//your code
})
// 按钮提交事件
button.click = function(){
// some code
// 检测验证码是否ready, 验证码的onReady是否执行
captchaObj.showBox(); //显示验证码
// some code
}
});

btnWidth

调节验证按钮的宽度,使按钮适应宿主页面的尺寸。

默认:260px * 50px

通过设置 btnWidth btnHeight 使按钮的宽度与输入框一致:

示例: 设置按钮宽度和高度为 100%,使按钮的宽度与其父元素的宽度一致

initGeetest4({
// 省略必须的配置参数
btnHeight: '100%'
btnWidth: '100%'
}, handler);

language

设置验证界面文字的语言。目前可选语言有:

  • zh(简体中文)
  • en(英文)
  • zh-tw(台湾)
  • zh-hk(香港)
  • ja(日文)
  • id(印尼)
  • ko(韩语)
  • ru(俄语)
  • ar(阿拉伯语)
  • es(西班牙语)
  • pt(葡萄牙语)
  • fr(法语)
  • de(德语)

其它语言会陆续增加支持,注意 : 验证图片上的文字是不会根据语言设置来切换的,因为他本身是一张图片,如需要设置图片,可在后台上传自定义图集。

设置为简体中文和英文时的效果图如下:

简体中文:

lang-zh-cn-demo

英文:

lang-en-demo

设置界面语言为英文

initGeetest4({
// 省略必须的配置参数

language: 'en'
});

protocol

设置验证请求头。常见的有 http://https://。默认值与宿主页面所使用的协议一致。

initGeetest4({
// 省略必须的配置参数

protocol: "https://"
});

outside

设置点击验证弹窗区域外,是否关闭验证码,默认为true。
如果不想点击验证区域外关闭验证码,将其设置为false

initGeetest4({
// 省略必须的配置参数

outside: false
});

timeout

设置验证码单个请求加载超时时间,默认为30000毫秒

initGeetest4({
// 省略必须的配置参数

timeout: 10000
});

初始化

使用初始化函数 initGeetest4 初始化后,它的第二个参数是一个回调,回调的第一个参数即是验证实例,如下代码所示。

initGeetest4({
// 省略配置参数
}, function (captchaObj) {
// 现在可以调用验证实例 captchaObj 的方法了
});

Web API方法

appendTo(position)

appendTo 方法用于将验证按钮插到宿主页面,使其显示在页面上。接受的参数可以是 id 选择器(例如 #captcha-box),或者 DOM 元素对象。

可以通过以下方式传入:

1.传入 id 选择器

<div id="captcha-box"></div>
...
<script>
initGeetest4({
// 省略配置参数
}, function (captchaObj) {
captchaObj.appendTo('#captcha-box');

// 省略其他方法的调用
});
</script>

2.传入 DOM 元素

<div id="captcha-box"></div>
...
<script>
var captchaBox = document.getElementById('#captcha-box');
initGeetest4({
// 省略配置参数
}, function (captchaObj) {
captchaObj.appendTo(captchaBox);

// 省略其他方法的调用
});
</script>

getValidate()

获取用户进行成功验证(onSuccess)所得到的结果,该结果用于进行服务端 SDK 进行二次验证。getValidate 方法返回一个对象,该对象包含一些验证需要的字段。

其他情况下返回 false,因此,网站开发者也可以根据该返回值决定是否需要进行下一步的操作(提交表单或者 ajax 进行二次验证)。

通过 ajax 方式进行二次验证

initGeetest4({
// 省略配置参数
}, function (captchaObj) {
// 省略其他方法的调用

// 这里调用了 onSuccess 方法,该方法介绍见下文
captchaObj.onSuccess(function () {
var result = captchaObj.getValidate();

// ajax 伪代码
$.ajax({
url: '服务端',
data: result,
dataType: 'json',
success: function (res) {
console.log(res.result);
}
})
});
});

reset()

让验证回到初始状态。一般是在用户后台发现验证成功但其他信息不对的情况(比如用户名密码错误),或者验证出现错误的情况。因此,该接口只能在成功或者出错的时候调用才有效。对于bind模式,成功后再次调用showBox会自动reset,无需主动调用

发现用户名或者密码错误后进行重置

initGeetest4({
// 省略配置参数
}, function (captchaObj) {
// 省略其他方法的调用

// 这里调用了 onSuccess 方法,该方法介绍见下文
captchaObj.onSuccess(function () {
var result = captchaObj.getValidate();

// ajax 伪代码
ajax('/login', {
lot_number: result.lot_number,
captcha_output: result.captcha_output,
pass_token: result.pass_token,
gen_time: result.gen_time,

username: 'xxx',
password: 'xxx'

// 其他服务端需要的数据,比如登录时的用户名和密码
}, function (data) {
// 根据服务端二次验证的结果进行跳转等操作
if (data.status === 'fail') {
alert('用户名或密码错误,请重新输入并完成验证');
captchaObj.reset(); // 调用该接口进行重置
}
});
});
});

showBox()

当product为bind类型时,可以调用该接口进行验证。

这种形式的好处是,允许开发者先对用户所填写的数据进行检查,没有问题之后在调用验证接口。
但是要特别注意调用的时机,在验证码还未进入onReady状态,调用此方法不会有任何反应。

<div id="btn">提交按钮</div>
<script>
initGeetest4({
// 省略配置参数

product: 'bind'
}, function (captchaObj) {
// 省略其他方法的调用

document.getElementById('btn').addEventListener('click', function () {
if (check()) { // 检查是否可以进行提交
captchaObj.showBox();
}
});
captchaObj.onSuccess(function () {
// 用户验证成功后,进行实际的提交行为
// todo
})
});
</script>

onReady(callback)

监听验证按钮的 DOM 生成完毕事件。参数 callback 为函数类型。

根据 onReady 事件隐藏“加载验证提示语”

<div id="captcha-box">
<div id="loading-tip">加载中,请稍后...</div>
</div>
<script>
initGeetest4({
// 省略配置参数
}, function (captchaObj) {
captchaObj.appendto('#captcha-box');

// 省略其他方法的调用

captchaObj.onReady(function () {
// DOM 准备好后,隐藏 #loading-tip 元素
// 仅作示例用,用您适合的方式隐藏即可
document.getElementById('loading-tip').style.display = 'none';
});
});
</script>

onNextReady(callback)

监听验证下一步资源的加载完毕事件。参数 callback 为函数类型。

<div id="captcha-box">
<div id="loading-tip">加载中,请稍后...</div>
</div>
<script>
initGeetest4({
// 省略配置参数
}, function (captchaObj) {
captchaObj.appendto('#captcha-box');

// 省略其他方法的调用

captchaObj.onNextReady(function () {

});
});
</script>

onSuccess(callback)

监听验证成功事件。参数 callback 为函数类型。

监听验证成功事件,进行二次验证

initGeetest4({
// 省略配置参数
}, function (captchaObj) {
// 省略其他方法的调用

captchaObj.onSuccess(function () {
var result = captchaObj.getValidate();

// ajax 伪代码,进行二次验证
ajax('/login', {
lot_number: result.lot_number,
captcha_output: result.captcha_output,
pass_token: result.pass_token,
gen_time: result.gen_time,

// 其他服务端需要的数据,比如登录时的用户名和密码
}, function (data) {
// 根据服务端二次验证的结果进行跳转等操作
});
});
});

onFail(callback)

监听验证成功事件。参数 callback 为函数类型。
failObj操作失败对象包含: captcha_id、captcha_type、challenge,后续可能增加。
监听验证码操作失败事件,统计用户操作失败次数

initGeetest4({
// 省略配置参数
}, function (captchaObj) {
// 省略其他方法的调用

captchaObj.onFail(function (failObj) {
// 对错误信息做一些统计
});
});

onError(callback)

监听验证出错事件。参数 callback 为函数类型。
刷新过多、静态资源加载失败、网络不给力等验证码能捕获到的错误(参考ErrorCode),都会触发onError回调。
该错误对象包含三部分: code:错误码、msg:提示信息、desc: 该对象包含detail属性,描述具体的错误信息,后续可能会增加

当出错事件触发时,可以提示用户刷新页面重试。

initGeetest4({
// 省略配置参数
}, function (captchaObj) {
// 省略其他方法的调用

captchaObj.onError(function (error) {
// 出错啦,可以提醒用户稍后进行重试
// error 包含error_code、msg
// {code: '60000',msg:"用户配置错误",desc:{ detail: "用户id缺少"} }
});
});

onClose(callback)

当用户关闭弹出来的验证时,会触发该回调。

initGeetest4({
// 省略配置参数

product: 'bind'
}, function (captchaObj) {
// 省略其他方法的调用

captchaObj.onClose(function () {
// 用户把验证关闭了,这时你可以提示用户需要把验证通过后才能进行后续流程
});
});

destroy

销毁验证实例,验证相关UI以及验证注册的事件监听器都会被移除。

initGeetest4({
// 省略配置参数

product: 'bind'
}, function (captchaObj) {
// 省略其他方法的调用

captchaObj.onSuccess(function () {
var result = captchaObj.getValidate();

// ajax 伪代码
ajax('/login', {
lot_number: result.lot_number,
captcha_output: result.captcha_output,
pass_token: result.pass_token,
gen_time: result.gen_time,

username: 'xxx',
password: 'xxx'

// 其他服务端需要的数据,比如登录时的用户名和密码
}, function (data) {
// 根据服务端二次验证的结果进行跳转等操作
if (data.status === 'fail') {
alert('用户名或密码错误,请重新输入并完成验证');
captchaObj.reset(); // 调用该接口进行重置
}else if(data.status === 'success'){
// 结合业务逻辑,判断是否需要移除验证
captchaObj.destroy();
captchaObj = null;
}
});
});
});