Sending the data about video status

Information about video status helps us improve video playback quality on Yandex.Video. This information includes the time when a clip was started or paused, when the user jumped forward or back, and so on. We also need to know about errors that happened during playback.

  1. Events that send data about video status
  2. Error messages
  3. Supporting parameters in the player URL
  4. Managing the player on Smart TV devices

Events that send data about video status

To send data about video status, use the postMessage mechanism. For every event in the player (such as starting playback), call the window.parent.postMessage function in JavaScript. Pass the event name and the event parameters (for example, progress bar position) in the function arguments.

Note. Note that the postMessage function is called for the parent object window.parent. This is because videos on the Yandex main search results page are displayed in a separate frame (the iframe element). 
window.parent.postMessage({
    event: <Event name>,
    // additional event parameters
}, '*');

To display the player in the Yandex video app for TV and in the mobile video search, you need to send mandatory events and their parameters. Pass additional events to make the interaction with the player easier for the users.

Event Description Event parameters
Mandatory
inited

Player initialization.

—
started

Playback started or resumed after pause.
  • time — Current progress bar position in seconds.

    If the time parameter isn't specified, the default value is 0.

  • duration — Video duration in seconds. The number of seconds doesn't need to be rounded.
timeupdate Video playback (the event is repeated many times).
  • time — Current progress bar position in seconds.
  • duration — Video duration in seconds. The number of seconds doesn't need to be rounded.

Similar to the native timeupdate event of the <video> element.

paused

Playback paused.
  • time — Current progress bar position in seconds.
ended

Video playback is completed (the user reached the end of the clip).
  • time — Current progress bar position in seconds.
error

Playback error.

  • time — Current progress bar position in seconds.

  • code — The error code.

Additional
resumed

Playback resumed.
  • time — Current progress bar position in seconds.
  • duration — Video duration in seconds. The number of seconds doesn't need to be rounded.
Note. The resumed event can be replaced with the mandatory started event.
rewound

Video rewind.
  • time — Current progress bar position in seconds.
  • previousTime — Previous progress bar position in seconds.
volumechange Turning on audio, muting, or changing the volume.
  • volume — Current volume value (0..1).
  • muted — Current value of the muted flag (true, false).

Similar to the native volumechange event of the <video> element.

adShown

Start of ad playback.
  • time — Current progress bar position in seconds.
  • duration — Ad duration in seconds. The number of seconds doesn't need to be rounded.
Event Description Event parameters
Mandatory
inited

Player initialization.

—
started

Playback started or resumed after pause.
  • time — Current progress bar position in seconds.

    If the time parameter isn't specified, the default value is 0.

  • duration — Video duration in seconds. The number of seconds doesn't need to be rounded.
timeupdate Video playback (the event is repeated many times).
  • time — Current progress bar position in seconds.
  • duration — Video duration in seconds. The number of seconds doesn't need to be rounded.

Similar to the native timeupdate event of the <video> element.

paused

Playback paused.
  • time — Current progress bar position in seconds.
ended

Video playback is completed (the user reached the end of the clip).
  • time — Current progress bar position in seconds.
error

Playback error.

  • time — Current progress bar position in seconds.

  • code — The error code.

Additional
resumed

Playback resumed.
  • time — Current progress bar position in seconds.
  • duration — Video duration in seconds. The number of seconds doesn't need to be rounded.
Note. The resumed event can be replaced with the mandatory started event.
rewound

Video rewind.
  • time — Current progress bar position in seconds.
  • previousTime — Previous progress bar position in seconds.
volumechange Turning on audio, muting, or changing the volume.
  • volume — Current volume value (0..1).
  • muted — Current value of the muted flag (true, false).

Similar to the native volumechange event of the <video> element.

adShown

Start of ad playback.
  • time — Current progress bar position in seconds.
  • duration — Ad duration in seconds. The number of seconds doesn't need to be rounded.

Here is an example of sending the video data at the start of playback. When the user clicks the Play button in the player, the window.parent.postMessage. function with the desired parameters is called. 

// Sending a message when the video playback starts
window.parent.postMessage({
  event: 'started',
  duration: 30,
  time: 5 // If the playback is resumed at the 5th second
}, '*');

Error messages

The player should send the following error codes to the window.parent.postMessage function so that we are informed about errors that occur:

Error code Description
Video unavailable
101 Video deleted.
102 The video or account has been blocked.
103 The video doesn't exist or the URL is not supported.
100 Other situations where the video is inaccessible.
Restricted access to video
151 Not enough rights to view the video.
152 The video is prohibited from playing on other sites.
153 The video is prohibited from playing in this region.
154 Access restriction that requires user confirmation (for example, due to age restriction).
150 Other video viewing restrictions.
Other
5 Player error (HTML player error, and so on).
0 Other errors.
Error code Description
Video unavailable
101 Video deleted.
102 The video or account has been blocked.
103 The video doesn't exist or the URL is not supported.
100 Other situations where the video is inaccessible.
Restricted access to video
151 Not enough rights to view the video.
152 The video is prohibited from playing on other sites.
153 The video is prohibited from playing in this region.
154 Access restriction that requires user confirmation (for example, due to age restriction).
150 Other video viewing restrictions.
Other
5 Player error (HTML player error, and so on).
0 Other errors. 
// Sending the error message
window.parent.postMessage({
  event: 'error',
  time: 62,
  code: '101'
}, '*');

Supporting parameters in the player URL

To make it easier to view videos on Smart TVs and mobile devices, support the following parameters in the player URL:

Parameter Description Possible values
Mandatory
autoplay

Automatic playback.
  • 1 — Start video playback automatically.
  • 0 (or parameter omitted) — Don't start video playback automatically. 
<iframe 
  src="//www.videohosting.com/video?autoplay=1">
</iframe>
tv Showing interactive elements of the player on Smart TV devices.
  • 1 — Hide interactive elements automatically when playing the video.
  • 0 (or parameter omitted) — Don't hide interactive elements automatically when playing the video. 
<iframe
  src="//www.videohosting.com/video?tv=1">
</iframe>

This parameter manages showing all elements that can be clicked only with the mouse pointer. These include the progress bar, drop-down lists of seasons and episodes, playback quality buttons, the playback menu, and so on.

On TV, it is easier to watch a video if these elements are automatically hidden.
Additional
maxQuality Choosing the playback quality.
small

The player height is 240 pixels.

Minimum player size for the 4:3 format is 320 х 240 pixels.

medium

The player height is 360 pixels.

Minimum player size:

  • For the 16:9 format — 640 х 360 pixels.
  • For the 4:3 format — 480 х 360 pixels.
large

The player height is 480 pixels.

Minimum player size:

  • For the 16:9 format — 853 х 480 pixels.
  • For the 4:3 format — 640 х 480 pixels.
hd720

The player height is 720 pixels.

Minimum player size:

  • For the 16:9 format — 1280 х 720 pixels.
  • For the 4:3 format — 960 х 720 pixels.
hd1080

The player height is 1080 pixels.

Minimum player size:

  • For the 16:9 format — 1920 х 1080 pixels.
  • For the 4:3 format — 1440 х 1080 pixels.
highres

The player height is more than 1080 pixels.

The aspect ratio format is more than 1920 х 1080 pixels.

default

Defines the recommended playback quality based on the user settings, video file and other factors.

<iframe
  src="//www.videohosting.com/video?maxQuality=hd720">
</iframe>
Parameter Description Possible values
Mandatory
autoplay

Automatic playback.
  • 1 — Start video playback automatically.
  • 0 (or parameter omitted) — Don't start video playback automatically. 
<iframe 
  src="//www.videohosting.com/video?autoplay=1">
</iframe>
tv Showing interactive elements of the player on Smart TV devices.
  • 1 — Hide interactive elements automatically when playing the video.
  • 0 (or parameter omitted) — Don't hide interactive elements automatically when playing the video. 
<iframe
  src="//www.videohosting.com/video?tv=1">
</iframe>

This parameter manages showing all elements that can be clicked only with the mouse pointer. These include the progress bar, drop-down lists of seasons and episodes, playback quality buttons, the playback menu, and so on.

On TV, it is easier to watch a video if these elements are automatically hidden.
Additional
maxQuality Choosing the playback quality.
small

The player height is 240 pixels.

Minimum player size for the 4:3 format is 320 х 240 pixels.

medium

The player height is 360 pixels.

Minimum player size:

  • For the 16:9 format — 640 х 360 pixels.
  • For the 4:3 format — 480 х 360 pixels.
large

The player height is 480 pixels.

Minimum player size:

  • For the 16:9 format — 853 х 480 pixels.
  • For the 4:3 format — 640 х 480 pixels.
hd720

The player height is 720 pixels.

Minimum player size:

  • For the 16:9 format — 1280 х 720 pixels.
  • For the 4:3 format — 960 х 720 pixels.
hd1080

The player height is 1080 pixels.

Minimum player size:

  • For the 16:9 format — 1920 х 1080 pixels.
  • For the 4:3 format — 1440 х 1080 pixels.
highres

The player height is more than 1080 pixels.

The aspect ratio format is more than 1920 х 1080 pixels.

default

Defines the recommended playback quality based on the user settings, video file and other factors.

<iframe
  src="//www.videohosting.com/video?maxQuality=hd720">
</iframe>

Managing the player on Smart TV devices

The player management commands are sent in an iframe from the parent window using the postMessage mechanism. To receive messages inside the iframe, subscribe to the message event. The command is a JSON object with the mandatory method field.

Command Description
play

Start or resume playback.

{
    method: 'play'
}
pause

Pause.

{
    method: 'pause'
}
seek

Rewind or fast forward to an absolute time value.

{
    method: 'seek',
    time: 10, // time in seconds
}
setVolume

Setting the volume level.

{
    method: 'setVolume',
    volume: 0.5 // volume 0..1
}
mute

Muting the volume.

{
    method: 'mute'
}
unmute

Unmuting the volume.

{
    method: 'unmute'
}
setQuality

Setting the playback quality.

{
    method: 'setQuality',
    quality: 'hd720' // small, medium, large, hd720, hd1080, highres или default
}
Command Description
play

Start or resume playback.

{
    method: 'play'
}
pause

Pause.

{
    method: 'pause'
}
seek

Rewind or fast forward to an absolute time value.

{
    method: 'seek',
    time: 10, // time in seconds
}
setVolume

Setting the volume level.

{
    method: 'setVolume',
    volume: 0.5 // volume 0..1
}
mute

Muting the volume.

{
    method: 'mute'
}
unmute

Unmuting the volume.

{
    method: 'unmute'
}
setQuality

Setting the playback quality.

{
    method: 'setQuality',
    quality: 'hd720' // small, medium, large, hd720, hd1080, highres или default
}

Example of starting a video with a command

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

Response format

To get feedback about completed commands, use video status events.