极验行为验证第四代 面向开发者快速集成指南

本文用于让开发者在不跳转多份文档的情况下完成极验行为验证第四代 的标准接入。除非需要自定义 UI、语言、风控模式或特殊端能力，按本文即可完成客户端初始化、业务触发、服务端二次校验、异常排查和联调验收。

参考来源：

• 服务端部署：https://docs.geetest.com/gt4/deploy/server
• Web 客户端部署：https://docs.geetest.com/gt4/deploy/client/web/
• Web API：https://docs.geetest.com/gt4/apirefer/api/web
• iOS 部署：https://docs.geetest.com/gt4/deploy/client/ios
• Android 部署：https://docs.geetest.com/gt4/deploy/client/android
• HarmonyOS 部署：https://docs.geetest.com/gt4/deploy/client/harmonyos
• 小程序部署：https://docs.geetest.com/gt4/deploy/client/miniprogram/wx

官方快捷入口：

1. 接入目标

极验行为验证第四代 适合保护这些高风险动作：

• 登录
• 注册
• 重置密码
• 提交表单
• 支付、提现、领券等权益动作
• 保存配置
• 敏感后台操作

推荐原则：

• 只拦高风险动作，不拦普通页面浏览。
• 客户端负责拉起验证和拿到验证结果。
• 服务端必须调用极验 /validate 做二次校验。
• 服务端校验成功后才执行业务动作。

不能只做前端验证。客户端结果可以被伪造，安全闭环必须在服务端完成。

2. 标准交互流程

1. 页面或客户端页面加载时初始化极验验证。
2. 用户触发业务动作，例如点击“提交”“保存”“登录”。
3. 客户端拉起验证码。
4. 用户验证成功后，客户端拿到验证结果。
5. 客户端把业务参数和验证结果一起提交到业务服务端。
6. 业务服务端用 captcha_key 生成 sign_token。
7. 业务服务端调用极验二次校验接口 /validate。
8. result=success 时执行业务动作。
9. result=fail 或请求异常时按业务风险策略处理。

3. 必要参数

3.1 控制台参数

3.2 客户端验证成功后返回给服务端的参数

3.3 服务端提交给极验的参数

4. Web / H5 快速接入

4.1 引入脚本

<script src="https://static.geetest.com/v4/gt4.js"></script>

4.2 页面加载时初始化

<div id="captcha-box"></div>

<script>
  let captchaObj = null;
  let captchaReady = false;

  initGeetest4(
    {
      captchaId: "你的 captchaId",
      product: "bind",
      language: "zho",
      timeout: 10000,
      protocol: "https://"
    },
    function (captcha) {
      captchaObj = captcha;

      captcha
        .onReady(function () {
          captchaReady = true;
        })
        .onSuccess(function () {
          const result = captchaObj.getValidate();
          if (!result) return;

          submitBusinessWithCaptcha(result);
        })
        .onFail(function (failObj) {
          console.warn("captcha fail", failObj);
        })
        .onError(function (error) {
          console.error("captcha error", error);
          alert("验证加载异常，请刷新页面后重试");
        })
        .onClose(function () {
          alert("请完成验证后继续操作");
        });
    }
  );
</script>

说明：

• captchaId 必填。
• product: "bind" 适合“点击业务按钮后再拉起验证”。
• showCaptcha() 只能在 onReady() 后可靠调用。
• getValidate() 只应在 onSuccess() 后读取。
• getValidate() 返回 false 时不要提交业务。
• captcha_key 不能出现在前端代码、APP 包或小程序包中。

4.3 用户点击业务动作时触发验证

document.getElementById("saveButton").addEventListener("click", function (event) {
  event.preventDefault();

  if (!captchaObj || !captchaReady) {
    alert("验证组件加载中，请稍后重试");
    return;
  }

  captchaObj.showCaptcha();
});

4.4 提交业务接口

async function submitBusinessWithCaptcha(captchaResult) {
  const response = await fetch("/api/save-config", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      configName: "example",
      configValue: "value",
      lot_number: captchaResult.lot_number,
      captcha_output: captchaResult.captcha_output,
      pass_token: captchaResult.pass_token,
      gen_time: captchaResult.gen_time
    })
  });

  const data = await response.json();

  if (data.result === "success") {
    alert("保存成功");
    return;
  }

  captchaObj.reset();
  alert(data.reason || "验证失败，请重新验证");
}

5. 服务端快速接入

5.1 二次校验接口

5.2 Node.js 示例

import { createHmac } from "node:crypto";

function buildSignToken(lotNumber, captchaKey) {
  return createHmac("sha256", captchaKey).update(lotNumber).digest("hex");
}

async function validateGeeTest4({
  captchaId,
  captchaKey,
  lot_number,
  captcha_output,
  pass_token,
  gen_time
}) {
  if (!lot_number || !captcha_output || !pass_token || !gen_time) {
    return { result: "fail", reason: "missing captcha params" };
  }

  const signToken = buildSignToken(lot_number, captchaKey);
  const body = new URLSearchParams({
    lot_number,
    captcha_output,
    pass_token,
    gen_time,
    sign_token: signToken
  });

  const url = `https://gcaptcha4.geetest.com/validate?captcha_id=${encodeURIComponent(captchaId)}`;

  const response = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body,
    signal: AbortSignal.timeout(3000)
  });

  if (!response.ok) {
    throw new Error(`geetest validate http ${response.status}`);
  }

  return response.json();
}

5.3 业务接口判定

app.post("/api/save-config", async (req, res) => {
  try {
    const gt = await validateGeeTest4({
      captchaId: process.env.GEETEST_CAPTCHA_ID,
      captchaKey: process.env.GEETEST_CAPTCHA_KEY,
      lot_number: req.body.lot_number,
      captcha_output: req.body.captcha_output,
      pass_token: req.body.pass_token,
      gen_time: req.body.gen_time
    });

    if (gt.result !== "success") {
      return res.status(403).json({
        result: "fail",
        reason: gt.reason || gt.msg || "captcha validate failed",
        code: gt.code
      });
    }

    // 在这里执行真实业务，例如保存配置、登录、提交订单。
    return res.json({ result: "success" });
  } catch (error) {
    // 高风险动作建议失败关闭：极验接口异常时拒绝业务。
    return res.status(503).json({
      result: "fail",
      reason: "captcha service unavailable"
    });
  }
});

失败策略建议：

• 登录、注册、保存配置、支付等高风险动作：极验异常时拒绝业务。
• 低风险动作：可按业务需要做降级放行，但必须记录日志和监控。

6. 全客户端快捷部署

6.1 Web / H5

适用：PC Web、移动 H5、内嵌 WebView。

步骤：

1. 引入 https://static.geetest.com/v4/gt4.js。
2. 页面加载时调用 initGeetest4({ captchaId })。
3. popup / float 模式使用 appendTo() 插入按钮。
4. bind 模式在业务按钮点击时调用 showCaptcha()。
5. onSuccess() 后调用 getValidate()。
6. 把 lot_number、captcha_output、pass_token、gen_time 发给业务服务端。
7. 服务端调用 /validate 二次校验。

注意：

• 同一页面多个验证场景需要分别初始化。
• iframe 内使用时需要 sandbox="allow-scripts allow-popups"。
• 避免全局 CSS 污染极验组件，例如全局 button、弹层、通配选择器。

6.2 React / Vue / Angular

适用：SPA 项目。

步骤：

1. 在入口 HTML 加载 gt4.js，或在组件挂载阶段动态加载一次脚本。
2. 在业务页面组件 mounted / useEffect / ngOnInit 阶段初始化。
3. 将 captchaObj 保存在组件状态或 ref 中。
4. 组件卸载时调用 destroy()。
5. 业务按钮点击时调用 showCaptcha()。
6. onSuccess() 里将验证结果和业务数据提交给服务端。

注意：

• 路由切换后不要复用已销毁实例。
• React Strict Mode 开发环境可能触发双初始化，需用 ref 防重。
• 如果业务页面有多个按钮入口，每个场景应单独初始化。

6.3 React Native

适用：React Native 客户端。

快捷方式：

1. 优先参考官方 react-native demo。
2. 若使用 WebView 方式承载 H5 验证页，H5 页面仍按 Web / H5 流程接入。
3. 验证成功后通过 WebView bridge 把结果传回 Native。
4. Native 调业务后端，业务后端再调极验 /validate。

必须保证：

• Native 包内不包含 captcha_key。
• 二次校验只在服务端完成。

6.4 Flutter

适用：Flutter 客户端。

快捷方式：

1. 使用官方 gt4_flutter_plugin。
2. 初始化时传入 captchaId。
3. 在业务动作触发时启动验证。
4. 成功回调里拿到验证结果字符串或对象。
5. 将结果透传给业务服务端做二次校验。

必须保证：

• 客户端只持有 captchaId。
• captcha_key 只在服务端环境变量或密钥系统中保存。

6.5 iOS 原生

环境要求：

• iOS 9+
• Xcode 13+
• 依赖 WebKit.framework

步骤：

1. 导入 GTCaptcha4.framework 或 GTCaptcha4.xcframework。
2. 在 Linked Frameworks and Libraries 中确认已添加。
3. Other Linker Flags 添加 -ObjC。
4. 同时引入 GTCaptcha4.Bundle。
5. 实现 <GTCaptcha4SessionTaskDelegate>。
6. 初始化 GTCaptcha4Session，传入 captchaID。
7. 在页面加载时提前创建 session。
8. 业务按钮点击时调用 verify。
9. 在 didReceive:result: 中判断 code。
10. code == "1" 时把 result 提交给业务后端二次校验。
11. 在 didReceiveError: 中记录并展示错误码。

核心代码：

#import <GTCaptcha4/GTCaptcha4.h>

#define captchaID @"你的 captchaId"

@interface ViewController () <GTCaptcha4SessionTaskDelegate>
@property (nonatomic, strong) GTCaptcha4Session *captchaSession;
@end

- (GTCaptcha4Session *)captchaSession {
  if (!_captchaSession) {
    _captchaSession = [GTCaptcha4Session sessionWithCaptchaID:captchaID];
    _captchaSession.delegate = self;
  }
  return _captchaSession;
}

- (void)viewDidLoad {
  [super viewDidLoad];
  [self captchaSession];
}

- (void)startVerify {
  [self.captchaSession verify];
}

- (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession
              didReceive:(NSString *)code
                  result:(NSDictionary *)result {
  if ([@"1" isEqualToString:code] && result.count > 0) {
    // 提交 result 到业务服务端二次校验
  }
}

- (void)gtCaptchaSession:(GTCaptcha4Session *)captchaSession
         didReceiveError:(GTC4Error *)error {
  NSLog(@"captcha error: %@", error.description);
}

6.6 Android 原生

环境要求：

• Android 5.0+，minSdk 21
• Android Studio 2020.3.1+
• Android Gradle Plugin 7+

步骤：

1. 下载 Android SDK，并把 .aar 放入 libs。
2. repositories 添加 flatDir { dirs 'libs' }。
3. 添加依赖 implementation(name: 'geetest_captcha_android_vx.y.z_date', ext: 'aar')。
4. 非 Kotlin 工程按 SDK 要求补充 Kotlin 插件与标准库。
5. 添加权限 INTERNET，低版本兼容场景添加 ACCESS_NETWORK_STATE。
6. 如需日志分析，按需添加存储权限。
7. 使用 GTCaptcha4Client.getClient(activity).init(captchaId, config) 初始化。
8. 点击业务按钮时调用 verifyWithCaptcha()。
9. addOnSuccessListener 中 status == true 时把 response 提交服务端。
10. onDestroy() 调用 destroy()。
11. 横竖屏切换时调用 configurationChanged(newConfig)。

核心代码：

GTCaptcha4Config config = new GTCaptcha4Config.Builder()
    .setDebug(false)
    .setLanguage("zh")
    .setTimeOut(10000)
    .setCanceledOnTouchOutside(true)
    .build();

gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
    .init("your captcha_id", config)
    .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
      @Override
      public void onSuccess(boolean status, String response) {
        if (status) {
          // 提交 response 到业务服务端二次校验
        } else {
          // 用户答案验证错误
        }
      }
    })
    .addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
      @Override
      public void onFailure(String error) {
        // 记录 error，展示错误码
      }
    });

gtCaptcha4Client.verifyWithCaptcha();

生命周期：

@Override
public void onDestroy() {
  super.onDestroy();
  if (gtCaptcha4Client != null) {
    gtCaptcha4Client.destroy();
  }
}

@Override
public void onConfigurationChanged(Configuration newConfig) {
  super.onConfigurationChanged(newConfig);
  if (gtCaptcha4Client != null) {
    gtCaptcha4Client.configurationChanged(newConfig);
  }
}

6.7 HarmonyOS Next

环境要求：

• HarmonyOS Next
• DevEco Studio 6.0.1 Release
• API Version 20 Release

步骤：

1. 在极验后台下载 HarmonyOS Next SDK。
2. 将 SDK 引入工程。
3. 初始化时传入 captchaId。
4. 在业务动作触发时启动验证。
5. 成功回调中拿到验证结果。
6. 将验证结果提交业务服务端。
7. 服务端做 /validate 二次校验。
8. 错误回调中记录错误码，按错误类型处理。

注意：

• Context 需要符合 SDK 要求。
• 网络、证书、WebView 类错误按错误码排查。
• 客户端不得保存 captcha_key。

6.8 微信小程序

环境要求：

• 微信开发者工具
• 基础库 2.10.4+

步骤：

1. 在小程序后台“设置 - 第三方服务 - 插件管理”添加插件。
2. 使用插件 appid：wx1629d117cf9be937。
3. 在 app.json 声明插件。

{
  "plugins": {
    "captcha4": {
      "version": "2.7.5",
      "provider": "wx1629d117cf9be937"
    }
  }
}

4. 在页面 JSON 引入组件。

{
  "usingComponents": {
    "captcha4": "plugin://captcha4/captcha4"
  }
}

5. 在 WXML 插入组件。

<captcha4
  id="captcha"
  wx:if="{{loadCaptcha}}"
  captchaId="{{captchaId}}"
  bindSuccess="captchaSuccess"
/>

6. 页面加载时传入 captchaId。

onLoad() {
  this.setData({
    loadCaptcha: true,
    captchaId: "你的 captchaId"
  });
}

7. 成功回调中保存验证结果。

captchaSuccess(result) {
  this.setData({ captchaResult: result.detail });
}

8. 提交业务时把 captchaResult 发给业务服务端。

captchaValidate() {
  const data = this.data.captchaResult;
  if (typeof data !== "object") {
    wx.showToast({ title: "请先完成验证", icon: "none" });
    return;
  }

  wx.request({
    url: "你的业务接口",
    method: "POST",
    data: Object.assign({}, data, { businessField: "value" }),
    success: (res) => {
      wx.showToast({ title: res.data.result });
    }
  });
}

6.9 支付宝小程序

环境要求：

• 支付宝开发者工具
• v1.x 基础库 1.25.1+
• v2.x 基础库 2.7.2+

步骤：

1. 在支付宝小程序后台“开发 - 插件服务 - 添加插件”或插件市场添加插件。
2. 插件 provider：2021002178617823。
3. app.json 声明插件。

{
  "plugins": {
    "captcha4": {
      "version": "*",
      "provider": "2021002178617823"
    }
  }
}

4. 页面 JSON 引入：

{
  "usingComponents": {
    "captcha4": "plugin://captcha4/captcha4"
  }
}

5. AXML 插入组件：

<captcha4
  id="captcha"
  a:if="{{loadCaptcha}}"
  captchaId="{{captchaId}}"
  onSuccess="captchaSuccess"
/>

6. onLoad 设置 loadCaptcha 和 captchaId。
7. captchaSuccess 保存 result.detail。
8. 调用 my.request 将结果提交到业务服务端。

6.10 字节 / 百度 / QQ / 快手小程序

通用步骤：

1. 在对应小程序平台添加极验行为验证第四代 插件或组件。
2. 在全局配置中声明插件。
3. 在页面配置中通过 plugin://captcha4/captcha4 或平台文档指定路径引入组件。
4. 在模板中传入 captchaId。
5. 监听成功回调并保存 result.detail。
6. 提交业务时把验证结果随业务参数提交到业务服务端。
7. 服务端统一走 /validate 二次校验。

差异点：

• 模板语法、事件名和请求 API 按平台分别使用，例如 tt.request、swan.request、qq.request、ks.request。
• 插件申请入口和 provider 以对应平台后台为准。
• 统一原则不变：客户端只拿验证结果，服务端做最终校验。

6.11 快应用

快捷方式：

1. 按官方快应用部署文档引入极验组件。
2. 初始化传入 captchaId。
3. 监听成功回调获取验证结果。
4. 使用快应用网络请求能力提交业务服务端。
5. 服务端二次校验。

6.12 Uniapp

快捷方式：

1. 使用官方 Uniapp demo 作为接入基线。
2. H5 目标按 Web / H5 流程。
3. 小程序目标按对应小程序平台流程。
4. App 目标可按 WebView 或原生插件方案接入。
5. 统一将验证结果提交业务服务端二次校验。

6.13 Taro

快捷方式：

1. 使用官方 Taro demo 作为接入基线。
2. Web 目标按 Web / H5 流程。
3. 小程序目标按对应平台插件流程。
4. 把 captchaId 做成环境配置。
5. 成功回调中统一调用业务服务端验证接口。

7. 必要错误码与处理办法

7.1 Web 错误码

Web 端处理建议：

• onError(error)：提示用户刷新或稍后重试，并上报 code、msg、desc。
• onFail(failObj)：统计失败次数，必要时提示重新验证。
• onClose()：提示用户需要完成验证后继续。
• 业务后端返回验证失败：调用 captchaObj.reset()。
• 页面销毁或路由离开：调用 captchaObj.destroy()。

7.2 服务端错误码

服务端处理建议：

• result === "success"：执行业务。
• result === "fail"：拒绝业务，前端重置验证码。
• status === "error"：按错误码排查配置或参数。
• HTTP 非 200 或请求超时：高风险业务拒绝，低风险业务按降级策略处理。

7.3 iOS 错误码

7.4 Android 错误码分类

7.5 HarmonyOS 错误码分类

8. 联调清单

客户端检查：

• gt4.js 或对应 SDK 是否成功加载。
• 页面加载时是否已初始化，不是在点击时才初始化。
• captchaId 是否正确。
• onReady() 是否触发。
• 点击业务按钮是否能拉起验证码。
• onSuccess() 是否触发。
• getValidate() 是否能拿到 lot_number、captcha_output、pass_token、gen_time。
• 失败或业务校验失败后是否调用 reset()。
• 页面卸载或实例不再使用时是否调用 destroy()。

服务端检查：

• captcha_key 是否只存在服务端。
• 是否用 captcha_key 对 lot_number 做 HMAC-SHA256。
• sign_token 是否为 hex 字符串。
• /validate 请求是否使用 application/x-www-form-urlencoded。
• captcha_id 是否传给极验。
• result=success 时才执行业务。
• result=fail 时是否拒绝业务并返回可排查原因。
• HTTP 超时、非 200、解析失败是否有明确降级策略。

上线检查：

• 生产环境关闭 Android setDebug(true) 等调试配置。
• 前端没有暴露 captcha_key。
• 日志记录 captcha_id、lot_number、错误码、reason，不要记录敏感业务数据。
• 全局 CSS 不影响极验组件。
• WebView、小程序、iframe 场景已检查域名、权限和 sandbox。

9. 常见异常处理