Memverifikasi token respons pengguna dengan SiteVerify lama

Halaman ini menjelaskan cara memverifikasi respons pengguna terhadap verifikasi reCAPTCHA dari backend aplikasi Anda menggunakan endpoint SiteVerify API versi lama (https://www.google.com/recaptcha/api/siteverify). Gunakan endpoint ini hanya jika Anda mempertahankan integrasi lama atau plugin pihak ketiga yang tidak dapat menggunakan CreateAssessment.

Sebelum memulai

Untuk memanggil endpoint SiteVerify, Anda memerlukan kunci rahasia lama kunci Anda. Untuk menemukan kunci rahasia di konsol Google Cloud , lihat Mengambil kunci rahasia di konsol Google Cloud . Jaga keamanan kunci rahasia Anda di server backend dan jangan pernah menampilkannya di kode sisi klien.

Mengambil token respons pengguna

Integrasi web lama memuat JavaScript API non-perusahaan (https://www.google.com/recaptcha/api.js), yang menyediakan metode pada objek grecaptcha, bukan grecaptcha.enterprise. Anda dapat mengambil token respons pengguna di frontend dengan salah satu cara berikut:

  • Dari parameter POST g-recaptcha-response saat pengguna mengirimkan formulir di situs Anda.
  • Dengan memanggil grecaptcha.getResponse(opt_widget_id) setelah pengguna menyelesaikan tantangan reCAPTCHA v2. Metode ini menampilkan token respons sebagai string, atau string kosong jika tantangan tidak diselesaikan. Parameter opt_widget_id opsional menentukan ID widget yang ditampilkan oleh grecaptcha.render(); jika tidak ditentukan, parameter ini akan ditetapkan secara default ke widget pertama yang dibuat.
  • Sebagai argumen string yang diteruskan ke fungsi callback Anda saat pengguna menyelesaikan tantangan, jika Anda menentukan nama fungsi callback dalam atribut data-callback elemen HTML g-recaptcha atau parameter callback metode grecaptcha.render(container, parameters).
  • Dari nilai Promise yang di-resolve yang ditampilkan oleh grecaptcha.execute(site_key, {action: action_name}) untuk kunci berbasis skor (v3).

Metode grecaptcha lama (render, getResponse, execute, ready, dan reset) serta atribut tag g-recaptcha menggunakan parameter yang sama dengan metode grecaptcha.enterprise yang setara. Untuk mengetahui detail parameter, lihat referensi API JavaScript untuk reCAPTCHA.

Untuk bermigrasi ke reCAPTCHA JavaScript API yang telah diupdate, lihat Memigrasikan reCAPTCHA JavaScript API.

Batasan token

Setiap token respons pengguna reCAPTCHA valid selama dua menit, dan Anda hanya dapat memverifikasi setiap token satu kali untuk mencegah serangan replay. Verifikasi token respons dengan reCAPTCHA dalam waktu dua menit setelah menerimanya. Jika Anda memerlukan token baru, jalankan kembali verifikasi reCAPTCHA.

Permintaan API

Kirim permintaan dengan endpoint dan metode berikut:

  • URL: https://www.google.com/recaptcha/api/siteverify (atau https://www.recaptcha.net/recaptcha/api/siteverify jika www.google.com tidak dapat diakses; lihat Menggunakan reCAPTCHA secara global)
  • Metode: POST

Sertakan parameter POST berikut dalam permintaan:

Parameter POST Deskripsi
secret Wajib. Kunci rahasia bersama antara situs Anda dan reCAPTCHA.
response Wajib. Token respons pengguna yang disediakan oleh integrasi sisi klien reCAPTCHA di situs Anda.
remoteip Opsional. Alamat IP pengguna.

Respons API

Endpoint SiteVerify menampilkan objek JSON.

Untuk integrasi web (kunci v3 berbasis skor, v2 kotak centang, atau v2 tidak terlihat), respons memiliki format berikut:

{
  "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
  "score": number,            // the score for this request (0.0 - 1.0) for score-based (v3) keys
  "action": string,           // the action name for this request (important to verify)
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

Referensi kode error

Tabel berikut menjelaskan kode error yang dapat muncul dalam array error-codes:

Kode error Deskripsi
missing-input-secret Parameter secret tidak ada.
invalid-input-secret Parameter secret tidak valid atau salah format.
missing-input-response Parameter response tidak ada.
invalid-input-response Parameter response tidak valid atau salah format.
bad-request Permintaan tidak valid atau salah format.
timeout-or-duplicate Respons tidak lagi valid karena sudah tidak berlaku atau sudah digunakan.

Langkah berikutnya