Powered by

Размеры и адаптив

SDK сам управляет размерами плеера: он берёт «натуральный» размер креатива из ответа ad-сервера и подгоняет его под доступное пространство в вёрстке. Этот документ объясняет, как именно работает ресайз и как им управлять.

Как SDK выбирает размер

При первом креативе и при каждом ресайзе родительского блока SDK проделывает следующее:

  1. Берёт исходный размер креатива — width × height, заданные на сервере.
  2. Определяет ограничивающий блок — это родитель контейнера, в который SDK был смонтирован (или сам контейнер, если родителя нет).
  3. Если ширина ограничивающего блока меньше ширины креатива или у блока явно задана width/max-width в стилях — SDK ужимает плеер по ширине ограничивающего блока, сохраняя aspect ratio креатива.
  4. Если у ограничивающего блока задана height или max-height — высота плеера дополнительно ограничивается этим значением, ширина пересчитывается через aspect ratio.
  5. Иначе — плеер занимает натуральные размеры креатива.

Между ресайзами и сменой креативов работает плавная CSS-анимация (transition: width/height ease). Отключить её — disableAnimations: true в конфиге.

Изменения размеров родительского блока отслеживаются через ResizeObserver — плеер автоматически перестраивается при ресайзе окна, изменении ориентации устройства или динамической вёрстке.

Алгоритм выше — для inline-форматов (video, multiformat, carouselMultiformat). Модалка живёт поверх страницы, бегущая строка фиксирует высоту — см. разделы ниже.

Форматы, которые считаются иначе

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

Полоса занимает всю ширину ограничивающего блока. Высота не берётся из креатива:

Ширина контейнера Высота полосы
≥ 960 px 90 px
< 960 px 60 px

Картинка масштабируется по высоте полосы и едет горизонтально. Задавать height контейнеру не нужно — достаточно ширины (например width: 100% или max-width: 100%).

Карусель (carouselMultiformat)

Высота считается от ширины контейнера и aspect ratio слайда (displayOptions.size). Сколько слайдов видно в ряд — зависит от ширины: SDK уменьшает число колонок, пока на слайд не останется минимум 200 px (плюс отступ между слайдами).

  • На широких экранах (≥ 769 px) рисуются стрелки, «уши» соседнего слайда скрыты.
  • На узких — свайп и peek соседнего слайда.
  • Если включён заголовок блока (useHeader), над слайдами добавляется ещё ~48 px.

Контейнеру лучше задать width: 100% или max-width: 100%, как обычному баннеру. Фиксировать высоту карусели не нужно — она пересчитается сама.

Модалка (modalwindow)

Модалка не занимает место в потоке контейнера. SDK монтируется в переданный container, но окно позиционируется fixed относительно viewport: нижняя шторка, карточка в углу или почти на весь экран — см. Форматы.

  • На время показа блокируется скролл страницы; при закрытии overflow у body возвращается.
  • width/height контейнера на размер окна почти не влияют: геометрию задаёт displayOptions и ширина viewport.
  • Если у предков контейнера есть transform, filter, perspective или contain, SDK перенесёт iframe к document.body, чтобы overlay покрыл экран.

Резервировать min-height под модалку в вёрстке не нужно — иначе останется пустая дыра.

Типовые сценарии

Фиксированная ширина

<div id="ad" style="width: 600px;"></div>

Плеер будет максимум 600 px шириной. Если креатив больше — он ужимается с сохранением пропорций. Если меньше — отображается в натуральную величину (не растягивается).

Фиксированная высота

<div id="ad" style="height: 400px;"></div>

Плеер ограничен по высоте. Ширина пересчитывается через aspect ratio креатива.

Полная ширина родителя (responsive)

<div id="ad" style="width: 100%;"></div>

Плеер растянется на ширину родительского блока. При ресайзе окна высота автоматически пересчитается.

Без ограничений

<div id="ad"></div>

Без width/height/max-* плеер примет натуральный размер креатива. Подходит для десктопа с местом «под креатив», но на узких экранах может вылезать за viewport — лучше задать хотя бы max-width: 100%.

Внутри flex/grid

<div style="display: flex;">
    !!!
...
!!!
    <div id="ad" style="flex: 1; min-width: 0;"></div>
</div>

Работает как «фиксированная ширина» — SDK подхватит реальную ширину flex-ячейки. Не забудьте min-width: 0, иначе flex-элемент не даст плееру ужаться.

SPA / динамические контейнеры

ResizeObserver пересоздаётся при инициализации плеера. Если ваш SPA удаляет и пересоздаёт контейнер с тем же id, нужно вручную:

  1. Вызвать player.destroy() перед удалением старого контейнера.
  2. После маунта нового контейнера снова вызвать window.MadsPlayer({...}).

См. Варианты интеграций.

Что НЕ работает

  • CSS aspect-ratio на контейнере — SDK сам управляет высотой и перепишет ваш aspect-ratio. Если нужно зафиксировать соотношение сторон, делайте это на родительском блоке через padding-trick или фиксированную высоту.
  • Трансформации (transform: scale) — ResizeObserver отслеживает «layout-размер» контейнера, а не визуальный после трансформации. Плеер будет считать, что у него исходные размеры.
  • Контейнер display: none — clientWidth будет 0, и SDK не сможет посчитать целевую ширину. Прячьте плеер через visibility: hidden или удаляйте через destroy().

FAQ

Креатив выходит за пределы экрана на мобильном. Добавьте max-width: 100% контейнеру или его родителю — SDK ужмёт плеер.

После ресайза окна плеер не подстраивается. Проверьте, что у родительского блока есть какое-либо ограничение (width, max-width, или хотя бы он сам не растягивается шире viewport). Без ограничения SDK считает, что ему можно занять натуральный размер.

Плеер «прыгает» при смене креатива в multiformat. Это нормально для ленты с разными размерами креативов — между ними играет fade + width/height анимация. Если нужен мгновенный переход — disableAnimations: true.

Хочу зафиксировать высоту, чтобы не было layout shift. Задайте контейнеру min-height: <px> под ожидаемый размер креатива. SDK не будет уменьшать высоту ниже, если креатив окажется меньше — но может увеличить, если креатив больше. Для modalwindow min-height не нужен: окно рисуется поверх страницы.