サーバーサイド検証

SilentShieldのNonceは必ずサーバー上で検証してください。クライアントサイドのチェックだけでは、ボットに回避される可能性があります。

なぜサーバーサイドが必要なのか？

ウィジェットはブラウザ上で動作し、フォームにNonceを挿入します。ボットはウィジェットをスキップしてフォームを直接送信する可能性があります。サーバーサイド検証により、NonceがSilentShieldによって正当に発行・検証されたことを確認できます。

APIエンドポイント

Method

POST

URL

https://api.silentshield.io/api/v1/captcha/verify-nonce

Headers

X-Api-Key: YOUR_API_KEY Content-Type: application/json

Body

{ "nonce": "the-nonce-from-the-form" }

レスポンス形式

{
  "ok": true,
  "verdict": "human",
  "confidence": 0.92,
  "requested_nonce": "..."
}

human

human — ユーザーは人間である可能性が非常に高いです。フォームを処理してください。

suspicious

suspicious — サーバーが拒否しました（HTTP 403、`ok: false`）。判定は理由を示すものであり、決定ではありません。決定はアカウントのしきい値によってすでに下されています。

bot

bot — ボットである確信度が高いです。フォームを拒否してください。

推奨される処理ロジック

サーバーはすでにアカウントのしきい値を適用しています。拒否は HTTP 403 と `ok: false` で返ります。したがって `bot` ではなく「通過したか」を確認してください。そうしないと、`suspicious` として下された拒否も、判定を含まない応答（無効なキー、割り当て超過）もすべて通してしまいます。

if not ok or verdict != "human":
    フォームを拒否する (403)
else:
    フォームを通常どおり処理する

AJAXで送信されるフォーム

ウィジェットは、フォームが通常の submit で送信されたときに送信を報告します。リクエスト本文に behavior_nonce フィールドが含まれていれば、XMLHttpRequest によるリクエスト（jQuery.ajax を含む）も報告します。リクエストを少しの間保留し、入力データとマウスデータを報告して、判定が出た時点でリクエストを送信します。遅くとも15秒後です。そのため、フォーム全体を隠しフィールドも含めてシリアライズしてください。サーバー側の検証は変わりません。

エラーハンドリング

SilentShield APIに到達できない場合（タイムアウト、5xxエラー）、対応方針を決定してください：

Fail Open

フェイルオープン — フォームを受け入れます（UXが良いが、安全性は低い）

Fail Closed

フェイルクローズド — フォームを拒否します（安全性が高いが、UXは悪い）