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

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

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

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

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

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

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

started

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

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

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

paused

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

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

ended

Просмотр ролика завершен (достигнут конец ролика).

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

error

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

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

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

Дополнительные
autoplay

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

  • autoplay=1 — автоматически начинать проигрывание видео;

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

<iframe src="//www.your-videohosting.com/video?autoplay=1"></iframe>
Примечание. Указывать адрес плеера с параметром autoplay в разметке необязательно, достаточно просто поддерживать этот параметр при его добавлении к плееру в поиске.
resumed

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

Примечание. Может быть заменено событием started.
  • time — позиция прогресс-бара в секундах.

rewound

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

Примечание. Может быть заменено событием started.
  • time — позиция прогресс-бара в секундах.

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

adShown

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

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

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

// Данная функция вызывается, когда пользователь нажал на плеере кнопку Play.
function videoStart() {
    ...
    // Отправка сообщения.
    window.parent.postMessage({
        event: 'started'
        // Также может быть передан параметр time.
        // Если параметр time не указан, то по умолчанию
        // он принимает значение 0.
    }, '*');
}

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

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

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