概述及资源

在您选择了对应的服务端 SDK 并运行 demo 后,可以看到一个简化了的使用验证的方式。也就是说在 demo 的基础上,我们还提供了其他常用的配置参数和接口。本文即用于详细说明验证前端相关的所有配置和接口。

环境需求

条目
兼容性 IE6+、Chrome、Firefox、Safari、Opera、主流手机浏览器、iOS 及 Android上的内嵌Webview

资源链接

条目
产品结构流程 通讯流程
接口文档 接口示例

安装

准备工作: 服务端部署完成(服务端部署文档)

  1. 引入初始化函数

    <script src="gt.js"></script>

行为验证要求初始化在业务页面加载时同时初始化,否则验证无法读取用户在业务页面操作的行为数据,会导致验证策略失效。

需要说明的是这里的gt.js文件,它用于加载对应的验证JS库。目前我们在每个后端语言的sdk中都存有一份,开发者部署到实际项目时需要将该文件复制到相应的项目中去使用。

之前该文件地址是http://static.geetest.com/static/tools/gt.js ,改为存放在用户的项目中,是为了防止这台静态服务器出问题无法加载该文件,导致后续过程终止,同时这样引用无法使用多静态服务器。

通过以上代码引入 `initGeetest` 初始化函数
  1. 调用初始化函数进行初始化

    ajax({
    url: "API1接口(详见服务端部署)",
    type: "get",
    dataType: "json",
    success: function (data) {
    //请检测data的数据结构, 保证data.gt, data.challenge, data.success有值
    initGeetest({
    // 以下配置参数来自服务端 SDK
    gt: data.gt,
    challenge: data.challenge,
    offline: !data.success,
    new_captcha: true
    }, function (captchaObj) {
    // 这里可以调用验证实例 captchaObj 的实例方法
    })
    }
    })

    以上初始化过程,需要结合服务端 SDK 使用,因为初始化所传入的配置参数来自服务端 SDK。

配置参数

这里说的配置参数,是指初始化验证时传入的 config 对象(key-value 结构),也就是调用初始化函数 initGeetest 时所传入的第一个参数。

以下为必需配置的参数:

参数 类型 说明
gt 字符串 验证 id,极验后台申请得到
challenge 字符串 验证流水号,后服务端 SDK 向极验服务器申请得到
offline 布尔 极验API服务器是否宕机(即处于 fallback 状态)
new_captcha 布尔 宕机情况下使用,表示验证是 3.0 还是 2.0,3.0 的 sdk 该字段为 true

开发者只需要将服务端 SDK 返回的这几个配置参数按照 demo 中的方式传入即可。

以下为可选配置参数:

参数 类型 说明 默认值 可选值
product 字符串 设置下一步验证的展现形式 popup floatpopupcustombind
width 字符串 设置按钮的长度 300px 单位可以是 px%emrempt
lang 字符串 设置验证界面文字的语言 zh-cn zh-cnzh-twenjaid
https 布尔 是否使用https请求 false true``hybrid开发使用请设置true
timeout 数字 设置验证过程中单个请求超时时间 30000(ms)

以下参数设置当productcustom时有效:

参数 类型 作用 说明
area 字符串 设置后续弹出的验证的区域 否者DOM元素。必填
next_width 字符串 设置后续弹出的验证的宽度 默认为弹出区域的90%
bg_color 字符串 设置弹出背景的颜色 默认为黑色,此时弹出背景的颜色为60%透明度的黑色。

product

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

目前提供四种展现形式

  • popup(弹出式)

  • float(浮动式)、

  • custom(与popup类似,但是可以自定义弹出区域)、

  • bind(隐藏按钮类型)。

对于custom类型,需要用户指定一个页面中的元素作为后续验证弹出的容器,这时验证码会在这块区域内居中显示。同时有两个可定制的地方:

  1. 设置背景区域的颜色,字段名为bg_color,颜色可以是任何一种不含透明的颜色,比如黑色(black#000000rgb(0,0,0))。不接受rgba格式的验证。注意我们会给该颜色设置一个60%的透明度

  2. 设置弹出的验证框的宽度(高度等比缩放),字段名为next_width。单位可以为任何有效的css3的长度单位。比如260px90%

对于bind类型,需要注意此时appendTo接口调用将无效,验证时调用verify实例方法进行验证。请参考下文中的实例方法说明部分。

各展现形式效果如下。

popup,弹出式:

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

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

demo地址:
点击弹出,
滑动弹出

float,浮动式:

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

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

demo地址:
点击浮动,
滑动浮动

width

custom,自定义弹出区域形式

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

product: 'custom',
area: '#area', // **必填参数**
next_width: '300px',
bg_color: 'black'
}, function (captchaObj) {
captchaObj.appendTo("#captchaBox"); //将验证按钮插入到宿主页面中captchaBox元素内
captchaObj.onReady(function(){
//your code
}).onSuccess(function(){
//your code
}).onError(function(){
//your code
})
});

demo地址:
点击custom,
滑动custom

bind,隐藏按钮式

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

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

demo地址:
点击绑定,
滑动绑定

width

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

默认:300px * 44px

注意只能调节宽度,高度固定不变。

例如下面的截图,通过设置 width 使按钮的宽度与输入框一致:

width-demo

设置按钮宽度为 100%,使按钮的宽度与其父元素的宽度一致

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

width: '100%'
}, handler);

设置按钮宽度为 20rem,使按钮的宽度为根元素 font-size(CSS 属性)的 20 倍

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

width: '20rem'
});

lang

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

  • zh-cn(简体中文)
  • zh-tw(繁体中文),
  • en(英文)
  • ja(日文)
  • id(印尼)

其它语言会陆续增加支持。设置为简体中文和英文时的效果图如下:

简体中文:

lang-zh-cn-demo

英文:

lang-en-demo

设置界面语言为英文

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

lang: 'en'
});

demo地址:
英语示例

https

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

用户在 http:// 的页面上使用 https://
hybrid开发用户使用https

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

https: true
});

实例

初始化

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

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

API方法

appendTo(position)

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

可以通过以下方式传入:

  1. 传入 id 选择器
<div id="captcha-box"></div>
...
<script>
initGeetest({
// 省略配置参数
}, function (captchaObj) {
captchaObj.appendTo('#captcha-box');

// 省略其他方法的调用
});
</script>
  1. 传入 DOM 元素
<div id="captcha-box"></div>
...
<script>
var captchaBox = document.getElementById('#captcha-box');
initGeetest({
// 省略配置参数
}, function (captchaObj) {
captchaObj.appendTo(captchaBox);

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

bindForm(position)

接受的参数类型与 appendTo 方法一致。该接口的作用是插入验证结果的三个 input 标签到指定的表单中。对于使用表单进行请求的场景,可以使用该接口,如果是使用 ajax 进行交互,则使用下面的 getValidate 方法获取验证的结果。插入的 html 片段如下:

<div class="geetest_form">
<input type="hidden" name="geetest_challenge" value="xxx">
<input type="hidden" name="geetest_validate" value="xxx">
<input type="hidden" name="geetest_seccode" value="xxx">
</div>

将验证的结果查到页面的表单中去

<form id="my-form">
<input name="username" placeholder="用户名">
<input name="password" placeholder="密码">
</form>
...
<script>
initGeetest({
// 省略配置参数
}, function (captchaObj) {
captchaObj.bindForm('#my-form');

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

最终 #my-form 表单中会包含以下标签:

<form id="my-form">
<input name="username" placeholder="用户名">
<input name="password" placeholder="密码">
<div class="geetest_form">
<input type="hidden" name="geetest_challenge" value="xxx">
<input type="hidden" name="geetest_validate" value="xxx">
<input type="hidden" name="geetest_seccode" value="xxx">
</div>
</form>

getValidate()

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

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

除了通过调用 getValidate 获取用户成功验证所得到的结果,在生成的 DOM 中也会包含 3 个 input 标签。如果用户通过表单的形式进行二次验证,用户只需要调用上文提到的 appendTo 方法,把验证按钮插到表单中去即可。

3个input标签代码如下:

...
<div class="geetest_form">
<input type="hidden" name="geetest_challenge">
<input type="hidden" name="geetest_validate">
<input type="hidden" name="geetest_seccode">
</div>
...

通过 ajax 方式进行二次验证

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

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

// ajax 伪代码
ajax(apirefer, {
geetest_challenge: result.geetest_challenge,
geetest_validate: result.geetest_validate,
geetest_seccode: result.geetest_seccode,

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

reset()

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

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

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

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

// ajax 伪代码
ajax('/api/gt-validate', {
geetest_challenge: result.geetest_challenge,
geetest_validate: result.geetest_validate,
geetest_seccode: result.geetest_seccode,

username: 'xxx',
password: 'xxx'

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

verify()

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

这种形式的好处是,允许开发者先对用户所填写的数据进行检查,没有问题之后在调用验证接口。

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

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

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

onReady(callback)

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

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

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

// 省略其他方法的调用

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

onSuccess(callback)

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

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

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

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

// ajax 伪代码,进行二次验证
ajax('/api/gt-validate', {
geetest_challenge: result.geetest_challenge,
geetest_validate: result.geetest_validate,
geetest_seccode: result.geetest_seccode,

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

onError(callback)

监听验证出错事件。参数 callback 为函数类型。

监听验证出错事件,提供用户或者刷新页面重试

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

captchaObj.onError(function () {
// 出错啦,可以提醒用户稍后进行重试
});
});

onClose(callback)

对于product为bind形式的验证。当用户关闭弹出来的验证时,会触发该回调。

initGeetest({
// 省略配置参数

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

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