---
title: Fraud Prevention — Ad Fraud
---

# Ad fraud

Ini ialah **panduan senario**. Integrasi teras tidak berubah — anda memuatkan
[Web SDK](../web-sdk), membaca [keputusan](../verdict-reference), dan menarik data
daripada [Data API](../data-api) tepat seperti yang diterangkan dalam halaman tersebut.
Halaman ini menambah beberapa perincian yang hanya senario ad-fraud perlukan.

Perlindungan ad fraud menapis bot dan trafik tidak sah keluar daripada kempen berbayar,
supaya advertiser dan platform iklan membayar untuk klik dan tera tulen — bukan volum
palsu. Apa yang membezakannya daripada kes penggunaan lain ialah **pihak ketiga
menghantar pelawat**, dan kedua-dua belah pihak perlu menyelesaikan pada kesimpulan
manusia / bot per klik yang bebas.

## Penyekatan masa nyata di sumbernya

Fraud Prevention berjalan inline di titik masuk dan memulangkan keputusan secara masa nyata — ia bukan laporan selepas kejadian. Sesiapa yang memiliki halaman tempat pelawat mendarat boleh bertindak atas keputusan itu serta-merta:

- **Advertiser** menjalankan SDK pada halaman pendaratan: trafik tidak sah dikesan — dan secara pilihan diberi challenge — pada saat ia tiba, sebelum ia masuk ke funnel atau memesongkan pelaporan.
- **Platform trafik** menjalankan SDK pada pre-lander atau halaman ubah hala mereka sendiri: satu klik disahkan *sebelum* ia diteruskan, jadi bot dihentikan di pintu masuk dan tidak pernah menjadi trafik yang dihantar.

Satu-satunya syarat ialah halaman yang boleh menjalankan SDK: sesuatu keputusan memerlukan isyarat pelayar, jadi 302 tulen di sebelah pelayan tidak mempunyai tempat untuk mengumpulnya — tambah satu halaman perantara ringan dan penyekatan masa nyata yang sama akan terpakai.

Click token yang ditandatangani dan Data API berada di atasnya untuk penyelarasan antara kedua-dua belah pihak; penyekatan inline masa nyata ialah mekanisme utama, dan pembersihan API selepas itu ialah sandaran bagi trafik tanpa halaman perantara.

## Dua peranan

- **Advertiser** — memiliki halaman pendaratan tempat pelawat tiba. Menjalankan Web SDK
  pada halaman itu untuk mendapatkan keputusan bagi setiap lawatan yang tiba, dan
  menarik keputusan daripada Data API untuk menyelaras apa yang ia dibilkan.
- **Provider** (sumber trafik / iklan) — menghantar klik. Ia perlu **membuktikan
  kualiti apa yang dihantarnya**, jadi ia mengeluarkan token klik setiap klik dan
  kemudian mencantumkan laporan penghantarannya dengan keputusan bebas.

Kedua-dua belah pihak mengesahkan diri ke [Data API](../data-api) dengan kelayakan
aplikasi mereka sendiri dan membaca keputusan per klik yang sama, dan inilah yang
membolehkan mereka menyelaras tanpa mempercayai log mentah satu sama lain.

## Aliran hujung ke hujung

Jujukan di bawah menunjukkan bagaimana satu klik bergerak daripada penghantaran
provider, melalui pelawat dan halaman pendaratan advertiser, kepada satu keputusan yang
**kedua-dua akaun kemudiannya baca dari pihak mereka sendiri**.

```mermaid
sequenceDiagram
    autonumber
    participant P as Provider (akaun B)
    participant V as Pelawat
    participant A as Halaman advertiser + SDK
    participant F as Fraud Prevention API

    P->>P: Tandatangan click_token (bot_kid + secret, membawa pkid)
    P->>V: Hantar pautan dengan ?_ctk=click_token
    V->>A: Klik → mendarat pada halaman advertiser (URL membawa _ctk)
    A->>A: SDK membaca _ctk dari URL
    A->>F: POST tersulit /bot/verify<br/>(app_key = advertiser, click_token = ditandatangan provider)
    F->>F: app_key → advertiser_app_id,<br/>sahkan pkid → provider_app_id, capai keputusan,<br/>tulis satu baris membawa kedua-dua app_id
    F-->>A: verdict → onVerdict
    A->>A: Kendali ikut verdict.action (rekod / sekat / challenge)

    Note over P,F: Penyelarasan (merentas akaun)
    A->>F: GET /v1/bot dengan App-Key advertiser
    F-->>A: Baris yang sama (dipadan pada advertiser_app_id)
    P->>F: GET /v1/bot dengan App-Key provider
    F-->>P: Baris yang sama (dipadan pada provider_app_id)
```

Sifat penentu: **kedua-dua app_id berada pada baris yang sama.** Advertiser membacanya
dipadan pada `advertiser_app_id`, provider membacanya dipadan pada `provider_app_id` —
dua akaun berbeza, setiap satu menanya dengan App-Key sendiri, setiap satu mendarat pada
keputusan bebas yang sama. Tiada pihak perlu mendedahkan atau mempercayai log mentah
pihak lain untuk bersetuju tentang apa yang berlaku bagi sesuatu klik.

## Token klik

**Token klik** (click token) mengikat klik yang dihantar oleh provider kepada keputusan
yang akhirnya diterima oleh lawatan. Ia ialah pengecam per klik yang kedua-dua pihak
selesaikan. Kes penggunaan Fraud Prevention yang lain tidak memerlukan token klik —
mereka menyelaras keputusan tanpanya.

Aliran:

1. **Keluarkan** — provider memperoleh token klik yang ditandatangan (satu setiap klik)
   apabila ia menghalakan pelawat ke halaman pendaratan advertiser.
2. **Bawa ia pada URL destinasi** — tambahkan token yang dikeluarkan ke URL pendaratan
   sebagai parameter pertanyaan:

   ```
   https://advertiser.example/lp?click_token=ct_xxxxxxxx
   ```

3. **Baca ia pada halaman** — [Web SDK](../web-sdk) membaca token daripada URL secara
   automatik. Jika anda menggunakan nama parameter yang berbeza, tetapkan `tokenParam`:

   ```js
   BotSignal.init({ appKey: 'YOUR_APP_KEY', tokenParam: 'click_token' });
   ```

4. **Selaras** — cari klik itu kemudian melalui Data API dan cantumkannya semula kepada
   laporan penghantaran provider.

::: info
Token sudah ditandatangan apabila ia dikeluarkan kepada anda — anda hanya perlu
**membawanya hingga ke URL pendaratan**. Tiada apa yang perlu ditandatangan atau dikira
di pihak anda.
:::

### Pilihan `tokenParam`

Web SDK memperoleh satu pilihan tambahan dalam senario ini:

| Pilihan | Jenis | Lalai | Keterangan |
| --- | --- | --- | --- |
| `tokenParam` | string | dikesan-auto | Nama parameter pertanyaan URL yang membawa token klik provider (cth. `click_token`). SDK membacanya daripada URL halaman dan mengikat keputusan kepada klik itu. Biarkan tidak ditetapkan jika anda tidak menggunakan token klik. |

## Penyelarasan & penyelesaian

Setelah lawatan membawa token klik, kedua-dua belah pihak menyelesaikan pada keputusan
bebas yang sama:

- **Dapatkan keputusan satu klik** — contohnya untuk membantah atau mengesahkan satu klik:

  ```bash
  GET /v1/bot/verdict?click_token=ct_xxx
  X-App-Key: YOUR_APP_KEY
  X-App-Secret: YOUR_APP_SECRET
  ```

- **Eksport baris per klik** — tarik satu julat masa dan cantumkan `click_token` setiap
  baris semula kepada log klik anda sendiri:

  ```bash
  GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
  X-App-Key: YOUR_APP_KEY
  X-App-Secret: YOUR_APP_SECRET
  ```

  Setiap baris membawa `click_token` lawatan (jika ada), cap masa, dan medan keputusan
  (`is_bot`, `score`, `level`, `action`).

Advertiser mengecualikan klik yang ditandai dan klik bot daripada apa yang ia bayar;
provider menyelaras laporan penghantarannya dengan kesimpulan yang sama. Kerana
kedua-dua pihak membaca **keputusan bebas yang sama**, penyelesaian tidak bergantung
pada log mentah mana-mana pihak.

## Model keselamatan

`cid` dan click token bergerak di dalam URL, jadi anggaplah ia sebagai pengecam — bukan kelayakan:

- **Membaca keputusan memerlukan App-Key + App-Secret.** Data API mengesahkan setiap panggilan dengan app secret anda (dibandingkan dalam masa malar) dan hanya memulangkan baris yang aplikasi anda menjadi advertiser atau provider. Sebuah `cid` semata-mata tidak mengambil apa-apa — pihak ketiga yang menyalinnya daripada URL tidak mempunyai secret dan bukan pihak kepada baris itu.
- **provider terikat oleh tandatangan.** Click token ditandatangani HMAC dengan secret milik provider dan membawa `pkid` provider; ia tidak boleh dipalsukan, dan sebuah `cid` hanya boleh dituntut sekali sahaja (dilindungi daripada main semula).
- **Pilihan untuk mengikat advertiser juga.** Tandatangani `app_key` advertiser sasaran ke dalam token sebagai `aud`. Pengesahan kemudian menuntut app_key halaman sepadan dengan `aud`, supaya token yang dikeluarkan untuk advertiser A tidak boleh mengatribusikan keputusan pada advertiser B. Tinggalkan `aud` maka mana-mana halaman advertiser boleh menerima token itu.

Kesan bersih: keputusan bagi sesuatu `cid` hanya boleh dibaca oleh dua aplikasi yang terikat padanya — advertiser yang halamannya menjalankan SDK dan provider yang token-nya ditunjukkan — masing-masing mengesahkan dengan App-Secret sendiri.

## Langkah seterusnya

- [Web SDK](../web-sdk) — kumpul keputusan pada halaman pendaratan
- [Verdict Reference](../verdict-reference) — setiap medan dan cara bertindak ke atasnya
- [Data API](../data-api) — tarik dan selaras keputusan di bahagian pelayan