---
metadata:
  - name: generator
    content: Diplodoc Platform v5.42.1
alternate:
  - https://yandex.uz/support/video/ru/partners/jsapi.md
  - https://yandex.uz/support/video/uz/partners/jsapi.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.uz/support/video/ru/llms.txt

# Передача данных о состоянии видео

Чтобы поиск по видео работал лучше и показывал более подходящие видеоролики, необходимо передавать информацию о событиях, которые помогают отслеживать состояние видеоролика (например, время начала, остановки, перемотки видео и т. д.) и о возможных ошибках. 

## События, которые сообщают о состоянии видео {#events}

Для передачи данных о состоянии видео применяйте механизм [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). Когда в плеере происходит событие (например, начинается воспроизведение видео), в JavaScript-коде вызовите функцию `window.parent.postMessage`. В качестве аргументов функции передайте название события и его параметры (например, позицию прогресс-бара). 


{% cut "Пример использования функции" %}

```javascript
window.parent.postMessage({
    event: <Название события>,
    // дополнительные параметры события
}, '*');
```

{% note info %}

Функция `postMessage` вызывается для родительского объекта `window.parent`, поскольку видео размещается не на основной странице результатов поиска Яндекса, а в отдельном фрейме (в элементе `iframe`).

{% endnote %}


{% endcut %}

Для отображения плеера в приложении поиска по видео для TV и в браузере необходимо передавать обязательные события и их параметры.

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


{% list tabs %}

- Обязательные события

  #|
  ||
  **Событие**
  |
  **Описание**
  |
  **Параметры события**
  ||
  ||
  `inited`
  |
  Инициализация плеера.
  |
  —
  ||
  ||
  `paused`
  |
  Остановка воспроизведения.
  |
  `time` — текущая позиция прогресс-бара в секундах.
  ||
  ||
  `ended`
  |
  Просмотр ролика завершен (достигнут конец ролика).
  |
  `time` — текущая позиция прогресс-бара в секундах.
  ||
  ||
  `started`
  |
  Начало воспроизведения или продолжение воспроизведения после паузы.
  |

  - `time` — текущая позиция прогресс-бара в секундах.

    Если параметр `time` не указан, то по умолчанию его значение равно `0`.

  - `duration` — общая продолжительность ролика в секундах. Секунды можно не округлять.

  - `muted` — признак выключенного звука, может принимать значения `0` или `1`.

  - `quality` — качество видео (возможные значения: `small`, `medium`, `large`, `hd720`, `hd1080`, `highres`, `4K` или `default`).

  ||
  ||
  `timeupdate`
  |
  Воспроизведение ролика (событие повторяется многократно).
  |
  - `time` — текущая позиция прогресс-бара в секундах.

  - `duration` — общая продолжительность ролика в секундах. Секунды можно не округлять.

    Аналогично нативному событию [timeupdate](https://developer.mozilla.org/en-US/docs/Web/Events/timeupdate) у элемента `<video>`.

  ||
  ||
  `error`
  |
  Ошибка воспроизведения, факт недоступности видео.
  |
  - `time` — текущая позиция прогресс-бара в секундах.

  - `code` — [код ошибки](#errors).

  - `message` — сообщение с информацией о типе ошибки.

  ||
  ||
  `adShown`
  |
  Начало показа рекламы.
  |
  - `count` — количество рекламных роликов, которые будут показаны в текущем рекламном блоке.

  - `time` — текущая позиция прогресс-бара в секундах.

  - `ads` — массив с данными списка рекламных роликов. Для каждого ролика в массиве нужны параметры:

    - `duration` — общая продолжительность рекламы в секундах. Секунды можно не округлять.

    - `skip` — возможен пропуск рекламы (в интерфейсе появится соответствующее уведомление), может принимать значения `0` или `1`.

  {% cut "Примеры данных для события adShown" %}

  {% cut "Пример 1" %}

  Если рекламный блок начинает воспроизведение на тридцатой секунде видео и включает в себя два объявления, из которых первое имеет длительность 15 секунд и возможность пропуска, а второе длится 25 секунд и не может быть пропущено, то в событии `adShown` должны присутствовать следующие данные: {#addshown}

  ```
  {
    count: 2,
    time: 30,
    ads: [
      {
        duration: 15.0,
        skip: 1
      },
      {
        duration: 25.3,
        skip: 0
      }
    ]
  }
  ```
  {% endcut %}

  {% cut "Пример 2" %}

  Если имеется блок с единственным рекламным объявлением, который воспроизводится в самом начале видео (`preroll`), длится 45 секунд и не может быть перемотан:

  ```
  {
    count: 1,
    time: 0,
    ads: [
      {
        duration: 45.5,
        skip: 0
      }
    ]
  }
  ```
  {% endcut %}

  {% endcut %}

  {% note info %}

  Допустимо отправлять информацию с параметрами рекламы отдельным событием `beforeAdStart`.

  {% endnote %}

  ||
  ||
  `adEnd`
  |
  Конец показа рекламы.
  |
  `time` — текущая позиция прогресс-бара в секундах.

  ||
  ||
  `contentImpression`
  |
  Показ первого кадра видео.

  {% note info %}

  Если перед началом видео воспроизводится реклама, отправляйте событие, когда после ее окончания появится первый кадр видео.

  {% endnote %}

  |

  `time` — текущая позиция прогресс-бара в секундах.

  ||
  |#

- Дополнительные события

  #|
  ||
  **Событие**
  |
  **Описание**
  |
  **Параметры события**
  ||
  ||
  `rewound`
  |
  Перемотка видео.
  |
  - `time` — текущая позиция прогресс-бара в секундах.

  - `previousTime` — предыдущая позиция прогресс-бара в секундах.
  ||
  ||
  `resumed`
  |
  Возобновление воспроизведения.
  |

  - `time` — текущая позиция прогресс-бара в секундах.

  - `duration` — общая продолжительность ролика в секундах. Секунды можно не округлять.

  - `muted` — признак выключенного звука, может принимать значения `0` или `1`.

  - `quality` — качество видео (возможные значения: `small`, `medium`, `large`, `hd720`, `hd1080`, `highres`, `4K` или `default`).

  {% note info %}

  Событие `resumed` может быть заменено обязательным событием `started`.

  {% endnote %}

  ||
  ||
  `volumechange`
  |
  Включение, выключение звука или изменение громкости.
  |

  - `volume` — текущее значение [громкости](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volume) (`0..1`).

  - `muted` — текущее состояние флага [muted](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/muted) (`1`, `0`).

  Аналогично нативному событию [volumechange](https://developer.mozilla.org/en-US/docs/Web/Events/volumechange) у элемента `<video>`.

  ||
  ||
  `bufferingStarted`
  |
  Начало процесса буфферизации видео/части видео.
  |
  - `size` — количество загружаемых байт.

  - `time` — текущая позиция прогресс-бара в секундах.

  - `quality` — качество видео (возможные значения: `small`, `medium`, `large`, `hd720`, `hd1080`, `highres`, `4K` или `default`).
  ||
  ||
  `bufferingEnded`
  |
  Конец загрузки части видео.
  |
  - `time` — текущая позиция прогресс-бара в секундах.
  - `quality` — качество видео (возможные значения: `small`, `medium`, `large`, `hd720`, `hd1080`, `highres`, `4K` или `default`).
  ||
  ||
  `adSkip`
  |
  Пропуск рекламы, не заменяет `adEnd`.
  |
  —
  ||
  ||
  `adSkippable`
  |
  Событие, которое свидетельствует о том, что рекламу можно пропустить методом `skipAd`.
  |
  - `time` — текущая позиция прогресс-бара в секундах.
  ||
  ||
  `qualityList`
  |
  Список доступных значений качества.
  |
  `list` — список значений качества для видео (возможные значения: `144`, `240`, `360`, `480`, `720`, `1080`, `1440`, `2160`).

  ||
  ||
  `qualityChange`
  |
  Смена качества видео.
  |
  - `quality` — качество видео (возможные значения: `small`, `medium`, `large`, `hd720`, `hd1080`, `highres`, `4K` или `default`).

  - `time` — текущая позиция прогресс-бара в секундах.

  ||
  ||
  `playbackRateChange`
  |
  Смена скорости воспроизведения.
  |
  - `time` — текущая позиция прогресс-бара в секундах.

  - `rate` — коэффициент ускорения/замедления.

  ||
  ||
  `fullscreen`
  |
  Переход плеера в полноэкранный режим или выход из полноэкранного режима.
  |
  `enabled` — включен или нет.

  ||
  ||
  `playerReady`
  |
  Плеер загрузился и готов к интерактивности (загружены данные, апи плеера).
  |
  —
  ||
  ||
  `playbackRateChanged`
  |
  Смена скорости воспроизведения видео.
  |
  - `rate` — скорость воспроизведения `0..1`.

  - `time` — текущая позиция прогресс-бара в секундах.
  ||
  ||
  `controlsHidden`
  |
  Признак программного скрытия элементов управления плеером (через метод `hideControls`, а не временное скрытие).
  |
  `time` — текущая позиция прогресс-бара в секундах.
  ||
  ||
  `controlsShown`
  |
  Признак показа элементов управления плеером плеера (в ответ на вызов метода `showControls`, а не временный показ).
  |
  `time` — текущая позиция прогресс-бара в секундах.
  ||
  ||
  `clickout`
  |
  Факт внешнего перехода из плеера в рекламу, на сервис.
  |
  - `source` — тип перехода. Возможные значения:

    - `adv` — переход по рекламе.

    - `related` — переход на другой ролик из блока роликов внутри плеера.

    - `self` — переход на то же самое видео на сервисе по клику в лого.

    - `unknown` — другой переход.

  - `url` — адрес страницы, на которую перешли.

  ||
  ||
  `sourceUpdated`
  |
  Это событие должно отправляться при любой замене ролика внутри фрейма (элемента `iframe`). Например, если плеер позволяет изменять видео через API без пересоздания плеера, событие сигнализирует о замене видео.
  |
  - `id` — идентификатор ролика.

  - `params` — любые другие параметры видео.

  ||
  ||
  `fullscreenError`
  |
  Произошла ошибка при попытке выйти или войти в полноэкранный режим.
  |
  `message` — сообщение об ошибке.
  ||
  ||
  `qualityList`
  |
  Список доступных значений качества.
  |
  `list` — возможные значения: `small`, `medium`, `large`, `hd720`, `hd1080`, `highres`, `4K` или `default`.
  ||
  |#

{% endlist %}

{% cut "Пример передачи данных о видео в момент его запуска" %}

Когда пользователь нажимает на плеере кнопку **Play**, вызывается функция `window.parent.postMessage` с нужными параметрами.

```javascript
// Отправка сообщения при старте проигрывания видео
window.parent.postMessage({
  event: 'started',
  duration: 30,
  time: 5 // Если проигрывание возобновляется с 5 секунды
}, '*');
```

{% endcut %}

## Сведения об ошибках {#errors}

Чтобы получать сведения об ошибках при работе с видео, плеер должен передавать функции `window.parent.postMessage` следующие коды ошибок:

#|
||
**Код ошибки**
|
**Описание**
||
|| **Недоступное видео** | > ||
||
101
|
Видео удалено.
||
||
102
|
Видеоролик или учетная запись заблокирована.
||
||
103
|
Видеоролик не существует либо URL не поддерживается.
||
||
100
|
Прочие случаи недоступного видео.
||
|| **Ограничение доступа к видеоролику** | > ||
||
151
|
Недостаточно прав для просмотра видео.
||
||
152
|
Видео запрещено к проигрыванию на других сайтах.
||
||
153
|
Видео запрещено к проигрыванию в данном регионе.
||
||
154
|
Ограничение доступа, которое требует подтверждения от пользователя (например, ограничения по возрасту, авторизация).
||
||
155
|
Ролик недоступен, потому что сервис посчитал запрос роботным.
||
||
156
|
Ролик доступен только по подписке.
||
||
150
|
Прочие ограничения просмотра видео.
||
|| **Прочее** | > ||
||
5
|
Сбой работы плеера (ошибки воспроизведения HTML-проигрывателя и др.).
||
||
0
|
Прочие ошибки.
||
|#


{% cut "Пример отправки сообщения об ошибке" %}

Если видео, которое открывается в плеере, было удалено, сообщение об ошибке может быть отправлено следующим образом:

```javascript
// Отправка сообщения об ошибке
window.parent.postMessage({
  event: 'error',
  time: 0,
  code: '101'
}, '*');
```
{% endcut %}

## Поддержка параметров в URL плеера {#url-params}

Чтобы воспроизведение видео на Smart TV и в браузере было удобнее для пользователей, добавьте поддержку следующих параметров в URL плеера:

#|
||
**Параметр**
|
**Описание**
|
**Возможные значения**
||
||
`autoplay`
|
Автозапуск воспроизведения.
|
- `1` — автоматически начинать проигрывание видео.

- `0` (или отсутствие параметра) — не начинать автоматическое проигрывание видео.

{% cut "Пример" %}

  ```javascript
  <iframe 
    src="//www.videohosting.com/video?autoplay=1">
  </iframe> 
  ```
{% endcut %}
||
||
`tv`
|
Управление отображением интерактивных элементов плеера на устройствах со Smart TV.
|
- `1` — автоматически скрывать интерактивные элементы при воспроизведении видео.

- `0` (или отсутствие параметра) — не скрывать интерактивные элементы автоматически при воспроизведении видео.

{% cut "Пример" %}

  ```javascript
  <iframe
    src="//www.videohosting.com/video?tv=1">
  </iframe> 
  ```

{% endcut %}

Параметр управляет отображением всех элементов, нажимать на которые можно только указателем мыши. К ним относятся:

- прогресс-бар; 

- выпадающие списки сезонов и серий; 

- кнопки выбора качества воспроизведения; 

- меню управления проигрыванием и др.

На телевизорах удобнее смотреть видео, если эти элементы скрыты автоматически.
||
||
`mute`
|
Загружать видео с выключенным звуком.
|
- `1` — не включать звук в видео, пока пользователь сам его не включит.

- `0` (или отсутствие параметра) — поведение звука в плеере на усмотрение хостинга, можно запускать видео со звуком при возможности.
||
||
`controls`
|
Нужно ли отображать в плеере элементы управления (прогресс-бар, смена качества и пр.).
|
- `1` (или отсутствие параметра) — показывать все элементы управления плеера.

- `0` — не отображать элементы управления плеером.

||
||
`t`
|
Временная метка, с которой надо начать воспроизведение видео.
|
`[number]` — число секунд.

{% cut "Пример" %}

В примере видео начнет воспроизведение с 10:00 (600&#160;c = 10&#160;мин).

```
<iframe
  src="//www.videohosting.com/video?t=600">
</iframe>
```

{% endcut %}

||
|#

## Управление плеером {#control-player}

Команды управления плеером передаются в `iframe` из внешнего окна с использованием механизма [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). Чтобы принимать сообщения внутри `iframe`, подпишитесь на событие `message`. Команды представляют собой JSON-объект с обязательным полем `method`.

#|
||
**Команда**
|
**Описание**
||
||
`play`
|
Начало или продолжение воспроизведения.

{% cut "Пример" %}

```javascript
{
    method: 'play'
} 
```
{% endcut %}

||
||
`pause`
|
Пауза.

{% cut "Пример" %}

```javascript
{
    method: 'pause'
} 
```
{% endcut %}

||
||
`seek`
|
Перемотка на абсолютное значение времени.

{% cut "Пример" %}

```javascript 
{
     method: 'seek',
     time: 10, // время в секундах
} 
```
{% endcut %}
||
||
`setVolume`
|
Установка громкости.

{% cut "Пример" %}

```javascript
{
     method: 'setVolume',
     volume: 0.5 // громкость 0..1
} 
```
{% endcut %}
||
||
`showControls`
|
Принудительный показ элементов управления плеером.

{% cut "Пример" %}

```javascript
{
    method: 'showControls'
} 
```
{% endcut %}
||
||
`skipAd`
|
Метод для пропуска рекламы.

{% cut "Пример" %}

```javascript
{
     method: 'skipAd',
} 
```
{% endcut %}
||
||
`setPlaybackRate`
|
Установка скорости воспроизведения видео.

{% cut "Пример" %}

```javascript
{
     method: 'setPlaybackRate',
     rate: 0.5 // скорость воспроизведения  0..1
} 
```
{% endcut %}
||
||
`mute`
|
Выключение звука.

{% cut "Пример" %}

```javascript 
{
     method: 'mute'
} 
```
{% endcut %}
||
||
`unmute`
|
Включение звука.

{% cut "Пример" %}

```javascript
{
     method: 'unmute'
} 
```
{% endcut %}
||
||
`setQuality`
|
Установка качества воспроизведения.

{% cut "Пример" %}

```javascript
{
     method: 'setQuality',
     quality: '720' // 144, 240, 360, 480, 720, 1080, 1440, 2160 или auto
} 
```
Параметр `auto` позволяет плееру самостоятельно определить оптимальное качество. Он может использовать значение по умолчанию, либо выбрать наиболее подходящее качество с учетом скорости соединения и параметров устройства пользователя.

{% endcut %}

||
||
`updateSource`
|
Метод для смены видео внутри плеера без перерисовки всего `iframe`.

`params` — параметры для загрузки очередного ролика.

{% cut "Пример" %}

```javascript
{
  method: 'updateSource',
  data: {
    id: 'some_id',
    params: {},
  }
}
```
{% endcut %}

||
||
`preload`
|
Метод для вызова начала буфферизации видео до его воспроизведения.

{% cut "Пример" %}

```javascript
{
  method: 'preload'
}
```
{% endcut %}

||
||
`requestFullscreen`
|
Метод для открытия полноэкранного режима.

{% cut "Пример" %}

```javascript
{
  method: 'requestFullscreen'
}
```
{% endcut %}

||
||
`exitFullscreen`
|
Метод для выхода из полноэкранного режима.

{% cut "Пример" %}

```javascript
{
  method: 'exitFullscreen'
}
```
{% endcut %}

||
||
`hideControls`
|
Скрытие элементов управления плеером.

{% cut "Пример" %}

```javascript
{
    method: 'hideControls'
} 
```
{% endcut %}

||
|#

{% cut "Пример запуска видео по команде" %}

```javascript
window.addEventListener('message', function (event) {
     if (event.data.method === 'play') {
         document.getElementById('video').play();
     }
});
```
{% endcut %}

### Формат ответа {#control-player}

Для обратной связи о выполнении команд используйте [события](#events), которые сообщают о состоянии видео.

Например:

- При вызове метода `skipAd`, в случае успешного пропуска рекламы генерируется событие `adSkip`, если же возникла проблема — событие не отправляется. 

- При использовании метода `setPlaybackRate` в ответ возникает событие `playbackRateChanged`. 

Для корректного отображения видео на Smart TV обязательно наличие ответного события для каждого метода.

<!-- source: ru/_includes/neuro.md -->

<!-- endsource: ru/_includes/neuro.md -->

<!-- source: ru/_includes/form-webmaster.md -->
<details>
<summary class="button">Написать в службу поддержки</summary>

<br>
<br>

<div style="padding: 15px;
     margin: 10px 0;
     background: #FFFFFF;
     border-radius: 10px;
     border: 1px solid var(--g-color-line-generic);">
  <iframe style="background: #FFFFFF;"
        height="700"
        width="100%"
        frameborder="0"
        src="https://forms.yandex.ru/surveys/1858/?&iframe=1">
  </iframe>
</div>
</details>




<!-- endsource: ru/_includes/form-webmaster.md -->

<!-- source: ru/_includes/style/no-bg-inside-table.md -->

<!-- endsource: ru/_includes/style/no-bg-inside-table.md -->