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

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

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

Протестировать работу DFP вы можете в нашем playground. Там вы увидите результат анализа вашего окружения: ваш user_id. bot_score, vpn, 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

Алгоритм и формат шифрования payload.

iv

Строка в Base64

Вектор инициализации. Используется при расшифровке payload.

payload

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

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

request_id

Строка

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

tag

Строка в Base64

Тег аутентификации AES-GCM. Нужен для проверки целостности и расшифровки payload.

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

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

{
  "details": {
    "bot_score": 0.215,
    "engine": "blink",
    "hosting": false,
    "incognito": false,
    "mobile": false,
    "os": "macos",
    "vpn": true
  },
  "user_id": "7d052a5b7e99b6d528646708f3422e6f",
  "referer_md5": "9f0b84073da2ef97a63c2f4179981a2e",
  "timestamp": 1780406318499,
  "version": 1,
  "custom_data": "action=signin"
}

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

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

details.bot_score

Число от 0 до 1

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

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

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

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

details.engine

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

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

details.hosting

true, false

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

details.incognito

true, false

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

details.mobile

true, false

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

details.os

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

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

details.vpn

true, false

Включен ли VPN.

user_id

Строка

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

Говоря проще, это ID, который описывает связку браузер+устройство. Он остаётся стабильным, даже если пользователь поменяет какие-то настройки устройства/браузера/сети, например:

  • включит VPN,

  • обновит ОС,

  • включит режим инкогнито,

  • поменяет время на компьютере,

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

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

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

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

referer_md5

MD5-хеш

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

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

timestamp

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

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

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

version

Число

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

custom_data

Строка

Данные, которые вы передали в запросе через customData.

В клиентском коде параметр называется customData, а в расшифрованном payload он возвращается как custom_data. Пусть это вас не пугает — поле то же самое и значение вернётся то, которое вы задали. Разница только в формате имени. customData — параметр JavaScript-метода, и в нём используется привычный для JavaScript формат camelCase. А custom_data — поле JSON-ответа, поэтому используется snake_case.

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

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

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