---
title: Prévention de la fraude — Fraude publicitaire
---

# Fraude publicitaire

Ceci est un **guide par scénario**. L’intégration de base reste inchangée — vous chargez le
[SDK Web](../web-sdk), lisez un [verdict](../verdict-reference) et récupérez les données
depuis l’[API de données](../data-api) exactement comme décrit dans ces pages. Cette page
ajoute les quelques spécificités propres au seul scénario de fraude publicitaire.

La protection contre la fraude publicitaire filtre les bots et le trafic invalide hors des
campagnes payantes, afin que les annonceurs et les plateformes publicitaires paient pour des
clics et des impressions authentiques — et non pour du volume factice. Ce qui la distingue
des autres cas d’usage, c’est qu’**un tiers fournit le visiteur** et que les deux parties
doivent s’accorder sur une conclusion humain / bot indépendante, par clic.

## Blocage en temps réel à la source

Fraud Prevention s’exécute inline au point d’entrée et renvoie un verdict en temps réel — ce n’est pas un rapport a posteriori. Celui qui possède la page sur laquelle arrive le visiteur peut agir sur ce verdict immédiatement :

- **Les annonceurs** exécutent le SDK sur la page de destination : le trafic invalide est détecté — et, en option, soumis à un challenge — dès son arrivée, avant qu’il n’entre dans le funnel ou ne fausse les rapports.
- **Les plateformes de trafic** exécutent le SDK sur leur propre pre-lander ou page de redirection : un clic est vérifié *avant* d’être transféré, de sorte que les bots sont arrêtés à l’entrée et ne deviennent jamais du trafic livré.

La seule condition est une page capable d’exécuter le SDK : un verdict a besoin de signaux du navigateur, donc une redirection 302 purement côté serveur n’a nulle part où les collecter — ajoutez une page intermédiaire légère et le même blocage en temps réel s’applique.

Le jeton de clic signé et la Data API viennent par-dessus pour le rapprochement entre les deux parties ; le blocage inline en temps réel est le mécanisme principal, et le nettoyage a posteriori via l’API est le recours pour le trafic sans page intermédiaire.

## Les deux rôles

- **Annonceur** — possède la page de destination sur laquelle arrive le visiteur. Exécute le
  SDK Web sur cette page pour obtenir un verdict pour chaque visite entrante, et récupère les
  verdicts depuis l’API de données pour rapprocher ce qui lui a été facturé.
- **Fournisseur** (source de trafic / publicitaire) — fournit le clic. Il doit **prouver la
  qualité de ce qu’il a envoyé**, c’est pourquoi il émet un jeton de clic par clic et
  rapproche ensuite son rapport de livraison des verdicts indépendants.

Les deux parties s’authentifient auprès de l’[API de données](../data-api) avec leurs propres
identifiants d’application et lisent le même verdict par clic, ce qui leur permet de se
rapprocher sans avoir à se fier aux journaux bruts l’une de l’autre.

## Flux de bout en bout

La séquence ci-dessous montre comment un clic chemine depuis la livraison du fournisseur, en
passant par le visiteur et la page de destination de l’annonceur, jusqu’à un verdict unique
que **les deux comptes lisent ensuite chacun de leur côté**.

```mermaid
sequenceDiagram
    autonumber
    participant P as Fournisseur (compte B)
    participant V as Visiteur
    participant A as Page de l’annonceur + SDK
    participant F as API de prévention de la fraude

    P->>P: Signe click_token (bot_kid + secret, contient pkid)
    P->>V: Livre le lien avec ?_ctk=click_token
    V->>A: Clic → arrive sur la page de l’annonceur (URL portant _ctk)
    A->>A: Le SDK lit _ctk depuis l’URL
    A->>F: POST chiffré /bot/verify<br/>(app_key = annonceur, click_token = signé par le fournisseur)
    F->>F: app_key → advertiser_app_id,<br/>vérifie pkid → provider_app_id, rend un verdict,<br/>écrit une ligne portant les deux app_ids
    F-->>A: verdict → onVerdict
    A->>A: Traite selon verdict.action (enregistrer / bloquer / challenge)

    Note over P,F: Rapprochement (inter-comptes)
    A->>F: GET /v1/bot avec l’App-Key de l’annonceur
    F-->>A: Même ligne (correspondance sur advertiser_app_id)
    P->>F: GET /v1/bot avec l’App-Key du fournisseur
    F-->>P: Même ligne (correspondance sur provider_app_id)
```

La propriété déterminante : **les deux app_ids figurent sur la même ligne.** L’annonceur la
lit par correspondance sur `advertiser_app_id`, le fournisseur la lit par correspondance sur
`provider_app_id` — deux comptes différents, chacun interrogeant avec sa propre App-Key,
chacun aboutissant au même verdict indépendant. Aucune des parties n’a à exposer ou à se fier
aux journaux bruts de l’autre pour s’accorder sur ce qui s’est passé pour un clic donné.

## Jetons de clic

Un **jeton de clic** relie le clic livré par un fournisseur au verdict que la visite finit par
recevoir. C’est l’identifiant par clic sur lequel les deux parties s’accordent. Les autres cas
d’usage de la prévention de la fraude n’ont pas besoin de jetons de clic — ils rapprochent les
verdicts sans eux.

Le flux :

1. **Émission** — le fournisseur obtient un jeton de clic signé (un par clic) lorsqu’il oriente
   un visiteur vers la page de destination de l’annonceur.
2. **Le porter sur l’URL de destination** — ajoutez le jeton émis à l’URL de destination en
   paramètre de requête :

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

3. **Le lire sur la page** — le [SDK Web](../web-sdk) lit automatiquement le jeton depuis
   l’URL. Si vous utilisez un nom de paramètre différent, définissez `tokenParam` :

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

4. **Rapprocher** — recherchez le clic plus tard via l’API de données et rapprochez-le du
   rapport de livraison du fournisseur.

::: info
Le jeton est déjà signé lorsqu’il vous est émis — vous n’avez qu’à le **transmettre jusqu’à
l’URL de destination**. Il n’y a rien à signer ni à calculer de votre côté.
:::

### Option `tokenParam`

Le SDK Web gagne une option supplémentaire dans ce scénario :

| Option | Type | Défaut | Description |
| --- | --- | --- | --- |
| `tokenParam` | string | détecté automatiquement | Nom du paramètre de requête de l’URL qui porte le jeton de clic du fournisseur (par ex. `click_token`). Le SDK le lit depuis l’URL de la page et relie le verdict à ce clic. À laisser non défini si vous n’utilisez pas de jetons de clic. |

## Rapprochement et règlement

Une fois que les visites portent un jeton de clic, les deux parties s’accordent sur les mêmes
verdicts indépendants :

- **Récupérer le verdict d’un clic unique** — par exemple pour contester ou confirmer un clic :

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

- **Exporter les lignes par clic** — récupérez une plage de temps et rapprochez le
  `click_token` de chaque ligne de vos propres journaux de clics :

  ```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
  ```

  Chaque ligne porte le `click_token` de la visite (lorsqu’il est présent), l’horodatage et
  les champs du verdict (`is_bot`, `score`, `level`, `action`).

L’annonceur exclut les clics signalés et les clics de bots de ce qu’il paie ; le fournisseur
rapproche son rapport de livraison des mêmes conclusions. Comme les deux lisent le **même
verdict indépendant**, le règlement ne dépend des journaux bruts d’aucune des parties.

## Modèle de sécurité

La `cid` et le jeton de clic circulent dans l’URL : traitez-les comme des identifiants, pas comme des informations d’authentification :

- **Lire un verdict requiert App-Key + App-Secret.** La Data API authentifie chaque appel avec votre app secret (comparé en temps constant) et ne renvoie que les lignes où votre application est l’advertiser ou le provider. Une `cid` seule ne récupère rien : un tiers qui la copie depuis l’URL n’a pas de secret et n’est pas partie prenante de la ligne.
- **Le provider est lié par la signature.** Le jeton de clic est signé en HMAC avec le secret du provider et porte le `pkid` du provider ; il ne peut pas être falsifié, et une `cid` ne peut être réclamée qu’une seule fois (protection contre le rejeu).
- **Liez aussi l’advertiser, en option.** Signez le `app_key` de l’advertiser cible dans le jeton sous la forme `aud`. La vérification exige alors que l’app_key de la page corresponde à `aud`, de sorte qu’un jeton émis pour l’advertiser A ne puisse pas attribuer un verdict à l’advertiser B. Omettez `aud` et toute page d’advertiser pourra accepter le jeton.

Effet net : le verdict d’une `cid` n’est lisible que par les deux applications qui y sont liées — l’advertiser dont la page a exécuté le SDK et le provider dont le jeton a été présenté — chacune s’authentifiant avec son propre App-Secret.

## Étapes suivantes

- [SDK Web](../web-sdk) — collectez les verdicts sur la page de destination
- [Référence du verdict](../verdict-reference) — chaque champ et comment agir dessus
- [API de données](../data-api) — récupérez et rapprochez les verdicts côté serveur