Apa Itu hCaptcha? Penjelasan Token, Siteverify, dan Enterprise

what is hcaptcha - What Is hCaptcha? Token, Siteverify and Enterprise Explained

hCaptcha adalah pemeriksaan bot yang Anda pasang di depan sebuah formulir. Pengunjung menyelesaikan challenge di dalam widget, lalu widget menambahkan token bernama h-captcha-response ke formulir. Server Anda mengirim token itu ke hCaptcha untuk memastikan keasliannya. Jadi apa itu hCaptcha bagi developer? Ia adalah sebuah widget, sebuah token, dan satu panggilan verifikasi, dan itu juga yang Anda tangani jika skrip harus melewatinya. Panduan ini membahas cara mengenalinya, apa yang diperiksa server, arti setiap error, dan apa yang dikirim skrip.

Untuk gambaran umum tentang CAPTCHA, lihat apa itu CAPTCHA dan mengapa situs memakainya. Halaman ini hanya membahas hCaptcha.

Cara mengenali hCaptcha di sebuah halaman

Panduan pengembang hCaptcha menampilkan widget sebagai elemen dengan class h-captcha yang membawa atribut data-sitekey. Halaman hCaptcha CapSkip menyebut sitekey sebagai UUID publik. Ketika skrip yang membangun widget, sitekey menjadi parameter hcaptcha.render(), yang didokumentasikan oleh panduan konfigurasi. Setelah challenge berhasil, panduan menyatakan bahwa hCaptcha menambahkan token h-captcha-response ke pengiriman formulir.

Jadi ada tiga hal yang mengenalinya: elemen dengan class h-captcha, sebuah sitekey, dan field formulir bernama h-captcha-response setelah challenge dilewati. Dokumentasi API CapSkip menambahkan bahwa formulir bisa membawa field kedua bernama g-recaptcha-response, yang diisi dengan token yang sama.

Checkbox, invisible, dan akun Enterprise

Checkbox dan invisible adalah dua mode widget. Enterprise adalah tingkat akun yang dapat memakai salah satunya, dan ia mengubah isi balasan verifikasi server. CapSkip memakai satu metode untuk semuanya.

  • Checkbox. Pengunjung mencentang sebuah kotak dan, menurut dokumentasi CapSkip, kadang menjawab challenge gambar.
  • Invisible. Panduan invisible menyatakan Anda mengatur data-size ke invisible pada elemen, lalu widget dirender di latar belakang dan menampilkan dirinya hanya ketika challenge diperlukan. Halaman Anda memicunya dengan hcaptcha.execute(), dan token dikirim ke fungsi callback Anda.
  • Enterprise. Balasan verifikasi mendapat dua field tambahan, score dan score_reason, yang oleh panduan hCaptcha ditandai hanya untuk Enterprise. CapSkip tidak memiliki opsi score pada sebuah task. Satu-satunya pengaturan terkait adalah High score mode untuk hCaptcha, yang dibahas di FAQ di bawah.

Beberapa situs Enterprise juga meneruskan sebuah nilai bernama rqdata ke widget lewat hcaptcha.setData() sebelum widget berjalan. Dokumentasi hCaptcha yang publik tidak menjelaskannya, jadi semua yang ada di sini tentangnya bersandar pada dokumentasi CapSkip: situs menerbitkan satu nilai per challenge dan nilai itu cepat basi, jadi skrip memerlukan yang baru untuk setiap task.

Yang dilakukan server dengan token

Server mengirim token lewat POST ke https://api.hcaptcha.com/siteverify sebagai body form URL-encoded, dan panduan memperingatkan agar tidak mengirim JSON. Dua field wajib: secret akun dan token, dikirim sebagai secret dan response. Panduan menyarankan remoteip (alamat pengguna) dan mencantumkan sitekey sebagai opsional, cara untuk menyatakan sitekey mana yang Anda harapkan. Jawaban JSON memiliki success, challenge_ts, hostname, dan error-codes.

Token bersifat sekali pakai. Satu-satunya masa berlaku yang diberikan panduan adalah default 120 detik, di dalam deskripsi salah satu kode error. Dokumentasi CapSkip menyebutnya sekitar dua menit. Minta token tepat sebelum Anda mengirim.

Error siteverify dan hal yang perlu diperiksa

Kode-kode ini berasal dari tabel error di panduan hCaptcha. Skrip biasanya hanya melihat formulir yang ditolak. Kolom terakhir adalah pembacaan atas hal yang perlu diperiksa, bukan teks dari hCaptcha.

Kode errorKata panduanYang perlu diperiksa
missing-input-responseParameter token hilang.POST formulir tidak membawa field h-captcha-response, atau situs membaca nama lain.
invalid-input-responseToken tidak valid atau salah format.Nilainya terpotong, diedit, atau di-encode dua kali dalam perjalanan ke formulir.
expired-input-responseToken kedaluwarsa (default 120 detik).Terlalu lama jeda antara memecahkan dan mengirim. Pecahkan, lalu kirim segera.
already-seen-responseToken sudah pernah diverifikasi satu kali.Sebuah token dipakai ulang, atau POST formulir diulang dengan token lama. Minta yang baru setiap kali.
sitekey-secret-mismatchSitekey tidak terdaftar pada secret yang diberikan.Masalah konfigurasi situs di sisi server, bukan sesuatu yang dikirim skrip.
invalid-input-secretSecret key tidak valid atau salah format.Juga di sisi server, di dalam kode pemilik situs.

Perbandingan dengan reCAPTCHA dan Turnstile

Ketiganya menaruh satu token di formulir dan memverifikasinya di sisi server, jadi perbedaannya ada pada nama dan angka. reCAPTCHA memakai g-recaptcha-response, dan panduan verifikasi Google menyatakan bahwa token berlaku dua menit dan hanya dapat diverifikasi sekali. Turnstile memakai cf-turnstile-response, dan dalam dokumentasi Cloudflare, panduan validasi sisi server menyebut 300 detik dan sekali pakai. Di SDK Python CapSkip, panggilannya adalah hcaptcha(), recaptcha(), dan turnstile(), diambil dari kode sumber 1.7.0.

Seperti apa request ke CapSkip

CapSkip berjalan di PC Windows Anda dan memakai format request 2captcha, jadi task hCaptcha adalah dua panggilan HTTP. Kedua perintah curl.exe di bawah berjalan apa adanya di PowerShell dan di cmd. Yang pertama mengirim task dan menjawab dengan job id. Yang kedua melakukan polling dengan id itu, dan CAPCHA_NOT_READY berarti tunggu beberapa detik lalu tanya lagi. Tambahkan field data hanya ketika halaman menetapkan rqdata. Key hanya berpengaruh ketika API Key Validation aktif di CapSkip.

curl.exe -X POST -d "key=YOUR_API_KEY&method=hcaptcha&sitekey=YOUR_SITEKEY&pageurl=https://example.com/login&json=1" http://127.0.0.1:8080/in.php
curl.exe "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"

Task yang sama lewat SDK Python adalah satu panggilan yang mengirim task, melakukan polling, dan mengembalikan hasilnya. Opsinya adalah invisible, data (rqdata Enterprise), userAgent, dan proxy. CapSkip memakai userAgent yang Anda kirim hanya jika cocok dengan browser yang dipakainya untuk memecahkan. Hasilnya membawa token sebagai code dan token, sebuah respKey, dan User-Agent yang memperoleh token itu.

# pip install capskip
from capskip import CapSkip

# The key matters only when API Key Validation is on in CapSkip.
solver = CapSkip(apiKey="YOUR_API_KEY", host="127.0.0.1", port=8080)

# For an Enterprise rqdata add data=RQDATA; for an invisible widget
# add invisible=1. Neither is needed for a plain checkbox.
result = solver.hcaptcha(
    sitekey="YOUR_SITEKEY",
    url="https://example.com/login",
)

# The token goes in h-captcha-response, sent with this User-Agent.
print(result["code"][:12], result["userAgent"])

Kedua blok dijalankan terhadap sebuah mock CapSkip, bukan aplikasi aslinya, dan masing-masing mengirim method=hcaptcha dengan sitekey dan alamat halaman yang diberikan. Tidak ada pemecahan sungguhan yang terjadi, jadi di sini tidak ada klaim tentang waktu pemecahan atau tingkat keberhasilan. Skrip lengkap dan setiap parameter ada di halaman pemecah hCaptcha CapSkip, dan metodenya tercantum di Dokumentasi API CapSkip.

Menjalankan CapSkip di server

Jika skrip Anda berjalan di mesin lain, alihkan CapSkip ke mode Server dan arahkan pengaturan host ke mesin itu. Lihat pengaturan koneksi di panduan penyiapan yang menjelaskan keduanya. Mode Server mengharuskan CapSkip berjalan sebagai administrator, dan mesin itu tetap sebuah PC Windows yang Anda kendalikan. Periksa alamat mana saja yang dapat menjangkau port, dan tambahkan aturan blokir Windows Firewall untuk yang tidak boleh. Karena pemecahan terjadi di mesin itu, hCaptcha melihat jaringannya, jadi pasang proxy pada task jika itu penting bagi situs.

Pertanyaan yang sering diajukan

Apakah hCaptcha sama dengan reCAPTCHA?

Bukan. Keduanya layanan terpisah dengan widget, nama field, dan host verifikasi masing-masing. Skrip harus mengirim field yang tepat dan meminta metode yang tepat dari CapSkip.

Bagaimana cara mengetahui bahwa sebuah situs memakai hCaptcha Enterprise?

Tidak selalu dari front end. Dokumentasi CapSkip menyatakan bahwa sebagian situs Enterprise meneruskan nilai rqdata ke hcaptcha.setData() sebelum widget berjalan. Jika Anda melihat panggilan itu, kirim nilainya sebagai opsi data, yang baru untuk setiap task. Jika tidak, pecahkan seperti biasa dan coba High score mode jika situs menolak token.

Mengapa formulir menolak token yang dikembalikan CapSkip?

Dokumentasi CapSkip mencantumkan penyebab yang umum: token yang sudah lama atau sudah dipakai, sitekey yang tidak cocok dengan halaman, atau User-Agent yang berbeda dari yang ada di balasan. Untuk situs yang ketat, dokumentasi menambahkan pengaturan High score mode untuk hCaptcha, di Settings, Captcha types, yang memerlukan Google Chrome di PC CapSkip.

Bisakah saya menjalankan CapSkip di server untuk task hCaptcha?

Bisa. Pakai mode Server di mesin Windows yang Anda kendalikan dan arahkan skrip Anda ke alamatnya.

Versi singkatnya

hCaptcha adalah widget yang berujung pada satu token sekali pakai, yang diperiksa satu kali di alamat siteverify hCaptcha. Sebuah pemecah captcha lokal di PC Windows Anda sendiri mencakup kasus checkbox, invisible, dan Enterprise dengan satu metode dan tanpa biaya per pemecahan.