# Форматы креативов

MADS Web SDK выбирает способ отображения креатива на основе поля `templateGroupName` из ответа ad-сервера. Паблишеру не нужно указывать формат вручную — он определяется настройками рекламного места (`padId`).

Этот документ описывает форматы, **реально поддерживаемые SDK сегодня**. По мере добавления новых форматов список будет пополняться.

## Поддерживаемые форматы

| `templateGroupName`    | Что это                                                                 | Контент             |
|------------------------|-------------------------------------------------------------------------|---------------------|
| `video`                | Один видеоролик в контейнере                                            | Только видео        |
| `multiformat`          | Последовательная лента. Вариант **RunningLine** — по `displayOptions.format` | Видео и изображения |
| `carouselMultiformat`  | Слайдер или сетка `1x1`…`6x1`                                           | Видео и изображения |
| `modalwindow`          | Overlay поверх страницы                                                 | Изображение или видео |

`stories` SDK пока не рендерит: контейнер останется пустым, `onError` не сработает.

### `video`

Один видеокреатив, который воспроизводится в контейнере. Используется для классической видеорекламы.

- Aspect ratio задаётся самим креативом (обычно 16:9 или вертикальное видео).
- Звук по умолчанию выключен; включается интеракцией пользователя.
- По окончании автоматически вызывается `onCompleted` и плеер убирается из DOM (в `default` режиме).
- Внутренние fade-переходы между креативами отключены — для видео они не нужны.

Если ad-сервер вернул у креатива поле `overlay`, поверх ролика показывается плашка (логотип, заголовок, описание). После ролика идёт **postview** — карточка с тем же оффером на время `overlay.duration`. Паблишер это не настраивает.

### `multiformat`

Последовательность из нескольких креативов (видео и/или изображений), которые проигрываются один за другим. Каждый креатив может иметь свои размеры — плеер плавно ресайзится между ними.

- Поддерживаются и `image`, и `video` элементы в одной ленте.
- Длительность изображения задаётся ad-сервером (`content.duration`).
- Между креативами есть короткая fade-анимация (см. [Размеры и адаптив](sizing.md) про `disableAnimations`).
- Клик по любому креативу ведёт по `link.url` этого креатива.
- Видеоэлементы с `overlay` ведут себя так же, как в формате `video` (плашка + postview).

#### Бегущая строка (`RunningLine`)

Если в ответе `templateGroupName: multiformat` и `displayOptions.format: 'RunningLine'`, SDK рисует горизонтальную полосу с картинкой, которая циклически проезжает слева направо.

- Только изображения: если в ленте видео, этот креатив показывается как обычный `multiformat`, не как полоса.
- Высота полосы фиксированная: **90 px** при ширине контейнера ≥ 960 px и **60 px** на более узких экранах. Ширина занимает контейнер.
- Скорость и длительность цикла считает SDK; паблишеру ничего настраивать не нужно.

Подробнее про высоту — в [Размерах и адаптив](sizing.md).

### `carouselMultiformat`

Слайдер из нескольких креативов. Вид задаёт `displayOptions.format` с ad-сервера:

| `format`                         | Что видит пользователь                                      |
|----------------------------------|-------------------------------------------------------------|
| `carousel`, `1x1`                | Один слайд, соседние выглядывают «ушами» на узких экранах   |
| `2x1`, `3x1`, `4x1`, `5x1`, `6x1`| Сетка: столько слайдов в ряд, сколько позволяет ширина      |

Поведение:

- На широких контейнерах (≥ 769 px) появляются стрелки. На узких — свайп / перетаскивание и peek соседнего слайда («уши»). Поле `earsWidth` из ответа ad-сервера SDK **игнорирует**: ширина ушей фиксированная.
- Число видимых слайдов уменьшается, если в контейнер не влезает минимум **200 px** на слайд (плюс отступ).
- Автопрокрутка включается ad-сервером (`useAutoScroll`, `autoScrollTimeout`). Пока в видимом окне играет видео, таймер не тикает — переход ждёт окончания ролика / postview.
- Опциональный заголовок и подзаголовок блока (`header`), если `useHeader: true`.
- Каждый слайд отправляет **свои** пиксели показа, видимости и клика. Подробнее — [События и трекинг](events-and-tracking.md).
- Слайды могут быть `image` и `video` вперемешку; у видео работает тот же `overlay` / postview, что в `video`.

### `modalwindow`

Модальное окно поверх страницы. Контейнер в вёрстке всё равно нужен — SDK монтируется в него, но само окно выезжает overlay на viewport и не занимает место в потоке. См. [Размеры и адаптив](sizing.md) и [Варианты интеграций](recipes.md).

Режим показа задаёт `displayOptions.presentation`:

| `presentation`  | Поведение                                                                 |
|-----------------|---------------------------------------------------------------------------|
| `auto`          | По умолчанию: `bottomSheet` при ширине viewport < 480 px, иначе `cornerFloat` |
| `bottomSheet`   | Нижняя шторка на всю ширину, затемнение фона                              |
| `cornerFloat`   | Карточка в углу viewport (по умолчанию ~360 px)                           |
| `fullscreen`    | Почти на весь экран, затемнение фона                                      |

Закрытие:

- Крестик, клавиша Escape или `skip()` в `sdk` режиме → колбэк `onSkipped`.
- В `default` режиме после закрытия плеер уничтожается.
- В `sdk` режиме overlay скрывается, инстанс остаётся — можно снова вызвать `play()`.
- **`onCompleted` не вызывается:** картинка без длительности, видео в модалке зациклено. Терминальное событие для паблишера и пикселей — только `skip`.

Пока модалка открыта, SDK блокирует скролл страницы (`overflow: hidden` на `body`) и возвращает его при закрытии.

Если у предков контейнера есть CSS `transform`, `filter`, `perspective` или `contain`, `position: fixed` ломается. SDK тогда переносит iframe в overlay-root у `document.body`, чтобы окно всё равно покрыло viewport.

## Поведение, общее для всех форматов

**Маркировка (ОРД)**
Каждый креатив, у которого ad-сервер вернул `markingInfo`, отображает блок «Реклама» с ERID. Блок появляется в момент `ready`/`playing`/`pause` и автоматически позиционируется относительно креатива.

**Клики**
Клик по креативу или CTA-кнопке открывает `link.url` в новой вкладке (`window.open(url, '_blank')`) и вызывает колбэк `onClicked`. URL валидируется — открываются только `http(s)://`.

**Окончание**
- В `default` режиме после `onCompleted` (или после `onSkipped` у `modalwindow`) плеер удаляется из DOM.
- В `sdk` режиме плеер ждёт следующих команд от паблишера и не уничтожается сам.
- При `loop: true` плейлист крутится бесконечно (только в `default` режиме; на модалку не влияет).

## Что делать, если формат не отображается

Если ad-сервер вернул `templateGroupName`, который SDK ещё не умеет рендерить, контейнер плеера останется пустым (без ошибки). В этом случае:

1. Проверьте `onError` — он не сработает, потому что это не критическая ошибка.
2. Убедитесь, что `padId` настроен на формат из таблицы выше.
3. Свяжитесь с командой Magnit Ads — возможно, для вашего места требуется обновление SDK.