Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Menginstal kunci Universal di halaman web

Dokumen ini menjelaskan cara menginstal dan mengintegrasikan kunci Universal dengan halaman web Anda.

Sebelum memulai

Menginstal kunci Universal di situs Anda

Untuk menginstal kunci Universal dan membantu melindungi halaman web, Anda dapat menggunakan konfigurasi AutoExecute, penginstalan JavaScript manual, atau kedua metode tersebut secara bersamaan di berbagai endpoint menggunakan kunci Universal yang sama:

Konfigurasi AutoExecute (direkomendasikan): Otomatis mengintersepsi permintaan jaringan asinkron ke jalur URL yang dikonfigurasi dan melampirkan token reCAPTCHA ke header permintaan.
Penginstalan manual: Menggunakan panggilan grecaptcha.enterprise.execute() manual atau atribut tombol HTML. Anda dapat menggunakan metode ini sendiri atau bersama AutoExecute untuk permintaan jaringan yang tidak didukung AutoExecute, permintaan yang memerlukan penempatan token kustom dalam payload, atau selama migrasi inkremental ke AutoExecute.

Bergantung pada pendekatan integrasi Anda, pilih opsi yang sesuai:

Konfigurasi AutoExecute

AutoExecute dapat membantu menyederhanakan integrasi JavaScript frontend Anda dengan mengintersepsi permintaan jaringan di halaman web Anda dan menghilangkan panggilan grecaptcha.enterprise.execute() manual untuk setiap tindakan frontend.

AutoExecute hanya menangkap permintaan jaringan asinkron yang dimulai dengan Fetch API atau XMLHttpRequest, termasuk permintaan dari framework seperti AJAX yang menggunakan API ini.
AutoExecute tidak didukung untuk resource yang dimuat secara otomatis pada waktu pemuatan halaman. Sebagai gantinya, terapkan AutoExecute ke permintaan jaringan yang dipicu oleh tindakan pengguna di halaman, seperti tombol login.
Untuk mencegah tantangan Fraud Defense menyebabkan waktu tunggu jaringan habis, terapkan waktu tunggu langsung ke permintaan. Gunakan AbortSignal.timeout(n) untuk Fetch API dan properti XMLHttpRequest.timeout untuk XMLHttpRequest.

Menambahkan tag skrip ke halaman web Anda

Untuk memuat Fraud Defense di halaman web Anda, tambahkan JavaScript API dengan kunci Universal Anda dalam elemen <head></head> di halaman web Anda:

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

Secara default, Fraud Defense menggunakan bahasa browser. 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?render=KEY_ID&hl=fr"></script>

Untuk mempelajari bahasa yang didukung, lihat kode bahasa untuk Fraud Defense.

Mengonfigurasi endpoint yang dilindungi

Skrip Fraud Defense otomatis terintegrasi dengan tindakan jaringan yang ditentukan dalam konfigurasi kebijakan kunci Universal Anda. Bagian ini menentukan pemetaan jalur URL (path) ke nama tindakan (action).

Jika skrip Fraud Defense mendeteksi permintaan jaringan asinkron ke jalur yang dipetakan, skrip tersebut akan menangkap permintaan, memicu evaluasi risiko, dan berpotensi menampilkan tantangan CAPTCHA kepada pengguna sebelum permintaan asli dilanjutkan. Token respons yang dihasilkan akan otomatis dilampirkan ke header X-Recaptcha-Token dalam permintaan.

gcloud

Untuk memeriksa konfigurasi kebijakan saat ini untuk kunci Universal Anda, gunakan perintah gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

Untuk memperbarui konfigurasi kebijakan dengan endpoint yang dilindungi, buat file YAML (misalnya, POLICY.yaml) yang menentukan jalur dan tindakan yang dilindungi:

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

Perbarui konfigurasi kunci Anda dengan file YAML menggunakan perintah gcloud alpha recaptcha policies update:

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

REST API

Untuk memperbarui konfigurasi kebijakan guna menentukan endpoint yang dilindungi menggunakan REST API, gunakan metode projects.keys.updatePolicy.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: Project ID Google Cloud Anda
KEY_ID: ID kunci Universal Anda

Metode HTTP dan URL:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup

Meminta isi JSON:

{
"clientSettings": {
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup"

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup" | Select-Object -Expand Content

Jika berhasil, permintaan akan menampilkan konfigurasi kebijakan yang diperbarui.

Anda dapat mengonfigurasi hingga 25 endpoint yang dilindungi per kunci Universal. Setiap endpoint harus memenuhi persyaratan berikut:

action: Nama tindakan harus berisi 1 hingga 100 karakter, dan hanya menggunakan huruf, angka, garis miring (/), dan garis bawah (_).
path (peka huruf besar/kecil): Jalur harus memenuhi kriteria berikut:
- Unik, dimulai dengan /, dan berisi 1 hingga 200 karakter tanpa garis miring berturut-turut (//).
- Menyertakan setidaknya satu segmen non-karakter pengganti (misalnya, tidak boleh berupa /, /*, /**, atau /*/).
- Karakter pengganti harus menempati segmen lengkap: * cocok dengan satu segmen (misalnya, /api/*/login atau /api/* valid; /api/login* tidak valid), dan ** cocok dengan beberapa segmen sebagai segmen akhir saja (misalnya, /api/** valid; /api/**/login tidak valid).

Permintaan pihak ketiga: Jika alat pihak ketiga yang berjalan di halaman Anda (seperti skrip analisis atau partner) mengirim permintaan ke jalur yang cocok dengan endpoint yang dilindungi (misalnya, https://analytics.example.net/login cocok dengan /login), AutoExecute juga akan mencegatnya. Hal ini dapat menyebabkan latensi jaringan tambahan, metrik yang tidak akurat, atau tantangan CAPTCHA yang tidak terduga. Untuk menghindari konflik, pastikan jalur yang dilindungi berbeda (misalnya, /auth/v1/login), atau gunakan Penginstalan manual jika terjadi konflik jalur.
API lintas domain: Jika API backend Anda dihosting di domain yang berbeda dengan situs Anda (misalnya, examplecdn.net versus www.example.com), AutoExecute akan berfungsi secara otomatis tanpa konfigurasi domain tambahan.

Jika pencocokan dengan domain tujuan tertentu penting untuk integrasi Anda, ajukan permintaan fitur.

Di backend Anda, dapatkan token respons dari header permintaan X-Recaptcha-Token dan buat penilaian dalam waktu dua menit.

Penginstalan manual

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

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

Menambahkan verifikasi pada interaksi pengguna
Menambahkan Fraud Defense di tombol HTML

Menambahkan verifikasi pada interaksi pengguna

Untuk memuat reCAPTCHA di halaman web Anda, tambahkan JavaScript API dengan kunci Universal Anda dalam elemen <head></head> di halaman web Anda:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Secara default, Fraud Defense menggunakan bahasa browser. 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?render=KEY_ID&hl=fr"></script>

Untuk mempelajari bahasa yang didukung, lihat kode bahasa untuk Fraud Defense.

Jika Anda ingin menentukan lokasi untuk badge, gunakan badge=LOCATION sebagai parameter kueri dalam tag skrip. Contoh, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Secara default, lokasi ditetapkan ke bottomright. Nilai lainnya yang mungkin digunakan adalah inline dan bottomleft.
Untuk menambahkan verifikasi Fraud Defense pada interaksi pengguna, lakukan hal berikut:
1. Untuk membantu memastikan bahwa grecaptcha.enterprise.execute() berjalan setelah library Fraud Defense dimuat, gunakan grecaptcha.enterprise.ready().
2. Panggil grecaptcha.enterprise.execute() pada setiap interaksi yang ingin Anda lindungi dengan kunci Universal. Tentukan nama yang bermakna untuk interaksi pengguna dalam parameter action. Untuk panduan selengkapnya, lihat Tindakan.
  
  Tips: Tambahkan panggilan execute ke tindakan sensitif seperti LOGIN, SIGNUP, PASSWORD_RESET, atau PURCHASE.
  
  Contoh berikut menunjukkan cara memanggil grecaptcha.enterprise.execute() pada tindakan login:
```
<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  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 Fraud Defense 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>
```
Setelah token dibuat, kirim token reCAPTCHA ke backend Anda dan buat penilaian dalam waktu dua menit.

Penting: Backend Anda harus menentukan assessment.event.expected_action (atau expectedAction di JSON) di CreateAssessmentRequest, dan harus cocok dengan tindakan yang dikonfigurasi dalam panggilan execute(). Misalnya, jika Anda mengonfigurasi tindakan frontend menjadi LOGIN, backend Anda harus menetapkan expected_action ke LOGIN saat membuat penilaian untuk permintaan tersebut. Jika ada ketidakcocokan, hal ini menunjukkan bahwa penyerang mencoba memalsukan tindakan.

Menambahkan Fraud Defense di tombol HTML

Untuk memuat reCAPTCHA di halaman web Anda, tambahkan JavaScript API dengan kunci Universal Anda dalam elemen <head></head> di halaman web Anda:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
Fraud Defense 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?render=KEY_ID&hl=fr"></script>

Untuk mempelajari bahasa yang didukung, lihat kode bahasa untuk Fraud Defense.
Untuk menambahkan Fraud Defense pada tombol HTML, lakukan tindakan 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 mengetahui informasi selengkapnya, lihat metode requestSubmit().
1. 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 badge, gunakan atribut data-badge="LOCATION" pada elemen yang memiliki class="g-recaptcha". Secara default, lokasi ditetapkan ke bottomright. Nilai lainnya yang mungkin digunakan adalah inline dan bottomleft.
1. Saat tombol ini digunakan untuk mengirimkan formulir di situs Anda, parameter POST g-recaptcha-response akan berisi token respons.
Catatan: Jika Anda menetapkan tombol g-recaptcha sebagai disabled, tombol akan diaktifkan saat Fraud Defense dimuat.
Setelah token dibuat, kirim token reCAPTCHA ke backend Anda dan buat penilaian dalam waktu dua menit.

Penting: Backend Anda harus menentukan assessment.event.expected_action (atau expectedAction di JSON) di CreateAssessmentRequest, dan harus cocok dengan tindakan yang dikonfigurasi pada tombol. Misalnya, jika Anda mengonfigurasi tindakan tombol menjadi submit, backend Anda harus menetapkan expected_action ke submit saat membuat penilaian untuk permintaan tersebut. Jika ada ketidakcocokan, hal ini menunjukkan bahwa penyerang mencoba memalsukan tindakan.

Langkah berikutnya

Untuk memicu verifikasi CAPTCHA berdasarkan aturan kustom, konfigurasikan kebijakan verifikasi.
Untuk menilai token respons reCAPTCHA, buat penilaian.