BotFlush 接入文档 | CAPTCHA 集成指南

快速入门

BotFlush 的基础接入分为 3 步：加载组件、渲染组件、在服务端验证 token。

1. 加载组件

在页面中异步加载 BotFlush widget 脚本。

<script src="https://challenge.botflush.com/widget.js" async defer></script>

2. 添加容器

在需要出现验证组件的位置放置容器，并填入站点密钥。

<div id="bf-captcha" data-sitekey="YOUR_SITE_KEY"></div>

3. 服务端验证

用户完成验证后会得到 token。后端使用 Secret Key 和 token 调用验证接口，再决定是否放行受保护动作。

POST https://challenge.botflush.com/api/siteverify
Content-Type: application/json

{
  "secret": "YOUR_SECRET_KEY",
  "token": "TOKEN_FROM_CLIENT"
}

Response:
{
  "success": true,
  "site_key": "YOUR_SITE_KEY",
  "timestamp": "2026-04-15T12:00:00Z"
}

JavaScript API

BotFlush.render()

通过 JavaScript 将验证组件渲染到指定容器。

BotFlush.render('bf-captcha', {
  siteKey: 'YOUR_SITE_KEY',
  callback: function(token) {
    // 收到 token 后发送到你的服务端
    console.log('Verified:', token);
  },
  'expired-callback': function() {
    // token 过期后提示用户重新验证
  },
  'error-callback': function() {
    // 验证过程中出现错误
  }
});

BotFlush.reset()

将组件重置到初始状态。表单提交失败后通常会用到。

BotFlush.reset();

BotFlush.getResponse()

读取当前验证 token。用户未完成验证时返回空字符串。

var token = BotFlush.getResponse();

现有 CAPTCHA 迁移

BotFlush 为常见复选框式 CAPTCHA 接入提供迁移路径。实际改动取决于你的应用如何处理回调、错误和服务端验证结果。

	原 CAPTCHA	BotFlush
组件脚本	`legacy-captcha.example/api.js`	`challenge.botflush.com/widget.js`
验证接口	`legacy-captcha.example/api/siteverify`	`challenge.botflush.com/api/siteverify`
站点密钥	原服务商站点密钥	控制台中的 BotFlush 站点密钥
容器 class	`captcha-widget`	BotFlush 容器属性
回调参数	`data-callback`	支持 `data-callback`

迁移示例

你可以从现有 CAPTCHA 接入中先调整脚本和站点密钥：

<!-- Before (existing CAPTCHA) -->
<script src="https://legacy-captcha.example/api.js"></script>
<div class="captcha-widget" data-sitekey="LEGACY_SITE_KEY"></div>

<!-- After (BotFlush) -->
<script src="https://challenge.botflush.com/widget.js"></script>
<div class="captcha-widget" data-sitekey="BOTFLUSH_KEY"></div>

服务端将验证接口从 legacy-captcha.example/api/siteverify 调整为 challenge.botflush.com/api/siteverify。验证接口会返回常见的 success 和 error 字段；迁移时请确认你的业务错误处理逻辑仍然符合预期。

隐私与数据控制

BotFlush 围绕隐私优先和最小化数据使用设计。实际数据处理范围取决于你的部署方式、账户设置和数据处理协议。

站点隐私配置

如果你的站点服务欧盟用户，或需要更严格的数据处理边界：

登录 BotFlush 控制台
进入对应站点的设置
启用当前套餐可用的隐私模式
根据配置限制可选统计和 cookie 使用

具体可用能力可能受套餐和部署方式影响。控制台是当前隐私与数据控制能力的准确信息来源。

验证模式

BotFlush 提供多种验证引擎。你可以在控制台中按站点配置允许的 CAPTCHA 类型。

引擎	类型	说明
Invisible Free	后台验证	低交互的基础验证流程
Visual Match	交互验证	图片模式匹配验证
Emoji Click	交互验证	从视觉网格中选择匹配表情
Invisible Pro	后台验证	更高阶的行为与环境信号分析
Invisible Max	后台验证	提高自动化攻击成本的计算型验证
Text Challenge	交互验证	本地化文字挑战

服务端验证

验证接口接受标准 POST 请求。选择你的后端语言查看对应示例。

const response = await fetch('https://challenge.botflush.com/api/siteverify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    secret: process.env.BOTFLUSH_SECRET,
    token: req.body['bf-token']
  })
});

const result = await response.json();
if (!result.success) {
  return res.status(403).send('Verification failed');
}

import requests

response = requests.post('https://challenge.botflush.com/api/siteverify', json={
    'secret': BOTFLUSH_SECRET,
    'token': request.form['bf-token'],
})

if not response.json().get('success'):
    abort(403)

$payload = json_encode([
  'secret' => getenv('BOTFLUSH_SECRET'),
  'token' => $_POST['bf-token'] ?? ''
]);

$context = stream_context_create(['http' => [
  'method' => 'POST',
  'header' => 'Content-Type: application/json',
  'content' => $payload,
]]);

$response = file_get_contents('https://challenge.botflush.com/api/siteverify', false, $context);
$result = json_decode($response, true);
if (empty($result['success'])) { http_response_code(403); exit; }

payload, _ := json.Marshal(map[string]string{
    "secret": os.Getenv("BOTFLUSH_SECRET"),
    "token":  r.FormValue("bf-token"),
})

resp, err := http.Post("https://challenge.botflush.com/api/siteverify",
    "application/json", bytes.NewBuffer(payload))
if err != nil { http.Error(w, "verify failed", 502); return }
defer resp.Body.Close()

var result struct{ Success bool }
json.NewDecoder(resp.Body).Decode(&result)
if !result.Success { w.WriteHeader(http.StatusForbidden); return }

HttpClient client = HttpClient.newHttpClient();
String body = """
{
  "secret": "%s",
  "token": "%s"
}
""".formatted(System.getenv("BOTFLUSH_SECRET"), token);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://challenge.botflush.com/api/siteverify"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
Map<String, Object> result = new ObjectMapper().readValue(response.body(), Map.class);
if (!Boolean.TRUE.equals(result.get("success"))) {
    throw new SecurityException("Verification failed");
}

using var client = new HttpClient();
var payload = new {
    secret = Environment.GetEnvironmentVariable("BOTFLUSH_SECRET"),
    token = Request.Form["bf-token"].ToString()
};

var response = await client.PostAsJsonAsync(
    "https://challenge.botflush.com/api/siteverify",
    payload);
var result = await response.Content.ReadFromJsonAsync<VerifyResult>();

if (result?.Success != true) {
    return Forbid();
}

下载

Node Inspector — Chrome 扩展

检查使用 BotFlush 的网站由哪个服务 endpoint 返回验证挑战。扩展会在页面右下角显示 endpoint URL。

安装：下载并解压，打开 Chrome 的 chrome://extensions，启用开发者模式，选择 Load Unpacked 后加载目录。

下载 Node Inspector (.zip)

开发文档