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.
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.
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. |
|
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. |
|
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 |
|
tv | Controls how interactive player elements are displayed on devices with Smart TV. |
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: 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 are displayed on devices with Smart TV. |
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: 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 |
|
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. |
pause | Pause. |
seek | Jump to an absolute time value. |
setVolume | Set volume. |
mute | Disable sound. |
unmute | Enable sound. |
setQuality | Set the video quality. |
Team | 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();
}
});
Response format
For feedback on command execution, use video status events.