---
type: how-to
title: hCaptcha から移行する
summary: "最小限の変更で hCaptcha を Caputchin に入れ替えます：同じクライアントのウィジェットにサーバー検証を足した形がほぼ 1 対 1 で対応します。各部品の正確な前後がこちらです。"
---

Caputchin は hCaptcha と同じ 2 つの部分のモデルを使います。トークンを生むページ上のウィジェットと、それを確認するサーバー側のチェックです。なので移行は、書き直しではなく、ほとんど機械的な入れ替えです。特にサーバーのやり取りは、hCaptcha 自身が従う `siteverify` の形を映します。このガイドは各部品の前後を示します。

まだ Caputchin のアカウントとサイトキーを作っていなければ、先に [アカウントを作成](/docs/getting-started/create-your-account) してください。ページのための **公開鍵**（`cpt_pub_...`）と、バックエンドのための **シークレット**（`cpt_sec_...`）が要ります。hCaptcha のサイトキーとシークレットキーと同じ分割です。

## メンタルモデルは変わらない

```mermaid
flowchart LR
  A["Widget on your page"] -->|token| B["Your form / request"]
  B -->|token| C["Your backend"]
  C -->|secret + token| D["siteverify endpoint"]
  D -->|success?| C
```

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` イベント](/docs/references/widget-methods-and-events) の `detail.token` |

hCaptcha と同じく、Caputchin のウィジェットは、それが座るフォームに **隠しのトークンフィールドを自動注入** するので、フォームがすでに通常の POST をしていたなら、変えるのは要素と、バックエンドが読むフィールド名だけです。完全なクライアントの設定は [ウィジェットを追加](/docs/getting-started/add-the-widget) を、[CDN と npm の選択](/docs/integration-guides/cdn) を参照してください。

## 2. サーバーの検証を入れ替える

ここが 2 つが最も近いところです。リクエストとレスポンスの形が、ほぼフィールドごとに揃います。

| | hCaptcha | Caputchin |
|---|---|---|
| エンドポイント | `POST https://api.hcaptcha.com/siteverify` | `POST https://verify.caputchin.com/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":"..."}`）に切り替えてください。フィールド自身は変わりません。完全なリクエスト/レスポンスのリファレンスは [バックエンドでトークンを検証](/docs/integration-guides/verify-on-your-backend) に、フレームワークのスニペットは [バックエンドの例](/docs/integration-guides/backend-examples) にあります。

## 3. hCaptcha Enterprise を使っていたなら、スコアを捨てる

hCaptcha Enterprise はリスクの `score`（**高い** 数値が **より多い** リスクを意味する）を返し、しきい値を選ぶよう求めます。Caputchin はそう動き **ません**。`success` は権威ある合格/不合格です。検証が実際にクリアされた（proof-of-work のチェック、または [サーバーで再導出されたゲームのラウンド](/docs/understanding-caputchin/gaming-anti-cheat)）からで、リスクの見積もりではありません。

コードに `if (data.score < 0.7)` があったなら、それを `if (data.success)` に置き換えてください。Caputchin の `score` フィールドは無関係です。それはゲームのラウンドのためだけに存在し、**ゲームの** スコア（情報用、あなた自身のリーダーボードのため）で、決してリスクやボットの可能性ではないので、それでアクセスを判断しないでください。（向きも逆であることに注意。hCaptcha のスコアはリスクとともに上がり、Caputchin のはゲームの成績とともに上がります。）

## 持ち越されるもの、良くなるもの

- **あなたが hCaptcha を選んだプライバシーの姿勢、保たれる。** Caputchin は IP、User-Agent、フィンガープリント、行動テレメトリを集めません。プロトコルには訪問者の識別子を置く場所がないので、漏らす、売るものがありません。[哲学](/docs/understanding-caputchin/philosophy) を参照。
- **任意のゲーム。** 画像選択のチャレンジの代わりに、検証を、訪問者が実際に遊ぶ短いゲームに変えられ、それが AI のソルバーに対して持ちこたえる部分です。[ゲームを追加](/docs/getting-started/add-a-game) を参照。
- **厳格な CSP は厳格なまま。** Caputchin はきつい Content-Security-Policy の下で走ります。ポリシーを緩めるのではなく、少数のオリジンを許可します。[Caputchin がゲームをどうサンドボックス化するか](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page) を参照。

## 落とし穴

- **2 つのキー、2 つの家。** 公開鍵（`cpt_pub_...`）はページに、シークレット（`cpt_sec_...`）はサーバー側だけに留まります。まさに hCaptcha の規律です。シークレットをブラウザに出荷しないでください。
- **トークンは一度きり。** hCaptcha と同じく、トークンは一度検証されます。キャッシュもリプレイもしないでください。
- **バックエンドが読むフィールド名を変える。** 隠しフィールドは `h-captcha-response` ではなく `caputchin-token` です。よくある一行の見落としです。
- **ボディの形式。** 検証のリクエストを、フォームエンコードではなく JSON として送ってください。

## あわせて読む

- [ウィジェットを追加](/docs/getting-started/add-the-widget)：完全なクライアントの設定。
- [バックエンドでトークンを検証](/docs/integration-guides/verify-on-your-backend)：権威ある `siteverify` のリファレンス。
- [バックエンドの例](/docs/integration-guides/backend-examples)：各言語での検証の呼び出し。
- [ゲームを追加](/docs/getting-started/add-a-game)：検証をゲームに変える。