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	type	default	Beschreibung
appKey	string	—	Erforderlich. Ihr Betrugsprävention-Anwendungsschlüssel.
domain	string	signal-v1.world-dynamic.com	Signal-Domain, an die das SDK sendet.
tokenParam	string	_ctk	URL-Query-Parameter, aus dem das SDK das Click-Token liest.
onVerdict	(v) => void	—	Wird einmal mit dem endgültigen Urteil aufgerufen. Der primäre Integrationspunkt. init() gibt außerdem ein Promise<BotVerdict> zurück.
onError	(err) => void	—	Wird bei jedem Fehler aufgerufen. Das SDK wirft niemals eine Ausnahme in Ihre Seite.
onChallenge	(v) => creds | null | Promise<…>	—	Überschreibt die Eskalations-Anmeldedaten: Geben Sie Ihre eigenen { appKey, serverToken } zurück (serverToken wird von Ihrem Backend ausgestellt) oder null, um die Eskalation zu überspringen. Ohne Angabe werden die vom Backend ausgestellten Standard-Anmeldedaten in verdict.escalate verwendet (zero-config).
challengeConfig	object	—	Captcha-Darstellung/Platzierung: product (popup/float/embed), container, theme, lang.
onEscalate	(displayType) => void	—	Wird aufgerufen, wenn ein Eskalations-Captcha angezeigt wird.
onEscalateDone	(passed, detail) => void	—	Wird nach der Eskalation aufgerufen. passed = der Besucher hat sie bestanden; detail = { token, challengeId, cid } für die serverseitige Verifizierung des Bestehens.

Die Eskalation wird serverseitig gesteuert. Das SDK zeigt nur dann ein Captcha an, wenn die action des Server-Urteils challenge lautet und die App mit einer passenden Eskalations-Aktion konfiguriert ist — es gibt dafür keinen clientseitigen Schalter. Verwenden Sie onChallenge, um eigene Anmeldedaten bereitzustellen oder die Eskalation zu überspringen, und challengeConfig, um deren Darstellung zu steuern. Nachdem ein Besucher bestanden hat, verifizieren Sie das Ergebnis auf Ihrem eigenen Backend mit detail.token (zusammen mit challenge_id/cid) — verlassen Sie sich nicht allein auf das clientseitige passed-Flag.

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 wird vom Server-Urteil gesteuert, nicht von einem clientseitigen Flag — es läuft, sobald die action des Urteils challenge lautet und für die App eine Eskalations-Aktion konfiguriert ist.

BotSignal.init({
  appKey: 'YOUR_APP_KEY',
  onEscalate: function (displayType) {
    // dem Besucher wird eine zusätzliche Verifizierung angezeigt
  },
  onEscalateDone: function (passed, detail) {
    if (passed) {
      // Besucher hat die zusätzliche Prüfung bestanden — detail.token auf Ihrem Backend verifizieren
    } else {
      // nicht bestanden — die Empfehlung des ursprünglichen Urteils beibehalten
    }
  },
  onVerdict: function (verdict) {
    // wenn der Besucher die Eskalation bestanden hat, wird verdict.is_bot auf false aktualisiert
  },
});

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.
• Standardmäßig verwendet das SDK die vom Backend ausgestellten Anmeldedaten in verdict.escalate (zero-config). Verwenden Sie onChallenge, um eigene { appKey, serverToken } bereitzustellen oder die Eskalation zu überspringen, und challengeConfig, um deren Darstellung zu steuern.
• Verifizieren Sie nach dem Bestehen detail.token (zusammen mit challenge_id/cid) auf Ihrem eigenen Backend — verlassen Sie sich nicht allein auf das clientseitige passed-Flag.
• 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