---
title: Pencegahan penipuan — Penipuan iklan
---

# Penipuan iklan

Ini adalah **panduan skenario**. Integrasi inti tidak berubah — Anda memuat [Web
SDK](../web-sdk), membaca sebuah [verdict](../verdict-reference), dan menarik data
dari [Data API](../data-api) persis seperti yang dijelaskan di halaman-halaman itu.
Halaman ini menambahkan sedikit spesifik yang hanya dibutuhkan skenario penipuan
iklan.

Perlindungan penipuan iklan menyaring bot dan trafik tidak valid dari kampanye
berbayar, sehingga advertiser dan platform iklan membayar untuk klik dan impresi yang
asli — bukan volume palsu. Yang membuatnya berbeda dari kasus penggunaan lain adalah
bahwa **pihak ketiga mengirimkan pengunjung**, dan kedua belah pihak perlu
menyepakati kesimpulan manusia / bot per-klik yang independen.

## Pemblokiran real-time di sumbernya

Fraud Prevention berjalan inline di titik masuk dan mengembalikan verdict secara real-time — ini bukan laporan setelah kejadian. Siapa pun yang memiliki halaman tempat pengunjung mendarat dapat bertindak atas verdict itu seketika:

- **Advertiser** menjalankan SDK pada landing page: trafik tidak valid terdeteksi — dan opsional diberi challenge — pada saat ia tiba, sebelum masuk ke funnel atau mendistorsi pelaporan.
- **Platform trafik** menjalankan SDK pada pre-lander atau halaman redirect mereka sendiri: sebuah klik diverifikasi *sebelum* diteruskan, sehingga bot dihentikan di pintu masuk dan tidak pernah menjadi trafik yang terkirim.

Satu-satunya syarat adalah halaman yang dapat menjalankan SDK: sebuah verdict membutuhkan sinyal browser, jadi 302 murni di sisi server tidak punya tempat untuk mengumpulkannya — tambahkan sebuah interstitial ringan dan pemblokiran real-time yang sama akan berlaku.

Click token bertanda tangan dan Data API berada di atasnya untuk rekonsiliasi antar kedua sisi; pemblokiran inline real-time adalah mekanisme utama, dan pembersihan API setelahnya adalah cadangan untuk trafik tanpa interstitial.

## Dua peran

- **Advertiser** — memiliki landing page tempat pengunjung tiba. Menjalankan Web SDK
  pada halaman tersebut untuk mendapatkan verdict bagi setiap kunjungan yang datang,
  dan menarik verdict dari Data API untuk merekonsiliasi apa yang ditagihkan
  kepadanya.
- **Provider** (sumber trafik / iklan) — mengirimkan klik. Ia perlu **membuktikan
  kualitas dari apa yang dikirimnya**, sehingga ia menerbitkan sebuah click token per
  klik dan kemudian menggabungkan laporan pengirimannya dengan verdict independen.

Kedua belah pihak mengautentikasi ke [Data API](../data-api) dengan kredensial
aplikasi mereka sendiri dan membaca verdict per-klik yang sama, yang memungkinkan
mereka merekonsiliasi tanpa saling mempercayai log mentah satu sama lain.

## Alur ujung-ke-ujung

Urutan di bawah menunjukkan bagaimana satu klik berjalan dari pengiriman provider,
melalui pengunjung dan landing page advertiser, hingga satu verdict yang **kemudian
dibaca oleh kedua akun dari sisi mereka masing-masing**.

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

    P->>P: Tanda tangani click_token (bot_kid + secret, membawa pkid)
    P->>V: Kirim tautan dengan ?_ctk=click_token
    V->>A: Klik → mendarat di halaman advertiser (URL membawa _ctk)
    A->>A: SDK membaca _ctk dari URL
    A->>F: POST terenkripsi /bot/verify<br/>(app_key = advertiser, click_token = ditandatangani provider)
    F->>F: app_key → advertiser_app_id,<br/>verifikasi pkid → provider_app_id, capai verdict,<br/>tulis satu baris membawa kedua app_id
    F-->>A: verdict → onVerdict
    A->>A: Tangani sesuai verdict.action (catat / blokir / challenge)

    Note over P,F: Rekonsiliasi (lintas-akun)
    A->>F: GET /v1/bot dengan App-Key advertiser
    F-->>A: Baris yang sama (cocok pada advertiser_app_id)
    P->>F: GET /v1/bot dengan App-Key provider
    F-->>P: Baris yang sama (cocok pada provider_app_id)
```

Properti yang menentukan: **kedua app_id berada pada baris yang sama.** Advertiser
membacanya yang dicocokkan pada `advertiser_app_id`, provider membacanya yang
dicocokkan pada `provider_app_id` — dua akun berbeda, masing-masing menanyakan dengan
App-Key-nya sendiri, masing-masing tiba pada verdict independen yang sama. Tidak ada
pihak yang harus mengekspos atau mempercayai log mentah pihak lain untuk menyepakati
apa yang terjadi pada suatu klik.

## Click token

Sebuah **click token** mengikat klik yang dikirim provider ke verdict yang akhirnya
diterima kunjungan tersebut. Ia adalah identifier per-klik yang disepakati kedua
pihak. Kasus penggunaan Fraud Prevention lainnya tidak membutuhkan click token —
mereka merekonsiliasi verdict tanpanya.

Alurnya:

1. **Terbitkan** — provider memperoleh click token bertanda tangan (satu per klik)
   ketika ia mengarahkan pengunjung menuju landing page advertiser.
2. **Bawa pada URL tujuan** — tambahkan token yang diterbitkan ke landing URL sebagai
   parameter query:

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

3. **Baca pada halaman** — [Web SDK](../web-sdk) membaca token dari URL secara
   otomatis. Jika Anda memakai nama parameter berbeda, atur `tokenParam`:

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

4. **Rekonsiliasi** — cari klik tersebut nanti via Data API dan gabungkan kembali ke
   laporan pengiriman provider.

::: info
Token sudah ditandatangani saat diterbitkan kepada Anda — Anda hanya perlu
**membawanya hingga ke landing URL**. Tidak ada yang perlu ditandatangani atau dihitung
di sisi Anda.
:::

### Opsi `tokenParam`

Web SDK memperoleh satu opsi tambahan dalam skenario ini:

| Opsi | Tipe | Default | Deskripsi |
| --- | --- | --- | --- |
| `tokenParam` | string | terdeteksi otomatis | Nama parameter query URL yang membawa click token provider (mis. `click_token`). SDK membacanya dari URL halaman dan mengikat verdict ke klik tersebut. Biarkan tidak diatur jika Anda tidak memakai click token. |

## Rekonsiliasi & penyelesaian

Setelah kunjungan membawa click token, kedua belah pihak menyepakati verdict
independen yang sama:

- **Ambil verdict satu klik** — misalnya untuk membantah atau mengonfirmasi satu
  klik:

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

- **Ekspor baris per-klik** — tarik rentang waktu dan gabungkan `click_token` setiap
  baris kembali ke 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` kunjungan (jika ada), timestamp, dan field
  verdict (`is_bot`, `score`, `level`, `action`).

Advertiser mengecualikan klik yang ditandai dan klik bot dari apa yang dibayarnya;
provider merekonsiliasi laporan pengirimannya dengan kesimpulan yang sama. Karena
keduanya membaca **verdict independen yang sama**, penyelesaian tidak bergantung pada
log mentah pihak mana pun.

## Model keamanan

`cid` dan click token berjalan di dalam URL, jadi perlakukan keduanya sebagai pengenal — bukan kredensial:

- **Membaca verdict memerlukan App-Key + App-Secret.** Data API mengautentikasi setiap panggilan dengan app secret Anda (dibandingkan dalam waktu konstan) dan hanya mengembalikan baris tempat aplikasi Anda berperan sebagai advertiser atau provider. Sebuah `cid` sendirian tidak mengambil apa pun — pihak ketiga yang menyalinnya dari URL tidak punya secret dan bukan bagian dari baris itu.
- **Provider terikat oleh tanda tangan.** Click token ditandatangani HMAC dengan secret milik provider dan membawa `pkid` provider; ia tidak dapat dipalsukan, dan sebuah `cid` hanya dapat diklaim satu kali (terlindungi dari replay).
- **Opsional, ikat juga advertiser-nya.** Tandatangani `app_key` advertiser tujuan ke dalam token sebagai `aud`. Verifikasi lalu mengharuskan app_key halaman cocok dengan `aud`, sehingga token yang diterbitkan untuk advertiser A tidak dapat mengatribusikan verdict pada advertiser B. Hilangkan `aud` maka halaman advertiser mana pun boleh menerima token tersebut.

Efek bersihnya: verdict untuk sebuah `cid` hanya dapat dibaca oleh dua aplikasi yang terikat padanya — advertiser yang halamannya menjalankan SDK dan provider yang token-nya disodorkan — masing-masing mengautentikasi dengan App-Secret-nya sendiri.

## Langkah berikutnya

- [Web SDK](../web-sdk) — kumpulkan verdict pada landing page
- [Referensi verdict](../verdict-reference) — setiap field dan cara menindaknya
- [Data API](../data-api) — tarik dan rekonsiliasi verdict di sisi server