Powered by

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

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-анимация (см. Размеры и адаптив про disableAnimations).
  • Клик по любому креативу ведёт по link.url этого креатива.
  • Видеоэлементы с overlay ведут себя так же, как в формате video (плашка + postview).

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

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

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

Подробнее про высоту — в Размерах и адаптив.

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.
  • Каждый слайд отправляет свои пиксели показа, видимости и клика. Подробнее — События и трекинг.
  • Слайды могут быть image и video вперемешку; у видео работает тот же overlay / postview, что в video.

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

Режим показа задаёт 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.