reCAPTCHA から移行する
Caputchin は reCAPTCHA と同じ 2 つの部分のモデルを使います。トークンを生むページ上のウィジェットと、それを確認するサーバー側のチェックです。なので移行は、書き直しではなく、ほとんど機械的な入れ替えです。特にサーバーのやり取りは、意図的に reCAPTCHA の siteverify の形を映します。このガイドは各部品の前後を示します。
まだ Caputchin のアカウントとサイトキーを作っていなければ、先に アカウントを作成 してください。ページのための 公開鍵（cpt_pub_...）と、バックエンドのための シークレット（cpt_sec_...）が要ります。reCAPTCHA のサイトキーとシークレットキーと同じ分割です。
メンタルモデルは変わらない
reCAPTCHA の周りにすでに作ったすべて、ウィジェットをレンダリングし、トークンを集め、それをサーバーに POST し、リクエストを信頼する前にそれを検証することは、そのままです。変わるのは名前とエンドポイントだけです。
1. クライアントのスニペットを入れ替える
| reCAPTCHA（v2 チェックボックス） | Caputchin | |
|---|---|---|
| スクリプト | <script src="https://www.google.com/recaptcha/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| 要素 | <div class="g-recaptcha" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| フォームのトークンフィールド | g-recaptcha-response（自動注入） | caputchin-token（自動注入） |
| JS でトークンを読む | grecaptcha.getResponse() | pass イベント の detail.token |
reCAPTCHA と同じく、Caputchin のウィジェットは、それが座るフォームに 隠しのトークンフィールドを自動注入 するので、フォームがすでに通常の POST をしていたなら、変えるのは要素と、バックエンドが読むフィールド名だけです。完全なクライアントの設定は ウィジェットを追加 を、CDN と npm の選択 を参照してください。
2. サーバーの検証を入れ替える
ここが 2 つが最も近いところです。リクエストとレスポンスの形が、ほぼフィールドごとに揃います。
| reCAPTCHA | Caputchin | |
|---|---|---|
| エンドポイント | POST https://www.google.com/recaptcha/api/siteverify | POST https://caputchin.com/api/v1/siteverify |
| リクエストのフィールド | secret、response | secret、response（同一） |
| レスポンス | { success, challenge_ts, hostname, "error-codes" } | { success, challenge_ts, hostname, error-codes, score? } |
| 信頼のルール | success === true のときだけ動く | success === true のときだけ動く（同一） |
ほとんどのスタックで、検証のコードへの唯一の変更は URL とシークレットの値です。エラーコードを含む完全なリクエスト/レスポンスのリファレンスは バックエンドでトークンを検証 に、フレームワークのスニペットは バックエンドの例 にあります。
3. reCAPTCHA v3 を使っていたなら、スコアを対応づける
reCAPTCHA v3 は score（0.0 から 1.0）を返し、しきい値を選ぶよう求めます。リクエストがどれだけ人間に見えたかを推測しているのです。Caputchin はそう動き ません。success は権威ある合格/不合格です。検証が実際にクリアされた（proof-of-work のチェック、または サーバーで再導出されたゲームのラウンド）からで、確率ではありません。
コードに if (data.score >= 0.5) があったなら、それを if (data.success) に置き換えてください。Caputchin の score フィールドはゲームのラウンドのためだけに存在し、それは ゲームの スコア（情報用、あなた自身のリーダーボードのため）で、決してボットの可能性ではないので、それでアクセスを判断しないでください。
移行で良くなるもの
- 訪問者データの収集なし。 reCAPTCHA はあなたの訪問者をプロファイルします。Caputchin は IP、User-Agent、フィンガープリント、行動テレメトリを集めません。プロトコルには訪問者の識別子を置く場所がありません。哲学 を参照。
- v2 か v3 かではなく、1 つのウィジェット。 選ぶべき別の不可視/スコアの製品はありません。1 つの要素がチェックボックスと任意のゲームをカバーします。
- 任意のゲーム。 信号機のグリッドの代わりに、検証を、訪問者が実際に遊ぶ短いゲームに変えられます。ゲームを追加 を参照。
- 厳格な CSP は厳格なまま。 Caputchin はきつい Content-Security-Policy の下で走ります。ポリシーを緩めるのではなく、少数のオリジンを許可します。Caputchin がゲームをどうサンドボックス化するか を参照。
落とし穴
- 2 つのキー、2 つの家。 公開鍵（
cpt_pub_...）はページに、シークレット（cpt_sec_...）はサーバー側だけに留まります。まさに reCAPTCHA の規律です。シークレットをブラウザに出荷しないでください。 - トークンは一度きり。 reCAPTCHA と同じく、トークンは一度検証されます。キャッシュもリプレイもしないでください。
- バックエンドが読むフィールド名を変える。 隠しフィールドは
g-recaptcha-responseではなくcaputchin-tokenです。よくある一行の見落としです。
あわせて読む
- ウィジェットを追加：完全なクライアントの設定。
- バックエンドでトークンを検証：権威ある
siteverifyのリファレンス。 - バックエンドの例：各言語での検証の呼び出し。
- ゲームを追加：検証をゲームに変える。