Web Integration

Environment Requirements

Modern browser with JavaScript support
HTTPS (required for production)

Production environments must use HTTPS, otherwise the captcha may not work properly.

Installation

Load the SDK from Geetest CDN:

index.html

<script src="https://static.geelabapi.com/v4/gl4.js"></script>

The CDN method requires no installation, can be used directly, and automatically gets the latest version.

Download and host on your CDN:

gl4.js - Main SDK
bypass.js - Fallback handler

index.html

<script src="/path/to/gl4.js"></script>

Self-hosting is suitable for scenarios with special requirements for resource loading.

Basic Integration

Create HTML Structure

index.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Captcha Example</title>
</head>
<body>
  <div id="captcha-container"></div>
  <button id="submit-btn">Submit</button>

  <script src="https://static.geelabapi.com/v4/gl4.js"></script>
  <script src="app.js"></script>
</body>
</html>

Initialize Captcha

app.js

// Initialize captcha
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'bind', // Display mode: 'float' | 'popup' | 'bind'
  apiServers: ['cap-global.geelabapi.com'], // Required: Configure based on region selected in console
  language: 'zh-cn'
}, function(captchaObj) {
  // Render captcha
  captchaObj.appendTo('#captcha-container');

  // Handle form submission
  document.getElementById('submit-btn').addEventListener('click', function() {
    const result = captchaObj.getValidate();

    if (!result) {
      alert('Please complete verification');
      return;
    }

    // Submit to your server
    fetch('/api/submit', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        lot_number: result.lot_number,
        captcha_output: result.captcha_output,
        pass_token: result.pass_token,
        gen_time: result.gen_time
      })
    });
  });
});

Important: The apiServers parameter is required and must correspond to the region you selected when creating the ID in the console.

Configuration Options

Region Configuration (Required)

apiServers is a required parameter and must correspond to the region you selected when creating the ID in the console.

Configure the corresponding apiServers based on the region you selected in the console:

Region	apiServers Configuration
🌏 Global	`['cap-global.geelabapi.com']`
🇪🇺 Europe	`['cap-eu.geelabapi.com']`
🇺🇸 North America	`['cap-na.geelabapi.com']`

Region Configuration Example

// Global region
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-global.geelabapi.com']
}, callback);

// Europe region
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-eu.geelabapi.com']
}, callback);

// North America region
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-na.geelabapi.com']
}, callback);

For a detailed region selection guide, please refer to Region Selection.

Display Modes

Button Binding - Captcha pops up when clicking a button

initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'bind',
  apiServers: ['cap-global.geelabapi.com']  // Configure based on your region
}, callback);

Suitable for: Registration forms, login pages, and other fixed locations

Float Mode - Displays as a floating button

initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'float',
  apiServers: ['cap-global.geelabapi.com']  // Configure based on your region
}, callback);

Suitable for: Scenarios where page space needs to be saved

Popup Mode - Verification window pops up after clicking

initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'popup',
  apiServers: ['cap-global.geelabapi.com']  // Configure based on your region
}, callback);

Suitable for: Verification before form submission

Language Settings

Supports multiple languages, set the language parameter:

Multi-language Configuration

initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-global.geelabapi.com'],  // Configure based on your region
  language: 'zh-cn' // zh-cn, en, ja, ko, es, fr, de, pt, ru, etc.
}, callback);

For a complete language list, please refer to the API Documentation.

Custom Styling

Style Customization

initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'bind',
  apiServers: ['cap-global.geelabapi.com'],  // Configure based on your region
  width: '300px',
  // More style options...
}, callback);

API Methods

getValidate()

Get verification result:

const result = captchaObj.getValidate();

if (result) {
  console.log(result);
  // {
  //   lot_number: "...",
  //   captcha_output: "...",
  //   pass_token: "...",
  //   gen_time: "..."
  // }
} else {
  console.log('User has not completed verification');
}

getValidate() returning false means the user has not completed verification. Please check before submission.

reset()

Reset captcha state:

captchaObj.reset();

destroy()

Destroy captcha instance:

captchaObj.destroy();

Remember to call destroy() to release resources when switching routes in single-page applications.

Error Handling

Error Handling Example

initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-global.geelabapi.com']  // Configure based on your region
}, function(captchaObj) {
  // Listen for error events
  captchaObj.onError(function(error) {
    console.error('Captcha error:', error);

    // Implement fallback logic
    // For example: Display alternative verification method or allow direct access
  });

  // Listen for ready event
  captchaObj.onReady(function() {
    console.log('Captcha is ready');
  });

  // Listen for success event
  captchaObj.onSuccess(function() {
    console.log('Verification successful');
  });
});

Server-Side Verification

Important: Client-side verification is only the first step. Secondary verification must be performed on the server side!

After successful client-side verification, you need to submit the verification result to the server for secondary verification:

Submit Verification Result

const result = captchaObj.getValidate();

fetch('/api/submit', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    lot_number: result.lot_number,
    captcha_output: result.captcha_output,
    pass_token: result.pass_token,
    gen_time: result.gen_time,
    // Your business data...
  })
});

For complete server-side verification implementation, please refer to:

Server Integration Guide - Integration steps and best practices
Server API Documentation - Complete API parameters and code examples

Common Issues

Captcha Not Loading

Possible causes:

gl4.js not loaded correctly
captcha_id configured incorrectly
Network connection issues

Solutions:

Check browser console for error messages
Confirm captcha_id is correct
Check if network requests are being blocked

Verification Always Fails

Checklist:

Is server-side signature generation correct
Is captcha_key correct
Are all parameters sent completely
Is server time accurate

CORS Errors

Ensure your domain is in the console whitelist. Production environments must use HTTPS.

Next Steps

Server Integration - Backend verification guide
API Reference - Complete API documentation
FAQ - More troubleshooting

Web Integration

On this page