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

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

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

1. **Внутри SDK** срабатывает условие (например, креатив попал в viewport на 50%).
2. SDK эмитит **событие** из набора `CurrentEvents` (см. таблицу ниже).
3. На каждое событие:
   - Отправляются **пиксели** — все 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 подставит из конфига:

```js
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 уже учитывает сам.