Référence du verdict

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

{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "consistency": { "ok": true },
  "reasons": [],
  "degraded": false,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "verdict_token": "vt1.eyJ2Ijoi...",
  "verdict_token_exp": 1767225600
}

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, flag ou deny. Voir ci-dessous. Traitez toute valeur inconnue comme flag, afin que votre intégration continue de fonctionner si de nouvelles valeurs sont ajoutées.
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 ».
reasons	string[]	Jusqu’à trois catégories de raisons générales expliquant un verdict à risque. Vide pour les visites saines.
verdict_id	string	Identifiant unique de ce verdict. Utilisez-le pour retrouver le verdict plus tard avec l’API de données.
verdict_token	string	Preuve signée de ce verdict, à vérifier par votre serveur. Voir Vérification côté serveur. Absent des verdicts de repli.
verdict_token_exp	number	Heure Unix (secondes) à laquelle verdict_token expire.

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 a atteint votre seuil de vérification (risque élevé par défaut).	Demandez une vérification supplémentaire avant de traiter le visiteur comme humain. Lorsque l’action de traitement de votre application est réglée sur challenge, le SDK Web l’exécute pour vous (voir Escalade) ; sinon, appliquez votre propre filtre.
deny	La visite correspond à une règle de blocage — par exemple une entrée de liste de blocage ou une politique que vous avez configurée pour bloquer.	Ne servez pas le contenu protégé. Aucun challenge n’est proposé. Les anciennes versions du SDK transmettent cette valeur telle quelle ; gérez-la donc dans onVerdict.

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.

Seuil et type de vérification

Lorsque l'action est challenge, deux réglages supplémentaires apparaissent dans la même section du tableau de bord :

• Seuil de vérification — le niveau de risque à partir duquel l'action configurée est renvoyée. Par défaut : risque élevé et plus. Le mode strict l'applique aussi aux visites à risque moyen : davantage de scrapers et d'agents IA sont bloqués, mais davantage de vrais visiteurs voient une vérification.
• Type de vérification — le type de CAPTCHA minimal affiché lors d'une escalade : curseur (par défaut), rotation, clic ou clic 3D. Plus le type est fort, plus il est difficile à résoudre pour les outils automatisés et l'IA.

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

reasons — catégories de raisons

reasons indique, en termes généraux, pourquoi une visite a paru risquée. Il contient au plus trois catégories, de la plus forte à la plus faible. Il ne contient jamais de signaux individuels ni de décomposition du score.

Catégorie	Signification
automation	Indices d’outillage automatisé, comme des navigateurs scriptés ou headless.
network	Le réseau paraît risqué ou incohérent, comme un proxy, un réseau de centre de données ou d’anonymisation, ou une adresse bloquée.
abnormal_requests	Schémas de requêtes inhabituels, comme trop de requêtes, des échecs répétés ou un historique de trafic automatisé.
device	L’appareil ou son environnement n’a pas pu être jugé fiable, ou n’a pas pu être reconnu.
behavior	La visite ne s’est pas comportée comme une personne, par exemple aucune interaction ou un lien réutilisé.
other	Toute autre raison, y compris vos propres règles et les verdicts de repli.

Considérez cette liste comme une explication pour le reporting, et non comme un signal sur lequel bâtir des règles. Branchez-vous plutôt sur is_bot, action ou score. De nouvelles catégories pourront être ajoutées.

Vérification côté serveur

Tout ce que la page reçoit peut être modifié par le visiteur. Si vous protégez du contenu (seules de vraies personnes peuvent voir une page, une réponse d’API ou un téléchargement), ne vous fiez pas à l’indicateur is_bot dans le navigateur. Envoyez verdict_token à votre propre serveur et vérifiez-le là-bas :

1. Dans onVerdict, envoyez verdict.verdict_token à votre backend, par exemple dans un en-tête ou un cookie.
2. Votre backend appelle POST /v1/bot/verdict/verify avec le jeton et l’adresse IP du visiteur.
3. Ne servez le contenu que si la réponse contient valid: true et que le verdict vous convient (par exemple verdict.is_bot vaut false).

Le jeton est lié à votre application, à ce verdict et au réseau du visiteur, et expire après peu de temps (10 minutes par défaut). Par défaut, un jeton peut être vérifié plusieurs fois, de sorte qu’un seul jeton peut couvrir les pages vues d’une visite. Passez consume: true lorsqu’un jeton ne doit être utilisé qu’une fois, par exemple pour une soumission de formulaire.

Si le visiteur réussit ensuite un challenge d’escalade, le jeton indique toujours le verdict d’origine. Vérifiez également le jeton de réussite du captcha issu de escalate_result avec l’API côté serveur du captcha.

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.

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 — recevez les verdicts sur votre page
• API de données — récupérez les verdicts et les statistiques côté serveur