---
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 | Défaut | Description |
| --- | --- | --- | --- |
| `appKey` | string | — | Votre clé d’application de prévention de la fraude (obligatoire). |
| `domain` | string | défaut du service | Point de terminaison du service de verdict. À laisser non défini, sauf si un domaine dédié vous a été fourni. |
| `escalate` | boolean | `false` | Autorise la prévention de la fraude à demander au visiteur **une vérification supplémentaire** lorsqu’une visite paraît à haut risque. Voir [Escalade](#escalade). |
| `collectWindowMs` | number | `1200` | Durée (ms) pendant laquelle le SDK observe la visite avant de demander un verdict. Des fenêtres plus longues produisent un verdict plus fiable au prix d’un léger délai. |
| `onVerdict` | `(v) => void` | — | Appelé une fois avec le verdict final. Le principal point d’intégration. |
| `onError` | `(err) => void` | — | Appelé en cas de problème. Le SDK ne lève jamais d’exception dans votre page. |
| `onEscalate` | `(displayType) => void` | — | Appelé lorsqu’une vérification supplémentaire est affichée (uniquement quand `escalate: true`). |
| `onEscalateDone` | `(passed) => void` | — | Appelé après la fin de la vérification supplémentaire ; `passed` vaut `true` si le visiteur l’a réussie. |

::: 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. C’est une fonctionnalité optionnelle.

Activez-la avec `escalate: true` :

```js
BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  escalate: true,
  onEscalate: function (displayType) {
    // an extra verification is being shown to the visitor
  },
  onEscalateDone: function (passed) {
    if (passed) {
      // visitor cleared the extra check — treat as human
    } else {
      // not cleared — keep the original verdict's recommendation
    }
  },
  onVerdict: function (verdict) {
    // if the visitor cleared escalation, verdict.is_bot is updated to 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.
- 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