---
title: Pencegahan penipuan — Web SDK
---

# Web SDK Pencegahan penipuan

Web SDK Fraud Prevention berjalan pada **halaman Anda** — landing page, layar
pendaftaran atau login, atau sumber daya terlindungi apa pun. Ia meminta verdict
untuk kunjungan saat ini dan menyerahkannya kembali ke kode Anda, sehingga Anda dapat
memutuskan apa yang harus dilakukan dengan trafik tersebut — mencatatnya,
menandainya, atau meminta pengunjung satu verifikasi tambahan.

## Mulai cepat

```html
<!-- Load the Fraud Prevention SDK -->
<script src="https://cdn.captcha-cdn.net/bot-signal.js"></script>

<script>
  BotSignal.init({
    appKey: 'YOUR_APP_KEY',
    onVerdict: function (verdict) {
      // verdict.is_bot, verdict.score, verdict.action — see Verdict Reference
      if (verdict.is_bot) {
        // exclude this visit from your funnel / suppress conversions
      }
    },
    onError: function (err) {
      console.error('bot-signal error', err);
    },
  });
</script>
```

`BotSignal.init()` juga mengembalikan sebuah `Promise<BotVerdict>`, sehingga Anda
dapat pula meng-`await` alih-alih menggunakan `onVerdict` — keduanya menerima objek
verdict yang sama.

```js
const verdict = await BotSignal.init({ appKey: 'YOUR_APP_KEY' });
```

## Opsi

| Opsi | Tipe | Default | Deskripsi |
| --- | --- | --- | --- |
| `appKey` | string | — | Kunci aplikasi Fraud Prevention Anda (wajib). |
| `domain` | string | default layanan | Endpoint layanan verdict. Biarkan tidak diatur kecuali Anda diberi domain khusus. |
| `escalate` | boolean | `false` | Mengizinkan Fraud Prevention meminta pengunjung **satu verifikasi tambahan** ketika sebuah kunjungan tampak berisiko tinggi. Lihat [Eskalasi](#eskalasi). |
| `collectWindowMs` | number | `1200` | Berapa lama (ms) SDK mengamati kunjungan sebelum meminta verdict. Jendela lebih panjang menghasilkan verdict yang lebih meyakinkan dengan biaya sedikit penundaan. |
| `onVerdict` | `(v) => void` | — | Dipanggil sekali dengan verdict akhir. Titik integrasi utama. |
| `onError` | `(err) => void` | — | Dipanggil jika terjadi kesalahan apa pun. SDK tidak pernah melempar exception ke halaman Anda. |
| `onEscalate` | `(displayType) => void` | — | Dipanggil ketika verifikasi tambahan ditampilkan (hanya saat `escalate: true`). |
| `onEscalateDone` | `(passed) => void` | — | Dipanggil setelah verifikasi tambahan selesai; `passed` bernilai `true` jika pengunjung lolos. |

::: tip Skenario sumber trafik
Jika pihak ketiga mengirimkan pengunjung kepada Anda dan kedua belah pihak perlu
merekonsiliasi pada kesimpulan per-klik, SDK juga dapat membaca click token dari URL
halaman. Itu spesifik untuk alur trafik berbayar — lihat panduan [Penipuan
iklan](./scenarios/ad-fraud).
:::

## Menggunakan verdict

`onVerdict` menerima sebuah objek `BotVerdict`. Dua field yang paling sering Anda
pakai:

- **`verdict.is_bot`** — `true` ketika kunjungan dinilai sebagai otomatis/tidak valid.
- **`verdict.action`** — apa yang kami rekomendasikan untuk Anda lakukan:
  `record_only`, `challenge`, atau `flag`.

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onVerdict: function (verdict) {
    switch (verdict.action) {
      case 'record_only':
        // normal-looking traffic — proceed, just log the verdict
        break;
      case 'flag':
        // suspicious — keep serving the page but mark this visit as low quality
        markLowQuality(verdict);
        break;
      case 'challenge':
        // high risk — handled by escalation if enabled (see below)
        break;
    }
  },
});
```

Lihat daftar field lengkap dan penanganan yang direkomendasikan di [Referensi
verdict](./verdict-reference).

## Eskalasi

Ketika sebuah kunjungan tampak berisiko tinggi, Fraud Prevention dapat meminta
pengunjung menyelesaikan **satu verifikasi tambahan** sebelum Anda memperlakukan
mereka sebagai pengguna nyata. Ini bersifat opt-in.

Aktifkan dengan `escalate: true`:

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // an extra verification is being shown to the visitor
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // visitor cleared the extra check — treat as human
    } else {
      // not cleared — keep the original verdict's recommendation
    }
  },
  onVerdict: function (verdict) {
    // if the visitor cleared escalation, verdict.is_bot is updated to false
  },
});
```

Catatan:

- Eskalasi hanya terpicu ketika `action` verdict bernilai `challenge`. Untuk semua
  kunjungan lain tidak ada yang ditampilkan dan pengalaman pengunjung tidak terganggu.
- Jika pengunjung lolos verifikasi tambahan, verdict yang dikirim ke `onVerdict`
  mencerminkan hal itu (diperlakukan sebagai manusia).
- Eskalasi **fail open**: jika verifikasi tambahan tidak dapat dimuat atau
  ditampilkan, SDK mempertahankan verdict asli alih-alih memblokir halaman Anda.

::: info
Fraud Prevention tidak pernah memutuskan *untuk* Anda. Bahkan pada
`challenge`/`flag`, kode Anda tetap mengendalikan apakah kunjungan diteruskan — SDK
hanya menampilkan verdict dan, opsional, menjalankan verifikasi tambahan.
:::

## Ketahanan

Jika layanan verdict tidak terjangkau atau terjadi kesalahan apa pun, SDK
mengembalikan verdict **degraded** (`degraded: true`) alih-alih menggagalkan halaman
Anda. Verdict degraded bersifat konservatif (`is_bot: false`, `action: record_only`)
sehingga tidak pernah memblokir pengguna nyata. Periksa `verdict.degraded` jika Anda
ingin memperlakukan kunjungan tersebut secara khusus.

## Langkah berikutnya

- [Referensi verdict](./verdict-reference) — setiap field dan cara menindaknya
- [Data API](./data-api) — tarik dan rekonsiliasi verdict di sisi server