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

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

---

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

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

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

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

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

---

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

```html
<!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. Конфигурация

```ts
window.MadsPlayer(config: UserConfig)
```

| Поле                | Тип                          | Обязательный | Описание                                                                 |
|---------------------|------------------------------|--------------|--------------------------------------------------------------------------|
| `container`         | `string \| Element`          | да           | CSS-селектор или DOM-элемент, в который SDK вставит плеер                |
| `padId`             | `number \| string`           | да           | ID рекламного места                                                      |
| `userId`            | `string`                     | нет          | Идентификатор пользователя на вашей площадке. Уходит в запрос ad-сервера |
| `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`                    | нет          | Зациклить воспроизведение (только `default` режим, не для модалки)       |
| `virtualVisit`      | `VisitResult \| null`        | нет          | Готовый ответ ad-сервера (для тестов / кастомных сценариев)              |

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

---

## 4. Колбэки

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

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

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

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

```js
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()`:

```js
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>`)                  |

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

```html
<!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 мгновенно.

**Как передать своего пользователя в ad-сервер.**
Передайте `userId` в конфиг — SDK добавит его в запрос креативов. Это тот же идентификатор, что в Mobile SDK и в API (`userId`). Без него реклама приходит, но без персонализации.