# События и трекинг

SDK сам отправляет аналитические пиксели в Magnit Ads — паблишеру не нужно ничего настраивать вручную. Но если вы строите свою аналитику поверх SDK или вам нужно понять, что SDK уже учитывает, эта страница для вас.

# Жизненный цикл события

Внутри SDK срабатывает условие (например, креатив попал в viewport на 50%).
SDK эмитит событие из набора CurrentEvents (см. таблицу ниже).
На каждое событие:
- Отправляются пиксели — все URL из statistics, тип которых совпадает с одним из алиасов события (см. ниже).
- Вызывается колбэк паблишера, если он существует и сопоставлен с этим событием.

# Таблица событий

Событие	Когда происходит	Колбэк	Алиасы пикселей
`viewin`	Контейнер попал в viewport (intersection ratio ≥ 0.5)	—	`viewin`, `render`
`impression`	Viewport ≥ 50% И вкладка в фокусе И видимость ≥ 50%	—	`impression`, `viewin`, `render`
`ready`	Креатив готов к показу	`onReady`	`start`
`play`	Первый старт воспроизведения	`onPlayed`	`play`, `playbackStarted`, `start`
`resume`	Возобновление после паузы	`onResumed`	`playbackResumed`
`pause`	Пауза	`onPaused`	`pause`, `playbackPaused`
`completed`	Креатив доигран до конца естественным путём	`onCompleted`	`playbackCompleted`
`skip`	Пользователь закрыл/пропустил креатив (`closedByUser`)	`onSkipped`	`closedByUser`
`click`	Клик по креативу или CTA-кнопке	`onClicked`	`click`, `ctaClick`
`stop`	Плеер остановлен явно	`onStopped`	(нет алиасов — отправляются только пиксели типа `stop`)

События viewin и impression не имеют пользовательских колбэков — они нужны только для отправки пикселей видимости. Если вам нужно отслеживать момент, когда креатив увидели, ориентируйтесь на onReady и onPlayed.

# Условные пиксели

Помимо пиксельных событий, SDK поддерживает условные пиксели — те, у которых в statistics указаны поля:

value — пиксель срабатывает, когда время воспроизведения креатива достигло value миллисекунд.
pvalue — пиксель срабатывает, когда воспроизведение достигло pvalue процентов длительности.
viewablePercent — пиксель срабатывает только при достижении заданного процента видимости плеера.

Эти условия могут комбинироваться: например, «отправь пиксель когда воспроизвели 50% креатива и плеер виден минимум на 75%».

Каждый условный пиксель отправляется ровно один раз за креатив.

# Дедупликация

Тип события	Поведение
`resume`, `pause`, `click`, `viewin`	Отправляются повторно при каждом срабатывании
Все остальные	Отправляются один раз за креатив

При смене креатива в multiformat ленте контекст «креативных» пикселей сбрасывается, а ранее отправленные общие события (viewin, impression) переотправляются на статистику нового креатива — чтобы сервер видел, что новый креатив тоже был просмотрен.

# Подстановка макросов

В URL пикселей можно использовать плейсхолдеры в квадратных скобках, которые SDK подставит из конфига:

window.MadsPlayer({
    container: '#ad',
    padId: 193,
    macro: {
        user_id: 'abc-123',
        session_id: 'xyz',
    },
});

Если в URL пикселя есть [user_id] — он будет заменён на abc-123 (URL-encoded). Это удобно для интеграции своей аналитики поверх стандартных пикселей Magnit Ads — обсудите с командой, какие плейсхолдеры можно вставить в шаблон креативов.

# Технические детали отправки

Транспорт: fetch(url, { mode: 'no-cors', keepalive: true }). Ответ сервера не читается — это пиксельный запрос.
Таймаут: 8 секунд. Если пиксель не отправился за это время, в консоль логируется warning.
Beacon на unload: при закрытии вкладки оставшиеся в очереди пиксели досылаются через navigator.sendBeacon.
Дубликаты внутри одного tick: один и тот же URL не отправляется дважды, пока предыдущий запрос не завершился.

# Что НЕ трекается автоматически

SDK не отправляет ничего за пределы пикселей из statistics ad-сервера и собственной телеметрии (mads-track.magnit.ru). Если вам нужны кастомные события (например, «пользователь дошёл до видео №3 в карусели») — добавьте свою логику в колбэки и отправляйте события в свою аналитику самостоятельно.