Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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, pilih konfigurasi Google Cloud Fraud Defense AutoExecute atau penginstalan JavaScript standar:

Konfigurasi AutoExecute

Fraud Defense AutoExecute dapat membantu menyederhanakan integrasi JavaScript frontend Anda dengan mencegat permintaan jaringan di halaman web Anda, sehingga Anda tidak perlu memanggil grecaptcha.enterprise.execute() secara manual untuk setiap tindakan frontend.

AutoExecute hanya mencegat permintaan jaringan asinkron yang dimulai dengan the Fetch API atau XMLHttpRequest, termasuk permintaan dari framework seperti AJAX yang menggunakan API ini.
AutoExecute tidak didukung untuk resource yang dimuat secara otomatis saat 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 reCAPTCHA di halaman web Anda, tambahkan JavaScript API dengan Kunci universal Anda dalam elemen <head></head> 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.

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 mencegat 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.

Parameter path mendukung pola glob dengan aturan berikut:

Harus diawali dengan / dan tidak boleh kosong.
Tidak boleh berupa /* atau /** yang berdiri sendiri, karena dapat berdampak negatif pada performa untuk memicu Fraud Defense pada setiap permintaan ke backend Anda.
Karakter pengganti * (yang cocok dengan satu segmen jalur) dan ** (yang cocok dengan beberapa segmen jalur) harus menempati seluruh segmen jalur (misalnya, /api/*/login atau /api/* valid; /api/login* tidak valid).
Karakter pengganti ** hanya boleh menempati segmen jalur terakhir (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 yang 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 standar jika terjadi tabrakan jalur.
API lintas domain: Jika backend API 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 standar

Sebaiknya tambahkan verifikasi Fraud Defense pada interaksi pengguna yang perlu diverifikasi. Misalnya, jika Anda ingin memverifikasi tindakan pengiriman formulir, Anda harus 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 pada 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> 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.

Jika Anda ingin menentukan lokasi untuk badge, gunakan badge=LOCATION sebagai parameter kueri di tag skrip. Misalnya, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Secara default, lokasi ditetapkan ke bottomright. Nilai lain yang mungkin adalah inline dan bottomleft.
Untuk menambahkan verifikasi Fraud Defense pada interaksi pengguna, lakukan hal berikut:
1. Untuk membantu memastikan 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 Anda. 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>
```
  s
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 dalam 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 pada tombol HTML

Untuk memuat reCAPTCHA di halaman web Anda, tambahkan JavaScript API dengan Kunci universal Anda dalam elemen <head></head> 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 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 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 untuk badge, gunakan atribut pada elemen yang memiliki class="g-recaptcha".data-badge="LOCATION" Secara default, lokasi ditetapkan ke bottomright. Nilai lain yang mungkin 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 dalam 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 tantangan CAPTCHA berdasarkan aturan kustom, konfigurasi kebijakan tantangan.
Untuk menilai token respons reCAPTCHA, buat penilaian.