# Быстрый старт — Web

Документ описывает минимальную интеграцию SDK на сайт.

# 1. Подключение

Подключите один тег <script> в <head> или перед закрывающим </body>:

<script async src="https://mads-media.magnit.ru/web-sdk/current/wrapper.js"></script>

Файл main.js подгружается автоматически из той же директории, что и wrapper.js — отдельно подключать его не нужно.

После загрузки на window появляется функция MadsPlayer(config).

# 2. Минимальный пример (Default mode)

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">
    <title>MADS Player</title>
</head>
<body>
    <div id="ad-container"></div>

    <script async src="https://mads-media.magnit.ru/web-sdk/current/wrapper.js"></script>
    <script>
        window.MadsPlayer({
            container: '#ad-container',
            padId: 193,
            onReady: () => console.log('Плеер готов'),
            onError: () => console.warn('Ошибка SDK'),
        });
    </script>
</body>
</html>

В режиме default плеер сам стартует при попадании в зону видимости (≥50%) и фокусе вкладки. Никаких дополнительных вызовов не требуется.

Важно: padId обязателен. Если вы передаёте параметр ?pad_id=... в URL страницы — он перекроет значение из конфига (удобно для тестирования).

# 3. Конфигурация

window.MadsPlayer(config: UserConfig)

Поле	Тип	Обязательный	Описание
`container`	`string \\| Element`	да	CSS-селектор или DOM-элемент, в который SDK вставит плеер
`padId`	`number \\| string`	да	ID рекламного места
`mode`	`'default' \\| 'sdk'`	нет	Режим работы. По умолчанию `'default'`
`playerUrl`	`string`	нет	Кастомный URL `main.js`. По умолчанию определяется по пути `wrapper.js`
`customUrl`	`string`	нет	Кастомный endpoint ad-сервера
`macro`	`Record<string, string>`	нет	Подстановки в URL пикселей
`disableAnimations`	`boolean`	нет	Отключить fade-out анимацию при `destroy()`
`loop`	`boolean`	нет	Зациклить воспроизведение
`virtualVisit`	`VisitResult \\| null`	нет	Готовый ответ ad-сервера (для тестов / кастомных сценариев)

Плюс любые из колбэков ниже.

# 4. Колбэки

Все колбэки опциональны. Колбэки жизненного цикла вызываются без аргументов; onError получает объект с деталями ошибки.

Колбэк	Аргумент	Когда вызывается
`onReady`	—	Плеер готов к воспроизведению
`onPlayed`	—	Старт воспроизведения креатива
`onPaused`	—	Пауза
`onResumed`	—	Возобновление после паузы
`onCompleted`	—	Креатив доигран до конца
`onSkipped`	—	Пользователь нажал «пропустить»
`onClicked`	—	Клик по CTA-кнопке или по креативу
`onStopped`	—	Плеер остановлен явно
`onError`	`{message, code, severity}`	Критическая ошибка SDK (см. ниже)

onError срабатывает только для критических ошибок (после которых плеер уничтожается). Объект:

{
    message: string;            // Человеко-читаемое сообщение
    code: 'UNKNOWN' | 'NETWORK_ERROR' | 'CONFIG_ERROR'
        | 'NO_ADS' | 'RENDER_ERROR' | 'TIMEOUT' | 'INIT';
    severity: 'critical' | 'warning' | 'info';
}

window.MadsPlayer({
    container: '#ad-container',
    padId: 193,
    onReady:     () => console.log('ready'),
    onPlayed:    () => console.log('played'),
    onPaused:    () => console.log('paused'),
    onResumed:   () => console.log('resumed'),
    onCompleted: () => console.log('completed'),
    onSkipped:   () => console.log('skipped'),
    onClicked:   () => console.log('clicked'),
    onStopped:   () => console.log('stopped'),
    onError:     (e) => console.log('error', e.code, e.message),
});

# 5. Уничтожение плеера

MadsPlayer(...) возвращает объект с методом destroy():

const player = window.MadsPlayer({
    container: '#ad-container',
    padId: 193,
});

// Когда плеер больше не нужен
await player.destroy();

destroy() возвращает Promise, который резолвится после fade-out анимации (~300 мс) и удаления DOM-узлов. Чтобы убрать плеер мгновенно, передайте в конфиг disableAnimations: true.

# 6. SDK mode — программное управление

Если вам нужны собственные кнопки play/pause/skip или плеер должен оставаться скрытым до явного запуска, используйте mode: 'sdk'.

В этом режиме:

Контейнер плеера создаётся, но скрыт (display: none) до первого вызова play().
Возвращаемый объект содержит методы управления воспроизведением.
Команды можно вызывать сразу — они буферизуются до готовности iframe и выполняются автоматически. Дожидаться onReady не обязательно.

# Возвращаемые методы

Метод	Действие
`play()`	Показать плеер и запустить воспроизведение
`pause()`	Поставить на паузу
`resume()`	Возобновить после паузы
`stop()`	Остановить воспроизведение
`skip()`	Пропустить текущий креатив
`mute()`	Выключить звук
`destroy()`	Уничтожить плеер (`Promise<void>`)

# Полный пример

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">
    <title>MADS Player — SDK mode</title>
</head>
<body>
    <div class="controls">
        <button id="btn-play">Play</button>
        <button id="btn-pause">Pause</button>
        <button id="btn-resume">Resume</button>
        <button id="btn-stop">Stop</button>
        <button id="btn-skip">Skip</button>
        <button id="btn-mute">Mute</button>
        <button id="btn-destroy">Destroy</button>
    </div>

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

    <script async src="https://mads-media.magnit.ru/web-sdk/current/wrapper.js"></script>
    <script>
        // Дождитесь загрузки wrapper.js — например, через 'load' или DOMContentLoaded
        window.addEventListener('load', () => {
            const player = window.MadsPlayer({
                mode: 'sdk',
                container: '#ad-container',
                padId: 193,
                onReady:     () => console.log('ready'),
                onCompleted: () => console.log('completed'),
                onError:     () => console.log('error'),
            });

            document.getElementById('btn-play').onclick    = () => player.play();
            document.getElementById('btn-pause').onclick   = () => player.pause();
            document.getElementById('btn-resume').onclick  = () => player.resume();
            document.getElementById('btn-stop').onclick    = () => player.stop();
            document.getElementById('btn-skip').onclick    = () => player.skip();
            document.getElementById('btn-mute').onclick    = () => player.mute();
            document.getElementById('btn-destroy').onclick = () => player.destroy();
        });
    </script>
</body>
</html>

# 7. FAQ / Troubleshooting

Плеер не появляется на странице. Убедитесь, что элемент container существует в DOM на момент вызова MadsPlayer(...). SDK сам дожидается DOMContentLoaded, но селектор должен резолвиться — иначе инициализация молча прерывается.

Не приходят креативы / onError срабатывает сразу. Проверьте корректность padId и доступность ad-сервера. Если вы используете нестандартный endpoint — передайте его в customUrl.

Хочу временно подменить ответ ad-сервера в тестах. Передайте готовый объект в virtualVisit — SDK не пойдёт за креативами в сеть.

Как протестировать с другим padId без редеплоя. Откройте страницу с query-параметром ?pad_id=42 — он имеет приоритет над значением из конфига.

Нужно убрать плеер без анимации. Передайте disableAnimations: true в конфиг, тогда destroy() удалит DOM мгновенно.