Menginstal kunci berbasis skor di situs

Halaman ini menjelaskan cara menginstal kunci berbasis skor tanpa tantangan di situs Anda. Dengan kunci berbasis skor, Anda dapat menyertakan reCAPTCHA di seluruh situs tanpa mengharuskan pengguna untuk menyelesaikan tantangan CAPTCHA.

Saat kunci berbasis skor diinstal, reCAPTCHA akan mengirimkan respons terenkripsi, yaitu token respons reCAPTCHA (juga dikenal sebagai token), saat pengguna akhir memicu interaksi. Setelah token dibuat, Anda harus membuat penilaian dalam waktu dua menit untuk menerima skor setiap permintaan. Berdasarkan skor, Anda dapat memahami tingkat risiko yang ditimbulkan interaksi pengguna dan mengonfigurasi respons (atau respons) yang sesuai. Selain itu, kunci berbasis skor dapat mengumpulkan telemetri aktivitas bot untuk peringatan dini terhadap serangan atau target baru.

Untuk meningkatkan model risiko reCAPTCHA, sebaiknya sertakan reCAPTCHA di setiap halaman situs Anda karena hal ini membantu memahami cara pengguna dan bot yang sebenarnya bertransisi di antara berbagai halaman dan tindakan.

Sebelum memulai

  1. Siapkan lingkungan Anda untuk reCAPTCHA.

  2. Buat kunci berbasis skor.

    Atau, Anda dapat menyalin ID kunci berbasis skor yang ada dengan melakukan salah satu langkah berikut:

    • Untuk menyalin ID kunci yang ada dari konsol Google Cloud, lakukan hal berikut:

      1. Buka halaman reCAPTCHA.

        Buka reCAPTCHA

      2. Di daftar kunci reCAPTCHA, arahkan kursor ke kunci yang ingin disalin, lalu klik .
    • Untuk menyalin ID kunci yang ada menggunakan REST API, gunakan metode projects.keys.list.
    • Untuk menyalin ID kunci yang ada menggunakan gcloud CLI, gunakan perintah gcloud recaptcha keys list.

Menempatkan kunci di situs Anda

reCAPTCHA berfungsi paling baik jika memiliki konteks tentang interaksi di situs Anda. reCAPTCHA memantau perilaku yang sah dan penyalahgunaan untuk mempelajari interaksi di situs Anda.

Untuk hasil terbaik, instal kunci berbasis skor di tempat berikut di situs Anda:

  • Formulir
  • Tindakan (interaksi pengguna)
  • Di latar belakang semua halaman web

Kunci berbasis skor tidak mengganggu pengguna, sehingga Anda dapat menjalankan reCAPTCHA dengan kunci berbasis skor kapan pun diperlukan tanpa memengaruhi konversi.

Mengintegrasikan kunci dengan frontend

Sebaiknya tambahkan verifikasi reCAPTCHA pada interaksi pengguna yang perlu diverifikasi. Misalnya, jika ingin memverifikasi tindakan pengiriman formulir, Anda perlu menambahkan verifikasi reCAPTCHA pada tindakan pengiriman.

Bergantung pada tempat Anda ingin menambahkan verifikasi reCAPTCHA, pilih opsi yang sesuai:

Anda dapat melihat contoh setiap opsi dalam kode sumber situs demo.

Menambahkan verifikasi pada interaksi pengguna

  1. Untuk memuat reCAPTCHA di halaman web, tambahkan JavaScript API dengan kunci berbasis skor dalam elemen <head></head> halaman web Anda.

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    reCAPTCHA menggunakan bahasa browser secara default. Jika Anda ingin menentukan bahasa lain, gunakan atribut hl=LANG dalam skrip Anda. Misalnya, untuk menggunakan bahasa Prancis, tentukan hal berikut: <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>. Untuk mempelajari bahasa yang didukung, lihat kode bahasa untuk reCAPTCHA.

    Jika Anda ingin menentukan lokasi untuk badge, gunakan badge=LOCATION sebagai parameter kueri dalam tag skrip. Contoh, www.google.com/recaptcha/enterprise.js?sitekey=KEY_ID&badge=bottomleft. Secara default, lokasi ditetapkan ke bottomright. Nilai yang mungkin lainnya adalah inline dan bottomleft.

  2. Untuk menambahkan verifikasi reCAPTCHA pada interaksi pengguna, lakukan hal berikut:

    1. Untuk memastikan grecaptcha.enterprise.execute() berjalan setelah library reCAPTCHA dimuat, gunakan grecaptcha.enterprise.ready().

    2. Panggil grecaptcha.enterprise.execute() pada setiap interaksi yang ingin Anda lindungi dengan kunci berbasis skor. Tentukan nama yang bermakna untuk interaksi pengguna di parameter action. Untuk panduan selengkapnya, lihat Tindakan.

      Contoh berikut menunjukkan cara memanggil grecaptcha.enterprise.execute() pada tindakan login:

      <script>
function onClick(e) {
  e.preventDefault();
  grecaptcha.enterprise.ready(async () => {
    const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'LOGIN'});
    // IMPORTANT: The 'token' that results from execute is an encrypted response sent by
    // reCAPTCHA to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha/docs/create-assessment
  });
}
</script>

      grecaptcha.enterprise.execute() menghasilkan token seperti yang ditunjukkan pada contoh berikut: 

      03AGdBq27tvcDrfiRuxQnyKs-SarXVzPODXLlpiwNsLqdm9BSQQRtxhkD-Wv6l2vBSnL_JQd80FZp3IeeF_TxNMrqhyQchk7hmg_ypDctt_F5RTr9zNO9TSDX3Fy0qHQTuaM9E3hrAkA1v1l7D-fCreg7uq8zoudfh1ZRmN49-2iAMAn4E8_ff-nmlLTNGVZmCSyeze-5xM24pM_JhhUVcCMIDKYtDUnr2imxg2ubIqMscCZGUtdXNUO_LRSzuwWDlLyAr3V2nVn29Z48PQa2QzbymEXzO9pCtoGQmY7kiZ8ILfD9DAJSSyUTMwJXVJptUeBmLM341fq_STYZBbPQJ0zYOEDvJoFsIwGMfuphkDet0nK56b0mkzaL8RCRy2oK31Mcx6n3PhGkCnQ6QIhiV5ZVmV1Hz9M3w99zYw6ekc3wPCNMZ6V6x1ApVpIk3reFfByRQ0C0_pRWwbKZHLXQ_oSTI1UI7kyH1VeXngsJAx2l7zcp0hQNipajC4YwL7Jb8X4cCD0NeiaY1YCrI5j87mK5axcMikq460I4niIFeDBlHGF-ndqu3CJstosAur-C_x827f-dPPjA9Vrw8MDb3x4KUb0vbA8xE9mJxPYGY0rPCR27vJ38Voa7DjEBGX9c-iufv5_wfj-yIfIAHy0iijnRLI0CVkWF2-iPdWv7LnkTwL3WKbF_MrEGZXmtyLX9dEZArfxmToeMuSdYkfikkgR2-k4Xzxlz15RbHJuWSAYqEyTTnpUXmOvDuTN92b0kYqbRelcLUI_Shm-8dq9e-L7K6YWQv32gV6NukZKY15dyrJaW10frBgTOGSTTpIyB7MNEL8S27WjWtOb-zWsgimIhoRNfS8BiJWkmK4gTj51m7Wur-qsDbHgV6gXlMvjJs_B7oXX-mKsKhY9ACtwukotBelGYQOvf1RDHjH3Yi1RDfELBY6AkwUK4tq8cACVGpCwa0gKUo-sbORTsGu_r7VTzYo1AaZD5HV4XUm8yoqszel6DmIfkJcI7PfzzvfUJuvMQ1itZSzpzuth3glbKBYsIjbKqG-q8cxtZ7u0l32j46ASo2zlCJWUjwP3W1P7MUenEoIZtjlyTB_tT6Fk8RxGgRv3oLP7NPFJGs9ZGOAl6tBHpZF8Y_FqEOCMKtBl2JYOE5h6_Es3buSdiMm7mtLr64pboGiEColF1vbVvYpyaaqGFPXBM6ekZSXEXLAI0_7rj_fCLgnB21KXfac95vZbM9vyJCASvDcWKwqajQwy5aGMNe9GtbMogYbZfz5UGWAIi24Vd8KSv3qKOOwvzbcw4H0HYdsBXA

  3. Setelah token dibuat, kirim token reCAPTCHA ke backend Anda dan buat penilaian dalam waktu dua menit.

    Untuk integrasi WAF, jika Anda mengintegrasikan kunci token tindakan, Anda harus melampirkan token ke header permintaan yang telah ditentukan dan Anda tidak perlu membuat penilaian. Untuk mengetahui detailnya, lihat Menerapkan token tindakan reCAPTCHA.

Menambahkan reCAPTCHA di tombol HTML

  1. Untuk memuat reCAPTCHA di halaman web, tambahkan JavaScript API dengan kunci berbasis skor dalam elemen <head></head> halaman web Anda.

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    reCAPTCHA menggunakan bahasa browser secara default. Jika Anda ingin menentukan bahasa lain, gunakan atribut hl=LANG dalam skrip Anda. Misalnya, untuk menggunakan bahasa Prancis, tentukan hal berikut: <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>. Untuk mempelajari bahasa yang didukung, lihat kode bahasa untuk reCAPTCHA.

  2. Untuk menambahkan reCAPTCHA pada tombol HTML sederhana, lakukan hal berikut:

    1. Tentukan fungsi callback untuk menangani token.

      <script>
   function onSubmit(token) {
     document.getElementById("demo-form").submit();
   } // Use `requestSubmit()` for extra features like browser input validation.
</script>

      Untuk informasi selengkapnya, lihat metode requestSubmit().

    2. Tambahkan atribut ke tombol html Anda.

      <button class="g-recaptcha"
data-sitekey="KEY_ID"
data-callback='onSubmit'
data-action='submit'>Submit</button>

      Jika Anda ingin menentukan lokasi untuk badge, gunakan atribut data-badge=LOCATION pada elemen yang memiliki class=g-recaptcha. Secara default, lokasi ditetapkan ke bottomright. Nilai yang mungkin lainnya adalah inline dan bottomleft.

    3. Saat tombol ini digunakan untuk mengirimkan formulir di situs Anda, parameter POST g-recaptcha-response akan berisi token respons.

  3. Setelah token dibuat, kirim token reCAPTCHA ke backend Anda dan buat penilaian dalam waktu dua menit.

    Untuk integrasi WAF, jika Anda mengintegrasikan kunci token tindakan, Anda harus melampirkan token ke header permintaan yang telah ditentukan dan Anda tidak perlu membuat penilaian. Untuk mengetahui detailnya, lihat Menerapkan token tindakan reCAPTCHA.

Langkah selanjutnya