API di verifica della posizione: geofencing e distanza IP

Il passaggio di verifica della posizione di Didit conferma dove si trova una persona mentre si verifica, leggendo la posizione del dispositivo una sola volta (tramite browser o SDK nativo) o la posizione IP della connessione, e confrontandola con le aree consentite e bloccate, con la posizione IP e con l’indirizzo presente sui suoi documenti. Nei workflow e nell’API corrisponde alla funzionalità GEOLOCATION, le sue impostazioni sono le chiavi geolocation_*, e il suo risultato è geolocation_checks[] nella decisione della sessione.

​

Quando utilizzarla

• Sei in possesso di una licenza valida solo per determinate giurisdizioni (gioco d’azzardo, intermediazione finanziaria, prestiti) e devi dimostrare che la persona si trovava all’interno di una di esse al momento della richiesta.
• Devi impedire alle persone di accedere da luoghi bloccati, come una regione soggetta a sanzioni o uno stato non servito.
• Vuoi un segnale di frode aggiuntivo: una posizione del dispositivo distante dalla posizione IP o dall’indirizzo sul documento d’identità, una posizione simulata, una VPN o un emulatore.
• Non hai bisogno degli spostamenti o della cronologia della persona, ma solo di una singola rilevazione effettuata durante la sessione.

​

Come funziona

​

Origini della posizione

Puoi scegliere da dove proviene la posizione con geolocation_position_source. Su un nodo che interroga il dispositivo, un tentativo senza posizione viene valutato come l’effettivo rifiuto o errore che rappresenta: la posizione IP non la sostituisce mai.

​

Valori predefiniti e limiti di configurazione

Tutte le chiavi sono facoltative. L’elenco completo è disponibile nel riferimento alle configurazioni delle funzionalità dei workflow.

​

Preset

geolocation_preset imposta il valore predefinito di ogni azione lasciata non configurata. licensing rifiuta una posizione al di fuori delle aree consentite, all’interno di un’area bloccata, dietro una VPN o Tor, oppure su un emulatore, e invia a revisione un proxy. fraud_screening applica gli stessi rilevamenti, ma invia a revisione tutto ciò che licensing rifiuterebbe. Un’azione impostata esplicitamente prevale sempre.

​

Geofencing

Attiva is_geolocation_geofencing_enabled ed elenca le geolocation_areas. Un’area può essere un intero paese, regioni (ISO 3166-2) di un paese, un cerchio (da 1 a 500 km) o un poligono (da 3 a 200 punti). Solo una posizione all’interno di un’area consentita supera il controllo, e un’area bloccata prevale sempre su una consentita. Un elenco può contenere fino a 50 aree e richiede almeno un’area consentita. Didit valuta l’intero cerchio di accuratezza della posizione, non solo il suo centro:

• Un cerchio completamente esterno a qualsiasi area consentita restituisce LOCATION_OUTSIDE_GEOFENCE.
• Un cerchio che attraversa un confine determinante per la risposta restituisce LOCATION_GEOFENCE_UNDETERMINED, mai “esterno”.
• Un cerchio completamente interno a un’area bloccata restituisce LOCATION_IN_BLOCKED_AREA, che viene generato in aggiunta al verdetto sull’area consentita.

Un paese o una regione termina dove inizia un’altra terraferma, non lungo la linea costiera. Alla persona viene mostrato dove il servizio è disponibile, ma mai quali aree sono bloccate. Le regole di area funzionano anche su un passaggio ip_only, valutate a partire dalla posizione IP. La precedente impostazione geolocation_geofencing_by_country continua a funzionare, ma non può essere combinata con geolocation_areas.

​

Controlli della distanza

geolocation_document_distance_basis seleziona l’indirizzo: document (il documento d’identità, poi la prova di residenza), proof_of_address o declared (expected_details.address dalla creazione della sessione). Con geolocation_travel_tolerance_enabled, una persona rilevata vicino al proprio indirizzo negli ultimi geolocation_travel_max_days giorni non viene segnalata se ora ne è distante. La tolleranza per i viaggi non giustifica mai una VPN, una posizione contraffatta, un’area bloccata o una posizione al di fuori delle aree consentite.

​

Segnali di spoofing e integrità

• Provider simulati: Android e iOS segnalano quando una posizione è simulata anziché misurata.
• Attestazione del dispositivo: gli SDK nativi possono allegare un’attestazione del dispositivo. Un’attestazione non riuscita comporta sempre un rifiuto. Un’attestazione mancante viene registrata e per impostazione predefinita non comporta alcuna azione. I browser non possono eseguire l’attestazione e vengono registrati come unsupported, non come fallimento.
• VPN, proxy e Tor: rilevati sulla connessione che ha condiviso la posizione. Quando la tua azione per uno di essi non è NO_ACTION, alla persona viene chiesto di disattivarlo e riprovare finché rimangono tentativi disponibili.
• Emulatori: segnalati solo dalle app native. Un emulatore termina il passaggio in quel tentativo poiché nessun nuovo tentativo cambierebbe il dispositivo.
• Replay: una challenge presentata su un’altra sessione viene sempre rifiutata.

​

Risultati

Il tentativo accettato del passaggio ha un outcome: Finché rimangono tentativi disponibili, un esito relativo a un raggio eccessivo, una posizione non aggiornata, approssimativa, rifiutata o un problema di area richiede alla persona di riprovare, e solo l’ultimo tentativo genera avvisi. Una posizione simulata, o un emulatore su cui interviene il tuo workflow, termina il passaggio nel tentativo che lo ha segnalato.

​

Esperienza dell’utente

​

Consenso e autorizzazione

Non viene letto nulla prima che la persona accetti l’informativa e risponda alla richiesta del sistema. L’informativa indica che la posizione viene letta una sola volta, per questa verifica, e non costituisce una registrazione dei suoi spostamenti. Una persona che rifiuta viene gestita in base a geolocation_refusal_path:

• retry_then_handoff chiede nuovamente finché rimangono tentativi disponibili e poi propone di continuare su uno smartphone.
• continue_without_location propone di proseguire senza una posizione e registra il rifiuto come risultato.
• end_session termina il passaggio e la sessione al primo rifiuto. Richiede che geolocation_permission_denied_action sia impostato su REVIEW o DECLINE, e la sessione non viene mai approvata.

Con geolocation_allow_skip abilitato, la persona può proseguire senza una posizione in qualsiasi momento, e il passaggio viene valutato in base a geolocation_unavailable_action.

​

Browser

Il flusso ospitato richiede la posizione al browser e mostra una guida passo passo per Chrome e Safari quando la geolocalizzazione è disattivata per il sito. Un browser non è in grado di distinguere un’autorizzazione precisa da una approssimativa, pertanto i risultati web non generano mai LOCATION_APPROXIMATE_ONLY e non segnalano mai un provider simulato, un emulatore o un’attestazione. Un computer non può condividere una posizione precisa, quindi il flusso propone un codice QR per continuare la stessa verifica sullo smartphone della persona (geolocation_allow_qr_handoff, attivo per impostazione predefinita), e il computer prosegue autonomamente quando lo smartphone termina. Quando incorpori il flusso in un iframe, includi geolocation nell’attributo allow; vedi iframe nel contesto. Una pagina che blocca la policy dei permessi di geolocalizzazione viene considerata come una decisione del sito, non come un rifiuto della persona.

​

SDK nativi

Gli SDK per iOS e Android richiedono la posizione al sistema operativo e possono allegare l’attestazione del dispositivo e i flag di posizione simulata. Su iOS aggiungi NSLocationWhenInUseUsageDescription a Info.plist, mentre su Android l’SDK dichiara ACCESS_FINE_LOCATION e ACCESS_COARSE_LOCATION e richiede l’autorizzazione a runtime solo quando un workflow include questo passaggio. Vedi gli SDK nativi. Un’autorizzazione approssimativa su iOS o Android genera LOCATION_APPROXIMATE_ONLY a meno che geolocation_accuracy_mode non sia impostato su approximate_allowed. Una build dell’app o dell’SDK precedente all’introduzione del passaggio viene chiusa con unsupported_client invece di lasciare la sessione bloccata.

​

Cosa restituisce la decisione

La decisione della sessione e il webhook status.updated contengono due elenchi:

• geolocation_checks[]: un elemento per ciascun passaggio Location, contenente il tentativo accettato di tale passaggio, con i relativi warnings.
• geolocation_attempts[]: ogni tentativo di ciascun passaggio Location, dal più vecchio al più recente.

Consulta il report di verifica della posizione per ogni campo. Le coordinate, l’accuratezza, la città e il paese sono dati personali dell’utente finale, pertanto gli attributi di risposta di un workflow possono limitare quali campi di geolocation_checks vengono restituiti dalla decisione.

​

Prezzi

La verifica della posizione costa $0.05 per verifica e non fa parte del piano gratuito. Didit addebita il costo una sola volta per ciascun passaggio Location in una sessione, qualunque sia il suo esito, poiché la verifica è stata eseguita e ha restituito una risposta. I nuovi tentativi all’interno dello stesso passaggio sono gratuiti. Un nuovo invio che completa nuovamente il passaggio viene addebitato nuovamente.

​

Sandbox

Le sessioni sandbox eseguono lo stesso passaggio nello stesso flusso ospitato e il dispositivo o il browser segnala comunque una posizione reale. Le sessioni sandbox non contattano mai il servizio di ricerca IP, pertanto il confronto dell’IP utilizza solo ciò che la sessione già contiene. L’utilizzo viene registrato a un prezzo pari a 0, quindi una sessione sandbox non viene mai addebitata. Non sono previsti input magici per questo passaggio.

​

Correlati

• Report di verifica della posizione - ogni campo di geolocation_checks[] e geolocation_attempts[].
• Avvisi di verifica della posizione - ogni codice LOCATION_* e la relativa azione.
• Configurazioni delle funzionalità del workflow - ogni chiave geolocation_*.
• Analisi dispositivo e IP - geolocalizzazione IP e controlli VPN per la sessione.