Ad fraud

This is a scenario guide. The core integration is unchanged — you load the Web SDK, read a verdict, and pull data from the Data API exactly as described in those pages. This page adds the few specifics that only the ad-fraud scenario needs.

Ad fraud protection filters bot and invalid traffic out of paid campaigns, so advertisers and ad platforms pay for genuine clicks and impressions — not fake volume. What makes it different from the other use cases is that a third party delivers the visitor, and both sides need to settle on an independent, per-click human / bot conclusion.

The two roles

• Advertiser — owns the landing page the visitor arrives on. Runs the Web SDK on that page to get a verdict for each arriving visit, and pulls verdicts from the Data API to reconcile what it was billed for.
• Provider (traffic / ad source) — delivers the click. It needs to prove the quality of what it sent, so it issues a click token per click and later joins its delivery report against the independent verdicts.

Both sides authenticate to the Data API with their own application credentials and read the same per-click verdict, which is what lets them reconcile without trusting each other's raw logs.

End-to-end flow

The sequence below shows how one click travels from the provider's delivery, through the visitor and the advertiser's landing page, to a single verdict that both accounts later read from their own side.

The decisive property: both app_ids live on the same row. The advertiser reads it matched on advertiser_app_id, the provider reads it matched on provider_app_id — two different accounts, each querying with its own App-Key, each landing on the same independent verdict. Neither side has to expose or trust the other's raw logs to agree on what happened for a given click.

Click tokens

A click token ties a provider's delivered click to the verdict the visit ultimately receives. It is the per-click identifier that both parties settle on. The other Fraud Prevention use cases don't need click tokens — they reconcile verdicts without them.

The flow:

1. Issue — the provider obtains a signed click token (one per click) when it routes a visitor toward the advertiser's landing page.

2. Carry it on the destination URL — append the issued token to the landing URL as a query parameter:

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

3. Read it on the page — the Web SDK reads the token from the URL automatically. If you use a different parameter name, set tokenParam:

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

4. Reconcile — look the click up later via the Data API and join it back to the provider's delivery report.

INFO

The token is already signed when it is issued to you — you only need to carry it through to the landing URL. There is nothing to sign or compute on your side.

tokenParam option

The Web SDK gains one extra option in this scenario:

Option	Type	Default	Description
tokenParam	string	auto-detected	Name of the URL query parameter that carries the provider click token (e.g. click_token). The SDK reads it from the page URL and ties the verdict to that click. Leave unset if you don't use click tokens.

Reconciliation & settlement

Once visits carry a click token, both sides settle on the same independent verdicts:

• Fetch a single click's verdict — for example to dispute or confirm one click:

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

• Export per-click rows — pull a time range and join each row's click_token back to your own click logs:

  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

  Each row carries the visit's click_token (when present), timestamp, and verdict fields (is_bot, score, level, action).

The advertiser excludes flagged and bot clicks from what it pays for; the provider reconciles its delivery report against the same conclusions. Because both read the same independent verdict, settlement does not depend on either side's raw logs.

Next steps

• Web SDK — collect verdicts on the landing page
• Verdict Reference — every field and how to act on it
• Data API — pull and reconcile verdicts server-side