Verdict-Referenz

Jedes Betrugsprävention-Urteil — ob an Ihren onVerdict-Callback im Web-SDK geliefert oder aus der Daten-API abgerufen — ist dasselbe BotVerdict-Objekt. Diese Seite dokumentiert jedes Feld und wie Sie darauf reagieren.

{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "reasons": [],
  "consistency": { "ok": true },
  "degraded": false,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "verdict_token": "vt1.eyJ2Ijoi...",
  "verdict_token_exp": 1767225600
}

Felder

Feld	Typ	Beschreibung
is_bot	boolean	Das Haupturteil. true = der Besuch wird als automatisierter oder ungültiger Datenverkehr beurteilt; false = er sieht nach einer echten Person aus. Dies ist das eine Feld, auf das die meisten Integrationen verzweigen.
score	number (0–100)	Wie verdächtig der Besuch ist. Höher bedeutet verdächtiger. Nutzen Sie ihn, um Ihre eigenen Schwellenwerte zu setzen — z. B. Besuche oberhalb einer von Ihnen gewählten Grenze auszuschließen. Der genaue Wert wird von unserem Risikomodell erzeugt und ist nicht dafür gedacht, rückentwickelt zu werden.
level	enum	Grobe Einstufung des score: low, medium, high, critical. Praktisch, wenn Sie Kategorien statt einer Rohzahl möchten.
action	enum	Unsere empfohlene Behandlung für den Besuch: record_only, challenge, flag oder deny. Siehe unten. Behandeln Sie unbekannte Werte als flag, damit Ihre Integration weiter funktioniert, wenn neue Werte hinzukommen.
reasons	string[]	Bis zu drei grobe Ursachenkategorien, die ein riskantes Urteil erklären. Leer bei sauberen Besuchen.
consistency	object	Ein signalübergreifendes Konsistenzfazit. Lesen Sie consistency.ok (boolean): true = die Signale des Besuchs passen wie erwartet zusammen; false = etwas ergab keinen Sinn und der Besuch verdient zusätzliche Prüfung. Die interne Aufschlüsselung hinter diesem Fazit wird nicht offengelegt.
degraded	boolean	true, wenn das Urteil nicht vollständig berechnet werden konnte (Dienst nicht erreichbar, Fehler usw.) und ein konservativer Fallback zurückgegeben wurde. Behandeln Sie herabgestufte Urteile als „unbekannt", nicht als „sauber".
verdict_id	string	Eindeutige ID dieses Urteils. Damit können Sie das Urteil später über die Daten-API abrufen.
verdict_token	string	Signierter Nachweis dieses Urteils, den Ihr Server verifiziert. Siehe Serverseitige Verifizierung. Fehlt bei Fallback-Urteilen.
verdict_token_exp	number	Unix-Zeit (Sekunden), zu der verdict_token abläuft.

action — was zu tun ist

action ist unsere Empfehlung; Sie behalten die Kontrolle über die endgültige Entscheidung.

action	Bedeutung	Was zu tun ist
record_only	Der Besuch sieht normal aus.	Fahren Sie wie gewohnt fort. Protokollieren Sie nur das Urteil für Reporting und Abstimmung.
flag	Der Besuch ist verdächtig, aber nicht eindeutig schlecht.	Liefern Sie die Seite weiter aus, markieren Sie den Besuch aber als geringe Qualität — schließen Sie ihn aus Ihren Kennzahlen aus, segmentieren Sie ihn aus nachgelagerten Flüssen heraus und gewichten Sie ihn in Ihren eigenen Entscheidungen (z. B. Conversion-Attribution oder wie sehr Sie dem Besuch vertrauen).
challenge	Der Besuch hat Ihre Challenge-Schwelle erreicht (standardmäßig hohes Risiko).	Bitten Sie um eine zusätzliche Verifizierung, bevor Sie den Besucher als Mensch behandeln. Ist die Behandlungsaktion Ihrer App auf challenge gesetzt, führt das Web-SDK das für Sie aus (siehe Eskalation); andernfalls wenden Sie Ihre eigene Sperre an.
deny	Der Besuch hat eine Sperrregel getroffen — zum Beispiel einen Blocklisten-Eintrag oder eine von Ihnen auf Blockieren konfigurierte Richtlinie.	Liefern Sie keine geschützten Inhalte aus. Es wird keine Challenge angeboten. Ältere SDK-Versionen reichen diesen Wert unverändert durch, behandeln Sie ihn also in onVerdict.

Konfigurierbare Behandlungsaktion

Was action für einen hochriskanten Besuch meldet, ist pro-App-Konfiguration, festgelegt im Dashboard unter den Details Ihrer Anwendung. Das Urteil ist serverautoritativ: action wird nur dann zu challenge oder flag, wenn der Besuch die Hochrisiko-Stufe erreicht und Ihre App mit der entsprechenden Aktion konfiguriert ist. Unterhalb dieser Stufe bleibt das Urteil record_only.

Einstellung	Bei hohem Risiko zurückgegebene action	Bedeutung
record_only (Standard)	record_only	Nur aufzeichnen. Das Urteil wird für Reporting und Abstimmung protokolliert; vom Besucher wird nichts verlangt.
challenge	challenge	Löst ein Re-Verifizierungs-CAPTCHA aus. Das Web-SDK zeigt eine Challenge an (das Styling wird über challengeConfig des SDK gesteuert).
flag	flag	Markiert den Besuch. Das Urteil trägt flag; Ihre Integration entscheidet, wie darauf reagiert wird (blockieren / segmentieren / behandeln).

Da die Entscheidung serverseitig getroffen wird, bleibt Ihr Code einfach: Lesen Sie verdict.action in onVerdict und reagieren Sie darauf — fortfahren, blockieren oder das SDK eine Challenge anzeigen lassen. Sie müssen das Risiko nicht selbst neu ableiten.

Challenge-Schwelle und -Typ

Ist die Aktion challenge, erscheinen im selben Dashboard-Bereich zwei weitere Einstellungen:

• Challenge-Schwelle – ab welcher Risikostufe die konfigurierte Aktion zurückgegeben wird. Standard ist hohes Risiko und höher. Der strenge Modus wendet sie auch auf Besuche mit mittlerem Risiko an: Mehr Scraper und KI-Agenten werden gestoppt, aber auch mehr echte Besucher sehen eine Challenge.
• Challenge-Typ – der Mindest-CAPTCHA-Typ bei einer Eskalation: Schieberegler (Standard), Drehen, Klicken oder 3D-Klick. Stärkere Typen sind für Automatisierungs- und KI-Tools schwerer zu lösen.

escalate_result

Vorhanden, nachdem eine verwaltete Captcha-Eskalation gelaufen ist — d. h. wenn action den Wert challenge hatte und das SDK das Captcha ausgeführt hat. null, wenn keine Eskalation lief. Wird außerdem an onEscalateDone(passed, detail) übergeben.

Feld	Beschreibung
passed	ob der Besucher das Captcha bestanden hat
token	das Captcha-Pass-Token — prüfe es serverseitig, um das Bestehen zu bestätigen (verlasse dich nicht allein auf das clientseitige passed)
challenge_id	die Captcha-Challenge-ID
cid	die Click-ID, an die diese Eskalation gebunden ist, sofern ein Click-Token vorhanden war

reasons — Ursachenkategorien

reasons sagt Ihnen in groben Zügen, warum ein Besuch riskant wirkte. Es enthält höchstens drei Kategorien, die stärkste zuerst. Es enthält nie einzelne Signale oder Score-Aufschlüsselungen.

Kategorie	Bedeutung
automation	Anzeichen für automatisierte Werkzeuge, etwa skriptgesteuerte oder Headless-Browser.
network	Das Netzwerk wirkt riskant oder inkonsistent, etwa ein Proxy, ein Rechenzentrums- oder Anonymisierungsnetzwerk oder eine gesperrte Adresse.
abnormal_requests	Ungewöhnliche Anfragemuster, etwa zu viele Anfragen, wiederholte Fehlschläge oder eine Historie automatisierten Datenverkehrs.
device	Dem Gerät oder seiner Umgebung konnte nicht vertraut werden, oder es konnte nicht erkannt werden.
behavior	Der Besuch verhielt sich nicht wie eine Person, zum Beispiel gar keine Interaktion oder ein wiederverwendeter Link.
other	Jeder andere Grund, einschließlich Ihrer eigenen Regeln und Fallback-Urteile.

Behandeln Sie die Liste als Erklärung für das Reporting, nicht als Signal, auf dem Sie Regeln aufbauen. Verzweigen Sie stattdessen auf is_bot, action oder score. Später können neue Kategorien hinzukommen.

Serverseitige Verifizierung

Alles, was die Seite erhält, kann vom Besucher verändert werden. Wenn Sie Inhalte schützen (nur echte Personen dürfen eine Seite, eine API-Antwort oder einen Download sehen), vertrauen Sie nicht dem is_bot-Flag im Browser. Senden Sie verdict_token an Ihren eigenen Server und verifizieren Sie es dort:

1. Senden Sie in onVerdict verdict.verdict_token an Ihr Backend, zum Beispiel in einem Header oder Cookie.
2. Ihr Backend ruft POST /v1/bot/verdict/verify mit dem Token und der IP-Adresse des Besuchers auf.
3. Liefern Sie den Inhalt nur aus, wenn die Antwort valid: true enthält und das Urteil für Sie akzeptabel ist (zum Beispiel verdict.is_bot ist false).

Das Token ist an Ihre App, an dieses Urteil und an das Netzwerk des Besuchers gebunden und läuft nach kurzer Zeit ab (standardmäßig 10 Minuten). Standardmäßig kann ein Token mehrfach geprüft werden, sodass ein Token die Seitenaufrufe eines Besuchs abdecken kann. Übergeben Sie consume: true, wenn ein Token nur einmal verwendet werden darf, etwa bei einem Formularversand.

Besteht der Besucher anschließend eine Eskalations-Challenge, zeigt das Token weiterhin das ursprüngliche Urteil. Verifizieren Sie zusätzlich das Captcha-Pass-Token aus escalate_result mit der serverseitigen Captcha-API.

level vs. score

level ist nur eine Einstufung des score, bereitgestellt zur Bequemlichkeit:

level	Nutzen Sie es, wenn
low	Als sauberen Datenverkehr behandeln.
medium	Grenzwertig — in Ordnung aufzuzeichnen, erwägen Sie den Ausschluss aus hochwertigen Funnels.
high	Stark verdächtig — markieren und ausschließen.
critical	Fast sicher ungültig — markieren/ausschließen und idealerweise eskalieren.

Wählen Sie das Feld, das zu Ihrer Pipeline passt

• Einfache Ja/Nein-Sperre → auf is_bot verzweigen.
• Empfehlungsgesteuert → auf action verzweigen.
• Eigene Schwellenwerte → auf score verzweigen (oder level für Kategorien).

Umgang mit herabgestuften Urteilen

Wenn degraded true ist, wurde das Urteil nicht vollständig berechnet. Der Fallback ist bewusst konservativ (is_bot: false, action: record_only), sodass echte Nutzer niemals blockiert werden. Behandeln Sie diese für das Reporting als unbekannt, statt sie als bestätigt-sauberen Datenverkehr zu zählen.

Nächste Schritte

• Web-SDK — Urteile auf Ihrer Seite empfangen
• Daten-API — Urteile und Statistiken serverseitig abrufen