API de verificação de localização: geofencing e IP

A etapa de verificação de localização da Didit confirma onde a pessoa está enquanto faz a verificação. Ela obtém uma vez a posição do dispositivo (navegador ou SDK nativo) ou a localização do IP da conexão e a compara com as áreas permitidas e bloqueadas, com a localização do IP e com o endereço nos documentos da pessoa. Nos fluxos de verificação (workflows) e na API, ela é o recurso GEOLOCATION, suas configurações são as chaves geolocation_* e seu resultado é geolocation_checks[] na decisão da sessão.

​

Quando usar

• Você tem licença apenas para algumas jurisdições (jogos de azar, corretagem, crédito) e precisa provar que a pessoa estava dentro de uma delas quando fez a solicitação.
• Você precisa impedir o acesso de pessoas em locais bloqueados, como uma região sancionada ou um estado que você não atende.
• Você quer mais um sinal de fraude: uma posição do dispositivo distante da localização do IP ou do endereço no documento de identidade, uma localização simulada, uma VPN ou um emulador.
• Você não precisa dos deslocamentos nem do histórico da pessoa, apenas de uma leitura feita durante a sessão.

​

Como funciona

​

Fontes de posição

Você escolhe de onde vem a posição com geolocation_position_source. Em um nó que solicita a posição ao dispositivo, uma tentativa sem posição é avaliada como a recusa ou falha que representa: a localização do IP nunca a substitui.

​

Padrões e limites de configuração

Todas as chaves são opcionais. A lista completa está na referência de configurações de recursos do fluxo.

​

Predefinições

geolocation_preset define o padrão de todas as ações que você não definir. licensing recusa uma posição fora das áreas permitidas, dentro de uma área bloqueada, com uma VPN ou Tor, ou em um emulador, e envia para revisão uma posição atrás de um proxy. fraud_screening aplica os mesmos critérios, mas envia para revisão tudo o que licensing recusaria. Uma ação que você define explicitamente sempre prevalece.

​

Geocercas

Ative is_geolocation_geofencing_enabled e liste as geolocation_areas. Uma área pode ser um país inteiro, regiões (ISO 3166-2) de um país, um círculo (de 1 a 500 km) ou um polígono (de 3 a 200 pontos). Só uma posição dentro de uma área permitida é aprovada, e uma área bloqueada sempre prevalece sobre uma permitida. Uma lista comporta até 50 áreas e precisa de pelo menos uma área permitida. A Didit avalia todo o círculo de precisão da posição, não apenas o seu centro:

• Um círculo totalmente fora de todas as áreas permitidas gera LOCATION_OUTSIDE_GEOFENCE.
• Um círculo que cruza uma borda decisiva para a resposta gera LOCATION_GEOFENCE_UNDETERMINED, nunca “fora”.
• Um círculo totalmente dentro de uma área bloqueada gera LOCATION_IN_BLOCKED_AREA, além do veredito sobre a área permitida.

Um país ou região termina onde começa outra porção de terra, não no seu litoral. A pessoa vê onde o serviço está disponível, mas nunca quais áreas estão bloqueadas. As regras de área também funcionam em uma etapa ip_only, avaliadas com base na localização do IP. A configuração mais antiga geolocation_geofencing_by_country ainda funciona, mas não pode ser combinada com geolocation_areas.

​

Verificações de distância

geolocation_document_distance_basis define o endereço usado: document (o documento de identidade ou, na falta deste, o comprovante de endereço), proof_of_address ou declared (expected_details.address informado na criação da sessão). Com geolocation_travel_tolerance_enabled, uma pessoa vista perto do seu endereço nos últimos geolocation_travel_max_days dias não é sinalizada por estar longe dele agora. A tolerância a viagens nunca se aplica a uma VPN, uma posição falsificada, uma área bloqueada ou uma posição fora das áreas permitidas.

​

Sinais de spoofing e integridade

• Provedores simulados: o Android e o iOS informam quando uma posição é simulada em vez de medida.
• Atestação do dispositivo: os SDKs nativos podem anexar um atestado do dispositivo. Uma atestação com falha sempre resulta em recusa. A ausência de atestação é registrada e, por padrão, não gera nenhuma ação. Os navegadores não conseguem fazer a atestação e são registrados como unsupported, não como falha.
• VPN, proxy e Tor: detectados na conexão que compartilhou a localização. Quando a sua ação para um deles não é NO_ACTION, a pessoa é solicitada a desativá-lo e verificar novamente enquanto restarem tentativas.
• Emuladores: informados apenas por aplicativos nativos. Um emulador encerra a etapa nessa tentativa, porque tentar novamente não muda o dispositivo.
• Replay: um desafio apresentado em outra sessão sempre resulta em recusa.

​

Resultados

A tentativa aceita da etapa tem um único outcome: Enquanto restarem tentativas, um raio maior que o limite, uma posição desatualizada ou aproximada, uma recusa ou uma área bloqueada ou não permitida pede que a pessoa tente novamente, e apenas a última tentativa gera avisos. Uma posição simulada, ou um emulador sobre o qual o seu fluxo age, encerra a etapa na tentativa em que isso foi informado.

​

Experiência da pessoa

​

Consentimento e permissão

Nada é lido antes de a pessoa aceitar o aviso e responder à solicitação do sistema. O aviso informa que a localização é lida uma única vez, para esta verificação, e que não é um registro dos seus deslocamentos. Uma pessoa que recusa é tratada de acordo com geolocation_refusal_path:

• retry_then_handoff pede novamente enquanto restarem tentativas e depois oferece continuar em um celular.
• continue_without_location oferece seguir sem localização e registra a recusa como resultado.
• end_session encerra a etapa e a sessão na primeira recusa. Exige que geolocation_permission_denied_action seja REVIEW ou DECLINE, e a sessão nunca é aprovada.

Com geolocation_allow_skip ativado, a pessoa pode continuar sem localização a qualquer momento, e a etapa é avaliada por geolocation_unavailable_action.

​

Navegador

O fluxo hospedado solicita a posição ao navegador e mostra ajuda passo a passo para Chrome e Safari quando a localização está desativada para o site. Um navegador não consegue distinguir uma permissão precisa de uma aproximada, por isso os resultados na web nunca geram LOCATION_APPROXIMATE_ONLY, e ele nunca informa um provedor simulado, um emulador ou um atestado. Um computador não consegue compartilhar uma posição precisa, por isso o fluxo oferece um QR code que continua a mesma verificação no celular da pessoa (geolocation_allow_qr_handoff, ativado por padrão), e o computador avança sozinho quando o celular termina. Ao incorporar o fluxo em um iframe, inclua geolocation no atributo allow; consulte iframe no contexto. Uma página que bloqueia a política de permissão de geolocalização é tratada como uma decisão do site, não como uma recusa da pessoa.

​

SDKs nativos

Os SDKs para iOS e Android fazem a solicitação ao sistema operacional e podem anexar a atestação do dispositivo e indicadores de localização simulada. No iOS, adicione NSLocationWhenInUseUsageDescription ao Info.plist; no Android, o SDK declara ACCESS_FINE_LOCATION e ACCESS_COARSE_LOCATION e só faz a solicitação em tempo de execução quando um fluxo tem esta etapa. Consulte os SDKs nativos. Uma permissão aproximada no iOS ou no Android gera LOCATION_APPROXIMATE_ONLY, a menos que geolocation_accuracy_mode seja approximate_allowed. Uma versão do aplicativo ou do SDK anterior à etapa recebe unsupported_client, em vez de deixar a sessão travada.

​

O que a decisão retorna

A decisão da sessão e o webhook status.updated trazem duas listas:

• geolocation_checks[]: um item por etapa de localização, com a tentativa aceita dessa etapa e seus warnings.
• geolocation_attempts[]: todas as tentativas de todas as etapas de localização, da mais antiga para a mais recente.

Consulte o relatório de verificação de localização para ver todos os campos. As coordenadas, a precisão, a cidade e o país são dados pessoais do usuário final, por isso os atributos de resposta de um fluxo podem restringir quais campos de geolocation_checks a sua decisão retorna.

​

Preços

A verificação de localização custa $0.05 por verificação e não faz parte do plano gratuito. A Didit cobra uma vez por etapa de localização em uma sessão, qualquer que seja o resultado, porque a verificação foi executada e retornou uma resposta. Novas tentativas dentro da mesma etapa são gratuitas. Um reenvio que conclui a etapa novamente é cobrado novamente.

​

Sandbox

As sessões de sandbox executam a mesma etapa no mesmo fluxo hospedado, e o dispositivo ou o navegador continua informando uma localização real. As sessões de sandbox nunca acessam o serviço de consulta de IP, por isso a comparação de IP usa apenas o que a sessão já contém. O uso é registrado com preço 0, então uma sessão de sandbox nunca é cobrada. Não há entradas mágicas para esta etapa.

​

Relacionados

• Relatório de verificação de localização - todos os campos de geolocation_checks[] e geolocation_attempts[].
• Avisos da verificação de localização - todos os códigos LOCATION_* e a respectiva ação.
• Configurações de recursos do fluxo - todas as chaves geolocation_*.
• Análise de dispositivo e IP - geolocalização por IP e verificações de VPN da sessão.