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