Документация
Панель управления API

Что значат поля из ответа Digital Fraud Protection

Описываем каждое поле, которое отправляет вам DFP.

DFP отправляет браузеру / мобильному приложению пользователя JSON с зашифрованным payload. Браузер / мобильное приложение пересылает этот ответ на ваш бэкенд, где вы расшифровываете его с помощью секретного ключа. В статье описываем все поля — и в ответе до расшифровки, и в расшифрованном payload.

Протестировать работу DFP вы можете в нашем playground. Откройте его и увидите результат анализа вашего окружения: ваш user_id, bot_score, proxy_score, hosting и другие данные.

Открыть playground DFP

Ответ DFP до расшифровки

Ответ DFP выглядит подобным образом:

{
  "cipher_type": "aes-256-gcm/json",
  "iv": "kUtwgQ8ket0kYwbY",
  "payload": "qaBKmqp5rmGHvqWXqvbyTDY3+M4cxO1LlB47gNOh+tRx0wq4IxhXlsNpxNtoMiegyNDDlHd3w2or8J5R8HM6HwMCKj0VeUuXn8pHd7AiTA2rESvQx8ziwKreFbgj8s1K7gbS0P+i7t0sD4dgw3tMkRB8XjAeasOBdbSZLceCgQQfKIM00HAVtyP3zbU4kybR4Z0FXcIK3q19kpaEiCqDgpXsfvrUPpOJgo3nQ0b4uhmbpb8e6BWjXSOSnzf86sQxJD6tu6aUlqUqtt3GxXuB6Ig2ffXEK9JCK7Uv0LnEAzqYJ4ZVdihIwJfrSzXW4agzRAFlSa92wwurSmXV5KBUfi1o2DuZkP+W8wiZ/5xmcSN1ZMYz/GD+WWfPVtI7FlwWSsXiKwjLm/+BcvdNv2QsSrV7gAOKJdhwPPz73bCFTvHZ7D/TYCpm5IQmQV00QPbyieBkBj/kNdp8eXLDwXgFvG+sFaBv9pXalFmvuvVtVbJMzT+WAjj9s6V95CRycR9tksCyD85l7XUuQzvYitu3m0nbd7eAeWkS0uNjsGo7vcOJtvws7q6bm1EidBgCrPknGSwJqd1LvdemKzm81SfFQoE72EzxVZ/cEedPPBFeax1NOQCtFaD/+WUl0cZa36OblMgTw4umdocEJvm9yJc=",
  "request_id": "cIK7aBF8WqM1",
  "success": true,
  "tag": "msxs6Dyk5LBzF6VnpVJ5bw=="
}

Описываем каждое поле.

Поле Возможные значения Что значит

success

true, false

Успешно ли DFP обработал запрос. true — успешно, false — неуспешно.

Если получили false, сохраните request_id и передайте его в поддержку — мы со всем разберёмся.

cipher_type

aes-256-gcm/json

aes-256-gcm — алгоритм шифрования, json — формат данных после расшифровки.

iv

Строка в Base64

Вектор инициализации, используется при расшифровке payload. Передаётся в Base64, после декодирования размер составит 12 байт.

payload

Зашифрованная строка в Base64

Результат анализа технических признаков клиентского окружения и сетевого взаимодействия при выполнении запроса. Этот результат отправляется в зашифрованном виде без тега аутентификации.

request_id

Строка

ID запроса. Нужен, чтобы наша поддержка могла быстро найти запрос, если с ним возникнут проблемы.

tag

Строка в Base64

Тег аутентификации AES-256-GCM, нужен для проверки целостности и расшифровки payload. После декодирования размер составит 16 байт.

Расшифрованный payload

После расшифровки бэкенд получает JSON примерно такого вида:

{
  "details": {
    "antidetect": false,
    "bot_hosting": false,
    "bot_score": 0.1,
    "engine": "gecko",
    "hosting": false,
    "incognito": false,
    "isp_active_subnet": true,
    "mobile": false,
    "os": "linux",
    "proxy_score": 0,
    "proxy_signs": [],
    "rdp": false,
    "tor": false,
    "vm": false,
    "vpn": false,
    "webview": false,
    "new_user": false,
    "confidence_score": 1
  },
  "custom_data": "{\"event\":\"login_attempt\",\"form_id\":\"main_login\"}",
  "referer_md5": "9f0b84073da2ef97a63c2f4179981a2e",
  "timestamp": 1777404974833,
  "user_id": "3849965ed6d75d7dc67568d620950bbb",
  "version": 2,
  "white_bot": false
}
Некоторые поля доступны только при интеграции DFP на сайт. В таблице ниже у таких полей стоят соответствующие примечания.

Рассказываем о каждом поле.

Поле Возможные значения Что значит

details.antidetect

true, false

Используется ли антидетект-браузер, который подменяет параметры браузера и отпечаток, чтобы с одного устройства можно было выдавать себя за разных пользователей.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.bot_hosting

true, false

Относится ли IP к хостинговой подсети, откуда мы зафиксировали активность ботов или другую подозрительную активность.

details.bot_score

Число от 0 до 1

Вероятность, что запрос отправлен ботом. Значения:

  • < 0.4 — обычный клиент.

  • От 0.4 до 0.5 — подозрительный клиент, выявлены некоторые признаки автоматизации, подмены параметров браузера и другой аномалии. При принятии решения советуем учесть данные других полей: hosting, bot_hosting, incognito, mobile, proxy_score, antidetect, vm, а также историю этого user_id в вашей системе.

  • От 0.5 и выше — наверняка бот. Выявлены значительные признаки, характерные для автоматизации или подмены параметров браузера.

details.engine

blink, webkit, gecko и другие

Браузерный движок.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.hosting

true, false

Относится ли IP к хостинговой подсети.

details.incognito

true, false

Включен или нет режим инкогнито в браузере.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.isp_active_subnet

true, false

Относится ли IP к активной подсети интернет-провайдера, которая используется для подключения частных или корпоративных клиентов к интернету.

details.mobile

true, false

Мобильное устройство или нет.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.os

Строка, например linux, windows, macos, ios, android

Операционная система на устройстве.

details.proxy_score

Число от 0 до 1

Вероятность, что при отправке запроса использовался VPN или прокси. DFP оценивает её, сравнивая параметры браузера с параметрами сетевого соединения. Значения:

  • < 0.5 — признаков VPN или прокси не выявлено.

  • От 0.5 и выше — использовался VPN или прокси.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.proxy_signs

Массив строк

Признаки, на основании которых DFP рассчитал proxy_score:

  • tcp — значение MSS не соответствует операционной системе;

  • tls — расхождение во времени RTT;

  • os — операционная система по сетевому отпечатку не совпадает с указанной в User-Agent;

  • tz — часовой пояс браузера не совпадает с часовым поясом IP-адреса.

Если признаков нет, приходит пустой массив [].

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.rdp

true, false

Используется ли на устройстве программа для удалённого доступа.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.tor

true, false

Относится ли IP к сети Tor, которая скрывает реальный адрес пользователя.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.vm

true, false

Запущен ли браузер в виртуальной машине.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.vpn

true, false

Включен ли VPN.

Для интеграции DFP на сайт поле считается устаревшим. Мы оставили его, чтобы не нарушить работу уже настроенных интеграций. Если настраиваете новую логику, используйте вместо него proxy_score и proxy_signs — они определяют и VPN, и прокси.

Для интеграции DFP в мобильное приложение поле актуально.

details.webview

true, false

Открыт ли ваш ресурс внутри другого приложения (WebView), например, по ссылке в мессенджере, а не в обычном браузере.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

details.new_user

true, false

Впервые ли ваш ресурс посещают из этого клиентского окружения.

details.confidence_score

Число от 0 до 1

Степень уверенности в том, что user_id определён правильно.

Если DFP встречает окружение, которое раньше не посещало ваш ресурс (new_user: true), то выдаёт ему новый user_id. В таких случаях confidence_score всегда равен 1.

Если DFP встречает окружение, которое уже посещало ваш ресурс, то выдаёт связанный с ним user_id. В этом случае confidence_score может отличаться от 1. Чем ниже значение, тем больше параметров текущего окружения отличается от набора, который DFP видел раньше. Но совпадений всё ещё достаточно, чтобы распознать его.

custom_data

Строка

Строка, которую вы передали в запросе через параметр customData. DFP возвращает её без изменений.

В веб-коде параметр называется customData, а в Servicepipe Mobile SDK он передаётся через метод FingerprintOptions.withCustomData(). При этом в расшифрованном payload параметр возвращается как custom_data. Пусть отличие в названиях вас не пугает — поле то же самое и значение вернётся то, которое вы задали. Просто в клиентском коде используется привычный для платформы формат имени, а в JSON-ответе DFP — формат snake_case.

referer_md5

MD5-хеш

Хеш значения заголовка Referer.

Значение Referer — это URL страницы, где была запущена библиотека DFP. Сам URL в ответ не попадает, вы получаете только хеш. Его удобно использовать для сравнения и группировки запросов: например, чтобы отфильтровать DFP-проверки, которые пришли с одной и той же страницы.

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

timestamp

Unix timestamp в миллисекундах

Время, когда DFP сформировал результат анализа, который вы видите в этом payload.

Настройте бэкенд так, чтобы не доверять ответам старше нескольких секунд. Эта мера защитит вас от replay-атаки (атаки повторного воспроизведения). Подробнее.

user_id

Строка, в том числе пустая

Стабильный идентификатор клиентского окружения.

При интеграции на сайт для запросов с white_bot: true DFP не вычисляет user_id и возвращает пустую строку ("user_id": "").

Говоря проще, это ID, который описывает уникальную связку «конкретный браузер + конкретное устройство» (DFP для сайта) или уникальное устройство (DFP для мобильного приложения). ID остаётся стабильным, даже когда пользователь меняет разные настройки. Например, если он:

  • включит VPN;

  • обновит ОС;

  • поменяет время на компьютере/телефоне;

  • откроет инкогнито в браузере;

  • обновит версию браузера.

ID будет тем же самым, ведь главный критерий выполняется: устройство и браузер остались те же. А вот если пользователь откроет другой браузер или сделает запрос с нового устройства, вы увидите другой ID.

Протестировать, как это работает, вы можете в нашем playground: открывайте эту страницу из разных источников, меняйте свои настройки — вы увидите, что User ID не поменяется, пока вы не смените браузер/устройство.

version

Число

Версия ядра нашего ПО, которое лежит в основе DFP.

white_bot

true, false

От доверенного ли источника пришёл запрос.

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

Поле присутствует в payload только при интеграции DFP на сайт. При интеграции в мобильное приложение его не будет.

Запросы с white_bot: true рекомендуем автоматически пропускать на вашем бэкенде. Для них DFP не вычисляет user_id и возвращает в этом поле пустую строку ("user_id": "").

Как использовать эти данные

Советы по интерпретации значений из полей ответа читайте в статье Как интерпретировать ответ DFP.

Также мы подготовили для вас инструкции, как использовать DFP для конкретных бизнес-задач: