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

<!-- 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.

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

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.

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.

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.

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 :

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 — chaque champ et comment agir dessus
• API de données — récupérez et rapprochez les verdicts côté serveur