API проверки местоположения: геозоны и расстояние по IP

Шаг верификации местоположения Didit подтверждает, где находится человек во время прохождения верификации. Для этого однократно считываются координаты устройства (через браузер или нативный SDK) или определяется локация по IP-адресу соединения, после чего полученные данные сверяются с разрешенными и заблокированными зонами, локацией по IP и адресом из документов. В сценариях и API это функция GEOLOCATION, ее параметры задаются ключами geolocation_*, а результат возвращается в массиве geolocation_checks[] в решении по сессии.

​

Когда использовать

• У вас есть лицензия только для определенных юрисдикций (гемблинг, брокерские услуги, кредитование), и вам необходимо подтвердить, что пользователь находился в пределах одной из них при подаче заявки.
• Вам необходимо ограничить доступ пользователям из заблокированных регионов, таких как подсанкционные территории или штаты/регионы, которые вы не обслуживаете.
• Вам нужен дополнительный сигнал для защиты от фрода: координаты устройства значительно отличаются от локации по IP или адреса в удостоверении личности, обнаружены подмена геопозиции, VPN или эмулятор.
• Вам не требуется отслеживать перемещения или историю передвижений человека, достаточно единичного замера, сделанного во время сессии.

​

Как это работает

​

Источники координат

Вы можете выбрать источник координат с помощью параметра geolocation_position_source. Если узел настроен на запрос координат у устройства, попытка без полученных данных расценивается как отказ или сбой: локация по IP ни при каких обстоятельствах их не заменяет.

​

Значения по умолчанию и лимиты конфигурации

Все параметры являются необязательными. Полный список приведен в справочнике конфигураций функций сценариев.

​

Пресеты

Параметр geolocation_preset задает значение по умолчанию для каждого действия, которое вы не настроили явно. Пресет licensing отклоняет верификацию при нахождении вне разрешенных зон, внутри заблокированной зоны, при использовании VPN, Tor или эмулятора, и отправляет кейс на проверку при обнаружении прокси. Пресет fraud_screening использует те же проверки, но отправляет на ручную проверку все случаи, которые licensing отклонил бы. Явно настроенное действие всегда имеет приоритет над пресетом.

​

Геозоны

Включите is_geolocation_geofencing_enabled и перечислите геозоны в geolocation_areas. Зоной может быть страна целиком, регионы (ISO 3166-2) одной страны, окружность (радиусом от 1 до 500 км) или многоугольник (от 3 до 200 точек). Проверку проходят только координаты внутри разрешенной зоны; при этом заблокированная зона всегда имеет приоритет над разрешенной. Список может содержать до 50 зон и должен включать как минимум одну разрешенную зону. Didit оценивает весь круг погрешности координат, а не только его центр:

• Круг, полностью находящийся за пределами всех разрешенных зон, получает статус LOCATION_OUTSIDE_GEOFENCE.
• Круг, пересекающий границу, от которой зависит решение, получает статус LOCATION_GEOFENCE_UNDETERMINED, но никогда не считается находящимся «снаружи».
• Круг, полностью находящийся внутри заблокированной зоны, получает статус LOCATION_IN_BLOCKED_AREA, который выставляется в дополнение к вердикту по разрешенной зоне.

Граница страны или региона заканчивается там, где начинается другая суша, а не по береговой линии. Пользователю отображается информация о том, где доступен сервис, но никогда не показываются заблокированные зоны. Правила геозон также работают для шага с параметром ip_only, где оценка производится по локации по IP. Устаревший параметр geolocation_geofencing_by_country продолжает поддерживаться, но его нельзя использовать одновременно с geolocation_areas.

​

Проверки расстояния

Параметр geolocation_document_distance_basis выбирает адрес: document (документ, удостоверяющий личность, затем подтверждение адреса), proof_of_address или declared (expected_details.address при создании сессии). При включенном geolocation_travel_tolerance_enabled пользователь, зафиксированный рядом со своим адресом за последние geolocation_travel_max_days дней, не отмечается предупреждением за то, что сейчас находится далеко от него. Допуск на поездки никогда не освобождает от проверки использования VPN, спуфинга геопозиции, нахождения в заблокированной зоне или позиции за пределами разрешенных зон.

​

Сигналы спуфинга и целостности

• Фиктивные провайдеры: Android и iOS сообщают, когда позиция симулируется, а не измеряется.
• Аттестация устройства: нативные SDK могут прикреплять аттестацию устройства. Неудачная аттестация всегда приводит к отклонению. Отсутствующая аттестация фиксируется и по умолчанию не вызывает действий. Браузеры не поддерживают аттестацию и регистрируются со статусом unsupported, а не как ошибка.
• VPN, прокси и Tor: обнаруживаются в соединении, через которое передавалась геолокация. Если ваше действие для одного из них отличается от NO_ACTION, пользователю предлагается отключить его и повторить проверку, пока остаются попытки.
• Эмуляторы: регистрируются только нативными приложениями. Наличие эмулятора завершает шаг на этой попытке, поскольку повторная попытка не изменит устройство.
• Повторное воспроизведение: проверка, предъявленная в другой сессии, всегда отклоняется.

​

Результаты

Принятая попытка шага имеет один outcome: Пока остаются попытки, в случае слишком широкого радиуса, устаревших или приблизительных данных, отказа или несоответствия зоны пользователю предлагается повторить попытку, и только последняя попытка генерирует предупреждения. Симулированная позиция или эмулятор, на который реагирует ваш сценарий, завершают шаг на той попытке, где они были зафиксированы.

​

Взаимодействие с пользователем

​

Согласие и разрешения

Никакие данные не считываются до того, как пользователь примет уведомление и ответит на системный запрос. В уведомлении указано, что местоположение считывается один раз для данной верификации и не является записью перемещений. В случае отказа пользователя дальнейшие действия определяются параметром geolocation_refusal_path:

• retry_then_handoff запрашивает разрешение снова, пока остаются попытки, а затем предлагает продолжить на телефоне.
• continue_without_location предлагает продолжить без передачи местоположения и записывает отказ в качестве результата.
• end_session завершает шаг и сессию при первом же отказе. Для этого требуется, чтобы параметр geolocation_permission_denied_action имел значение REVIEW или DECLINE, при этом сессия никогда не одобряется.

При включенном параметре geolocation_allow_skip пользователь может продолжить без передачи местоположения в любой момент, а шаг оценивается в соответствии с geolocation_unavailable_action.

​

Браузер

Размещенный сценарий запрашивает позицию у браузера и отображает пошаговые подсказки для Chrome и Safari, если геолокация для сайта отключена. Браузер не может отличить точное разрешение от приблизительного, поэтому результаты в вебе никогда не вызывают LOCATION_APPROXIMATE_ONLY, а также никогда не сообщают о фиктивных провайдерах, эмуляторе или аттестации. Компьютер не может передать точную позицию, поэтому сценарий предлагает QR-код для продолжения той же верификации на телефоне пользователя (geolocation_allow_qr_handoff, включено по умолчанию), и компьютер автоматически переходит к следующему шагу, когда телефон завершает процесс. Если вы встраиваете сценарий в iframe, добавьте geolocation в атрибут allow, см. iframe в контексте. Страница, блокирующая политику разрешений геолокации, расценивается как решение сайта, а не как отказ пользователя.

​

Нативные SDK

SDK для iOS и Android запрашивают разрешение у операционной системы и могут прикреплять аттестацию устройства и флаги фиктивной геолокации. В iOS добавьте NSLocationWhenInUseUsageDescription в Info.plist, а на Android SDK объявляет ACCESS_FINE_LOCATION и ACCESS_COARSE_LOCATION и запрашивает разрешение во время выполнения только в том случае, если в сценарии есть этот шаг. См. нативные SDK. Предоставление только приблизительного разрешения на iOS или Android вызывает предупреждение LOCATION_APPROXIMATE_ONLY, если только geolocation_accuracy_mode не установлен в approximate_allowed. Сборка приложения или SDK, созданная до появления этого шага, завершается со статусом unsupported_client, предотвращая зависание сессии.

​

Что возвращает решение

Решение по сессии и webhook status.updated содержат два списка:

• geolocation_checks[]: по одному элементу на каждый шаг Location, содержащий принятую попытку этого шага вместе с ее warnings.
• geolocation_attempts[]: каждая попытка каждого шага Location, начиная с самых старых.

Ознакомьтесь с отчётом о верификации местоположения, чтобы узнать обо всех полях. Координаты, точность, город и страна являются персональными данными конечного пользователя, поэтому атрибуты ответа в сценарии позволяют ограничить, какие поля geolocation_checks возвращает ваше решение.

​

Цены

Верификация местоположения стоит $0.05 за проверку и не входит в бесплатный тариф. Didit списывает средства один раз за каждый шаг Location в сессии независимо от его результата, поскольку проверка была выполнена и вернула ответ. Повторные попытки внутри одного и того же шага бесплатны. Повторная отправка данных, заново завершающая шаг, тарифицируется повторно.

​

Песочница

Сессии в песочнице выполняют тот же шаг в том же размещенном сценарии, и устройство или браузер по-прежнему передают реальное местоположение. Сессии в песочнице никогда не обращаются к сервису поиска по IP, поэтому сравнение IP использует только те данные, которые уже есть в сессии. Использование фиксируется по цене 0, поэтому за сессию в песочнице плата не взимается. Специальных тестовых входных данных для этого шага нет.

​

Связанные материалы

• Отчёт о верификации местоположения - все поля geolocation_checks[] и geolocation_attempts[].
• Предупреждения верификации местоположения - каждый код LOCATION_* и соответствующее действие.
• Конфигурация функций сценария - каждый ключ geolocation_*.
• Анализ устройства и IP - геолокация по IP и проверки VPN для сессии.