---
metadata:
  - name: generator
    content: Diplodoc Platform v5.42.1
alternate:
  - https://yandex.kz/support/video/kk/partners/jsapi.md
  - https://yandex.kz/support/video/ru/partners/jsapi.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.kz/support/video/kk/llms.txt

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

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

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

Видеоның күйі туралы деректерді жіберіп отыру үшін [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) механизмін қолданыңыз. Плеерде оқиға орындалған кезде (мысалы, видеоны ойнату басталған кезде), JavaScript-код арқылы `window.parent.postMessage` функциясын шақыртыңыз. Функция аргументтері ретінде оқиғаның атауы мен оның параметрлерін (мысалы, прогресс-бар позициясын) жіберіңіз. 


{% cut "Функцияны пайдалану мысалы" %}

```javascript
window.parent.postMessage({

    event: <Оқиға атауы>,

    // оқиғаның қосымша параметрлері
 }, '*');
```

{% note info %}

`postMessage` функциясы `window.parent` негізгі объектісі үшін шақырылады, себебі видео Яндекстен іздеу нәтижелерінің негізгі бетінде емес, бөлек фреймде (`iframe` элементінде) орналасады.

{% endnote %}


{% endcut %}

TV мен браузерге арналған видео бойынша іздеу қосымшасында бейнеленуі үшін міндетті шаралар мен олардың параметрлерін жіберіп тұру қажет.

Қосымша оқиғаларды жіберіп отыру плеермен өзара әрекеттесуді жақсартады, ал сигналдар видеоны тиімдірек саралауға көмектеседі.


{% list tabs %}

- Міндетті оқиғалар

  #|
  ||
  **Оқиға**
  |
  **Сипаттамасы**
  |
  **Оқиға параметрлері**
  ||
  ||
  `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](https://developer.mozilla.org/en-US/docs/Web/Events/timeupdate) нативті оқиғасына ұқсас.

  ||
  ||
  `error`
  |
  Ойнату қатесі, видеоның қолжетімсіздігі фактісі.
  |
  - `time` — прогресс-бардың секундпен берілген ағымдағы жайғасымы.

  - `code` — [қате коды](#errors).

  - `message` — қатенің типімен ақпараты бар хабарлама.

  ||
  ||
  `adShown`
  |
  Жарнаманың басталуы.
  |
  - `count` — ағымдағы жарнама блогында көрсетілетін жарнамалық роликтердің саны.

  - `time` — прогресс-бардың секундпен берілген ағымдағы жайғасымы.

  - `ads` — жарнамалық роликтердің тізімі бар деректермен массив. Әр ролик үшін массивте мына параметрлер болуы шарт:

    - `duration` — жарнаманың секундпен берілген жалпы ұзақтығы. Секундты дөңгелектемеуге болады.

    - `skip` — жарнаманы өткізіп алу ықтималдығы (интерфейсте сәйкесінше хабарлама пайда болады), `0` немесе `1` мәндерін қабылдауы мүмкін.

  {% cut "adShown оқиғасы үшін деректердің мысалы" %}

  {% cut "1-мысал" %}

  Егер жарнамалық блок видеоның он үшінші секундынан басталса және екі хабарландырудан құралса, оның ішінде алғашқысының ұзақтығы 15 секунд және өткізіп жіберу мүмкіндігі бар, ал екіншісі 25 секундтан тұрады және өткізіп алу мүмкіндігі жоқ болса, онда `adShown` оқиғасында келесі деректер көрсетілуі керек: {#addshown}

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

  {% cut "2-мысал" %}

  Егер бір ғана жарнама хабарландыруы бар блок болса, ол видеоның ең басында ойнатылып (`preroll`), ұзақтығы 45 секунд және алға айналдыру мүмкіндігі болмаса:

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

  {% endcut %}

  {% note info %}

  `beforeAdStart` бөлек оқиғасымен жарнама параметрлерімен ақпаратты жіберу орын алуы мүмкін.

  {% endnote %}

  ||
  ||
  `adEnd`
  |
  Жарнаманы көрсету аяқталды.
  |
  `time` — прогресс-бардың секундпен берілген ағымдағы жайғасымы.

  ||
  ||
  `contentImpression`
  |
  Видеоның алғашқы кадрын көрсету.

  {% note info %}

  Егер видеоның басында жарнама ойнатылса, оқиғаны ол аяқталғаннан кейін видеоның бірінші кадры пайда болған кезде жіберіңіз.

  {% endnote %}

  |

  `time` — прогресс-бардың секундпен берілген ағымдағы жайғасымы.

  ||
  |#

- Қосымша оқиғалар

  #|
  ||
  **Оқиға**
  |
  **Сипаттамасы**
  |
  **Оқиға параметрлері**
  ||
  ||
  `rewound`
  |
  Видеоны қайта орау.
  |
  - `time` — прогресс-бардың секундпен берілген ағымдағы жайғасымы.

  - `previousTime` — секундына прогресс-бардың алдыңғы позициясы.
  ||
  ||
  `resumed`
  |
  Ойнатуды жалғастыру.
  |

  - `time` — прогресс-бардың секундпен берілген ағымдағы жайғасымы.

  - `duration` — роликтің секундпен берілген жалпы ұзақтығы. Секундты дөңгелектемеуге болады.

  - `muted` — өшірілген дыбыстың нышаны, `0` немесе `1` мәндерін қабылдауы мүмкін.

  - `quality` — видеоның сапасы (ықтимал мәндері: `small`, `medium`, `large`, `hd720`, `hd1080`, `highres`, `4K` немесе `default`).

  {% note info %}

  `resumed` оқиғасы міндетті `started` оқиғасымен ауыстырылуы мүмкін.

  {% endnote %}

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

  - `volume` — [дыбыс деңгейінің](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volume) (`0..1`) ағымдағы мәні.

  - `muted` — [muted](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/muted) (`1`, `0`) жалауының ағымдағы күйі.

  `<video>` элементіндегі [volumechange](https://developer.mozilla.org/en-US/docs/Web/Events/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`.
  ||
  |#

{% endlist %}

{% cut "Видеоны іске қосу кезінде деректерді жіберу мысалы" %}

Пайдаланушы ойнатқышта **Play** батырмасын басқанда қажетті параметрлері бар `window.parent.postMessage` функциясы шақырылады.

```javascript
// Бейне ойнатуды бастау кезінде хабарламаны жіберу
 window.parent.postMessage({
   event: 'started',
   duration: 30,
   time: 5 // Егер ойнату 5 секундта жаңартылса
  }, '*');
```

{% endcut %}

## Қате туралы мәліметтер {#errors}

Видеомен жұмыс істеген кезде қателер туралы мәліметтер алып отыру үшін плеер `window.parent.postMessage` функциясына мына қате кодтарын жіберіп отыру керек:

#|
||
**Қате коды**
|
**Сипаттамасы**
||
|| **Қолжетімсіз видео** | > ||
||
101
|
Видео жойылған.
||
||
102
|
Бейнеролик немесе тіркелгі құлыпталған.
||
||
103
|
Бейнеролик жоқ немесе URL қолдауы жоқ.
||
||
100
|
Қолжетімсіз видеоның басқа жағдайлары.
||
|| **Бейнероликке қатынауды шектеу** | > ||
||
151
|
Видеоны көру үшін құқықтарыңыз жеткіліксіз.
||
||
152
|
Видеоның басқа сайттарда ойнатылуына тыйым салынған.
||
||
153
|
Видеоны осы аймақта ойнатуға тыйым салынады.
||
||
154
|
Пайдаланушының растауын қажет ететін қолжетімділікті шектеу (мысалы, жасы бойынша шектеу, авторлану).
||
||
155
|
Ролик қолжетімсіз, өйткені сервис сұранымды роботтың жасағанына күмәнданады.
||
||
156
|
Ролик жазылым бойынша ғана қолжетімді.
||
||
150
|
Басқа видеоны көру шектеулері.
||
|| **Өзгесі** | > ||
||
5
|
Плеер жұмысының бұзылуы (HTML ойнатқыштың ойнату қателері және т.б.).
||
||
0
|
Басқа қателер.
||
|#


{% cut "Қате туралы хабарлама жіберудің мысалы" %}

Егер плеерде ашылатын видео жойылған болса, қате туралы хабарлама төмендегідей жіберілуі мүмкін:

```javascript
// Қате туралы хабарламаны жіберу
window.parent.postMessage({
  event: 'error',
  time: 0,
  code: '101'
}, '*');
```
{% endcut %}

## Ойнатқыштың URL параметрлерін қолдау {#url-params}

Видеоны Smart TV мен браузерде ойнату пайдаланушылар үшін ыңғайлырақ болу үшін плеердің URL-іне мына параметрлерді қолдануды қосыңыз:

#|
||
**Параметр**
|
**Сипаттамасы**
|
**Мүмкін болатын мәндер**
||
||
`autoplay`
|
Ойнатуды автоматты түрде іске қосу.
|
- `1` — видео ойнатуды автоматты түрде бастау;

- `0` (немесе параметрдің болмауы) — видеоны автоматты түрде ойнатуды бастамаңыз.

{% cut "Мысал" %}

  ```javascript
  <iframe 
    src="//www.videohosting.com/video?autoplay=1">
  </iframe> 
  ```
{% endcut %}
||
||
`tv`
|
Smart TV құрылғысында ойнатқыштың интерактивті элементтерін көрсетуді басқару.
|
- `1` — видеоны ойнату кезінде интерактивті элементтерді автоматты түрде жасыру;

- `0` (немесе параметр жоқ) — бейнені ойнату кезінде интерактивті элементтерді автоматты түрде жасырмау.

{% cut "Мысал" %}

  ```javascript
  <iframe
    src="//www.videohosting.com/video?tv=1">
  </iframe> 
  ```

{% endcut %}

Параметр барлық элементтердің көрсетілуін басқарады, тек тінтуір көрсеткішімен ғана басуға болады. Оларға мыналар жатады:

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

- маусымдар мен сериялардың аспа тізімдері; 

- ойнату сапасын таңдау батырмалары; 

- ойнатуды басқару мәзірі және т.б.

Бұл элементтер автоматты түрде жасырылса, теледидарда видеоларды көруге ыңғайлы болады.
||
||
`mute`
|
Видеоның дыбысын өшіріп қойып жүктеу.
|
- `1` — видеоның дыбысын пайдаланушы өзі қоспағанша қоспау.

- `0` (немесе параметрдің жоқтығы) — плеердегі дыбыстың хостингтің қалауы бойынша әрекеті, видеоны мүмкіндігінше дыбыспен қосуға болады.
||
||
`controls`
|
Плеерді басқару элементтерін бейнелеу қажет пе (прогресс-бар, сапаны ауыстыру және т.б.).
|
- `1` (немесе параметрдің жоқтығы) — плеерді басқарудың барлық элементтерін көрсету.

- `0` — плеерді басқару элементтерін бейнелемеу.

||
||
`t`
|
Видеоны ойнатуды бастау қажет уақытша белгі.
|
`[number]` — секунд саны.

{% cut "Мысал" %}

Мысалда видео 10:00 (600 c = 10 мин) бастап ойнатыла бастайды.

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

{% endcut %}

||
|#

## Плеерді басқару {#control-player}

Плеермен басқару командалары `iframe-ге` сыртқы терезеден [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) механизмін қолданып жіберіледі. Хабарламаларды `iframe` ішінде қабылдау үшін `message` оқиғасына жазылыңыз. Пәрмендер `method` міндетті өрісі бар JSON-объект болып табылады.

#|
||
**Команда**
|
**Сипаттамасы**
||
||
`play`
|
Ойнатуды бастау немесе жалғастыру.

{% cut "Мысал" %}

```javascript
{
    method: 'play'
} 
```
{% endcut %}

||
||
`pause`
|
Кідірту.

{% cut "Мысал" %}

```javascript
{
    method: 'pause'
} 
```
{% endcut %}

||
||
`seek`
|
Уақыттың абсолютті мәніне айналдыру.

{% cut "Мысал" %}

```javascript 
{
     method: 'seek',
     time: 10, // уақыт секунд түрінде
} 
```
{% endcut %}
||
||
`setVolume`
|
Дыбыс деңгейін орнату.

{% cut "Мысал" %}

```javascript
{
     method: 'setVolume',
     volume: 0.5 // дыбыс деңгейі 0..1
} 
```
{% endcut %}
||
||
`showControls`
|
Плеерді басқару элементтерін мәжбүрлеп көрсету.

{% cut "Мысал" %}

```javascript
{
    method: 'showControls'
} 
```
{% endcut %}
||
||
`skipAd`
|
Жарнаманы өткізіп жіберу әдісі.

{% cut "Мысал" %}

```javascript
{
     method: 'skipAd',
} 
```
{% endcut %}
||
||
`setPlaybackRate`
|
Видеоны ойнату жылдамдығын орнату.

{% cut "Мысал" %}

```javascript
{
     method: 'setPlaybackRate',
     rate: 0.5 // ойнату жылдамдығы  0..1
} 
```
{% endcut %}
||
||
`mute`
|
Дыбысты өшіру.

{% cut "Мысал" %}

```javascript 
{
     method: 'mute'
} 
```
{% endcut %}
||
||
`unmute`
|
Дыбысты қосу.

{% cut "Мысал" %}

```javascript
{
     method: 'unmute'
} 
```
{% endcut %}
||
||
`setQuality`
|
Ойнату сапасын орнату.

{% cut "Мысал" %}

```javascript
{
     method: 'setQuality',
     quality: '720' // 144, 240, 360, 480, 720, 1080, 1440, 2160 немесе auto
} 
```
`auto` параметрі плеерге оңтайлы сапаны өз бетінше таңдауға мүмкіндік береді. Ол әдепкі мәнді қолдана алады немесе қосылым жылдамдығы мен пайдаланушы құрылғысының параметрлерін ескере отырып, барынша жарамды сапаны таңдай алады.

{% endcut %}

||
||
`updateSource`
|
Плеерді `iframe` мәнін тұтас қайта салмай-ақ плеер ішінде ауыстыру.

`params` — кезекті роликті жүктеу параметрлері.

{% cut "Мысал" %}

```javascript
{
  method: 'updateSource',
  data: {
    id: 'some_id',
    params: {},
  }
}
```
{% endcut %}

||
||
`preload`
|
Видеоны ойнатқанға дейін буфферлеуді бастау әдісі.

{% cut "Мысал" %}

```javascript
{
  method: 'preload'
}
```
{% endcut %}

||
||
`requestFullscreen`
|
Толық экрандық режимді ашу әдісі.

{% cut "Мысал" %}

```javascript
{
  method: 'requestFullscreen'
}
```
{% endcut %}

||
||
`exitFullscreen`
|
Толық экрандық режимнен шығу әдістері.

{% cut "Мысал" %}

```javascript
{
  method: 'exitFullscreen'
}
```
{% endcut %}

||
||
`hideControls`
|
Плеерді басқару элементтерін жасыру.

{% cut "Мысал" %}

```javascript
{
    method: 'hideControls'
} 
```
{% endcut %}

||
|#

{% cut "Команда бойынша бейнені іске қосу мысалы" %}

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

### Жауап пішімі {#control-player}

Пәрмендердің орындалуы туралы кері хабар алу үшін видеоның күйі туралы хабарлайтын [оқиғаларды](#events) қолданыңыз.

Мысалы:

- `skipAd` әдісін шақырған кезде жарнаманы сәтті өткізіп жібергенде `adSkip` оқиғасы құралады, егер бір мәселе туындаса — оқиға жіберілмейді. 

- `setPlaybackRate` әдісін қолданған кезде оған жауап ретінде `playbackRateChanged` оқиғасы туындайды. 

Видеоны Smart TV арқылы дұрыс көрсету үшін әрбір әдіс үшін жауап оқиға міндетті түрде болу керек.

<!-- source: kk/_includes/form-webmaster.md -->
<details>
<summary class="button">Қолдау қызметіне жазу</summary>

<br>
<br>

<div style="padding: 15px;
     margin: 10px 0;
     background: #FFFFFF;
     border-radius: 10px;
     border: 1px solid var(--g-color-line-generic);">
  <iframe style="background: #FFFFFF;"
        height="700"
        width="100%"
        frameborder="0"
        src="https://forms.yandex.kz/surveys/1858/?&iframe=1&lang=kk">
  </iframe>
</div>
</details>




<!-- endsource: kk/_includes/form-webmaster.md -->

<!-- source: kk/_includes/style/no-bg-inside-table.md -->

<!-- endsource: kk/_includes/style/no-bg-inside-table.md -->