Web 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('/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 () {
// 用户把验证关闭了,这时你可以提示用户需要把验证通过后才能进行后续流程
});
});