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.
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.
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. |
|
timeupdate | Video plays (this event is repeated multiple times). |
Similar to the native timeupdate event used with the |
paused | Stop playing. |
|
ended | Clip viewed through to the end. |
|
error | Error playing video. |
|
Additional | ||
resumed | Continue playing video. |
Note. The resumed event can be replaced with themandatory started event. |
rewound | Jump back in video |
|
volumechange | Turn sound on, off, or change the volume. | Similar to the native volumechange event used with the |
adShown | Start of ad display. |
|
Event | Description | Event parameter |
---|---|---|
Mandatory | ||
inited | Player initialization. | — |
started | Start or continue playing after a pause. |
|
timeupdate | Video plays (this event is repeated multiple times). |
Similar to the native timeupdate event used with the |
paused | Stop playing. |
|
ended | Clip viewed through to the end. |
|
error | Error playing video. |
|
Additional | ||
resumed | Continue playing video. |
Note. The resumed event can be replaced with themandatory started event. |
rewound | Jump back in video |
|
volumechange | Turn sound on, off, or change the volume. | Similar to the native volumechange event used with the |
adShown | Start of ad display. |
|
Event | Description | Event parameter |
---|---|---|
Mandatory | ||
inited | Player initialization. | — |
started | Start or continue playing after a pause. |
|
paused | Stop playing. |
|
ended | Clip viewed through to the end. |
|
error | Error playing video. |
|
Additional | ||
resumed | Continue playing video. |
Note. The resumed event can be replaced with themandatory started event. |
rewound | Jump back in video |
|
adShown | Start of ad display. |
|
Event | Description | Event parameter |
---|---|---|
Mandatory | ||
inited | Player initialization. | — |
started | Start or continue playing after a pause. |
|
paused | Stop playing. |
|
ended | Clip viewed through to the end. |
|
error | Error playing video. |
|
Additional | ||
resumed | Continue playing video. |
Note. The resumed event can be replaced with themandatory started event. |
rewound | Jump back in video |
|
adShown | Start of ad display. |
|
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 |
|
tv | Controls how interactive player elements display on devices with Smart TV. |
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: large Player height — 480 pixels. Minimum player dimensions: hd720 Player height — 720 pixels. Minimum player dimensions: hd1080 Player height — 1080 pixels. Minimum player dimensions: 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. |
Parameter | Description | Possible values |
---|---|---|
Mandatory | ||
autoplay | Autoplay |
|
tv | Controls how interactive player elements display on devices with Smart TV. |
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: large Player height — 480 pixels. Minimum player dimensions: hd720 Player height — 720 pixels. Minimum player dimensions: hd1080 Player height — 1080 pixels. Minimum player dimensions: 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. |
To make it easier for users to play videos on mobile devices, make sure to support the required parameter in the player URL:
Parameter | Description | Possible values |
---|---|---|
autoplay | Autoplay |
|
Parameter | Description | Possible values |
---|---|---|
autoplay | Autoplay |
|
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. |
pause | Pause. |
seek | Jump to an absolute time value. |
setVolume | Set volume. |
mute | Disable sound. |
unmute | Enable sound. |
setQuality | Set the video quality. |
Command | Description |
---|---|
play | Start or continue playing video. |
pause | Pause. |
seek | Jump to an absolute time value. |
setVolume | Set volume. |
mute | Disable sound. |
unmute | Enable sound. |
setQuality | Set the video quality. |
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.