Betrugsprävention Web-SDK

Das Betrugsprävention Web-SDK läuft auf Ihrer Seite — einer Landingpage, einem Anmelde- oder Login-Bildschirm oder jeder geschützten Ressource. Es fordert ein Urteil für den aktuellen Besuch an und gibt es an Ihren Code zurück, damit Sie entscheiden können, was mit dem Datenverkehr geschehen soll — ihn aufzeichnen, markieren oder den Besucher um eine zusätzliche Verifizierung bitten.

Schnellstart

<!-- 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() gibt außerdem ein Promise<BotVerdict> zurück, sodass Sie es auch mit await verwenden können, statt onVerdict zu nutzen — beide erhalten dasselbe Urteilsobjekt.

const verdict = await BotSignal.init({ appKey: 'YOUR_APP_KEY' });

Optionen

Option	Typ	Standard	Beschreibung
appKey	string	—	Ihr Betrugsprävention-Anwendungsschlüssel (erforderlich).
domain	string	Service-Standard	Endpunkt des Urteilsdienstes. Lassen Sie ihn unbesetzt, sofern Ihnen keine dedizierte Domain zugewiesen wurde.
escalate	boolean	false	Erlaubt der Betrugsprävention, den Besucher um eine zusätzliche Verifizierung zu bitten, wenn ein Besuch hochriskant aussieht. Siehe Eskalation.
collectWindowMs	number	1200	Wie lange (ms) das SDK den Besuch beobachtet, bevor es ein Urteil anfordert. Längere Fenster liefern ein zuverlässigeres Urteil auf Kosten einer kleinen Verzögerung.
onVerdict	(v) => void	—	Wird einmal mit dem endgültigen Urteil aufgerufen. Der primäre Integrationspunkt.
onError	(err) => void	—	Wird aufgerufen, wenn etwas schiefgeht. Das SDK wirft niemals eine Ausnahme in Ihre Seite.
onEscalate	(displayType) => void	—	Wird aufgerufen, wenn eine zusätzliche Verifizierung angezeigt wird (nur bei escalate: true).
onEscalateDone	(passed) => void	—	Wird aufgerufen, nachdem die zusätzliche Verifizierung abgeschlossen ist; passed ist true, wenn der Besucher sie bestanden hat.

Szenarien mit Datenverkehrsquellen

Wenn ein Dritter Besucher zu Ihnen liefert und beide Seiten sich auf ein per-Klick gefälltes Fazit abstimmen müssen, kann das SDK auch ein Click-Token aus der Seiten-URL lesen. Das ist spezifisch für Flüsse mit bezahltem Datenverkehr — siehe den Leitfaden Anzeigenbetrug.

Das Urteil verwenden

onVerdict erhält ein BotVerdict-Objekt. Die beiden Felder, die Sie am meisten nutzen werden:

• verdict.is_bot — true, wenn der Besuch als automatisiert/ungültig beurteilt wird.
• verdict.action — was wir Ihnen empfehlen zu tun: record_only, challenge oder 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;
    }
  },
});

Die vollständige Feldliste und empfohlene Behandlung finden Sie in der Verdict-Referenz.

Eskalation

Wenn ein Besuch hochriskant aussieht, kann Betrugsprävention den Besucher bitten, eine zusätzliche Verifizierung abzuschließen, bevor Sie ihn als echten Nutzer behandeln. Dies ist optional (Opt-in).

Aktivieren Sie sie mit 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
  },
});

Hinweise:

• Eskalation wird nur ausgelöst, wenn die action des Urteils challenge ist. Bei allen anderen Besuchen wird nichts angezeigt und das Besuchererlebnis bleibt unberührt.
• Wenn der Besucher die zusätzliche Verifizierung besteht, spiegelt das an onVerdict gelieferte Urteil dies wider (als Mensch behandelt).
• Eskalation fällt offen aus (fail open): Wenn die zusätzliche Verifizierung nicht geladen oder angezeigt werden kann, behält das SDK das ursprüngliche Urteil bei, statt Ihre Seite zu blockieren.

INFO

Betrugsprävention entscheidet niemals für Sie. Selbst bei challenge/flag bleibt Ihr Code in Kontrolle darüber, ob der Besuch fortgesetzt wird — das SDK legt nur das Urteil offen und führt optional die zusätzliche Verifizierung durch.

Robustheit

Wenn der Urteilsdienst nicht erreichbar ist oder ein Fehler auftritt, gibt das SDK ein herabgestuftes Urteil (degraded: true) zurück, statt Ihre Seite scheitern zu lassen. Ein herabgestuftes Urteil ist konservativ (is_bot: false, action: record_only), sodass es niemals echte Nutzer blockiert. Prüfen Sie verdict.degraded, wenn Sie diese Besuche besonders behandeln möchten.

Nächste Schritte

• Verdict-Referenz — jedes Feld und wie Sie darauf reagieren
• Daten-API — Urteile serverseitig abrufen und abstimmen