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 Enterprise di seluruh situs tanpa mengharuskan pengguna menyelesaikan tantangan CAPTCHA.

Setelah menginstal kunci berbasis skor, Anda harus membuat penilaian dan menerima skor untuk setiap permintaan. Berdasarkan skor tersebut, Anda dapat memahami tingkat risiko yang ditimbulkan oleh interaksi pengguna dan mengonfigurasi respons (atau respons) yang sesuai. Selain itu, kunci berbasis skor dapat mengumpulkan telemetri aktivitas bot untuk memberikan peringatan awal terhadap serangan atau target baru.

Untuk meningkatkan model risiko reCAPTCHA Enterprise, sebaiknya sertakan reCAPTCHA Enterprise di setiap halaman situs Anda untuk membantu memahami proses transisi antara pengguna dan bot yang sebenarnya di antara berbagai halaman dan tindakan.

Sebelum memulai

  1. Siapkan lingkungan Anda untuk reCAPTCHA Enterprise.

  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 Google Cloud Console, lakukan hal berikut:

      1. Buka halaman reCAPTCHA Enterprise.

        Buka reCAPTCHA Enterprise

      2. Dalam daftar kunci reCAPTCHA, arahkan kursor ke kunci yang ingin Anda salin, 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.

Tempatkan kunci tersebut di situs Anda

reCAPTCHA Enterprise berfungsi optimal jika memiliki konteks tentang interaksi di situs Anda. reCAPTCHA Enterprise memantau perilaku yang sah dan melanggar untuk mempelajari interaksi di situs Anda.

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

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

Kunci berbasis skor tidak mengganggu pengguna, sehingga Anda dapat menjalankan reCAPTCHA Enterprise dengan kunci berbasis skor setiap kali diperlukan tanpa memengaruhi konversi.

Mengintegrasikan kunci dengan frontend

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

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

Menambahkan verifikasi pada interaksi pengguna

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

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

    reCAPTCHA Enterprise menggunakan bahasa browser secara default. Jika 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 Enterprise.

    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. Kemungkinan nilai lainnya adalah inline dan bottomleft.

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

    1. Untuk memastikan bahwa 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 Enterprise 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 dalam 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 dan buat penilaian dalam waktu dua menit.

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

Menambahkan reCAPTCHA pada tombol HTML

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

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

    reCAPTCHA Enterprise menggunakan bahasa browser secara default. Jika 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 Enterprise.

  2. Untuk menambahkan reCAPTCHA Enterprise 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 ingin menentukan lokasi untuk badge, gunakan atribut data-badge=LOCATION pada elemen yang memiliki class=g-recaptcha. Secara default, lokasi ditetapkan ke bottomright. Kemungkinan nilai lainnya adalah inline dan bottomleft.

    3. Jika 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 dan buat penilaian dalam waktu dua menit.

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

Langkah selanjutnya