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

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.

Особенности форматов

Карусель (carouselMultiformat) Пиксели impression / viewin / play / click и условные пиксели отправляются по каждому слайду, а не один раз на весь блок. Блочная статистика из корня ответа (statistics визита) по-прежнему общая. Паблишеру ничего дополнительно вызывать не нужно.

Модалка (modalwindow) Терминальное событие — только skip (крестик, Escape, skip() в sdk-режиме). Событие completed и колбэк onCompleted не вызываются.

viewableImpression / unviewableImpression Пара пикселей видимости: viewableImpression уходит, когда плеер в фокусе вкладки и в viewport; unviewableImpression — если вкладка в фоне или плеер вне экрана. Срабатывает один раз за креатив (за слайд — в карусели).

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

Помимо пиксельных событий, 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). Если нужны события, которых нет в таблице выше (например, «пользователь долистал карусель руками до слайда 4» в своей аналитике), добавьте логику в колбэки и отправляйте их самостоятельно. Показы и клики слайдов карусели SDK уже учитывает сам.