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

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

  1. События, сообщающие о состоянии видео
  2. Сведения об ошибках
  3. Поддержка параметров в URL плеера
  4. Управление плеером на устройствах Smart TV

События, сообщающие о состоянии видео

Для передачи данных о состоянии видео используйте механизм postMessage — для каждого события, возникающего в плеере (например, начало воспроизведения видеоролика), в коде на JavaScript вызовите функцию window.parent.postMessage. В качестве аргументов ей следует передать название события с параметрами этого события (например, позицию прогресс-бара).

Примечание. Обратите внимание, что функцию postMessage необходимо вызывать для родительского объекта — window.parent. Это связано с тем, что видео размещается не на основной странице результатов поиска Яндекса, а в отдельном фрейме (в элементе iframe).
window.parent.postMessage({
    event: <Название события>,
    // дополнительные параметры события
}, '*');

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

Событие Описание Параметры события
Обязательные
inited

Инициализация плеера.

—
started

Начало воспроизведения или продолжение воспроизведения после паузы.
  • time — текущая позиция прогресс-бара в секундах.

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

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

Аналогично нативному событию timeupdate у элемента <video>.

paused

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

Просмотр ролика завершен (достигнут конец ролика).
  • time — текущая позиция прогресс-бара в секундах.
error

Ошибка воспроизведения.

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

  • code — код ошибки.
Дополнительные
resumed

Возобновление воспроизведения.
  • time — текущая позиция прогресс-бара в секундах.
  • duration — общая продолжительность ролика в секундах. Секунды можно не округлять.
Примечание. Событие resumed может быть заменено обязательным событием started.
rewound

Перемотка видео.
  • time — текущая позиция прогресс-бара в секундах.
  • previousTime — предыдущая позиция прогресс-бара в секундах.
volumechange Включение, выключение звука или изменение громкости.
  • volume — текущее значение громкости (0..1).
  • muted — текущее состояние флага muted (true, false).

Аналогично нативному событию volumechange у элемента video.
adShown

Начало показа рекламы.
  • time — текущая позиция прогресс-бара в секундах.
  • duration — общая продолжительность рекламы в секундах. Секунды можно не округлять.
  • skipAdEnabled — возможен пропуск рекламы (в интерфейсе появится соответствующее уведомление).
  • skipAd — пропуск рекламы.
Событие Описание Параметры события
Обязательные
inited

Инициализация плеера.

—
started

Начало воспроизведения или продолжение воспроизведения после паузы.
  • time — текущая позиция прогресс-бара в секундах.

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

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

Аналогично нативному событию timeupdate у элемента <video>.

paused

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

Просмотр ролика завершен (достигнут конец ролика).
  • time — текущая позиция прогресс-бара в секундах.
error

Ошибка воспроизведения.

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

  • code — код ошибки.
Дополнительные
resumed

Возобновление воспроизведения.
  • time — текущая позиция прогресс-бара в секундах.
  • duration — общая продолжительность ролика в секундах. Секунды можно не округлять.
Примечание. Событие resumed может быть заменено обязательным событием started.
rewound

Перемотка видео.
  • time — текущая позиция прогресс-бара в секундах.
  • previousTime — предыдущая позиция прогресс-бара в секундах.
volumechange Включение, выключение звука или изменение громкости.
  • volume — текущее значение громкости (0..1).
  • muted — текущее состояние флага muted (true, false).

Аналогично нативному событию volumechange у элемента video.
adShown

Начало показа рекламы.
  • time — текущая позиция прогресс-бара в секундах.
  • duration — общая продолжительность рекламы в секундах. Секунды можно не округлять.
  • skipAdEnabled — возможен пропуск рекламы (в интерфейсе появится соответствующее уведомление).
  • skipAd — пропуск рекламы.

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

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

Сведения об ошибках

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

Код ошибки Описание
Недоступное видео
101 Видео удалено.
102 Видеоролик или учетная запись заблокирована.
103 Видеоролик не существует либо URL не поддерживается.
100 Прочие случаи недоступного видео.
Ограничение доступа к видеоролику
151 Недостаточно прав для просмотра видео.
152 Видео запрещено к проигрыванию на других сайтах.
153 Видео запрещено к проигрыванию в данном регионе.
154 Ограничение доступа, требующее подтверждения от пользователя (например, ограничения по возрасту).
150 Прочие ограничения просмотра видео.
Прочее
5 Сбой работы плеера (ошибки воспроизведения HTML-проигрывателя и др.).
0 Прочие ошибки.
Код ошибки Описание
Недоступное видео
101 Видео удалено.
102 Видеоролик или учетная запись заблокирована.
103 Видеоролик не существует либо URL не поддерживается.
100 Прочие случаи недоступного видео.
Ограничение доступа к видеоролику
151 Недостаточно прав для просмотра видео.
152 Видео запрещено к проигрыванию на других сайтах.
153 Видео запрещено к проигрыванию в данном регионе.
154 Ограничение доступа, требующее подтверждения от пользователя (например, ограничения по возрасту).
150 Прочие ограничения просмотра видео.
Прочее
5 Сбой работы плеера (ошибки воспроизведения HTML-проигрывателя и др.).
0 Прочие ошибки. 
// Отправка сообщения об ошибке
window.parent.postMessage({
  event: 'error',
  time: 62,
  code: '101'
}, '*');

Поддержка параметров в URL плеера

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

Параметр Описание Возможные значения
Обязательные
autoplay

Автозапуск воспроизведения.
  • 1 — автоматически начинать проигрывание видео;
  • 0 (или отсутствие параметра) — не начинать автоматическое проигрывание видео.
<iframe 
  src="//www.videohosting.com/video?autoplay=1">
</iframe>
tv Управление отображением интерактивных элементов плеера на устройствах со Smart TV.
  • 1 — автоматически скрывать интерактивные элементы при воспроизведении видео;
  • 0 (или отсутствие параметра) — не скрывать интерактивные элементы автоматически при воспроизведении видео. 
<iframe
  src="//www.videohosting.com/video?tv=1">
</iframe>

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

На телевизорах удобнее смотреть видео, если эти элементы скрыты автоматически.

Дополнительные
maxQuality Выбор качества воспроизведения.
small

Высота проигрывателя — 240 пикселей.

Минимальные размеры проигрывателя для формата 4:3 — 320 × 240 пикселей.

medium

Высота проигрывателя — 360 пикселей.

Минимальные размеры проигрывателя:

  • для формата 16:9 — 640 × 360 пикселей;
  • для формата 4:3 — 480 × 360 пикселей.
large

Высота проигрывателя — 480 пикселей.

Минимальные размеры проигрывателя:

  • для формата 16:9 — 853 × 480 пикселей;
  • для формата 4:3 — 640 × 480 пикселей.
hd720

Высота проигрывателя — 720 пикселей.

Минимальные размеры проигрывателя:

  • для формата 16:9 — 1280 × 720 пикселей;
  • для формата 4:3 — 960 × 720 пикселей.
hd1080

Высота проигрывателя — 1080 пикселей.

Минимальные размеры проигрывателя:

  • для формата 16:9 — 1920 × 1080 пикселей;
  • для формата 4:3 — 1440 × 1080 пикселей.
highres

Высота проигрывателя — более 1080 пикселей.

Формат соотношения сторон более 1920 × 1080 пикселей.

default

Определяет рекомендуемое качество воспроизведения в зависимости от настроек пользователя, видеофайла и других условий.

<iframe
  src="//www.videohosting.com/video?maxQuality=hd720">
</iframe>
Параметр Описание Возможные значения
Обязательные
autoplay

Автозапуск воспроизведения.
  • 1 — автоматически начинать проигрывание видео;
  • 0 (или отсутствие параметра) — не начинать автоматическое проигрывание видео.
<iframe 
  src="//www.videohosting.com/video?autoplay=1">
</iframe>
tv Управление отображением интерактивных элементов плеера на устройствах со Smart TV.
  • 1 — автоматически скрывать интерактивные элементы при воспроизведении видео;
  • 0 (или отсутствие параметра) — не скрывать интерактивные элементы автоматически при воспроизведении видео. 
<iframe
  src="//www.videohosting.com/video?tv=1">
</iframe>

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

На телевизорах удобнее смотреть видео, если эти элементы скрыты автоматически.

Дополнительные
maxQuality Выбор качества воспроизведения.
small

Высота проигрывателя — 240 пикселей.

Минимальные размеры проигрывателя для формата 4:3 — 320 × 240 пикселей.

medium

Высота проигрывателя — 360 пикселей.

Минимальные размеры проигрывателя:

  • для формата 16:9 — 640 × 360 пикселей;
  • для формата 4:3 — 480 × 360 пикселей.
large

Высота проигрывателя — 480 пикселей.

Минимальные размеры проигрывателя:

  • для формата 16:9 — 853 × 480 пикселей;
  • для формата 4:3 — 640 × 480 пикселей.
hd720

Высота проигрывателя — 720 пикселей.

Минимальные размеры проигрывателя:

  • для формата 16:9 — 1280 × 720 пикселей;
  • для формата 4:3 — 960 × 720 пикселей.
hd1080

Высота проигрывателя — 1080 пикселей.

Минимальные размеры проигрывателя:

  • для формата 16:9 — 1920 × 1080 пикселей;
  • для формата 4:3 — 1440 × 1080 пикселей.
highres

Высота проигрывателя — более 1080 пикселей.

Формат соотношения сторон более 1920 × 1080 пикселей.

default

Определяет рекомендуемое качество воспроизведения в зависимости от настроек пользователя, видеофайла и других условий.

<iframe
  src="//www.videohosting.com/video?maxQuality=hd720">
</iframe>

Управление плеером на устройствах Smart TV

Команды управления плеером отправляются в iframe из внешнего окна с помощью механизма postMessage. Для приема сообщений внутри iframe нужно подписаться на событие message. Формат команды — JSON-объект с обязательным полем method.

Команда Описание
play

Начало или продолжение воспроизведения.

{
    method: 'play'
}
pause

Пауза.

{
    method: 'pause'
}
seek

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

{
    method: 'seek',
    time: 10, // время в секундах
}
setVolume

Установка громкости.

{
    method: 'setVolume',
    volume: 0.5 // громкость 0..1
}
mute

Выключение звука.

{
    method: 'mute'
}
unmute

Включение звука.

{
    method: 'unmute'
}
setQuality

Установка качества воспроизведения.

{
    method: 'setQuality',
    quality: 'hd720' // small, medium, large, hd720, hd1080, highres или default
}
Команда Описание
play

Начало или продолжение воспроизведения.

{
    method: 'play'
}
pause

Пауза.

{
    method: 'pause'
}
seek

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

{
    method: 'seek',
    time: 10, // время в секундах
}
setVolume

Установка громкости.

{
    method: 'setVolume',
    volume: 0.5 // громкость 0..1
}
mute

Выключение звука.

{
    method: 'mute'
}
unmute

Включение звука.

{
    method: 'unmute'
}
setQuality

Установка качества воспроизведения.

{
    method: 'setQuality',
    quality: 'hd720' // small, medium, large, hd720, hd1080, highres или default
}

Пример запуска видео по команде

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

Формат ответа

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