Web SDK Integration Guide
Compatibility
| Item | Description |
|---|---|
| Compatibility | IE9+, Chrome, Firefox, Safari, Opera, mainstream mobile browsers, embedded WebView on iOS and Android |
Verification Forms
["slide","icon","nine","match"]
Currently supported forms:
| Name | Description |
|---|---|
| slide | Sliding puzzle |
| icon | Sequential icon clicking |
| nine | Nine-grid |
| match | Match-three game |
Quick Start
Import
gt4.js file
Provided by EngageLab
Importing gt4.js will globally mount the initialization function initGeetest.
<script src="https://captcha-stat.engagelab.com/www/gt4.js"></script>
Initialize Captcha
💡 Tip
Before initialization, you need to obtain a verification ID from the server. See configuration parameters for details.
Use the initGeetest function to get the captcha instance. The first parameter of this function is the configuration parameters for the captcha, and the second parameter is the callback function after initialization is completed.
var config = {
captchaId: 'xxxx', // Verification ID
apiServers: ['https://captcha-api.engagelab.com'], // List of verification server addresses, must be configured as required
staticServers: ['https://captcha-stat.engagelab.com/www/js'] // List of static resource server addresses, must be configured as required
}
/**
* @desc Callback after initialization is completed
* @param { Object } gt Captcha instance
*/
var callback = function(gt) {
// Handle related business based on the captcha instance, such as triggering the captcha window, listening for successful verification events...
}
initGeetest(config, callback)
Trigger Captcha Window
💡 Tip
Paired with the configuration parameter
product, there are two ways to trigger the captcha window:
- Click the built-in button provided to trigger. (
productvalue is notbind) - Call the
showCaptchamethod of the captcha instance. (productvalue isbind)
<div id="captch_wrap" class="captch-wrap"></div>
var config = {
captchaId: 'xxxx', // Verification ID
apiServers: ['https://captcha-api.engagelab.com'], // List of verification server addresses, must be configured as required
staticServers: ['https://captcha-stat.engagelab.com/www/js'], // List of static resource server addresses, must be configured as required
product: 'bind' // Scenario 2
}
/**
* @desc Callback after initialization is completed
* @param { Object } gt Captcha instance
*/
var callback = function(gt) {
gt.onReady(function() {
// Scenario 1: Use the built-in button provided by EngageLab to trigger the captcha window
// Add the built-in button to the specified area
gt.appendTo("#captch_wrap")
// Scenario 2: Custom trigger for the captcha window
// Call the instance's showCaptcha method during a specific event
// For example, trigger immediately after the captcha is ready
gt.showCaptcha()
})
}
initGeetest(config, callback)
Get Verification Result
/**
* @desc Callback after initialization is completed
* @param { Object } gt Captcha instance
*/
var callback = function(gt) {
// Trigger captcha window...
// Listen for verification results
gt.onSuccess(function(res) {
console.log(res)
})
}
initGeetest({...}, callback)
Configuration Parameters
Configuration Parameters
| Parameter | Type | Description | Default Value |
|---|---|---|---|
| captchaId | string | Verification ID, obtained from EngageLab backend | Required |
| product | string | Captcha window display mode, optional values: float, popup, bind | float |
| language | string | Priority is given to the passed value, followed by the current browser language. If neither matches correctly, the default value is used | zh |
| protocol | string | Network protocol | // |
| apiServers | array | Verification request service address (excluding protocol), must be configured as ['https://captcha-api.engagelab.com'] | - |
| staticServers | array | Static resource service address required for verification (excluding protocol), must be configured as ['https://captcha-stat.engagelab.com/www/js'] | - |
| post | boolean | When set to true, the request method is ajax; otherwise, it is jsonp | false |
| showSuccessTip | boolean | Controls the success notification window when product is bind | true |
| riskType | string | Specifies verification forms such as sliding, clicking, etc. (only effective when the backend system's verification mode is set to risk fusion mode) | - |
| timeout | number | Timeout for verification requests | 30000 |
| offlineCb | function | Custom offline handling function | - |
| onError | function | Error capture before captcha initialization | - |
| mask | Object | Configuration for captcha window mask | |
| nativeButton | Object | Configuration related to the built-in button | |
| toolbar | Array | Toolbar configuration | |
| clientType | string | Client type, optional value: web | |
| width | string | Sets the captcha window width. Maximum width is 340px (captcha window height is adaptive, aspect ratio is approximately | 340px |
| zoom | number | Scaling value for special scenarios, not limited by the maximum value (fixed value is 1 for Firefox browser) | 1 |
Mask Object Configuration
| Parameter | Type | Description | Default Value |
|---|---|---|---|
| backgroundColor | string | Valid color value | - |
| outside | boolean | Close captcha when clicking outside the captcha area | - |
NativeButton Object Configuration
| Parameter | Type | Description | Default Value |
|---|---|---|---|
| width | string | Width of the built-in trigger button | - |
| height | string | Height of the built-in trigger button | - |
Toolbar Array Configuration
initGeetest({..., toolbar: ['close', 'refresh']}, function() {...})
Language Configuration
initGeetest({..., language: 'zh'}, function() {...})
| Valid Value | Type | Description |
|---|---|---|
| close | string | Close captcha window button |
| refresh | string | Refresh captcha window button |
Language (18 Types)
| Optional Value | Language |
|---|---|
| ara | Arabic |
| deu | German |
| eng | English |
| fra | French |
| ind | Indonesian |
| jpn | Japanese |
| kor | Korean |
| msa | Malay |
| pon | Brazilian Portuguese |
| por | European Portuguese |
| rus | Russian |
| spa | Spanish |
| tha | Thai |
| udm | Uyghur |
| vie | Vietnamese |
| zh | Simplified Chinese |
| zho-hk | Traditional Chinese (Hong Kong) |
| zho-tw | Traditional Chinese (Taiwan) |
Behavior Verification Offline Mode
Offline mode is set up to handle extreme situations, ensuring that abnormal captcha verification processes do not affect normal business processes.
Offline mode mainly occurs when the website's main server cannot connect to the verification server, resulting in connection timeouts and other issues.
In offline mode, all verification processes bypass the verification server. The integrator needs to add verification logic or have a product downgrade plan.

When the verification server enters offline mode,
The client process remains unchanged, and triggering the captcha will immediately pass, entering onSuccess.
The business system sends a secondary verification to the captcha system, and if it times out, it is confirmed as offline.
initGeetest({...}, function(gt) {
...
gt.onSuccess(function(res) {
console.log(res) // Example of successful verification result
{
captcha_id: "59bbe0f128f0624fdd185a6a2207aa54",
captcha_output: "X000Q5p.....i-SFRyH1",
client_type: "web",
gen_time: "1648204854",
lot_number: "200e2e58e1d3a6906e08cc9ff5c6e0b5",
offline: true,
pass_token: "e000b4dc372c1397976f7b8f12d66ea8d5c993ab2db5810258e835429f6fa4ae"
}
// Submit to the business system...
})
})









