サーバー側の連携

ウィジェットはブラウザに一度きりのトークンを渡します。そのトークンは、サーバーが Caputchin で確認するまで何も証明しません。これは、目に見えるチャレンジを本物の保護に変えるステップで、HTTPS 呼び出し 1 回で済みます。

外向きのリクエストを出せるバックエンドと、そこで使えるサイトキーのシークレット（cpt_sec_...、決してブラウザにはないもの）が必要です。

1. トークンを読む

フォームがポストすると、ハンドラーはあなた自身のフィールドと並んで 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 はクライアントが申告するメタデータ（どのゲーム、スコア、所要時間）です。これは null になり得て、セキュリティのシグナルではありません。お望みなら分析のために記録してかまいませんが、スコアで信頼を判断しては決していけません。

あなたを守るルール

一度きり。 トークンは一度だけ検証されます。同じものをもう一度送ると success: false が返るので、リプレイを自分で追跡する必要はありません。
短命。 トークンは発行から 10 分で期限切れになるので、遅延ジョブではなく、送信の処理中に検証してください。
シークレットはサーバーに留まる。 それは決してブラウザへは行かず、呼び出しを認証するものです。

よくある間違い

クライアント側で検証する。 pass イベントとトークンの存在は UX のためだけです。すべての信頼の判断は、ここで、サーバー側で、あなたのシークレットを使って起きます。
score で判断する。 それはメタデータであり、信頼度の値ではありません。

あわせて読む

あなたの言語でのこの呼び出しについてはバックエンド連携の例。
バックエンドを完全に省くにはホスト型認証。