使用教程 - ShowBot

ShowBot 组件详细使用教程

本教程将引导你完成 ShowBot 人机验证组件的接入、配置和进阶用法。

第一步：注册账户并获取 API 密钥

1. 前往注册页面创建账户。

2. 注册成功后，系统会返回你的 API 密钥（格式为 sb_ 开头），请妥善保存。

3. 你也可以在控制台查看和复制你的 API 密钥。

API 密钥是你的唯一身份凭证，请勿泄露给他人。每个账户每月享有 1,000,000 次免费验证。

第二步：引入组件脚本

在你的网页 <head> 标签中引入 ShowBot 客户端脚本：

该脚本体积小、加载快，不会影响页面性能。脚本会自动检测页面中的验证组件并渲染。

第三步：放置验证组件

在需要人机验证的位置放置一个 div 容器，并设置 data-sitekey 属性为你的 API 密钥：

脚本加载后会自动扫描页面中所有 .showbot-widget 元素并渲染验证组件，无需额外初始化代码。

第四步：获取验证结果

组件验证通过后，会返回一个短期有效的通行令牌（pass_token）。你可以通过以下方式获取：

方式一：自动渲染 + 回调函数

使用 ShowBot.render() 方法手动渲染组件，并通过 onVerified 回调获取令牌：

<div id="my-widget"></div>

<script>
  ShowBot.render('sb_your_api_key_here', {
    container: '#my-widget',
    onVerified: function(resp) {
      // resp.pass_token 是验证通过后的通行令牌
      console.log('验证通过，令牌：', resp.pass_token);

      // 将令牌提交到你的后端进行服务端验证
      fetch('/your-verify-endpoint', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token: resp.pass_token })
      });
    }
  });
</script>

方式二：表单隐藏字段

将令牌写入隐藏字段，随表单一起提交：

<form action="/submit" method="POST">
  <div class="showbot-widget" data-sitekey="sb_your_api_key_here"></div>
  <input type="hidden" name="showbot_token" id="showbot_token">
  <button type="submit">提交</button>
</form>

<script>
  ShowBot.render('sb_your_api_key_here', {
    container: '.showbot-widget',
    onVerified: function(resp) {
      document.getElementById('showbot_token').value = resp.pass_token;
    }
  });
</script>

第五步：服务端验证令牌

收到前端传来的通行令牌后，在你的后端调用 ShowBot 的服务端验证接口确认令牌有效性：

POST https://bot.xcmdy.top/api/v1/siteverify

Header: Authorization: Bearer sb_your_api_key_here
Body: { "token": "收到的通行令牌", "remoteip": "用户IP（可选）" }

验证成功返回：

{ "success": true, "hostname": "...", "challenge_ts": "..." }

服务端验证是确保安全的关键步骤。即使前端验证通过，也必须在后端二次确认令牌有效性，防止令牌被伪造或重放。

各语言示例

Python (requests)

import requests

resp = requests.post(
    'https://bot.xcmdy.top/api/v1/siteverify',
    headers={'Authorization': 'Bearer sb_your_api_key_here'},
    json={'token': user_token, 'remoteip': user_ip}
)
result = resp.json()
if result.get('success'):
    print('验证通过')
else:
    print('验证失败')

Node.js (fetch)

const resp = await fetch('https://bot.xcmdy.top/api/v1/siteverify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sb_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ token: userToken, remoteip: userIp })
});
const result = await resp.json();
if (result.success) {
  console.log('验证通过');
}

PHP (cURL)

$ch = curl_init('https://bot.xcmdy.top/api/v1/siteverify');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer sb_your_api_key_here',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'token' => $user_token,
    'remoteip' => $user_ip
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['success'] ?? false) {
    echo '验证通过';
}

组件参数详解

ShowBot.render(apiKey, options) 方法接受以下参数：

参数	类型	说明
`apiKey`	string	你的 API 密钥（`sb_` 开头），传入 `null` 则匿名模式运行
`options.container`	string \| DOM	CSS 选择器或 DOM 元素，指定组件渲染位置
`options.onVerified`	function	验证通过回调，参数 `resp` 包含 `pass_token` 和 `success`
`options.isAuth`	boolean	是否为认证模式（登录/注册页面使用），默认 `false`
`options.autoOpen`	boolean	是否自动开始验证，默认 `false`
`options.compact`	boolean	是否使用紧凑模式（更小的组件尺寸），默认 `false`

HTML 属性方式

除了 JavaScript 调用，你也可以纯 HTML 方式使用组件：

<!-- 基本用法 -->
<div class="showbot-widget" data-sitekey="sb_your_api_key"></div>

<!-- 自动开始验证 -->
<div class="showbot-widget" data-sitekey="sb_your_api_key" data-autoopen="true"></div>

<!-- 认证模式（登录/注册页面） -->
<div class="showbot-widget" data-mode="auth"></div>

属性	说明
`data-sitekey`	API 密钥，留空则匿名模式
`data-mode`	设为 `auth` 则使用认证模式
`data-autoopen`	设为 `true` 则页面加载后自动开始验证

验证流程说明

当用户点击验证组件时，ShowBot 会执行以下流程：

1. 浏览器特征扫描：组件收集屏幕分辨率、时区、Canvas/WebGL 指纹、插件信息等浏览器环境特征。
2. 风险评估：将特征数据发送到 ShowBot 服务器进行风险评估，计算风险分数。
3. 智能决策：
- 低风险：直接通过，用户无感知，返回通行令牌。
- 中/高风险：弹出四位数字图片验证码，用户输入正确后返回通行令牌。
4. 令牌返回：验证通过后，组件通过 onVerified 回调返回包含 pass_token 的响应对象。
5. 服务端验证：前端将令牌提交到你的后端，后端调用 /api/v1/siteverify 确认令牌有效性。

配额与用量管理

每个账户每月享有 1,000,000 次免费验证配额。
验证次数统计仅包含成功请求（创建挑战 + 验证通过 + 服务端验证），失败的验证不消耗配额。
在控制台可实时查看本月用量和剩余配额。
超出配额后 API 返回 HTTP 429，请联系管理员提升额度。

安全最佳实践

API 密钥可公开暴露在前端代码中（类似 Cloudflare Turnstile 的 sitekey），真正的安全保障来自服务端验证。
务必在后端验证令牌，不要仅依赖前端验证结果。
通行令牌有效期为 10 分钟，过期后需重新验证。
每个令牌只能验证一次，不可重复使用。
如发现异常流量，可在管理后台禁用相关账户。

完整示例

以下是一个完整的 HTML 页面示例，包含组件接入和表单提交：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <title>我的表单 - ShowBot 保护</title>
  <script src="https://bot.xcmdy.top/static/showbot.js"></script>
</head>
<body>
  <form id="myForm" action="/api/submit" method="POST">
    <label>用户名</label>
    <input name="username" required>

    <label>邮箱</label>
    <input name="email" type="email" required>

    <label>人机验证</label>
    <div id="showbot-container"></div>
    <input type="hidden" name="showbot_token" id="showbot_token">

    <button type="submit">提交</button>
  </form>

  <script>
    ShowBot.render('sb_your_api_key_here', {
      container: '#showbot-container',
      onVerified: function(resp) {
        document.getElementById('showbot_token').value = resp.pass_token;
      }
    });

    // 表单提交前检查是否完成验证
    document.getElementById('myForm').addEventListener('submit', function(e) {
      if (!document.getElementById('showbot_token').value) {
        e.preventDefault();
        alert('请先完成人机验证');
      }
    });
  </script>
</body>
</html>

常见问题

Q: 组件不显示怎么办？

请检查：1) 脚本是否正确加载（浏览器控制台无报错）；2) data-sitekey 是否填写正确；3) 容器元素是否存在。

Q: 验证通过但令牌无效？

通行令牌有效期为 10 分钟且只能使用一次。请确保在令牌过期前提交到后端验证。如果令牌已过期，需要用户重新点击验证。

Q: 如何在 SPA（单页应用）中使用？

在路由切换后，手动调用 ShowBot.render() 重新渲染组件即可。每次调用会创建新的验证实例。

Q: 可以自定义组件样式吗？

组件支持浅色/深色主题自动适配。你可以通过 CSS 覆盖 .sb-widget 相关类名来微调外观，但不建议修改核心结构。

Q: 匿名模式和 API 密钥模式有什么区别？

匿名模式（不传 API 密钥或传 null）适用于登录/注册等认证场景，使用内部验证码系统。API 密钥模式适用于网站防护场景，验证次数计入账户配额。