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.

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.

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.

For float style, Please configure the following parameters.

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.

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)
• th (Thailand)
• tr (Turkey)
• vi (Vietnam)
• ta (Tamil)
• it (Italy)
• bn (Bangladesh)
• mr (Marathi)

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

Simplified Chinese：

English：

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

api_server

Controls the address of the api request.

initGeetest({
    ...
    api_server:'api.geetest.com' // The optional parameter is 'api.geetest.com'.
});

api_server_v3

Controls the address of the api request.

initGeetest({
    ...
    api_server_v3:['api.geetest.com'] // The optional parameter is 'api.geetest.com'.
});

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>

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