Standortverifizierung-API: Geofencing und IP-Distanz

Der Standortverifizierungsschritt von Didit bestätigt den Aufenthaltsort einer Person während der Verifizierung. Dazu wird die Geräteposition einmalig (über den Browser oder das native SDK) oder der IP-Standort der Verbindung ermittelt und mit zulässigen sowie gesperrten Gebieten, dem IP-Standort und der Adresse auf den Ausweisdokumenten abgeglichen. In Workflows und der API entspricht dies der Funktion GEOLOCATION, die Einstellungen werden über die Schlüssel geolocation_* konfiguriert und das Ergebnis wird unter geolocation_checks[] in der Sitzungsentscheidung ausgegeben.

​

Wann Sie sie einsetzen sollten

• Sie besitzen eine Lizenz nur für bestimmte Jurisdiktionen (Glücksspiel, Brokerage, Kreditvergabe) und müssen nachweisen, dass sich die Person bei der Antragstellung in einer dieser Jurisdiktionen aufhielt.
• Sie müssen Personen aus gesperrten Regionen fernhalten, beispielsweise aus sanktionierten Gebieten oder Bundesstaaten, in denen Sie nicht tätig sind.
• Sie benötigen ein zusätzliches Betrugssignal: eine Geräteposition, die weit vom IP-Standort oder der Adresse auf dem Ausweisdokument entfernt ist, eine manipulierte Position (Mock Location), ein VPN oder ein Emulator.
• Sie benötigen keine Bewegungsprofile oder Standortverläufe der Person, sondern lediglich eine einzelne Standortabfrage während der Sitzung.

​

Wie es funktioniert

​

Positionsquellen

Mit geolocation_position_source legen Sie fest, woher die Position bezogen wird. Bei einem Knoten, der das Gerät abfragt, wird ein Versuch ohne Positionsangabe als die entsprechende Verweigerung oder der entsprechende Fehler gewertet: Der IP-Standort springt dafür niemals ein.

​

Standardeinstellungen und Grenzwerte der Konfiguration

Alle Schlüssel sind optional. Die vollständige Liste finden Sie in der Referenz zu den Konfigurationen der Workflow-Funktionen.

​

Voreinstellungen

geolocation_preset legt den Standardwert für jede Aktion fest, die Sie nicht explizit konfigurieren. licensing lehnt eine Position außerhalb der zulässigen Gebiete, innerhalb eines gesperrten Gebiets, hinter einem VPN oder Tor oder auf einem Emulator ab und führt bei einem Proxy zu einer Prüfung. fraud_screening wendet dieselben Prüfungen an, übermittelt jedoch alles, was licensing ablehnen würde, zur Prüfung. Eine explizit gesetzte Aktion hat stets Vorrang.

​

Geofencing

Aktivieren Sie is_geolocation_geofencing_enabled und listen Sie die geolocation_areas auf. Ein Gebiet kann ein ganzes Land, Regionen (ISO 3166-2) eines Landes, ein Kreis (1 bis 500 km) oder ein Polygon (3 bis 200 Punkte) sein. Nur eine Position innerhalb eines zulässigen Gebiets gilt als bestanden, und ein gesperrtes Gebiet hat stets Vorrang vor einem zulässigen Gebiet. Eine Liste fasst bis zu 50 Gebiete und erfordert mindestens ein zulässiges Gebiet. Didit bewertet den gesamten Genauigkeitskreis der Position, nicht nur den Mittelpunkt:

• Ein Kreis, der vollständig außerhalb aller zulässigen Gebiete liegt, führt zu LOCATION_OUTSIDE_GEOFENCE.
• Ein Kreis, der eine entscheidungsrelevante Grenze schneidet, führt zu LOCATION_GEOFENCE_UNDETERMINED, niemals zu “außerhalb”.
• Ein Kreis, der vollständig innerhalb eines gesperrten Gebiets liegt, führt zu LOCATION_IN_BLOCKED_AREA, und dieser Befund wird zusätzlich zum Ergebnis für das zulässige Gebiet ausgelöst.

Ein Land oder eine Region endet dort, wo anderes Festland beginnt, nicht an der Küstenlinie. Der Person wird angezeigt, wo der Dienst verfügbar ist, jedoch niemals, welche Gebiete gesperrt sind. Gebietsregeln funktionieren auch bei einem ip_only-Schritt und werden dann anhand des IP-Standorts bewertet. Die ältere Einstellung geolocation_geofencing_by_country funktioniert weiterhin, kann jedoch nicht mit geolocation_areas kombiniert werden.

​

Distanzprüfungen

geolocation_document_distance_basis wählt die Adresse aus: document (das Ausweisdokument, dann der Adressnachweis), proof_of_address oder declared (expected_details.address aus der Sitzungserstellung). Bei aktiviertem geolocation_travel_tolerance_enabled wird eine Person, die in den letzten geolocation_travel_max_days Tagen in der Nähe ihrer Adresse erfasst wurde, nicht dafür markiert, dass sie sich jetzt weit davon entfernt befindet. Die Reisetoleranz gilt niemals als Ausnahme für ein VPN, eine gespoofte Position, einen blockierten Bereich oder eine Position außerhalb der zulässigen Bereiche.

​

Spoofing- und Integritätssignale

• Mock-Provider: Android und iOS melden, wenn eine Position simuliert statt gemessen wird.
• Geräteattestierung: Native SDKs können eine Geräteattestierung anhängen. Eine fehlgeschlagene Attestierung führt immer zu einer Ablehnung. Eine fehlende wird erfasst und führt standardmäßig zu keiner Aktion. Browser können keine Attestierung durchführen und werden als unsupported erfasst, nicht als Fehlschlag.
• VPN, Proxy und Tor: Werden über die Verbindung ermittelt, über die der Standort geteilt wurde. Wenn Ihre Aktion für eines davon nicht NO_ACTION ist, wird die Person aufgefordert, den Dienst zu deaktivieren und es erneut zu versuchen, solange noch Versuche verbleiben.
• Emulatoren: Werden nur von nativen Apps gemeldet. Ein Emulator beendet den Schritt bei diesem Versuch, da ein Wiederholungsversuch am Gerät nichts ändern würde.
• Replay: Eine Challenge, die in einer anderen Sitzung vorgelegt wurde, wird immer abgelehnt.

​

Ergebnisse

Der akzeptierte Versuch des Schritts hat ein outcome: Solange noch Versuche verbleiben, fordert ein ungenauer, veralteter, ungefährer, verweigerter oder bereichsbezogener Befund die Person zu einem erneuten Versuch auf, und erst der letzte Versuch löst Warnungen aus. Eine simulierte Position oder ein Emulator, auf den Ihr Workflow reagiert, beendet den Schritt bei dem Versuch, der dies gemeldet hat.

​

Benutzererlebnis

​

Einwilligung und Berechtigung

Es wird nichts ausgelesen, bevor die Person den Hinweis akzeptiert und die Systemabfrage beantwortet hat. Der Hinweis besagt, dass der Standort einmalig für diese Verifizierung erfasst wird und keine Aufzeichnung ihrer Bewegungen erfolgt. Eine Person, die ablehnt, wird gemäß geolocation_refusal_path behandelt:

• retry_then_handoff fragt erneut, solange noch Versuche verbleiben, und bietet dann an, auf einem Smartphone fortzufahren.
• continue_without_location bietet an, ohne Standort fortzufahren, und erfasst die Verweigerung als Ergebnis.
• end_session beendet den Schritt und die Sitzung bei der ersten Verweigerung. Dies erfordert, dass geolocation_permission_denied_action auf REVIEW oder DECLINE gesetzt ist, und die Sitzung wird niemals genehmigt.

Bei aktiviertem geolocation_allow_skip kann die Person jederzeit ohne Standort fortfahren, und der Schritt wird nach geolocation_unavailable_action bewertet.

​

Browser

Der gehostete Ablauf fragt den Browser nach der Position und zeigt eine Schritt-für-Schritt-Hilfe für Chrome und Safari, wenn der Standort für die Website deaktiviert ist. Ein Browser kann eine präzise Standortfreigabe nicht von einer ungefähren unterscheiden, weshalb Web-Ergebnisse niemals LOCATION_APPROXIMATE_ONLY auslösen und Browser weder Mock-Provider noch Emulatoren oder Attestierungen melden. Ein Computer kann keine genaue Position teilen, daher bietet der Ablauf einen QR-Code an, über den dieselbe Verifizierung auf dem Smartphone der Person fortgesetzt werden kann (geolocation_allow_qr_handoff, standardmäßig aktiviert), und der Computer fährt automatisch fort, sobald das Smartphone fertig ist. Wenn Sie den Ablauf in einem Iframe einbetten, fügen Sie geolocation in das allow-Attribut ein, siehe In-Context-Iframe. Eine Seite, die die Berechtigungsrichtlinie für die Geolokalisierung blockiert, wird als Entscheidung der Website gewertet, nicht als Verweigerung durch die Person.

​

Native SDKs

Die iOS- und Android-SDKs fragen das Betriebssystem ab und können eine Geräteattestierung sowie Flags für simulierte Standorte anhängen. Fügen Sie unter iOS NSLocationWhenInUseUsageDescription zu Info.plist hinzu; unter Android deklariert das SDK ACCESS_FINE_LOCATION sowie ACCESS_COARSE_LOCATION und fragt diese zur Laufzeit nur ab, wenn ein Workflow diesen Schritt enthält. Siehe die nativen SDKs. Eine ungefähre Freigabe unter iOS oder Android löst LOCATION_APPROXIMATE_ONLY aus, es sei denn, geolocation_accuracy_mode ist auf approximate_allowed gesetzt. Ein App- oder SDK-Build, der vor der Einführung dieses Schritts veröffentlicht wurde, wird mit unsupported_client abgeschlossen, anstatt die Sitzung hängen zu lassen.

​

Was die Entscheidung zurückgibt

Die Sitzungsentscheidung und der status.updated-Webhook enthalten zwei Listen:

• geolocation_checks[]: ein Eintrag pro Location-Schritt, der den akzeptierten Versuch dieses Schritts mit seinen warnings enthält.
• geolocation_attempts[]: jeder Versuch jedes Location-Schritts, die ältesten zuerst.

Im Bericht zur Standortverifizierung finden Sie alle Felder. Koordinaten, Genauigkeit, Stadt und Land sind personenbezogene Daten des Endbenutzers; daher können die Antwortattribute eines Workflows einschränken, welche geolocation_checks-Felder Ihre Entscheidung zurückgibt.

​

Preise

Die Standortverifizierung kostet $0.05 pro Prüfung und ist nicht Teil des kostenlosen Kontingents. Didit stellt pro Location-Schritt in einer Sitzung einmalig Gebühren in Rechnung, unabhängig vom Ergebnis, da die Prüfung ausgeführt wurde und eine Antwort geliefert hat. Wiederholungsversuche innerhalb desselben Schritts sind kostenlos. Eine erneute Einreichung, die den Schritt erneut abschließt, wird erneut berechnet.

​

Sandbox

Sandbox-Sitzungen führen denselben Schritt im selben gehosteten Ablauf aus, und das Gerät oder der Browser übermittelt weiterhin eine reale Position. Sandbox-Sitzungen erreichen niemals den IP-Lookup-Dienst, sodass der IP-Abgleich nur das verwendet, was die Sitzung bereits enthält. Die Nutzung wird mit einem Preis von 0 erfasst, sodass für eine Sandbox-Sitzung niemals Kosten anfallen. Es gibt keine magischen Eingaben für diesen Schritt.

​

Verwandte Themen

• Bericht zur Standortverifizierung – alle Felder von geolocation_checks[] und geolocation_attempts[].
• Warnungen der Standortverifizierung – alle LOCATION_*-Codes und die jeweilige Aktion.
• Workflow-Funktionskonfigurationen – alle geolocation_*-Schlüssel.
• Geräte- und IP-Analyse – IP-Geolokalisierung und VPN-Prüfungen für die Sitzung.