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

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

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