Eine Registrierungsprüfung auswerten

Nutzen Sie die äußere action der Antwort, um über den weiteren Registrierungsablauf zu entscheiden. Auch eine zustellbare E-Mail-Adresse kann wegen der Besuchssignale eine Bestätigung benötigen. Ein Signal, das eine Bestätigung verlangt, stellt nicht fest, dass der Besuch von einem Bot stammt.

Die folgenden Beispiele zeigen die kombinierte Antwort von POST /v1/signup-checks. Es sind fiktive, gekürzte Darstellungen ausgewählter Felder. Sie sind weder vollständige API-Antworten noch Messungen realer Besuche.

Die Antwort in dieser Reihenfolge lesen

1. Lesen Sie die äußere action: allow, allow_with_email_confirmation oder reject. Diese Empfehlung berücksichtigt beide Teile der Prüfung.
2. Lesen Sie email.action und email.status, um die E-Mail-Entscheidung zu verstehen. Die reason_codes der E-Mail erklären ihre Belege und Grenzen.
3. Lesen Sie signals.status. Der Wert zeigt, ob Besuchssignale ausgewertet wurden, der Token unbrauchbar war oder der Dienst nicht verfügbar war.
4. Prüfen Sie in signals.findings und signal_codes, welche Befunde eine Bestätigung verlangt haben. Gegebenenfalls zeigen not_evaluated und not_evaluated_classes, welche Vergleiche nicht möglich waren.

Diese Felder beantworten unterschiedliche Fragen. evaluated beschreibt den Zustand der Signalauswertung. Es bestätigt keine erfolgreiche Registrierung. Eine leere Liste signal_codes bedeutet, dass kein Befund die Empfehlung verschärft hat. Sie belegt weder, dass jeder Vergleich ausgeführt wurde, noch einen sicheren Besuch.

Verwenden Sie stattdessen POST /v1/signup-signals, enthält die Antwort keinen E-Mail-Teil. Ihre action ist die reine Signalempfehlung, mit derselben Grundlage wie bei einer E-Mail-Aktion allow. Sie ersetzt die E-Mail-Regeln an anderer Stelle nicht.

Auch eine zustellbare E-Mail kann eine Bestätigung benötigen

In diesem Beispiel erlaubt das E-Mail-Ergebnis die Registrierung. Derselbe Token wurde in einem neuen Vorgang vorgelegt. Deshalb verlangt ein Signal eine Bestätigung:

{
  "action": "allow_with_email_confirmation",
  "signal_codes": ["fp_token_reused"],
  "email": {"status": "deliverable", "action": "allow"},
  "signals": {
    "status": "evaluated",
    "findings": [
      {"code": "fp_token_reused", "class": "token", "default_raises": true}
    ]
  }
}

Wer nur email.action liest, übersieht die erforderliche Bestätigung. Die äußere action berücksichtigt sie. Der Befund dokumentiert die Tokenwiederverwendung. Er stellt weder deren Grund noch die Identität der Person fest, die die Anfrage gesendet hat.

Ihre Anwendung setzt allow_with_email_confirmation um: Sie sendet eine Bestätigungsnachricht und prüft deren Link oder Code, bevor sie Zugang gewährt, der Postfachkontrolle voraussetzt. Die E-Mail-Verifizierung von Emvero sendet keine Nachricht an die geprüfte Adresse. Hier ist die Unterscheidung zwischen E-Mail-Verifizierung und E-Mail-Bestätigung entscheidend. Die Bestätigung belegt den Zugriff auf ein Postfach, keine eindeutige menschliche Identität.

Signale können eine E-Mail-Entscheidung von allow auf allow_with_email_confirmation anheben. Sie können weder reject auslösen noch eine E-Mail-Ablehnung abschwächen oder eine bestehende Bestätigungspflicht aufheben. Lautet die äußere Aktion reject, beruht sie auf der E-Mail-Entscheidung.

Die Belege finden, die die Aktion verändert haben

signals.findings enthält die gemeldeten Befunde. Das Feld default_raises eines Befunds zeigt, ob er nach den Standardregeln von Emvero eine Bestätigung verlangt. Die oberste Liste signal_codes enthält die Codes der Befunde mit default_raises: true, in der zurückgegebenen Reihenfolge und ohne Duplikate.

Ein Befund kann also erscheinen, ohne die Aktion zu ändern. Dieses VPN-Beispiel behält die E-Mail-Entscheidung bei:

{
  "action": "allow",
  "signal_codes": [],
  "email": {"status": "deliverable", "action": "allow"},
  "signals": {
    "status": "evaluated",
    "findings": [
      {"code": "fp_network_vpn", "class": "identity", "default_raises": false}
    ]
  }
}

fp_network_vpn meldet eine Netzwerkbeobachtung. Mit default_raises: false verlangt dieser Befund allein keine Bestätigung. VPN-, Tor-, Proxy- und Hosting-Befunde sind standardmäßig informativ. Eine Netzwerkkennzeichnung belegt keinen Missbrauch. Lesen Sie den zurückgegebenen Wert, statt die Wirkung aus dem Codenamen abzuleiten. Die Signalcode-Referenz definiert das Vokabular.

Die reason_codes der E-Mail bleiben innerhalb von email. Sie erklären E-Mail-Belege und werden nicht zu Signalcodes. Der Artikel zum E-Mail-Ergebnis beschreibt diesen Teil ausführlich. Halten Sie beide Codelisten getrennt, wenn Sie ein Ergebnis anzeigen oder eine Registrierung untersuchen.

signal_codes kann auch dann Einträge enthalten, wenn die E-Mail bereits eine Bestätigung oder Ablehnung verlangt. Die Liste erfasst die Signale, die ihren Teil der Empfehlung verschärft haben. Sie besagt nicht, dass Signale die einzige Ursache der endgültigen Aktion waren.

Browserbefunde und Hinweise haben unterschiedliche Aufgaben

signals.probe meldet, ob die Browserprüfung gelesen wurde und welche ihrer Prüfungen möglich waren. fp_probe_forged und fp_probe_automation haben default_raises: true und können eine E-Mail-Bestätigung verlangen. fp_probe_tampering ist informativ, weil auch Browsererweiterungen und Seitencode native Eigenschaften verändern können.

Das separate Array signals.notes enthält rtt_extra_leg, webtransport, ua_brand, bot_claim und bot_operator. notes_version bezeichnet das Vokabular; aktuell ist Version 2. Hinweise gelangen nicht in signal_codes und ändern die Standardaktion nicht. Ein nicht verfügbarer Hinweis oder eine fehlende Browserprüfung begrenzt die Belege. Das bedeutet weder einen fehlerhaften Token noch einen Ausfall des Signaldiensts. Jeder Hinweis enthält value, rules_version und group. Ihre Anwendung kann Hinweise mit ihrer eigenen Historie berücksichtigen. Beobachtungen derselben Gruppe können eine gemeinsame Ursache beschreiben und sollten nicht als unabhängige Beweise behandelt werden.

bot_claim meldet einen angegebenen Crawler aus dem Netz seines Betreibers (crawler_verified), eine solche Angabe außerhalb dieses Netzes (crawler_unverified), einen Crawler ohne unterstützte Betreiberprüfung (crawler_unchecked), ein angegebenes Werkzeug (tool) oder keine solche Angabe (none). bot_operator nennt den Betreiber des angegebenen Crawlers. unavailable bedeutet, dass der Hinweis nicht ausgewertet werden konnte. none belegt keinen menschlichen Besuch. Auch crawler_unverified ist rein informativ. Wiederholte Besuche werden nicht gezählt; eine Erkennung von Farm-Clustern und ein verschärfendes Signal für angegebene Werkzeuge stehen derzeit nicht zur Verfügung.

Eine fehlende Browserprüfung kann fp_probe_not_evaluated erzeugen, während der Token gültig bleibt und signals.status den Wert evaluated hat. Dieser Vorgang kostet weiterhin fünf Signal-Credits. Der Hinweiswert unavailable oder unknown begrenzt die Aussage des Hinweises. Er bedeutet nicht, dass der gesamte Signaldienst ausgefallen war. Die Signalcode-Referenz erklärt die neuen Befunde und das Hinweisvokabular.

Kombinierte Ergebnisse vergleichen

Diese zehn fiktiven Fälle nutzen denselben Ergebnisvertrag. Der gewöhnliche Fall enthält keine gemeldeten Befunde. Der VPN-Fall enthält einen informativen Befund, aber keinen verschärfenden Code.

Die beiden allow-Ergebnisse bei ausgewerteten und nicht verfügbaren Signalen haben unterschiedliche Aussagekraft. Im gewöhnlichen Fall wurden Signale ausgewertet, ohne die Aktion zu verschärfen. Im nicht verfügbaren Fall gab es keine abgeschlossene Signalauswertung. Allein die E-Mail bestimmte die Empfehlung.

Unbrauchbaren Token und nicht verfügbare Signale unterscheiden

Ein fehlender Token erzeugt signals.status: token_unusable mit fp_token_absent in signal_codes. Ein abgelaufener Token erzeugt ebenfalls token_unusable, mit fp_token_expired. Diese Befunde verlangen eine Bestätigung, wenn die E-Mail die Registrierung sonst erlauben würde. Sie verlangen nicht, den Besuch als missbräuchlich zu behandeln. Ein blockiertes Skript oder ein lange geöffnetes Formular kann auch bei einem gewöhnlichen Besuch dazu führen, dass kein nutzbarer Token vorliegt.

Kann der Signaldienst die Anfrage nicht auswerten, kann der kombinierte Endpunkt HTTP 200 mit signals.status: unavailable liefern. In diesem Fall enthält das Objekt signals nur den Status:

{
  "action": "allow",
  "signal_codes": [],
  "email": {"status": "deliverable", "action": "allow"},
  "signals": {"status": "unavailable"}
}

Der Dienst hat weder einen sicheren Besuch noch das Fehlen eines VPN festgestellt. Die äußere Aktion folgt allein der E-Mail. Ihre Anwendung bestimmt, welchen Zugang sie bei nicht verfügbaren Signalbelegen erlaubt. Verlangte die E-Mail eine Bestätigung oder Ablehnung, bliebe diese Anforderung bestehen.

Auch ein Ergebnis evaluated kann Lücken enthalten. Fehlende IP-Adresse, fehlende Browserinformationen oder eine nicht verfügbare Messung können einzelne Vergleiche verhindern. Soweit zurückgegeben, beschreiben not_evaluated und not_evaluated_classes diese Lücken. Es sind keine zusätzlichen E-Mail-Urteile. Ein fehlender Befund beweist nicht, dass sein Vergleich bestanden wurde.

Ein HTTP-Fehler, durch den Sie kein Registrierungsergebnis erhalten, ist ein eigener Integrationsfall. Machen Sie daraus kein erfundenes Ergebnis evaluated. Der API-Antwortvertrag unterscheidet Signalergebnisse von Anfrage-, Verbindungs- und Abrechnungsfehlern.

Eine laufende E-Mail-Prüfung bedeutet keine laufenden Signale

Bei email.status: pending stehen die Signale bereits fest. Die äußere action bleibt allow_with_email_confirmation, während die E-Mail-Prüfung abgeschlossen wird. Bewahren Sie die Prüfkennung auf und rufen Sie nach email.retry_after_ms den Endpunkt GET /v1/signup-checks/{id} ab.

Dieser Abruf liefert das aktuelle E-Mail-Ergebnis mit den gespeicherten Signalen und berechnet die kombinierte Aktion neu. Er wertet den Besuch nicht erneut aus. Liefert die E-Mail später allow, verlangt ein gespeicherter verschärfender Signalbefund weiterhin eine Bestätigung. Liefert sie reject, wird auch die kombinierte Aktion zu reject.

pending bezeichnet eine noch laufende E-Mail-Prüfung. Ein endgültiges E-Mail-Ergebnis unknown bedeutet, dass die Belege keine klare Antwort zur Adresse erlauben. Keiner dieser Zustände stellt fest, dass die Adresse ungültig ist. Folgen Sie der zurückgegebenen Aktion und nutzen Sie die E-Mail-Belege, um die Grenze zu verstehen.

Den Vorgang wiederholen, ohne eine neue Tokenvorlage zu erzeugen

Geht eine Antwort verloren, wiederholen Sie denselben logischen Vorgang mit dem gespeicherten Idempotency-Key und demselben Anfrageinhalt. Innerhalb des 30-minütigen Wiederholungsfensters liefert die API die gespeicherte Prüfung. Dabei werden weder die gespeicherten Signale erneut ausgewertet noch die Anfrage ein zweites Mal berechnet. Bei einer kombinierten Prüfung kann der gespeicherte Datensatz ein neueres E-Mail-Ergebnis enthalten. Die Wiederholung verspricht nicht, dass jedes Antwortbyte unverändert bleibt, während die E-Mail-Prüfung abgeschlossen wird.

Ein neuer Vorgang mit demselben Token ist eine zweite Vorlage. Er kann fp_token_reused hinzufügen und eine Bestätigung verlangen, wie im ersten Beispiel. Ein neuer Schlüssel nach einer verlorenen Antwort ändert die Bedeutung der Anfrage. Verwenden Sie für eine Wiederholung nach Übertragungsfehlern den ursprünglichen Schlüssel und für einen tatsächlich neuen Registrierungsversuch einen neuen Token.

Derselbe Schlüssel mit einem anderen Inhalt führt zu 409 idempotency_conflict. Läuft die erste Anfrage noch, fordert 409 request_in_progress zum Warten gemäß Retry-After auf. Die Idempotenzdokumentation erklärt die Vorgangsgrenze. Auch der Abruf der gespeicherten Prüfung mit GET unterscheidet sich von einer neuen Prüfung mit demselben Token.

Der Leitfaden zum Verhindern von Bot-Registrierungen verbindet diese Entscheidungen mit Ihrem Registrierungsablauf. Die Signup-Protection-Seite erklärt das Produkt und die Einrichtung von Formular und Server.