---
title: Prévention de la fraude — Référence du verdict
---

# Référence du verdict

Chaque verdict de prévention de la fraude — qu’il soit transmis à votre rappel `onVerdict`
dans le [SDK Web](./web-sdk) ou récupéré depuis l’[API de données](./data-api) — est le
même objet `BotVerdict`. Cette page documente chaque champ et la manière d’agir dessus.

```json
{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "consistency": { "ok": true },
  "degraded": false
}
```

## Champs

| Champ | Type | Description |
| --- | --- | --- |
| `is_bot` | boolean | Le verdict principal. `true` = la visite est jugée comme du trafic automatisé ou invalide ; `false` = elle ressemble à une personne réelle. C’est le champ sur lequel se branchent la plupart des intégrations. |
| `score` | number (0–100) | À quel point la visite est suspecte. **Plus la valeur est élevée, plus elle est suspecte.** Utilisez-le pour définir vos propres seuils — par exemple, exclure les visites au-dessus d’un seuil de votre choix. La valeur exacte est produite par notre modèle de risque et n’est pas destinée à être rétro-conçue. |
| `level` | enum | Bande grossière du `score` : `low`, `medium`, `high`, `critical`. Pratique lorsque vous voulez des paliers plutôt qu’une valeur brute. |
| `action` | enum | Notre **traitement recommandé** pour la visite : `record_only`, `challenge` ou `flag`. Voir ci-dessous. |
| `consistency` | object | Une conclusion de cohérence inter-signaux. Lisez `consistency.ok` (boolean) : `true` = les signaux de la visite concordent comme prévu ; `false` = quelque chose ne correspond pas et la visite mérite un examen supplémentaire. Le détail interne derrière cette conclusion n’est pas exposé. |
| `degraded` | boolean | `true` lorsque le verdict n’a pas pu être entièrement calculé (service injoignable, erreur, etc.) et qu’un repli conservateur a été renvoyé. Traitez les verdicts dégradés comme « inconnus », pas comme « sains ». |

## `action` — que faire

`action` est notre recommandation ; vous gardez la main sur la décision finale.

| `action` | Signification | Que faire |
| --- | --- | --- |
| `record_only` | La visite paraît normale. | Continuez comme d’habitude. Enregistrez simplement le verdict pour le reporting et le rapprochement. |
| `flag` | La visite est suspecte mais pas définitivement mauvaise. | Continuez à servir la page, mais marquez la visite comme de faible qualité — excluez-la de vos métriques, retirez-la des flux en aval et pondérez-la dans vos propres décisions (par ex. attribution des conversions ou degré de confiance accordé à la visite). |
| `challenge` | La visite est à haut risque. | Demandez une vérification supplémentaire avant de traiter le visiteur comme humain. Avec l’option `escalate: true` du SDK Web, cela est pris en charge pour vous (voir [Escalade](./web-sdk#escalade)) ; sinon, appliquez votre propre filtre. |

## Action de traitement configurable

Ce que `action` rapporte pour une visite à **haut risque** relève de la **configuration par
application**, définie dans le tableau de bord, dans les détails de votre application. Le
verdict fait **autorité côté serveur** : `action` ne devient `challenge` ou `flag` que
lorsque la visite atteint la bande de haut risque **et** que votre application est configurée
avec l’action correspondante. En dessous de cette bande, le verdict reste `record_only`.

| Réglage | `action` renvoyée à haut risque | Signification |
| --- | --- | --- |
| `record_only` (défaut) | `record_only` | Enregistrement seul. Le verdict est journalisé pour le reporting et le rapprochement ; rien n’est demandé au visiteur. |
| `challenge` | `challenge` | Déclenche un CAPTCHA de re-vérification. Le SDK Web affiche un challenge (le style est contrôlé par le `challengeConfig` du SDK). |
| `flag` | `flag` | Marque la visite. Le verdict porte `flag` ; votre intégration décide comment agir dessus (bloquer / segmenter / traiter). |

Comme la décision est prise côté serveur, votre code reste simple : lisez `verdict.action`
dans `onVerdict` et agissez en conséquence — continuer, bloquer ou laisser le SDK présenter
un challenge. Vous n’avez pas besoin de redériver le risque vous-même.

### `escalate_result`

Présent après l'exécution d'une escalade de captcha gérée — c'est-à-dire lorsque `action` valait `challenge` et que le SDK a lancé le captcha. `null` si aucune escalade n'a eu lieu. Également transmis à `onEscalateDone(passed, detail)`.

| champ | description |
|---|---|
| `passed` | si le visiteur a réussi le captcha |
| `token` | le pass token du captcha — **vérifiez-le côté serveur** pour confirmer la réussite (ne vous fiez pas au seul `passed` côté client) |
| `challenge_id` | l'id du challenge captcha |
| `cid` | l'id de clic auquel cette escalade est rattachée, si un click token était présent |

## `level` vs `score`

`level` n’est qu’un découpage du `score` en bandes, fourni pour plus de commodité :

| `level` | À utiliser quand |
| --- | --- |
| `low` | À traiter comme du trafic sain. |
| `medium` | Limite — acceptable à enregistrer, envisagez d’exclure des entonnoirs à forte valeur. |
| `high` | Fortement suspect — à signaler et exclure. |
| `critical` | Presque certainement invalide — à signaler/exclure et, idéalement, escalader. |

::: tip Choisissez le champ adapté à votre pipeline
- Filtre oui/non simple → branchez-vous sur **`is_bot`**.
- Piloté par la recommandation → branchez-vous sur **`action`**.
- Seuils personnalisés → branchez-vous sur **`score`** (ou **`level`** pour des paliers).
:::

## Traiter les verdicts dégradés

Lorsque `degraded` vaut `true`, le verdict n’a pas été entièrement calculé. Le repli est
délibérément conservateur (`is_bot: false`, `action: record_only`), de sorte que les
utilisateurs réels ne sont jamais bloqués. Pour le reporting, traitez-les comme
**inconnus** plutôt que de les compter comme du trafic confirmé sain.

## Étapes suivantes

- [SDK Web](./web-sdk) — recevez les verdicts sur votre page
- [API de données](./data-api) — récupérez les verdicts et les statistiques côté serveur