概述及资源

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

环境需求

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

资源链接

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

安装

  1. 引入初始化函数

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

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

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

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

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

    initGeetest({
    // 以下配置参数来自服务端 SDK
    gt: data.gt,
    challenge: data.challenge,
    offline: !data.success,
    new_captcha: data.new_captcha
    }, 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 中的方式传入即可。

对于有定制需求,可以参考以下可选配置参数,简要说明如下(详细说明见下文):

  • width: 字符串类型。设置按钮的长度,单位可以是 px%emrempt 等。默认值 300px
  • product: 字符串类型。设置下一步验证的展现形式,值可以是 floatpopupcustombindcustombind的使用有些注意事项,请参照下面的详细说明)。默认值 popup
  • lang: 字符串类型。设置验证界面文字的语言,值可以是 zh-cnen(其它语言会陆续增加)。默认值 zh-cn
  • protocol: 字符串类型。设置验证涉及到的请求的协议,值可以是 http://https:// 等。默认值与宿主页面所使用的协议一致
  • area: 字符串类型否者DOM元素。当product为custom时有效,必填。用于设置后续弹出的验证的区域。
  • next_width: 字符串类型。当product为custom时有效,默认为弹出区域的90%。用于设置后续弹出的验证的宽度。
  • bg_color: 字符串类型。当product为custom时有效,默认为黑色,此时弹出背景的颜色为60%透明度的黑色。用于设置弹出背景的颜色。
  • timeout: 数字类型。设置验证过程中单个请求的超时时间,默认为30000,即30000毫秒。

width

调节验证按钮的宽度,使按钮适应宿主页面的尺寸。默认情况下,按钮的尺寸为 300px * 44px。注意只能调节宽度,高度固定不变。

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

width-demo

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

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

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

initGeetest({
// 省略必须的配置参数
width: '20rem'
});

product

在验证3.0版本后,绝大多数真实用户仅需点击一下即可通过验证。但是考虑到实际风险情况,被极验判定为有风险的请求,会进入下个阶段的验证。此时,极验提供了弹出二级验证的交互样式,方便用户兼容自己本身的界面。目前提供了两种展现形式,分别是 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,弹出式:

popup-demo

demo地址:

点击弹出,
滑动弹出

initGeetest({
// 省略必须的配置参数
product: 'popup'
})

float,浮动式:

float-demo

demo地址:

点击浮动,
滑动浮动

initGeetest({
// 省略必须的配置参数
product: 'float'
});

custom,自定义弹出区域形式

custom

demo地址:http://www.geetest.com/demo/click-custom.html,http://www.geetest.com/demo/slide-custom.html

initGeetest({
// 省略必须的配置参数
product: 'custom',
area: '#area', // 假设页面有一个id为area的标签
next_width: '300px',
bg_color: 'black'
});

bind,隐藏按钮式

bind

demo地址:

点击绑定,
滑动绑定

initGeetest({
// 省略必须的配置参数
product: 'bind'
});

lang

目前可选语言仅为中文,更多语言正在推出

设置验证界面文字的语言。目前可选语言有:zh-cnen(其它语言会陆续增加)。分别设置为简体中文和英文时的效果图如下:

简体中文:

lang-zh-cn-demo

英文:

lang-en-demo

设置界面语言为英文

initGeetest({
// 省略必须的配置参数
lang: 'en'
});

protocol

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

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

initGeetest({
// 省略必须的配置参数
protocol: 'https://'
});

实例

初始化

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

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

方法

  • appendTo(position): 将验证按钮插入到宿主页面中,参数可以是 id 选择器,也可以是具体的元素
  • bindForm(position): 假如您的页面信息通过表单进行提交的,可以通过此接口将验证参数的结果绑定到一个表单上去
  • getValidate(): 获取二次验证所需的凭证
  • reset(): 重置验证到初始状态
  • verify(): 供product为bind类型的验证使用,进行验证
  • onReady(callback): 监听验证按钮的 DOM 生成完毕事件
  • onSuccess(callback): 监听验证成功事件
  • onError(callback): 监听验证出错事件
  • onClose(callback): 监听product为bind时的关闭验证事件

appendTo(position)

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

可以通过以下方式传入:

  1. 传入 id 选择器

    <div id="captcha-box"></div>
    ...
    <script>
    initGeetest({
    // 省略配置参数
    }, function (captchaObj) {
    captchaObj.appendTo('#captcha-box');
    // 省略其他方法的调用
    });
    </script>
  2. 传入 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()

获取用户进行成功验证所得到的结果,该结果用于进行服务端 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('/api/gt-validate', {
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 () {
// 用户把验证关闭了,这时你可以提示用户需要把验证通过后才能进行后续流程
});
});