Captcha v4
部署文档

Web 集成

Web 和 H5 应用集成指南

环境要求

  • 支持 JavaScript 的现代浏览器
  • HTTPS（生产环境必需）

生产环境必须使用 HTTPS，否则验证码可能无法正常工作。

安装

从 Geetest CDN 加载 SDK：

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

CDN 方式无需安装，直接引入即可使用，且能自动获取最新版本。

下载并托管在您的 CDN：

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

自托管方式适合对资源加载有特殊要求的场景。

基础集成

创建 HTML 结构

index.html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>验证码示例</title>
</head>
<body>
  <div id="captcha-container"></div>
  <button id="submit-btn">提交</button>

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

初始化验证码

app.js
// 初始化验证码
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'bind', // 显示模式: 'float' | 'popup' | 'bind'
  apiServers: ['cap-global.geelabapi.com'], // 必填：根据控制台选择的地域配置
  language: 'zh-cn'
}, function(captchaObj) {
  // 渲染验证码
  captchaObj.appendTo('#captcha-container');

  // 处理表单提交
  document.getElementById('submit-btn').addEventListener('click', function() {
    const result = captchaObj.getValidate();

    if (!result) {
      alert('请完成验证');
      return;
    }

    // 提交到您的服务器
    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
      })
    });
  });
});

重要： apiServers 参数是必填项，必须与您在控制台创建 ID 时选择的地域对应。

配置选项

地域配置（必填）

apiServers 是必填参数，必须与您在控制台创建 ID 时选择的地域对应。

根据您在控制台选择的地域配置对应的 apiServers：

地域apiServers 配置
🌏 全球['cap-global.geelabapi.com']
🇪🇺 欧洲['cap-eu.geelabapi.com']
🇺🇸 北美['cap-na.geelabapi.com']
地域配置示例
// 全球地域
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-global.geelabapi.com']
}, callback);

// 欧洲地域
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-eu.geelabapi.com']
}, callback);

// 北美地域
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-na.geelabapi.com']
}, callback);

详细的地域选择指南请参考 地域选择。

显示模式

按钮绑定 - 点击某个按钮验证码弹出

initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'bind',
  apiServers: ['cap-global.geelabapi.com']  // 根据您的地域配置
}, callback);

适用于：注册表单、登录页面等固定位置

浮动模式 - 显示为浮动按钮

initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'float',
  apiServers: ['cap-global.geelabapi.com']  // 根据您的地域配置
}, callback);

适用于：需要节省页面空间的场景

弹窗模式 - 点击后弹出验证窗口

initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'popup',
  apiServers: ['cap-global.geelabapi.com']  // 根据您的地域配置
}, callback);

适用于：表单提交前的验证

语言设置

支持多种语言，设置 language 参数：

多语言配置
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-global.geelabapi.com'],  // 根据您的地域配置
  language: 'zh-cn' // zh-cn, en, ja, ko, es, fr, de, pt, ru 等
}, callback);

完整的语言列表请参考 API 文档。

自定义样式

样式自定义
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  product: 'bind',
  apiServers: ['cap-global.geelabapi.com'],  // 根据您的地域配置
  width: '300px',
  // 更多样式选项...
}, callback);

API 方法

getValidate()

获取验证结果：

const result = captchaObj.getValidate();

if (result) {
  console.log(result);
  // {
  //   lot_number: "...",
  //   captcha_output: "...",
  //   pass_token: "...",
  //   gen_time: "..."
  // }
} else {
  console.log('用户未完成验证');
}

getValidate() 返回 false 表示用户未完成验证，请在提交前检查。

reset()

重置验证码状态：

captchaObj.reset();

destroy()

销毁验证码实例：

captchaObj.destroy();

在单页应用中切换路由时，记得调用 destroy() 释放资源。

错误处理

错误处理示例
initGeetest4({
  captchaId: 'YOUR_CAPTCHA_ID',
  apiServers: ['cap-global.geelabapi.com']  // 根据您的地域配置
}, function(captchaObj) {
  // 监听错误事件
  captchaObj.onError(function(error) {
    console.error('验证码错误:', error);

    // 实现降级逻辑
    // 例如：显示备用验证方式或直接放行
  });

  // 监听准备就绪事件
  captchaObj.onReady(function() {
    console.log('验证码已准备就绪');
  });

  // 监听验证成功事件
  captchaObj.onSuccess(function() {
    console.log('验证成功');
  });
});

服务端验证

重要： 客户端验证只是第一步，必须在服务端进行二次验证！

客户端验证成功后，您需要将验证结果提交到服务器进行二次验证：

提交验证结果
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,
    // 您的业务数据...
  })
});

完整的服务端验证实现请参考：

常见问题

验证码无法加载

可能原因：

  • gl4.js 未正确加载
  • captcha_id 配置错误
  • 网络连接问题

解决方法：

  1. 检查浏览器控制台是否有错误信息
  2. 确认 captcha_id 是否正确
  3. 检查网络请求是否被拦截

验证总是失败

检查清单：

  • 服务端签名生成是否正确
  • captcha_key 是否正确
  • 所有参数是否完整发送
  • 服务器时间是否准确

CORS 错误

确保域名已在控制台白名单中，生产环境必须使用 HTTPS。

下一步

部署指南

各平台集成指南

iOS 集成

iOS 原生应用集成指南

On this page

环境要求安装基础集成创建 HTML 结构初始化验证码配置选项地域配置（必填）显示模式语言设置自定义样式API 方法getValidate()reset()destroy()错误处理服务端验证常见问题验证码无法加载验证总是失败CORS 错误下一步