Transmit data about video status

To improve the quality of videos in the Yandex.Video search, we need to get information about video status. For example, the time when the video started or stopped, was rewound, etc. It is also important to transmit information about errors that occurred while the video was playing.

  1. Events that relate to video status
  2. Error notifications
  3. Support parameters in player URL
  4. Managing your player on Smart TV devices

Events that relate to video status

To transmit data about video status, use the postMessage function for each event that occurs in the player (for example, when the video starts playing). Call the window.parent.postMessage function in JavaScript. Pass the name of the event along with the event's parameters (for example, the progress bar position) as arguments.

Note. Please note that the postMessage function must be called for the parent object — window.parent. This is because the video is placed in a separate frame (in the iframe element) rather than on the main Yandex search results page.
window.parent.postMessage({
    event: <Event name>,
    // additional event parameters
}, ' *');

To display the player in the Yandex.Video app for TV and mobile video search, you need to pass the mandatory events and their parameters. Transmitting additional events makes it easier for users to interact with the player.

Event Description Event parameter
Mandatory
inited

Player initialization.

—
started

Start or continue playing after a pause.
  • time - current progress bar position in seconds.

    If the time parameter is not specified, the default value is 0.

  • duration - total length of the video in seconds. You can round to the nearest second.
timeupdate Video plays (this event is repeated multiple times).
  • time - current progress bar position in seconds.
  • duration - total length of the video in seconds. You can round to the nearest second.

Similar to the native timeupdate event used with the <video> element.
paused

Stop playing.
  • time - current progress bar position in seconds.
ended

Clip viewed through to the end.
  • time - current progress bar position in seconds.
error

Error playing video.

  • time - current progress bar position in seconds.

  • code - error code.
Additional
resumed

Continue playing video.
  • time - current progress bar position in seconds.
  • duration - total length of the video in seconds. You can round to the nearest second.
Note. The resumed event can be replaced with themandatory started event.
rewound

Jump back in video
  • time - current progress bar position in seconds.
  • previousTime — previous progress bar position in seconds.
volumechange Turn sound on, off, or change the volume.
  • volume — current value volumes (0..1).
  • muted - current state of the muted flag (true, false).

Similar to the native volumechange event used with the video element.
adShown

Start of ad display.
  • time - current progress bar position in seconds.
  • duration — total duration of ad in seconds. You can round to the nearest second.
  • skipAdEnabled — ad can be skipped (a notification will appear in the interface).
  • skipAd — skip ad.
Event Description Event parameter
Mandatory
inited

Player initialization.

—
started

Start or continue playing after a pause.
  • time - current progress bar position in seconds.

    If the time parameter is not specified, the default value is 0.

  • duration - total length of the video in seconds. You can round to the nearest second.
timeupdate Video plays (this event is repeated multiple times).
  • time - current progress bar position in seconds.
  • duration - total length of the video in seconds. You can round to the nearest second.

Similar to the native timeupdate event used with the <video> element.
paused

Stop playing.
  • time - current progress bar position in seconds.
ended

Clip viewed through to the end.
  • time - current progress bar position in seconds.
error

Error playing video.

  • time - current progress bar position in seconds.

  • code - error code.
Additional
resumed

Continue playing video.
  • time - current progress bar position in seconds.
  • duration - total length of the video in seconds. You can round to the nearest second.
Note. The resumed event can be replaced with themandatory started event.
rewound

Jump back in video
  • time - current progress bar position in seconds.
  • previousTime — previous progress bar position in seconds.
volumechange Turn sound on, off, or change the volume.
  • volume — current value volumes (0..1).
  • muted - current state of the muted flag (true, false).

Similar to the native volumechange event used with the video element.
adShown

Start of ad display.
  • time - current progress bar position in seconds.
  • duration — total duration of ad in seconds. You can round to the nearest second.
  • skipAdEnabled — ad can be skipped (a notification will appear in the interface).
  • skipAd — skip ad.

An example of data being transferred at the moment when a video launches is given below. When a user clicks the Play button on the player, the window.parent.postMessage function is called along with the necessary parameters.

// Sends message when the video starts playing
window.parent.postMessage({
  event: 'started',
  duration: 30,
  time: 5 / / If the video continues playing starting at 5 seconds
}, ' *');

Error notifications

The player should pass the following error codes to the window.parent.postMessage function so that we find out about any problems that occur:

Error code Description
Video unavailable
101 Video deleted.
102 The videoclip or account has been blocked.
103 The videoclip doesn't exist or the URL is not supported.
100 Other situations when a video is inaccessible.
Restricted access to videoclip
151 Insufficient video viewing rights.
152 Not permitted to play video on other sites.
153 Not permitted to play video in current region.
154 Restricted access requiring user confirmation (for example, due to age restriction).
150 Other video viewing restrictions.
Misc.
5 Player malfunction (error with HTML player, etc.).
0 Misc. errors.
Error code Description
Video unavailable
101 Video deleted.
102 The videoclip or account has been blocked.
103 The videoclip doesn't exist or the URL is not supported.
100 Other situations when a video is inaccessible.
Restricted access to videoclip
151 Insufficient video viewing rights.
152 Not permitted to play video on other sites.
153 Not permitted to play video in current region.
154 Restricted access requiring user confirmation (for example, due to age restriction).
150 Other video viewing restrictions.
Misc.
5 Player malfunction (error with HTML player, etc.).
0 Misc. errors. 
// Sends an error message
window.parent.postMessage({
  event: 'error',
  time: 62,
  code: '101'
}, ' *');

Support parameters in player URL

To make playing videos on Smart TV devices or mobile devices easier for users, you should support the following parameters in the player URL:

Parameter Description Possible values
Mandatory
autoplay

Autoplay
  • 1 — video starts playing automatically
  • 0 (or no parameter) — video will not start playing automatically.
<iframe 
  src="//www.videohosting.com/video?autoplay=1">
</iframe>
tv Controls how interactive player elements display on devices with Smart TV.
  • 1 — interactive elements are automatically hidden when video plays
  • 0 (or no parameter) — interactive elements are not hidden automatically when video plays
<iframe
  src="//www.videohosting.com/video?tv=1">
</iframe>

This parameter controls how all elements that can only be clicked on using a mouse display. These include the progress bar, drop-down lists of seasons and series, buttons for selecting video quality, the video control menu, etc.

If these elements are hidden automatically, it creates a better viewing experience on TVs.
Additional
maxQuality Video quality selection.
small

Player height — 240 pixels.

Minimum player size in 4:3 format is 320 x 240 pixels.

medium

Player height — 360 pixels.

Minimum player dimensions:

  • for 16:9 format — 640 x 360 pixels
  • for 4:3 format — 480 x 360 pixels
large

Player height — 480 pixels.

Minimum player dimensions:

  • for 16:9 format — 853 x 480 pixels
  • for 4:3 format — 640 x 480 pixels
hd720

Player height — 720 pixels.

Minimum player dimensions:

  • for 16:9 format — 1280 x 720 pixels
  • for 4:3 format — 960 x 720 pixels
hd1080

Player height — 1080 pixels.

Minimum player dimensions:

  • for 16:9 format — 1920 x 1080 pixels
  • for 4:3 format — 1440 x 1080 pixels
highres

Player height — 1080 pixels.

Aspect ratio format of more than 1920 x 1080 pixels.

default

Determines the recommended video quality depending on the user settings, video file, and other conditions.

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

Autoplay
  • 1 — video starts playing automatically
  • 0 (or no parameter) — video will not start playing automatically.
<iframe 
  src="//www.videohosting.com/video?autoplay=1">
</iframe>
tv Controls how interactive player elements display on devices with Smart TV.
  • 1 — interactive elements are automatically hidden when video plays
  • 0 (or no parameter) — interactive elements are not hidden automatically when video plays
<iframe
  src="//www.videohosting.com/video?tv=1">
</iframe>

This parameter controls how all elements that can only be clicked on using a mouse display. These include the progress bar, drop-down lists of seasons and series, buttons for selecting video quality, the video control menu, etc.

If these elements are hidden automatically, it creates a better viewing experience on TVs.
Additional
maxQuality Video quality selection.
small

Player height — 240 pixels.

Minimum player size in 4:3 format is 320 x 240 pixels.

medium

Player height — 360 pixels.

Minimum player dimensions:

  • for 16:9 format — 640 x 360 pixels
  • for 4:3 format — 480 x 360 pixels
large

Player height — 480 pixels.

Minimum player dimensions:

  • for 16:9 format — 853 x 480 pixels
  • for 4:3 format — 640 x 480 pixels
hd720

Player height — 720 pixels.

Minimum player dimensions:

  • for 16:9 format — 1280 x 720 pixels
  • for 4:3 format — 960 x 720 pixels
hd1080

Player height — 1080 pixels.

Minimum player dimensions:

  • for 16:9 format — 1920 x 1080 pixels
  • for 4:3 format — 1440 x 1080 pixels
highres

Player height — 1080 pixels.

Aspect ratio format of more than 1920 x 1080 pixels.

default

Determines the recommended video quality depending on the user settings, video file, and other conditions.

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

Managing your player on Smart TV devices

Player control commands are sent to iframe from the outside window using the postMessage function. To receive messages inside the iframe, you need to subscribe to the message event. The command format is a JSON object with the mandatory method field.

Command Description
play

Start or continue playing video.

{
    method: 'play'
}
pause

Pause.

{
    method: 'pause'
}
seek

Jump to an absolute time value.

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

Set volume.

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

Disable sound.

{
    method: 'mute'
}
unmute

Enable sound.

{
    method: 'unmute'
}
setQuality

Set the video quality.

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

Start or continue playing video.

{
    method: 'play'
}
pause

Pause.

{
    method: 'pause'
}
seek

Jump to an absolute time value.

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

Set volume.

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

Disable sound.

{
    method: 'mute'
}
unmute

Enable sound.

{
    method: 'unmute'
}
setQuality

Set the video quality.

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

Example of launching a video using a command

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

Answer format

For feedback on command execution, use video status events.