---
type: how-to
title: Migrasi dari hCaptcha
summary: "Tukar hCaptcha dengan Caputchin dengan perubahan minimal: bentuk widget-klien-plus-verify-server yang sama memetakan hampir satu-lawan-satu, inilah sebelum-dan-sesudah persis untuk tiap potongan."
---

Caputchin memakai model dua-bagian yang sama dengan hCaptcha, sebuah widget di halaman yang menghasilkan token, dan pemeriksaan sisi-server yang memastikannya, jadi migrasi sebagian besar adalah tukar mekanis, bukan penulisan-ulang. Pertukaran server khususnya mencerminkan bentuk `siteverify` yang diikuti hCaptcha sendiri. Panduan ini memberi sebelum-dan-sesudah untuk tiap potongan.

Jika kamu belum membuat akun Caputchin dan kunci situs, lakukan [buat akunmu](/docs/getting-started/create-your-account) dulu; kamu akan butuh **public key** (`cpt_pub_...`) untuk halaman dan **secret** (`cpt_sec_...`) untuk backend-mu, pemisahan yang sama dengan site key dan secret key hCaptcha.

## Model mental tak berubah

```mermaid
flowchart LR
  A["Widget di halamanmu"] -->|token| B["Formulir / permintaanmu"]
  B -->|token| C["Backend-mu"]
  C -->|secret + token| D["Endpoint siteverify"]
  D -->|success?| C
```

Semua yang sudah kamu bangun di sekitar hCaptcha, render widget, kumpulkan token, POST ke servermu, verifikasi sebelum memercayai permintaan, tetap. Hanya nama dan endpoint yang berubah.

## 1. Tukar cuplikan klien

| | hCaptcha | Caputchin |
|---|---|---|
| Skrip | `<script src="https://js.hcaptcha.com/1/api.js" async defer>` | `<script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js">` |
| Elemen | `<div class="h-captcha" data-sitekey="...">` | `<caputchin-widget sitekey="cpt_pub_...">` |
| Field token di formulir | `h-captcha-response` (disuntik-otomatis) | `caputchin-token` (disuntik-otomatis) |
| Membaca token di JS | `hcaptcha.getResponse()` | `detail.token` [event `pass`](/docs/references/widget-methods-and-events) |

Seperti hCaptcha, widget Caputchin **menyuntik-otomatis sebuah field token tersembunyi** ke formulir tempat ia berada, jadi jika formulirmu sudah melakukan POST biasa, kamu hanya mengubah elemen dan nama field yang dibaca backend-mu. Lihat [tambahkan widget](/docs/getting-started/add-the-widget) untuk penyiapan klien lengkap dan [pilihan CDN vs npm](/docs/integration-guides/cdn).

## 2. Tukar verify server

Di sinilah keduanya paling dekat, bentuk permintaan dan respons sejajar hampir field demi field.

| | hCaptcha | Caputchin |
|---|---|---|
| Endpoint | `POST https://api.hcaptcha.com/siteverify` | `POST https://verify.caputchin.com/v1/siteverify` |
| Field permintaan | `secret`, `response` | `secret`, `response` (identik) |
| Respons | `{ success, challenge_ts, hostname, "error-codes", score? }` | `{ success, challenge_ts, hostname, error-codes, score? }` |
| Aturan kepercayaan | bertindak hanya jika `success === true` | bertindak hanya jika `success === true` (identik) |

Satu catatan format: endpoint verify hCaptcha mengharapkan `application/x-www-form-urlencoded`, sementara Caputchin menerima JSON. Jika kode yang adamu mengirim field form-encoded, ganti body ke JSON (`{"secret":"...","response":"..."}`) dengan `Content-Type: application/json`. Field-nya sendiri tak berubah. Referensi permintaan/respons penuh ada di [verifikasi token di backend-mu](/docs/integration-guides/verify-on-your-backend); cuplikan framework ada di [contoh backend](/docs/integration-guides/backend-examples).

## 3. Buang skor, jika kamu memakai hCaptcha Enterprise

hCaptcha Enterprise mengembalikan `score` risiko (di mana angka **lebih tinggi** berarti risiko **lebih banyak**) dan memintamu memilih ambang. Caputchin **tak** bekerja seperti itu: `success` adalah lolos/gagal otoritatif, karena verifikasi sebenarnya dituntaskan (pemeriksaan proof-of-work, atau [ronde game yang diturunkan-ulang di server](/docs/understanding-caputchin/gaming-anti-cheat)), bukan perkiraan risiko.

Jika kodemu punya `if (data.score < 0.7)`, ganti dengan `if (data.success)`. Bidang `score` Caputchin tak terkait: ia ada hanya untuk ronde game dan adalah skor **game** (informasional, untuk papan-peringkatmu sendiri), tak pernah risiko atau kemungkinan-bot, jadi jangan menggerbang akses padanya. (Perhatikan arahnya juga berlawanan, skor hCaptcha naik dengan risiko; skor Caputchin naik dengan performa game.)

## Apa yang terbawa, dan apa yang jadi lebih baik

- **Sikap privasi yang menjadi alasanmu memilih hCaptcha, tetap.** Caputchin tak mengumpulkan IP, User-Agent, sidik jari, atau telemetri perilaku; protokol tak punya tempat untuk menaruh pengenal pengunjung, jadi tak ada yang bocor atau dijual. Lihat [filosofi](/docs/understanding-caputchin/philosophy).
- **Game opsional.** Alih-alih tantangan pemilihan-gambar, kamu bisa mengubah verifikasi menjadi game pendek yang sungguh dimainkan pengunjungmu, dan ia bagian yang bertahan melawan pemecah AI. Lihat [tambahkan game](/docs/getting-started/add-a-game).
- **CSP ketat tetap ketat.** Caputchin berjalan di bawah Content-Security-Policy yang rapat; kamu mengizinkan beberapa origin ketimbang melonggarkan kebijakanmu. Lihat [bagaimana Caputchin men-sandbox game](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page).

## Hal yang sering terlewat

- **Dua key, dua rumah.** Public key (`cpt_pub_...`) masuk ke halaman; secret (`cpt_sec_...`) tetap hanya di sisi-server, persis disiplin hCaptcha. Jangan kirim secret ke peramban.
- **Token sekali-pakai.** Seperti hCaptcha, sebuah token terverifikasi sekali. Jangan cache atau putar-ulang ia.
- **Ubah nama field yang dibaca backend-mu.** Field tersembunyinya `caputchin-token`, bukan `h-captcha-response`, kelewatan satu-baris yang umum.
- **Format body.** Kirim permintaan verify sebagai JSON, bukan form-encoded.

## Lihat juga

- [Tambahkan widget](/docs/getting-started/add-the-widget): penyiapan klien lengkap.
- [Verifikasi token di backend-mu](/docs/integration-guides/verify-on-your-backend): referensi `siteverify` otoritatif.
- [Contoh backend](/docs/integration-guides/backend-examples): panggilan verify di tiap bahasa.
- [Tambahkan game](/docs/getting-started/add-a-game): ubah verifikasi menjadi game.