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) Whole numbers greater than zero
remUnit Number Set the reference value of rem unit 1 remUnit = font-size of root element / DPR(Deivce pixel Ratio)
zoomEle String If set, the coords will be adjusted along with image scaling  null Element or id selector. DOM element has to be valid.
hideSuccess Boolean Hide the verification succeeded message or not false true/false
hideClose Boolean Hide the close button or not false true/false
hideRefresh Boolean Hide the refresh button or not false true/false

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"); //Embed CAPTCHA button into "captchaBox" of the host page
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"); //Embed CAPTCHA button into "captchaBox" of the host page
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', // **Required**
next_width: '300px',
bg_color: 'black'
}, function (captchaObj) {
captchaObj.appendTo("#captchaBox"); //Embed CAPTCHA button into "captchaBox" of the host page
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(){
//Call verify method to show CAPTCHA only when onReady is executed.
}).onSuccess(function(){
//your code
}).onError(function(){
//your code
})
// Click to submit
button.click = function(){
// some code
// Verify if onReady is executed
captchaObj.verify(); //Show CAPTCHA
// 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);

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

remUnit

Pass a valid Number type argument. The pixels will be converted into rem based on remUnit. This method applies to H5 page.
remUnit = font-size of root element / DPR(device pixel ratio).

//Assume font-size of root element is 124.2 and DPR is 3.
initGeetest ({
...
remUnit: 124.2 / 3;
});

zoomEle

Pass an element containing zoom CSS property or id selector to scale the coordinates to adpat to the page. Please note that the element has to exist and contain zoom CSS property.

<body style = "zoom: 0.7;" id="zoomEle">
</body>
initGeetest({
...
zoomEle: '#zoomEle';
});

hideSuccess

Hide verification succeeded message or not. Boolean value and default is false.

initGeetest({
...
hideSuccess: true;
});

hideClose

Hide close button or not. Boolean value and default is false.

initGeetest({
...
hideClose: true;
});

hideRefresh

Hide refresh button or not. Boolean value and default is false.

initGeetest({
...
hideRefresh: 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) {
// It's time to call captchaObj instance method.
});

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 same as appendTo. This API could be used to send 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 the sample code:

<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="Username">
<input name="password" placeholder="Password">
</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="Username">
<input name="password" placeholder="Password">
<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 method is called. Refer below for detailed description
captchaObj.onSuccess(function () {
var result = captchaObj.getValidate();

// ajax pseudocode
ajax(apirefer, {
geetest_challenge: result.geetest_challenge,
geetest_validate: result.geetest_validate,
geetest_seccode: result.geetest_seccode,

// Passing the data needed by server side, such as username, password, etc.
}, function (data) {
// Handle the logic based on secondary verification result.
});
});
});

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 method is called. See below for detailed description
captchaObj.onSuccess(function () {
var result = captchaObj.getValidate();

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

username: 'xxx',
password: 'xxx'

// Passing the data needed by server side, such as username, password, etc
}, function (data) {
// Handle the logic based on secondary verification result.
if (data.status === 'fail') {
alert('Username or password is wrong. Please re-enter and complete the verification');
captchaObj.reset(); // 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">Submit</div>
<script>
initGeetest({
...

product: 'bind'
}, function (captchaObj) {
...

document.getElementById('btn').addEventListener('click', function () {
if (check()) { // Verify wether submission can proceed or not
captchaObj.verify();
}
});
captchaObj.onSuccess(function () {
// Handle the logic for the user completing the verification
// 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">Loading.Please wait...</div>
</div>
<script>
initGeetest({
...
}, function (captchaObj) {
captchaObj.appendto('#captcha-box');

...

captchaObj.onReady(function () {
// When DOM is ready, hide the element #loading-top
// The following is sample code. You can choose your own way to hide #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 pseudocode. Secondary verification
ajax('/api/gt-validate', {
geetest_challenge: result.geetest_challenge,
geetest_validate: result.geetest_validate,
geetest_seccode: result.geetest_seccode,

// Passing the data needed by server side, such as username, password, etc
}, function (data) {
// Handle the logic based on secondary verification result.
});
});
});

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 () {
// Handle the logic when error occurs.
});
});

onClose(callback)

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

initGeetest({
...

product: 'bind'
}, function (captchaObj) {
...

captchaObj.onClose(function () {
// User closes the CAPTCHA. For instance, you can prompt the user to complete the verification to proceed to the next step
});
});