---
title: Fraud Prevention — Web SDK
---

# Fraud Prevention Web SDK

Fraud Prevention Web SDK berjalan pada **halaman anda** — halaman pendaratan, skrin
pendaftaran atau log masuk, atau mana-mana sumber yang dilindungi. Ia meminta keputusan
untuk lawatan semasa dan menyerahkannya semula kepada kod anda, supaya anda boleh
memutuskan apa yang hendak dilakukan dengan trafik itu — rekodkannya, tandainya, atau
minta pelawat satu pengesahan tambahan.

## Mula pantas

```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 `Promise<BotVerdict>`, jadi anda boleh `await`
ia dan bukannya menggunakan `onVerdict` — kedua-duanya menerima objek keputusan yang
sama.

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

## Pilihan

| Pilihan | Jenis | Lalai | Keterangan |
| --- | --- | --- | --- |
| `appKey` | string | — | Kunci aplikasi Fraud Prevention anda (diperlukan). |
| `domain` | string | lalai perkhidmatan | Titik akhir perkhidmatan keputusan. Biarkan tidak ditetapkan melainkan anda diberi domain khusus. |
| `escalate` | boolean | `false` | Benarkan Fraud Prevention meminta pelawat **satu pengesahan tambahan** apabila sesuatu lawatan kelihatan berisiko tinggi. Lihat [Escalation](#escalation). |
| `collectWindowMs` | number | `1200` | Berapa lama (ms) SDK memerhati lawatan sebelum meminta keputusan. Tetingkap yang lebih panjang menghasilkan keputusan yang lebih yakin dengan kos sedikit kelewatan. |
| `onVerdict` | `(v) => void` | — | Dipanggil sekali dengan keputusan akhir. Titik integrasi utama. |
| `onError` | `(err) => void` | — | Dipanggil jika ada apa-apa yang tidak kena. SDK tidak pernah membuang ralat ke halaman anda. |
| `onEscalate` | `(displayType) => void` | — | Dipanggil apabila pengesahan tambahan dipaparkan (hanya apabila `escalate: true`). |
| `onEscalateDone` | `(passed) => void` | — | Dipanggil selepas pengesahan tambahan selesai; `passed` ialah `true` jika pelawat melepasinya. |

::: tip Senario sumber trafik
Jika pihak ketiga menghantar pelawat kepada anda dan kedua-dua belah pihak perlu
menyelaras pada kesimpulan per klik, SDK juga boleh membaca token klik daripada URL
halaman. Itu khusus untuk aliran trafik berbayar — lihat panduan [Ad fraud](./scenarios/ad-fraud).
:::

## Menggunakan keputusan

`onVerdict` menerima objek `BotVerdict`. Dua medan yang paling kerap anda gunakan:

- **`verdict.is_bot`** — `true` apabila lawatan dinilai sebagai automatik/tidak sah.
- **`verdict.action`** — apa yang kami cadangkan 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 senarai medan penuh dan pengendalian yang disyorkan dalam
[Verdict Reference](./verdict-reference).

## Escalation

Apabila sesuatu lawatan kelihatan berisiko tinggi, Fraud Prevention boleh meminta
pelawat melengkapkan **satu pengesahan tambahan** sebelum anda melayan mereka sebagai
pengguna sebenar. Ini bersifat pilihan masuk (opt-in).

Dayakannya 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
  },
});
```

Nota:

- Escalation hanya dicetuskan apabila `action` keputusan ialah `challenge`. Untuk semua
  lawatan lain, tiada apa yang dipaparkan dan pengalaman pelawat tidak terjejas.
- Jika pelawat melepasi pengesahan tambahan, keputusan yang dihantar ke `onVerdict`
  mencerminkan perkara itu (dilayan sebagai manusia).
- Escalation **gagal terbuka** (fails open): jika pengesahan tambahan tidak dapat dimuat
  atau dipaparkan, SDK mengekalkan keputusan asal dan bukannya menyekat halaman anda.

::: info
Fraud Prevention tidak pernah membuat keputusan *untuk* anda. Walaupun pada
`challenge`/`flag`, kod anda kekal mengawal sama ada lawatan itu diteruskan — SDK hanya
mengetengahkan keputusan dan, secara pilihan, menjalankan pengesahan tambahan.
:::

## Daya tahan

Jika perkhidmatan keputusan tidak dapat dicapai atau sebarang ralat berlaku, SDK
mengembalikan keputusan **degraded** (`degraded: true`) dan bukannya menggagalkan
halaman anda. Keputusan degraded bersifat konservatif (`is_bot: false`, `action:
record_only`) supaya ia tidak pernah menyekat pengguna sebenar. Semak `verdict.degraded`
jika anda mahu melayan lawatan tersebut secara khas.

## Langkah seterusnya

- [Verdict Reference](./verdict-reference) — setiap medan dan cara bertindak ke atasnya
- [Data API](./data-api) — tarik dan selaras keputusan di bahagian pelayan