Видео жағдайы туралы деректерді беру

Видео арқылы іздеу жақсырақ істеп, барынша жарамды видеороликтерді көрсету үшін видеороликтің күйін қадағалап отыруға көмектесетін оқиғалар (мысалы, басталған, тоқтаған, видеоны айналдырған уақыты және т.б.) және ықтимал қателер туралы ақпаратты жіберіп отыру керек.

Видеоның күйі туралы хабарлап отыратын оқиғалар

Видеоның күйі туралы деректерді жіберіп отыру үшін 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 — роликтің секундпен берілген жалпы ұзақтығы. Секундты дөңгелектемеуге болады.

    <video> элементінің timeupdate нативті оқиғасына ұқсас.

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

Дыбысты қосу, өшіру немесе дыбыс деңгейін өзгерту.

<video> элементіндегі volumechange табиғи күйіне ұқсас.

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 оқиғасына жазылыңыз. Пәрмендер method міндетті өрісі бар JSON-объект болып табылады.

Команда

Сипаттамасы

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 арқылы дұрыс көрсету үшін әрбір әдіс үшін жауап оқиға міндетті түрде болу керек.

Қолдау қызметіне жазу

Алдыңғы
Мобильді плеер
Келесі
Іздеуде бейнені көрсетуге тыйым салу