Справочник по вердиктам

Каждый вердикт Fraud Prevention — доставлен ли он в ваш колбэк onVerdict в Web SDK или получен из Data API — это один и тот же объект BotVerdict. На этой странице описано каждое поле и как на него реагировать.

{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "reasons": [],
  "consistency": { "ok": true },
  "degraded": false,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "verdict_token": "vt1.eyJ2Ijoi...",
  "verdict_token_exp": 1767225600
}

Поля

Поле	Тип	Описание
is_bot	boolean	Основной вердикт. true = визит признан автоматизированным или недействительным трафиком; false = он выглядит как реальный человек. Это единственное поле, по которому ветвится большинство интеграций.
score	number (0–100)	Насколько подозрителен визит. Чем выше, тем подозрительнее. Используйте его, чтобы задать собственные пороги — например, исключать визиты выше выбранной вами отсечки. Точное значение производится нашей моделью рисков и не предназначено для обратной разработки.
level	enum	Грубая полоса значения score: low, medium, high, critical. Удобно, когда нужны корзины вместо сырого числа.
action	enum	Наша рекомендуемая обработка визита: record_only, challenge, flag или deny. См. ниже. Неизвестные значения обрабатывайте как flag, чтобы интеграция продолжала работать при добавлении новых значений.
reasons	string[]	До трёх общих категорий причин, объясняющих рискованный вердикт. Пусто для чистых визитов.
consistency	object	Вывод о согласованности между сигналами. Читайте consistency.ok (boolean): true = сигналы визита сходятся как ожидалось; false = что-то не сошлось, и визит заслуживает дополнительного внимания. Внутренняя детализация, стоящая за этим выводом, не раскрывается.
degraded	boolean	true, когда вердикт не удалось полностью вычислить (сервис недоступен, ошибка и т. д.) и был возвращён консервативный запасной вариант. Относитесь к деградированным вердиктам как к «неизвестно», а не «чисто».
verdict_id	string	Уникальный id этого вердикта. Используйте его, чтобы позже найти вердикт через Data API.
verdict_token	string	Подписанное подтверждение этого вердикта для проверки вашим сервером. См. Серверную проверку. Отсутствует в запасных вердиктах.
verdict_token_exp	number	Время Unix (секунды), когда истекает verdict_token.

action — что делать

action — это наша рекомендация; окончательное решение остаётся за вами.

action	Значение	Что делать
record_only	Визит выглядит нормально.	Продолжайте как обычно. Просто логируйте вердикт для отчётности и сверки.
flag	Визит подозрителен, но не однозначно плох.	Продолжайте показывать страницу, но пометьте визит как низкокачественный — исключите его из метрик, выделите из нижестоящих потоков и учтите его вес в собственных решениях (например, в атрибуции конверсий или в том, насколько вы доверяете визиту).
challenge	Визит достиг вашего порога challenge (по умолчанию — высокий риск).	Запросите одну дополнительную проверку, прежде чем относиться к посетителю как к человеку. Когда действие обработки вашего приложения установлено в challenge, Web SDK выполняет её за вас (см. Эскалацию); иначе примените собственный шлюз.
deny	Визит совпал с правилом блокировки — например, записью чёрного списка или политикой, которую вы настроили на блокировку.	Не отдавайте защищённый контент. Проверка не предлагается. Старые версии SDK передают это значение без изменений, поэтому обрабатывайте его в onVerdict.

Настраиваемое действие обработки

То, что action сообщает для высокорискового визита, — это конфигурация на уровне приложения, задаваемая в панели управления в деталях вашего приложения. Вердикт авторитетен на стороне сервера: action становится challenge или flag, только когда визит достигает высокорисковой полосы и ваше приложение настроено на соответствующее действие. Ниже этой полосы вердикт остаётся record_only.

Настройка	action, возвращаемое при высоком риске	Значение
record_only (по умолчанию)	record_only	Только запись. Вердикт логируется для отчётности и сверки; от посетителя ничего не запрашивается.
challenge	challenge	Запуск повторной проверки CAPTCHA. Web SDK показывает challenge (стилизация управляется через challengeConfig в SDK).
flag	flag	Пометка визита. Вердикт несёт flag; ваша интеграция сама решает, как на это реагировать (блокировать / сегментировать / обработать).

Поскольку решение принимается на стороне сервера, ваш код остаётся простым: читайте verdict.action в onVerdict и реагируйте на него — продолжайте, блокируйте или позвольте SDK показать challenge. Вам не нужно заново выводить риск самостоятельно.

Порог и тип проверки

Если действие — challenge, в том же разделе панели появляются ещё две настройки:

• Порог проверки — с какого уровня риска возвращается настроенное действие. По умолчанию — высокий риск и выше. В строгом режиме оно применяется и к визитам со средним риском: останавливается больше парсеров и ИИ-агентов, но проверку видит больше реальных посетителей.
• Тип проверки — минимальный тип CAPTCHA при эскалации: слайдер (по умолчанию), поворот, клик или 3D-клик. Чем сильнее тип, тем сложнее его решить автоматизированным и ИИ-инструментам.

escalate_result

Присутствует после того, как отработала управляемая эскалация captcha — то есть когда action был challenge и SDK запустил captcha. null, если эскалации не было. Также передаётся в onEscalateDone(passed, detail).

поле	описание
passed	прошёл ли посетитель captcha
token	pass token captcha — проверьте его на сервере, чтобы подтвердить прохождение (не доверяйте только клиентскому passed)
challenge_id	id challenge captcha
cid	click id, с которым связана эта эскалация, если был передан click token

reasons — категории причин

reasons в общих чертах объясняет, почему визит выглядел рискованным. Содержит не более трёх категорий, от самой сильной. Никогда не содержит отдельных сигналов или разбивки score.

Категория	Значение
automation	Признаки автоматизированных инструментов, например скриптовых или headless-браузеров.
network	Сеть выглядит рискованной или несогласованной, например прокси, дата-центр или анонимизирующая сеть, либо заблокированный адрес.
abnormal_requests	Необычные паттерны запросов, например слишком много запросов, повторяющиеся сбои или история автоматизированного трафика.
device	Устройству или его окружению нельзя было доверять, либо их не удалось распознать.
behavior	Визит вёл себя не как человек, например полное отсутствие взаимодействия или повторно использованная ссылка.
other	Любая другая причина, включая ваши собственные правила и запасные вердикты.

Используйте этот список как пояснение для отчётов, а не как сигнал для построения правил. Ветвитесь по is_bot, action или score. Новые категории могут быть добавлены позже.

Серверная проверка

Всё, что получает страница, посетитель может изменить. Если вы ограничиваете доступ к контенту (только реальные люди могут видеть страницу, ответ API или загрузку), не доверяйте флагу is_bot в браузере. Отправьте verdict_token на свой сервер и проверьте его там:

1. В onVerdict отправьте verdict.verdict_token на свой бэкенд, например в заголовке или cookie.
2. Ваш бэкенд вызывает POST /v1/bot/verdict/verify с токеном и IP-адресом посетителя.
3. Отдавайте контент только тогда, когда в ответе valid: true и вердикт для вас приемлем (например, verdict.is_bot равно false).

Токен привязан к вашему приложению, к этому вердикту и к сети посетителя и истекает через короткое время (по умолчанию 10 минут). По умолчанию токен можно проверять много раз, так что один токен покрывает просмотры страниц в рамках визита. Передайте consume: true, когда токен должен использоваться только один раз, например для отправки формы.

Если затем посетитель проходит проверку эскалации, токен всё равно отражает исходный вердикт. Также проверьте pass token captcha из escalate_result через серверный API captcha.

level и score

level — это просто разбивка score на полосы, предоставляемая для удобства:

level	Когда использовать
low	Считайте чистым трафиком.
medium	Пограничный — записывать можно, стоит рассмотреть исключение из высокоценных воронок.
high	Сильно подозрительный — пометьте и исключите.
critical	Почти наверняка недействительный — пометьте/исключите и, в идеале, эскалируйте.

Выбирайте поле под ваш конвейер

• Простой шлюз да/нет → ветвитесь по is_bot.
• На основе рекомендации → ветвитесь по action.
• Собственные пороги → ветвитесь по score (или по level для корзин).

Обработка деградированных вердиктов

Когда degraded равно true, вердикт не был полностью вычислен. Запасной вариант намеренно консервативен (is_bot: false, action: record_only), поэтому реальные пользователи никогда не блокируются. В отчётности относитесь к таким визитам как к неизвестным, а не считайте их подтверждённо чистым трафиком.

Дальнейшие шаги

• Web SDK — получайте вердикты на вашей странице
• Data API — получайте вердикты и статистику на стороне сервера