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

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

  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 — пропуск рекламы.

Ниже рассмотрен пример передачи данных о видео в момент его запуска. Когда пользователь нажимает на плеере кнопку 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Прочие ошибки.
// Отправка сообщения об ошибке
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>

Управление плеером на устройствах 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
}

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

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

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

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