Migrasi dari Cloudflare Turnstile
Caputchin memakai model dua-bagian yang sama dengan Cloudflare Turnstile, sebuah widget di halaman yang menghasilkan token, dan pemeriksaan sisi-server yang memastikannya, jadi migrasi sebagian besar adalah tukar mekanis, bukan penulisan-ulang. Turnstile adalah yang paling dekat dari penyedia umum ke Caputchin, karena keduanya mengembalikan lolos/gagal otoritatif ketimbang skor risiko, jadi tak ada ambang untuk disetel-ulang. 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 Turnstile.
Model mental tak berubah
Semua yang sudah kamu bangun di sekitar Turnstile, render widget, kumpulkan token, POST ke servermu, verifikasi sebelum memercayai permintaan, tetap. Hanya nama dan endpoint yang berubah.
1. Tukar cuplikan klien
| Turnstile | Caputchin | |
|---|---|---|
| Skrip | <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| Elemen | <div class="cf-turnstile" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Field token di formulir | cf-turnstile-response (disuntik-otomatis) | caputchin-token (disuntik-otomatis) |
| Membaca token di JS | turnstile.getResponse() | detail.token event pass |
Seperti Turnstile, 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.
| Turnstile | Caputchin | |
|---|---|---|
| Endpoint | POST https://challenges.cloudflare.com/turnstile/v0/siteverify | POST https://caputchin.com/api/v1/siteverify |
| Field permintaan | secret, response | secret, response (identik) |
| Respons | { success, challenge_ts, hostname, "error-codes", action, cdata } | { success, challenge_ts, hostname, error-codes } |
| Aturan kepercayaan | bertindak hanya jika success === true | bertindak hanya jika success === true (identik) |
Di kebanyakan stack satu-satunya perubahan pada kode verifikasimu adalah URL dan nilai secret; keduanya sudah bercabang pada success, jadi tak ada ambang skor untuk dipindahkan. Turnstile juga menerima JSON untuk panggilan verify, persis seperti Caputchin, jadi bentuk body terbawa tak berubah. Referensi permintaan/respons penuh, termasuk kode galat, ada di verifikasi token di backend-mu; cuplikan framework ada di contoh backend.
Jika integrasi Turnstile-mu membaca action atau cdata dari respons, perhatikan Caputchin tak punya padanan langsung; itu adalah label khusus-Turnstile yang kamu setel pada widget. Metadata analog Caputchin (game mana yang dimainkan, skornya) hidup di blok platform respons dan hanya informasional.
Apa yang terbawa, dan apa yang jadi lebih baik
- Tetap lolos/gagal yang bersih. Kamu menjaga aturan kepercayaan paling sederhana,
if (success), tanpa probabilitas atau ambang untuk dipelihara. - Sikap privasi yang menjadi alasanmu memilih Turnstile, tetap. Caputchin tak mengumpulkan IP, User-Agent, sidik jari, atau telemetri perilaku; protokol tak punya tempat untuk menaruh pengenal pengunjung. Lihat filosofi.
- Game opsional. Alih-alih tantangan tak-kasatmata atau terkelola, 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 Turnstile. Jangan kirim secret ke peramban. - Token sekali-pakai. Seperti Turnstile, sebuah token terverifikasi sekali. Jangan cache atau putar-ulang ia.
- Ubah nama field yang dibaca backend-mu. Field tersembunyinya
caputchin-token, bukancf-turnstile-response, kelewatan satu-baris yang umum. - Tanpa
action/cdata. Jika kamu bercabang pada itu, pindahkan logika itu ke tempat lain; Caputchin tak membawanya.
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.