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

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

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

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

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

Примечание

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

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

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

Событие

Описание

Параметры события

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 у элемента <video>.

error

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

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

  • code — код ошибки.

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

adShown

Начало показа рекламы.

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

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

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

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

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

Примеры данных для события adShown
Пример 1

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

{
  count: 2,
  time: 30,
  ads: [
    {
      duration: 15.0,
      skip: 1
    },
    {
      duration: 25.3,
      skip: 0
    }
  ]
}
Пример 2

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

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

Примечание

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

adEnd

Конец показа рекламы.

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

contentImpression

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

Примечание

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

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

Событие

Описание

Параметры события

rewound

Перемотка видео.

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

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

resumed

Возобновление воспроизведения.

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

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

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

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

Примечание

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

volumechange

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

  • volume — текущее значение громкости (0..1).

  • muted — текущее состояние флага muted (1, 0).

Аналогично нативному событию 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.
Пример передачи данных о видео в момент его запуска

Когда пользователь нажимает на плеере кнопку 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

Ограничение доступа, которое требует подтверждения от пользователя (например, ограничения по возрасту, авторизация).

155

Ролик недоступен, потому что сервис посчитал запрос роботным.

156

Ролик доступен только по подписке.

150

Прочие ограничения просмотра видео.

Прочее

5

Сбой работы плеера (ошибки воспроизведения HTML-проигрывателя и др.).

0

Прочие ошибки.
Пример отправки сообщения об ошибке

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

// Отправка сообщения об ошибке
window.parent.postMessage({
  event: 'error',
  time: 0,
  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>

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

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

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

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

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

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

mute

Загружать видео с выключенным звуком.

  • 1 — не включать звук в видео, пока пользователь сам его не включит.

  • 0 (или отсутствие параметра) — поведение звука в плеере на усмотрение хостинга, можно запускать видео со звуком при возможности.

controls

Нужно ли отображать в плеере элементы управления (прогресс-бар, смена качества и пр.).

  • 1 (или отсутствие параметра) — показывать все элементы управления плеера.

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

t

Временная метка, с которой надо начать воспроизведение видео.

[number] — число секунд.

Пример

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

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

Управление плеером

Команды управления плеером передаются в 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
}

showControls

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

Пример
{
    method: 'showControls'
}

skipAd

Метод для пропуска рекламы.

Пример
{
     method: 'skipAd',
}

setPlaybackRate

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

Пример
{
     method: 'setPlaybackRate',
     rate: 0.5 // скорость воспроизведения  0..1
}

mute

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

Пример
{
     method: 'mute'
}

unmute

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

Пример
{
     method: 'unmute'
}

setQuality

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

Пример
{
     method: 'setQuality',
     quality: '720' // 144, 240, 360, 480, 720, 1080, 1440, 2160 или auto
}

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

updateSource

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

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

Пример
{
  method: 'updateSource',
  data: {
    id: 'some_id',
    params: {},
  }
}

preload

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

Пример
{
  method: 'preload'
}

requestFullscreen

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

Пример
{
  method: 'requestFullscreen'
}

exitFullscreen

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

Пример
{
  method: 'exitFullscreen'
}

hideControls

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

Пример
{
    method: 'hideControls'
}
Пример запуска видео по команде
window.addEventListener('message', function (event) {
     if (event.data.method === 'play') {
         document.getElementById('video').play();
     }
});

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

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

Например:

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

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

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

Написать в службу поддержки

Предыдущая
Мобильный плеер
Следующая
Запрет на показ видео в поиске