开发文档

快速入门

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();

reCAPTCHA 风格迁移

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

迁移示例

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

<!-- Before (reCAPTCHA) -->
<script src="https://www.google.com/recaptcha/api.js"></script>
<div class="g-recaptcha" data-sitekey="GOOGLE_KEY"></div>

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

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

隐私与数据控制

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

站点隐私配置

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

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

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

验证模式

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

服务端验证

验证接口接受标准 POST 请求。下面是常见语言示例。

Node.js

const res = 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 data = await res.json();
if (!data.success) return res.status(403).send('Verification failed');

Python

import requests

resp = requests.post('https://challenge.botflush.com/api/siteverify', json={
    'secret': BOTFLUSH_SECRET,
    'token': request.form['bf-token']
})
if not resp.json().get('success'):
    abort(403)

PHP

$response = file_get_contents('https://challenge.botflush.com/api/siteverify', false,
  stream_context_create(['http' => [
    'method' => 'POST',
    'header' => 'Content-Type: application/json',
    'content' => json_encode([
      'secret' => BOTFLUSH_SECRET,
      'token' => $_POST['bf-token']
    ])
  ]])
);
$result = json_decode($response, true);
if (!$result['success']) { http_response_code(403); exit; }

Go

payload, _ := json.Marshal(map[string]string{
    "secret": os.Getenv("BOTFLUSH_SECRET"),
    "token":  r.FormValue("bf-token"),
})
resp, _ := http.Post("https://challenge.botflush.com/api/siteverify",
    "application/json", bytes.NewBuffer(payload))
var result struct{ Success bool }
json.NewDecoder(resp.Body).Decode(&result)
if !result.Success { w.WriteHeader(403); return }

下载

Node Inspector — Chrome 扩展

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