Migrasi dari hCaptcha
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 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
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 |
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 untuk penyiapan klien lengkap dan pilihan CDN vs npm.
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://caputchin.com/api/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; cuplikan framework ada di contoh backend.
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), 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.
- 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.
- 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.
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, bukanh-captcha-response, kelewatan satu-baris yang umum. - Format body. Kirim permintaan verify sebagai JSON, bukan form-encoded.
Lihat juga
- Tambahkan widget: penyiapan klien lengkap.
- Verifikasi token di backend-mu: referensi
siteverifyotoritatif. - Contoh backend: panggilan verify di tiap bahasa.
- Tambahkan game: ubah verifikasi menjadi game.