---
title: Prévention de la fraude — SDK Web
---

# SDK Web de prévention de la fraude

Le SDK Web de prévention de la fraude s’exécute sur **votre page** — une page de
destination, un écran d’inscription ou de connexion, ou toute ressource protégée. Il demande
un verdict pour la visite en cours et le restitue à votre code, afin que vous puissiez
décider quoi faire du trafic — l’enregistrer, le signaler ou demander au visiteur une
vérification supplémentaire.

## Démarrage rapide

```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()` renvoie également une `Promise<BotVerdict>`, vous pouvez donc aussi
`await` le résultat au lieu d’utiliser `onVerdict` — les deux reçoivent le même objet
verdict.

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

## Options

| option | type | default | description |
| --- | --- | --- | --- |
| `appKey` | string | — | Obligatoire. Votre clé d’application de prévention de la fraude. |
| `domain` | string | `signal-v1.world-dynamic.com` | Domaine Signal vers lequel le SDK envoie ses requêtes. |
| `tokenParam` | string | `_ctk` | Paramètre de requête de l’URL depuis lequel le SDK lit le jeton de clic. |
| `onVerdict` | `(v) => void` | — | Appelé une fois avec le verdict final. Le principal point d’intégration. `init()` renvoie également une `Promise<BotVerdict>`. |
| `onError` | `(err) => void` | — | Appelé en cas d’échec. Le SDK ne lève jamais d’exception dans votre page. |
| `onChallenge` | `(v) => creds \| null \| Promise<…>` | — | Remplace les identifiants d’escalade : renvoyez vos propres `{ appKey, serverToken }` (serverToken émis par **votre backend**), ou `null` pour ignorer l’escalade. Si non défini, les identifiants par défaut émis par le backend dans `verdict.escalate` sont utilisés (zéro configuration). |
| `challengeConfig` | object | — | Apparence/placement du captcha : `product` (`popup`/`float`/`embed`), `container`, `theme`, `lang`. |
| `onEscalate` | `(displayType) => void` | — | Appelé lorsqu’un captcha d’escalade est affiché. |
| `onEscalateDone` | `(passed, detail) => void` | — | Appelé après l’escalade. `passed` = le visiteur l’a réussie ; `detail` = `{ token, challengeId, cid }` pour la **vérification côté serveur** de la réussite. |

**L’escalade est pilotée par le serveur.** Le SDK n’affiche un captcha que lorsque l’`action` du verdict du serveur est `challenge` *et* que l’application est configurée avec une action d’escalade correspondante — il n’existe aucun interrupteur côté client pour cela. Utilisez `onChallenge` pour fournir vos propres identifiants ou pour ignorer l’escalade, et `challengeConfig` pour contrôler son apparence. Une fois qu’un visiteur a réussi, vérifiez le résultat sur votre propre backend avec `detail.token` (ainsi que `challenge_id`/`cid`) — ne vous fiez pas au seul indicateur `passed` côté client.

::: tip Scénarios de source de trafic
Si un tiers vous fournit des visiteurs et que les deux parties doivent se rapprocher sur
une conclusion par clic, le SDK peut aussi lire un jeton de clic depuis l’URL de la page.
Cela est propre aux flux de trafic payant — voir le guide [Fraude publicitaire](./scenarios/ad-fraud).
:::

## Exploiter le verdict

`onVerdict` reçoit un objet `BotVerdict`. Les deux champs que vous utiliserez le plus :

- **`verdict.is_bot`** — `true` lorsque la visite est jugée automatisée/invalide.
- **`verdict.action`** — ce que nous recommandons de faire : `record_only`, `challenge` ou
  `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;
    }
  },
});
```

Consultez la liste complète des champs et le traitement recommandé dans la
[Référence du verdict](./verdict-reference).

## Escalade

Lorsqu’une visite paraît à haut risque, la prévention de la fraude peut demander au visiteur
de réaliser **une vérification supplémentaire** avant que vous ne le traitiez comme un
utilisateur réel. Ceci est piloté par le verdict du serveur, et non par un indicateur côté
client — cela se déclenche dès que l’`action` du verdict est `challenge` et que l’application
dispose d’une action d’escalade configurée.

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // une vérification supplémentaire est affichée au visiteur
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // le visiteur a réussi la vérification supplémentaire — vérifiez detail.token sur votre backend
    } else {
      // non réussie — conservez la recommandation du verdict initial
    }
  },
  onVerdict: function (verdict) {
    // si le visiteur a réussi l’escalade, verdict.is_bot est mis à jour à false
  },
});
```

Remarques :

- L’escalade ne se déclenche que lorsque l’`action` du verdict est `challenge`. Pour toutes
  les autres visites, rien n’est affiché et l’expérience du visiteur reste intacte.
- Par défaut, le SDK utilise les identifiants émis par le backend dans `verdict.escalate`
  (zéro configuration). Utilisez `onChallenge` pour fournir vos propres
  `{ appKey, serverToken }` ou pour ignorer l’escalade, et `challengeConfig` pour contrôler
  son apparence.
- Après une réussite, vérifiez `detail.token` (ainsi que `challenge_id`/`cid`) sur votre
  propre backend — ne vous fiez pas au seul indicateur `passed` côté client.
- Si le visiteur réussit la vérification supplémentaire, le verdict transmis à `onVerdict`
  en tient compte (traité comme humain).
- L’escalade **échoue en mode ouvert** : si la vérification supplémentaire ne peut pas être
  chargée ou affichée, le SDK conserve le verdict initial plutôt que de bloquer votre page.

::: info
La prévention de la fraude ne décide jamais *à votre place*. Même en cas de
`challenge`/`flag`, votre code garde la main sur la décision de laisser la visite se
poursuivre — le SDK ne fait que présenter le verdict et, en option, exécuter la
vérification supplémentaire.
:::

## Résilience

Si le service de verdict est injoignable ou qu’une erreur se produit, le SDK renvoie un
verdict **dégradé** (`degraded: true`) au lieu de faire échouer votre page. Un verdict
dégradé est conservateur (`is_bot: false`, `action: record_only`), de sorte qu’il ne bloque
jamais d’utilisateurs réels. Vérifiez `verdict.degraded` si vous souhaitez traiter ces
visites de manière particulière.

## Étapes suivantes

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