Transmit data about video status

To improve video quality in searches, we need information about video status. For example, the time when the video started, stopped, or was rewound. It's also important to pass on 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. Manage your player on Smart TV devices

Events that relate to video status

To pass on data about a video's 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 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 video search app for TV and in the 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: The current progress bar position in seconds.

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

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

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

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

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

Error playing video.

  • time: The current progress bar position in seconds.

  • code: Error code.
Additional
resumed

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

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

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

Start of ad display.
  • time: The current progress bar position in seconds.
  • duration: The total ad duration in seconds. You don't need to round to the nearest second.
  • skipAdEnabled: The ad can be skipped (a notification appears in the interface).
  • skipAd: Skip the ad.
Event Description Event parameter
Mandatory
inited

Player initialization.

—
started

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

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

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

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

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

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

Error playing video.

  • time: The current progress bar position in seconds.

  • code: Error code.
Additional
resumed

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

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

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

Start of ad display.
  • time: The current progress bar position in seconds.
  • duration: The total ad duration in seconds. You don't need to round to the nearest second.
  • skipAdEnabled: The ad can be skipped (a notification appears in the interface).
  • skipAd: Skip the ad.

Below is an example of data that's transferred when a video starts. When a user clicks on 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 must 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 video doesn't exist or the URL isn't supported.
100 Other situations when a video is inaccessible.
Restricted access to video
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.
Other
5 Player malfunction (for example, an error with the HTML player).
0 Misc. errors.
Error code Description
Video unavailable
101 Video deleted.
102 The videoclip or account has been blocked.
103 The video doesn't exist or the URL isn't supported.
100 Other situations when a video is inaccessible.
Restricted access to video
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.
Other
5 Player malfunction (for example, an error with the HTML player).
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, support the following parameters in the player URL:

Parameter Description Possible values
Mandatory
autoplay

Autoplay
  • 1: Video starts playing automatically.
  • 0 (or no parameter): The video doesn't start playing automatically.
<iframe 
  src="//www.videohosting.com/video?autoplay=1">
</iframe>
tv Controls how interactive player elements are displayed on devices with Smart TV.
  • 1: Interactive elements are automatically hidden when a video plays.
  • 0 (or no parameter): Interactive elements aren't hidden automatically when a video plays.
<iframe
  src="//www.videohosting.com/video?tv=1">
</iframe>

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

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: 320 x 240 pixels.

medium

Player height: 360 pixels.

Minimum player dimensions:

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

Player height: 480 pixels.

Minimum player dimensions:

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

Player height: 720 pixels.

Minimum player dimensions:

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

Player height: 1080 pixels.

Minimum player dimensions:

  • For the 16:9 format: 1920 x 1080 pixels.
  • For the 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): The video doesn't start playing automatically.
<iframe 
  src="//www.videohosting.com/video?autoplay=1">
</iframe>
tv Controls how interactive player elements are displayed on devices with Smart TV.
  • 1: Interactive elements are automatically hidden when a video plays.
  • 0 (or no parameter): Interactive elements aren't hidden automatically when a video plays.
<iframe
  src="//www.videohosting.com/video?tv=1">
</iframe>

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

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: 320 x 240 pixels.

medium

Player height: 360 pixels.

Minimum player dimensions:

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

Player height: 480 pixels.

Minimum player dimensions:

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

Player height: 720 pixels.

Minimum player dimensions:

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

Player height: 1080 pixels.

Minimum player dimensions:

  • For the 16:9 format: 1920 x 1080 pixels.
  • For the 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>

Manage your player on Smart TV devices

Player control commands are sent to the 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.

Team Description
play

Start or continue playing video.

{
    method: 'play'
}
pause

Pause.

{
    method: 'pause'
}
seek

Jump to an absolute time value.

{
    method: 'seek',
    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
}
Team Description
play

Start or continue playing video.

{
    method: 'play'
}
pause

Pause.

{
    method: 'pause'
}
seek

Jump to an absolute time value.

{
    method: 'seek',
    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();
     }
});

Response format

For feedback on command execution, use video status events.