---
title: Betrugsprävention — Web-SDK
---

# 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

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

```js
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](#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. |

::: tip 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](./scenarios/ad-fraud).
:::

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

```js
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](./verdict-reference).

## 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`:

```js
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](./verdict-reference) — jedes Feld und wie Sie darauf reagieren
- [Daten-API](./data-api) — Urteile serverseitig abrufen und abstimmen