События SDK

SDK уведомляет о ключевых этапах проверки визита. Вы можете подписаться на события, чтобы перенаправить пользователя после проверки, отправить данные в аналитику или обработать ошибки.

Какие события доступны

Событие	Данные	Описание
ready	—	SDK завершил проверку — fingerprint собран, вердикт получен, challenge (если требовался) завершён. Безопасно продолжать
fraud-detected	{ verdict: Verdict }	Визит признан фродовым
challenge-shown	—	Challenge показан пользователю
challenge-complete	{ passed: boolean }	Challenge завершён. passed — пройден (true) или нет (false)
error	unknown	Произошла ошибка при работе SDK. Обработчик получает ошибку напрямую, без обёртки в объект

Объект Verdict

Поле	Тип	Описание
fraud	boolean	true, если визит признан фродовым
reasons	string[]	Причины — названия сработавших правил
traffic_back	boolean?	Нужно ли перенаправить пользователя (traffic back)
challenge	boolean?	Нужно ли показать challenge
challenge_design	string?	Идентификатор шаблона challenge

Как подписаться

Добавьте обработчик через window.adsafee.push(). Подписаться можно до загрузки SDK — обработчики будут вызваны автоматически, когда SDK загрузится:

(window.adsafee = window.adsafee || []).push({
  on: 'ready',
  handler: function() {
    console.log('Проверка завершена');
  }
});

Одноразовая подписка

Используйте once вместо on — обработчик сработает один раз и будет удалён:

(window.adsafee = window.adsafee || []).push({
  once: 'fraud-detected',
  handler: function(data) {
    console.log('Обнаружен фрод', data.verdict);
  }
});

Отписка

Передайте ту же функцию, которую использовали при подписке:

function onError(err) {
  console.error(err);
}

// Подписаться
(window.adsafee = window.adsafee || []).push({
  on: 'error',
  handler: onError
});

// Отписаться
window.adsafee.push({
  off: 'error',
  handler: onError
});

Порядок событий

1. SDK загружается и собирает данные о визите
2. Отправляет данные на проверку и получает вердикт
3. Если визит признан фродом — срабатывает fraud-detected
4. Если требуется challenge — срабатывает challenge-shown, после завершения — challenge-complete
5. Когда вся проверка завершена — срабатывает ready
6. При ошибке на любом этапе — срабатывает error

Шаги 3 и 4 срабатывают только при необходимости. Событие ready срабатывает всегда — даже если не было ни фрода, ни challenge.

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

Подпишитесь на ready, чтобы выполнить действие после полной проверки — например, перенаправить пользователя или разблокировать контент.

Ошибки не блокируют работу

Событие error сообщает о проблемах, но не останавливает SDK. Событие ready сработает в любом случае — и при успешной проверке, и после ошибки.

Примеры

Перенаправление после проверки

(window.adsafee = window.adsafee || []).push({
  once: 'ready',
  handler: function() {
    window.location.href = '/thank-you';
  }
});

Отправка данных о фроде в аналитику

(window.adsafee = window.adsafee || []).push({
  on: 'fraud-detected',
  handler: function(data) {
    gtag('event', 'fraud_detected', {
      reasons: data.verdict.reasons.join(', ')
    });
  }
});

Отслеживание результатов challenge

(window.adsafee = window.adsafee || []).push({
  on: 'challenge-complete',
  handler: function(data) {
    console.log(data.passed ? 'Challenge пройден' : 'Challenge провален');
  }
});

Мониторинг ошибок

(window.adsafee = window.adsafee || []).push({
  on: 'error',
  handler: function(err) {
    Sentry.captureException(err);
  }
});

Что дальше

• Настроить challenge — когда и как включить интерактивную проверку
• Обработать фродовый трафик — пометить, перенаправить или заблокировать
• Справочник метрик — все метрики, включая Challenge Total и Challenge Pass