Transmit the video status data

To make video search work better and show more relevant recommendations, make sure to transmit information about video status events (such as playback start, pause, and rewind times) and any possible errors.

Events that relate to video status

To transmit the video status data, use the postMessage function. When an event occurs in the player (for example, when a video starts playing), call the window.parent.postMessage function in JavaScript. Pass the name of the event along with its parameters (for example, the progress bar position) as arguments.

Function usage example
window.parent.postMessage({
    event: <Event name>,
    // additional event parameters
}, '*');

Note

The postMessage function is called for the parent object, window.parent, because the video is placed in a separate frame (in the iframe element) rather than on the main Yandex search results page.

To display the video player in the video search app for TV and in your browser, you need to transmit the mandatory events and their parameters.

Transmitting additional events enhances the user experience when interacting with the player and helps us rank videos more effectively.

Event

Description

Event parameter

inited

Player initialization.

—

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.

started

Start or continue playing after a pause.

  • time: The current progress bar position in seconds.

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

  • duration: The video duration in seconds. You can round to the nearest second.

  • muted: The sound is off. Possible values: 0 or 1.

  • quality: The video quality (possible values: small, medium, large, hd720, hd1080, highres, 4K, or default).

timeupdate

Video plays (this event is repeated multiple times).

  • time: The current progress bar position in seconds.

  • duration: The video duration in seconds. You can round to the nearest second.

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

error

Error playing video, the video is unavailable.

  • time: The current progress bar position in seconds.

  • code: The error code.

  • message: The message with information about the error type.

adShown

Start of ad display.

  • count: The number of ads to be shown in the current ad unit.

  • time: The current progress bar position in seconds.

  • ads: The array of the ad list data. It contains the following parameters for each ad in the array:

    • duration: The total ad length in seconds. You can round to the nearest second.

    • skip: The ad can be skipped (a notification appears in the interface). Possible values: 0 or 1.

Examples of data for the adShown event
Example 1

When an ad unit begins playback at the 30th second of the video and consists of two ads, where the first ad is 15 seconds and can be skipped, and the second ad is 25 seconds and can't be skipped, the adShown event should include the following:

{
  count: 2,
  time: 30,
  ads: [{
      duration: 15.0,
      skip: 1
    },{
      duration: 25.3,
      skip: 0
    }
  ]
}
Example 2

For an ad unit with a single ad that plays at the very beginning of the video (preroll), lasts 45 seconds, and can't be skipped:

{
  count: 1,
  time: 0,
  ads: [{
      duration: 45.5,
      skip: 0
    }
  ]
}

Note

The ad parameters can be sent as a separate beforeAdStart event.

adEnd

End of ad display.

time: The current progress bar position in seconds.

contentImpression

First video frame display.

Note

If the video is preceded by an ad, send this event during the first frame of the actual video, after the ad ends.

time: The current progress bar position in seconds.

Event

Description

Event parameter

rewound

Jump back in video

  • time: The current progress bar position in seconds.

  • previousTime : The previous progress bar position in seconds.

resumed

Continue playing video.

  • time: The current progress bar position in seconds.

  • duration: The video duration in seconds. You can round to the nearest second.

  • muted: The sound is off. Possible values: 0 or 1.

  • quality: The video quality (possible values: small, medium, large, hd720, hd1080, highres, 4K, or default).

Note

The resumed event can be replaced with the mandatory started event.

volumechange

Turn sound on, off, or change the volume.

  • volume: The current volume value (0..1).

  • muted: The current state of the muted flag (1, 0).

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

bufferingStarted

Buffering of the video or a video segment has started.

  • size: The number of bytes to be loaded.

  • time: The current progress bar position in seconds.

  • quality: The video quality (possible values: small, medium, large, hd720, hd1080, highres, 4K, or default).

bufferingEnded

A video segment has loaded.
  • time: The current progress bar position in seconds.
  • quality: The video quality (possible values: small, medium, large, hd720, hd1080, highres, 4K, or default).

adSkip

Skips the ad. Doesn't substitute adEnd.

—

adSkippable

Indicates whether the ad can be skipped using the skipAd method.
  • time: The current progress bar position in seconds.

qualityList

List of available quality values.

list: List of quality values available for a video (possible values: 144, 240, 360, 480, 720, 1080, 1440, 2160).

qualityChange

Change the video quality

  • quality: The video quality (possible values: small, medium, large, hd720, hd1080, highres, 4K, or default).

  • time: The current progress bar position in seconds.

playbackRateChange

Change the playback rate.

  • time: The current progress bar position in seconds.

  • rate: Acceleration/deceleration rate.

fullscreen

Switch the player to fullscreen or exit fullscreen.

enabled: Enabled or not.

playerReady

The player is now loaded and ready for use (data and player API have loaded)

—

playbackRateChanged

Change the video playback rate.

  • rate: Playback speed 0..1.

  • time: The current progress bar position in seconds.

controlsHidden

Whether the player controls are hidden programmatically (using the hideControls method rather than through temporary hiding).

time: The current progress bar position in seconds.

controlsShown

Whether the player controls are visible (as a result of a showControls method call rather than being displayed temporarily).

time: The current progress bar position in seconds.

clickout

Clickout to ads (service) from the player.

  • source: Clickout type. Possible values:

    • adv: Clickout to ads.

    • related: Clickout to another video from the video unit inside the player.

    • self: Clickout to the same video in the service via the logo.

    • unknown: Other clickout.

  • url: Destination URL.

sourceUpdated

Send this event whenever a video is replaced inside the iframe. For example, if the player allows changing the video through the API without rebuilding the player, the event signals a video replacement.

  • id: The video identifier.

  • params: Any other video parameters.

fullscreenError

An error occurred while trying to switch to fullscreen or exit fullscreen.

message: The error message.

qualityList

List of available quality values.

list: Possible values: small, medium, large, hd720, hd1080, highres, 4K, or default.
Example of transferring data 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.

// Send a 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

To enable video error notifications, the player needs to pass the following error codes to the window.parent.postMessage function:

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 that requires the user to confirm something, for example, their age or a login attempt.

155

The video isn't available because the service flagged the request as coming from a bot.

156

The video requires a subscription to view.

150

Other video viewing restrictions.

Other

5

Player malfunction (error with HTML player, etc.).

0

Misc. errors.
Example of sending an error message

If the video the player attempts to open has been deleted, you can send an error message as follows:

// Send an error message
window.parent.postMessage({
  event: 'error',
  time: 0,
  code: '101'
}, '*');

Support parameters in player URL

For a smoother video experience on Smart TVs and in browsers, add support for these parameters to the player URL:

Parameter

Description

Possible values

autoplay

Autoplay

  • 1: The video starts playing automatically.

  • 0 (or no parameter): The video doesn't start playing automatically.

Example
<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 a video plays.

  • 0 (or no parameter): Interactive elements aren't hidden automatically when a video plays.

Example
<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:

  • Progress bar.

  • Dropdown lists with seasons and episodes.

  • Playback quality controls.

  • Menu with playback controls and other options.

If these elements are hidden automatically, it creates a better viewing experience on TVs.

mute

Load muted videos.

  • 1: Don't enable sound in the video until the user turns it on manually.

  • 0 (or no parameter): The hosting controls the sound in the player and can turn on the sound for videos when possible.

controls

Display control elements (progress bar, quality change, and others) in the video player.

  • 1 (or no parameter): Show all the player control elements.

  • 0: Don't display the player control elements.

t

The timestamp where the video should start playing.

[number]: Number of seconds.

Example

The example shows the video starting at 10:00 (600 seconds = 10 minutes).

<iframe
  src="//www.videohosting.com/video?t=600">
</iframe>

Managing the player

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

Team

Description

play

Start or continue playing video.

Example
{
    method: 'play'
}

pause

Pause.

Example
{
    method: 'pause'
}

seek

Jump to an absolute time value.

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

setVolume

Set volume.

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

showControls

Force the display of the player controls.

Example
{
    method: 'showControls'
}

skipAd

Method for skipping the ad.

Example
{
     method: 'skipAd',
}

setPlaybackRate

Set the video playback speed.

Example
{
     method: 'setPlaybackRate',
     rate: 0.5 // playback speed  0..1
}

mute

Disable sound.

Example
{
     method: 'mute'
}

unmute

Enable sound.

Example
{
     method: 'unmute'
}

setQuality

Set the video quality.

Example
{
     method: 'setQuality',
     quality: '720' // 144, 240, 360, 480, 720, 1080, 1440, 2160, or auto
}

The auto parameter allows the player to determine the optimal quality automatically. It can use the default value or choose the optimal quality based on the user's internet speed and device settings.

updateSource

Method for changing the video inside the player without re-rendering the whole iframe.

params: Parameters for loading the next video.

Example
{
  method: 'updateSource',
  data: {
    id: 'some_id',
    params: {},
  }
}

preload

Method for triggering video buffering before playback.

Example
{
  method: 'preload'
}

requestFullscreen

Method for switching to fullscreen.

Example
{
  method: 'requestFullscreen'
}

exitFullscreen

Method for exiting fullscreen.

Example
{
  method: 'exitFullscreen'
}

hideControls

Hide the player controls.

Example
{
    method: 'hideControls'
}
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 events indicating the video status.

For example:

  • Successfully skipping an ad via a skipAd call generates an adSkip event. If a problem occurs, the event isn't sent.

  • Using the setPlaybackRate method triggers the playbackRateChanged event in response.

To ensure correct video playback on Smart TVs, each method must have a response event.

Contact support

Previous
Mobile player
Next
Prohibit showing videos in search results