Configuration

The parameter configuration refers to the config object (key-value structure) which is passed during the captcha verification. It is the first parameter passed when called the initGeetest. Please check the client integration documentation for the required parameters. The followings parameters are optional to be configured.

Variables Type Description Default value Value
product String captcha challenge pop-out style popup float, popup, custom, bind
width String Width of the captcha button 300px The width could be in px%emrempt.
lang String Language of captcha zh-cn zh-cnzh-hkzh-twenjakoidruarespt-ptfrde
https Boolean Use https protocol or others false true. Please set it to true when the project is based on hybrid framework
timeout Number Duration of request timeout 30000(ms)

product

For most of real users, click at the captcha button and then they could pass the captcha test. Suspicious requests will be provided with captcha challenges. GeeTest captcha provides many pop-out styles for captcha challenge.

Four pop-out styles:

  • popup (Pop up style)
  • float(Float style)
  • custom(Similar with popup, but you can custom the pop-out area)
  • bind(Bind GeeTest captcha button to a custom button, invisible captcha)。

For the custom style, it’s required to provide an element in the web page as a container for the pop-out challenge. The captcha will be centered within this area. Please configure the following parameters.

Variables Type Description
area String Set an area for pop-out challenge. The DOM element is required.
next_width String Width of the pop-out challenge. It could be any length unit supported by css3, e.g. 260px, 90%. The default width is the 90% of area.
bg_color String Color of background mask layer. The default color is black. You can set it to any color without opacity. Do not support color in RGBA format. The default opacity is 60%.

For popup and bind style, you could also provide an element in the web page as a container for the pop-out challenge. It’s not required. The captcha challenge will be centered within this area. Please configure the following parameters.

Variables Type Description
area String Set an area for pop-out challenge. The DOM element is not required.
next_width String Width of the pop-out challenge. It could be any length unit supported by css3, e.g. 260px, 90%. The default width is the 90% of area.
bg_color String Color of background mask layer. The default color is black. You can set it to any color without opacity. Do not support color in RGBA format. The default opacity is 60%.

For float style, Please configure the following parameters.

Variables Type Description
next_width String Width of the pop-out challenge. It could be any length unit supported by css3, e.g. 260px, 90%. The default width is the 90% of area.

For the bind style, the appendTo API is invalid. Please call verify method instead to process the verification. Please refer to the example below.

The following section presents examples and demos for each style.

popup style:

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

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

Demo:
Click captcha with popup style
Slide captcha with popup style

float style:

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

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

Demo:
Click captcha with float style
Slide captcha with float style

How to set the width?

custom style

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:
Click captcha with custom style
Slide captcha with custom style

bind style

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:
Click captcha with bind style
Slide captcha with bind style

width

Modify the width of captcha button.

Default: 300px * 44px

Notice: the height of the captcha is fixed, the width is modifiable.

Please find the example below. The width of button can be set by width to fit with input field.

width-demo

Set the width to 100%, then the width of the button will be the same as the width of its parent element

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

width: '100%'
}, handler);y

Set the width to 20rem, then the button will be 20 times the width of root element font-size (CSS property)

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

width: '20rem'
});

lang

GeeTest captcha support for 77 languages. The following are part of the examples.

  • zh-cn (Simplified Chinese)
  • zh-tw (Traditional Chinese, Taiwan)
  • zh-hk (Traditional Chinese, Hong Kong)
  • en (English)
  • ja (Japanese)
  • id (Indonesian)
  • ko (Korean)
  • ru (Russian)
  • ar (Arabic)
  • es (Spanish)
  • pt-pt (Portuguese)
  • fr (French)
  • de (German)

Please find the visual presentation of captcha in Chinese and English below.

Simplified Chinese:

lang-zh-cn-demo

English:

lang-en-demo

Set the captcha language in English

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

lang: 'en'
});

Demo:
Example in English

https

Use https or not. The default value is in consistent with the one used by the webpage in which the captcha has been integrated.
If you want to send https:// captcha request in http:// page or your project is based on hybrid, please refer the following example to set the https:// request.

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

https: true
});

Instance

Captcha initialization

After initializing captcha with initGeetest, its second parameter is a callback function. The first parameter of the callback function is the captcha instance. Please find the example below.

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

API method

appendTo(position)

appendTo method could insert captcha button into the host page. The input value could be id selector (e.g. #captcha-box) or DOM element object.

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

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

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

bindForm(position)

The input value type of bindForm is the same with appendTo. This API could be used to sends a new HTTP request with form submit. While sending a new HTTP request with form submit, the bindForm(position) will insert 3 input tags (see the following html code) into the form.

The following is an example of the inserted 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>

The following code is an example to call the bindForm.

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

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

After the bindForm has been called, three input tags will be added to my-form as shown in the example below.

<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>

If ajax has been applied to perform the HTTP request, please use the following getValidate method to get the verification result.

getValidate()

Use getValidate() if ajax has been applied to perform the HTTP request. Get the verification result from onSuccess if end user has successfully answer the captcha question. This result could be used to perform secondary verification in server SDK. The getValidate will return an object, which contains geetest_challenge, geetest_validate and geetest_seccode.

If the verification failed, the onSuccess will return false. You can decide to submit form or continue to perform the secondary verification with ajax according to the verification result.

If you call the getValidate, it will also automatically insert 3 input tags (see the following html example) to the DOM element. If the HTTP request is sent with form submit, use bindForm(position) method instead of getValidate()

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

Perform secondary verification with 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()

Reset captcha and the verification status will jump to the status that the captcha initialization has finished. It could be used, for example, when usename or password is incorrect but user has passed the captcha test, or error occurs with the captcha.

The following is example that reset the captcha when account or password was incorrect.

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()

When the pop-out style is set to bind, call verify() to process the verification. The verify() could only be used in bind.

The advantages for this style is that it allows developers to examine the answer which user fills in the form first. If the answer is okay, then call the API.

<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)

Listen if the DOM element which contains captcha button is ready.

You can hide the loading prompt of captcha with onReady event.

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

// 省略其他方法的调用

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

onSuccess(callback)

Listen the verification success event.

Listen the verification success event to perform the secondary verification.

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)

Listen the verification error event.
You can ask user to reload the webpage and retry the captcha if error occurs. Please find the example below.

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

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

onClose(callback)

If the product is set to bind, when user close the captcha challenge, it will trigger the callback function.

initGeetest({
// 省略配置参数

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

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