События SDK

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

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

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

Объект Verdict

Поле	Тип	Описание
traffic_signals	TrafficSignal[]	Публичные сигналы классификации визита
traffic_back	boolean?	Нужно ли перенаправить пользователя (traffic back)
challenge	boolean?	Нужно ли показать challenge
challenge_design	string?	Идентификатор шаблона challenge

Объект TrafficSignal

Поле	Тип	Описание
scope	"givt" | "sivt" | "context"	Тип сигнала: явный невалидный трафик, подозрительный трафик или контекст для правил
name	string	Публичное имя сигнала, например known_crawler, click_rate_limit, device_spoofing, hosting_like, proxy_like
confidence	"low" | "medium" | "high"	Уверенность сигнала

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

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

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

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

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

(window.adsafee = window.adsafee || []).push({
  once: 'verdict',
  handler: function(verdict) {
    console.log('Вердикт получен', verdict.traffic_signals);
  }
});

Отписка

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

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. Срабатывает verdict с публичными traffic signals
4. Если требуется challenge — срабатывает challenge-shown, после завершения — challenge-complete
5. Когда вся проверка завершена — срабатывает ready
6. При ошибке на любом этапе — срабатывает error

Challenge-события срабатывают только при необходимости. Событие ready срабатывает всегда — даже если не было ни сигналов, ни challenge.

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

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

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

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

Примеры

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

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

Отправка traffic signals в аналитику

(window.adsafee = window.adsafee || []).push({
  on: 'verdict',
  handler: function(verdict) {
    gtag('event', 'adsafee_verdict', {
      signals: verdict.traffic_signals
        .map(function(signal) {
          return signal.scope + '/' + signal.name + '/' + signal.confidence;
        })
        .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