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

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

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

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

Примечание

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

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

Для отображения плеера в приложении поиска по видео для 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.

См. Примеры*

Примечание

Допустимо отправлять информацию с параметрами рекламы отдельным событием 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.

qualityChange

Смена качества видео.
  • quality — small, medium, large, hd720, hd1080, highres, 4K или default.
  • time — текущая позиция прогресс-бара в секундах.

playbackRateChange

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

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

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

fullscreen

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

playerReady

Плеер загрузился и готов к интерактивности (загружены данные, апи плеера).

clickout

Факт внешнего перехода из плеера в рекламу, на сервис.

  • source — тип перехода.

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

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

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

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

  • url — ссылка, на которую ушли.

sourceUpdated

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

  • id — идентификатор ролика.

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

fullscreenError

Произошла ошибка при попытке выйти или войти в полноэкранный режим.
  • message — сообщение об ошибке.

qualityList

Список доступных значений качества.
  • list — список значений из списка: small, medium, large, hd720, hd1080, highres, 4K или default.

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

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

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

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

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

Ниже рассмотрен пример передачи данных о видео в момент его запуска. Когда пользователь нажимает на плеере кнопку 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] — число секунд.
<iframe
  src="//www.videohosting.com/video?t=600">
</iframe>

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

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

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

updateSource

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

  • params — параметры для загрузки очередного ролика.
{
  method: 'updateSource',
  data: {
    id: 'some_id',
    params: {},
  }
}

preload

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

{
  method: 'preload'
}

requestFullscreen

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

{
  method: 'requestFullscreen'
}

exitFullscreen

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

{
  method: 'exitFullscreen'
}

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

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

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

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

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

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