接入文档

前端轻量采集多维特征，后端通过 API 校验 Token 并获取风险评估结果。

请先前往 管理后台 创建 Sitekey，并将对应的 Secret 保存至业务服务端。前端脚本须直接从当前服务域名加载，请勿使用第三方源或在本地持久化缓存 api.js。

前端引入

无需预留挂载容器。在脚本 URL 中配置 Sitekey，评估完成后将自动向页面中的所有 <form> 注入隐藏字段 bot-passive-response。 

<form action="/signup" method="post">
  <input name="email" type="email" />
  <button type="submit">提交</button>
</form>
<script
  src="https://ORIGIN/v1/api.js?sitekey=pk_你的sitekey"
  defer
></script>

亦支持通过标签属性进行配置：

<script
  src="https://ORIGIN/v1/api.js"
  data-sitekey="pk_你的sitekey"
  defer
></script>

默认在页面加载完成后自动执行评估（包含约 1.5 秒行为观察期及工作量证明计算）。单页应用或异步请求可通过 botPassive.getResponse() 或 callback 回调获取 Token。

若页面中已有 <div class="bot-passive"> 元素，脚本将自动绑定至该元素。如需仅引入 JS API 并手动控制渲染，可添加参数 ?render=explicit。

按需触发评估

适用于在表单提交或用户触发关键动作时执行评估的场景：

<form id="signup">
  <button type="submit">提交</button>
</form>
<script
  src="https://ORIGIN/v1/api.js?sitekey=pk_你的sitekey&execution=execute"
  defer
></script>
<script>
  document.getElementById("signup").addEventListener("submit", async (e) => {
    e.preventDefault();
    await botPassive.execute();
    e.target.submit();
  });
</script>

配置参数

参数名称 说明
data-sitekey / ?sitekey= 必填。管理后台生成的 Sitekey
data-execution="render" 默认值。页面加载完成后自动执行评估
data-execution="execute" 手动模式。调用 botPassive.execute() 时触发评估
data-appearance="invisible" 默认值。无界面静默模式
data-appearance="badge" 在页面右下角显示状态徽标（验证中 / 已通过）
data-observe-ms 交互行为观察时间（毫秒）；未设置时采用服务端配置值
data-action 业务场景标识（如 login、signup），用于统计与审计
data-response-field-name 表单隐藏字段名称，默认为 bot-passive-response
data-response-field="false" 禁用自动注入表单字段，须通过 getResponse() 手动获取
data-form / ?form= 指定注入 Token 的表单选择器；未指定时注入页面所有表单

JavaScript API

API 规范兼容主流验证码标准。页面仅存在单个实例时，可省略 id 参数。

const id = botPassive.render({
  sitekey: "pk_你的sitekey",
  execution: "execute",
  callback(token) {},
  errorCallback(message) {},
  expiredCallback() {
    // Token 有效期约为 120 秒
  },
});

await botPassive.execute(id);
botPassive.getResponse(id);
botPassive.reset(id);    // 每次完成服务端校验后重置实例
botPassive.remove(id);
botPassive.ready(() => {});

服务端校验 (Siteverify)

业务服务端携带对应 Sitekey 的 Secret 与前端提交的 Token 请求校验接口，支持 application/x-www-form-urlencoded 及 application/json 格式。 

curl -X POST https://ORIGIN/v1/siteverify \
  -d "secret=$SITE_SECRET" \
  -d "response=$TOKEN" \
  -d "hostname=example.com"
字段 类型 说明
secret 必填 Sitekey 对应的 Secret 密钥
response 必填 前端上报的验证 Token
hostname 建议 预期请求的主机名（域名），不匹配将校验失败
remoteip 可选 客户端 IP 地址，用于核对签发环境与使用环境的一致性

响应示例：

{
  "success": true,
  "risk": 0.13,
  "verdict": "human",
  "score_reason": ["ok.hardware_gpu", "ok.residential_asn"],
  "challenge_ts": "2026-08-20T04:25:53.000Z",
  "hostname": "example.com",
  "ip_class": "residential_isp",
  "error-codes": []
}
  1. success !== true：验证未通过，建议拒绝当前业务操作。
  2. 结合业务场景评估 risk 分值与 verdict 结论：敏感业务（如登录、支付）建议拦截 automation，低风险业务（如发帖、浏览）可设定相对宽松的放行阈值。
  3. 结合 ip_class 制定差异化策略：hosting（数据中心）、vpn、tor_exit 具有较高风险； mobile（移动网络）与 relay（如 iCloud 私人中继）属于正常用户常见网络，建议放行。
  4. Token 仅限一次性使用。校验完成后前端应调用 botPassive.reset() 以准备后续交互。

错误代码

错误代码 说明
missing-input-secret / invalid-input-secret Secret 参数缺失、无效，或对应 Sitekey 已停用
missing-input-response / invalid-input-response Token 参数缺失、签名无效或数据损坏
timeout-or-duplicate Token 已过期（默认 120 秒）或已被重复校验
hostname-mismatch 请求域名与 Token 签发域名不一致
remoteip-mismatch 客户端 IP 与 Token 签发 IP 不一致
sitekey-mismatch Token 与当前使用的 Sitekey 不匹配

结果判定与规则体系

risk 分值范围为 0 至 1（0 表示正常人类行为，1 表示高置信度自动化脚本）。 系统按分值区间划分为不同 verdict 等级：低于 0.2 为 human（人类），0.2–0.45 为 likely_human（疑似人类），0.45–0.75 为 inconclusive（存疑），高于 0.75 或触发一票否决规则为 automation（自动化）。不同业务接口应根据自身安全等级配置相应的处置阈值。

前缀 说明
ip.* 网络属性：数据中心 / CDN / VPN / Tor 节点 / 住宅宽带
tls.* / hdr.* 传输层特征与 HTTP 请求头的一致性
env.* 浏览器运行环境与硬件特征
auto.* 自动化测试框架与调试工具特征
cons.* 声明标识与运行时实际特征的一致性
beh.* 输入设备轨迹、时序与交互行为特征
ok.* 降低风险评分的可信特征

访问 检查台 可体验完整的实时评估流程。详细推理数据的展示受 管理后台 中「调试与实时检测」开关控制。