服务端集成

组件递给浏览器一个一次性令牌。在你的服务器用 Caputchin 确认它之前，这个令牌什么都证明不了。这是把一个看得见的挑战变成真正防护的那一步，而它只是一个 HTTPS 调用。

你需要一个能发出站请求的后端，以及在那里可用的你站点密钥的密钥（cpt_sec_...），绝不放在浏览器里。

1. 读取令牌

当表单提交时，你的处理器会在你自己的字段旁收到一个额外字段：caputchin-token。访客通过挑战时，组件把它注入到了表单里。

2. 用 /siteverify 确认它

POST 这个令牌和你的密钥。请求和响应的形状仿照 reCAPTCHA 的 siteverify，所以一个现有的集成几乎不用改就能移植过来：

POST https://caputchin.com/api/v1/siteverify
Content-Type: application/json

{ "secret": "cpt_sec_...", "response": "<caputchin-token>" }

// Node 18+
const verdict = await fetch("https://caputchin.com/api/v1/siteverify", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    secret: process.env.CAPUTCHIN_SECRET,
    response: token,
  }),
}).then((r) => r.json());

if (!verdict.success) {
  // reject the submission
}

同样的调用在其他语言里见后端集成示例。

3. 读取响应

{
  "success": true,
  "error-codes": [],
  "platform": { "game_id": "caputchin/games/leaf-memory", "score": 847, "duration_ms": 4200 }
}

success 是唯一要据以分支的东西。true 意味着一位真实访客通过了挑战；信任该请求。false 意味着丢弃它。
error-codes 在 success 为 false 时出现，点明出了什么错（一个缺失的、过期的或已用过的令牌，等等）。
platform 是客户端声称的元数据（哪个游戏、分数、时长）。它可为空，并且 不是安全信号。你愿意的话可以为分析记录它，但绝不要把信任系在分数上。

保护你的那些规则

一次性使用。 一个令牌只核验一次。再次提交同一个会返回 success: false，所以你不必自己追踪重放。
短时有效。 一个令牌在签发十分钟后过期，所以在处理这次提交时就核验它，而不要放到一个延迟任务里。
密钥留在服务器上。 它绝不去浏览器，而它正是为这个调用做身份验证的东西。

常见错误

在客户端核验。 pass 事件和令牌的存在只是 UX。每一个信任决定都发生在这里，在服务端，用你的密钥。
据 score 设关卡。 它是元数据，不是一个置信度值。

另见

后端集成示例，看响应形状和那些规则。
托管验证，完全跳过后端。