Передавання даних про стан відео

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

  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 — загальна тривалість реклами в секундах. Секунди можна й не округлювати.

Нижче розглянуто приклад передачі даних про відео у момент його запуску. Коли користувач натискає на плеєрі на кнопку 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();
     }
});

Формат відповіді

Для зворотного зв’язку про виконання команд використовуйте події про стан відео.