Transmit the video status data

To improve the quality of video search and playback, we require information about the video's 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.

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 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 makes it easier for users to interact with the player. Signals help us rank videos better.

Event

Description

Event parameter

Mandatory

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 (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.

See Examples*

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 ads are played before the video, send the event when the first frame of the video shows up after the end of the ad unit.
  • time: The current progress bar position in seconds.

Additional

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 (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 (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 (small, medium, large, hd720, hd1080, highres, 4K, or default).

adSkip

Skips the ad. Doesn't substitute adEnd.

qualityChange

Change the video quality
  • quality: 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)

clickout

Clickout to ads (service) from the player.

  • source: Clickout type.

    • 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: The followed link.

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

* Examples of data for the adShown event

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
    }
  ]
}

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
    }
  ]
}

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.

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

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 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 (for example, an error with the HTML player).

0

Misc. errors.

If the video that opens in the player was deleted, the error message may look like this:

// 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 browsers, add these parameters to the player URL:

Parameter

Description

Possible values

Mandatory

autoplay

Autoplay

  • 1: automatically start playing video.

  • 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.

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.
<iframe
  src="//www.videohosting.com/video?t=600">
</iframe>

The example shows the video starting at 10:00 (600 c = 10 min).

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, 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
}

updateSource

Method to change the video inside the player without redrawing the entire iframe.

  • params: Parameters for loading the next video.
{
  method: 'updateSource',
  data: {
    id: 'some_id',
    params: {},
  }
}

preload

Method to trigger video buffering before playback.

{
  method: 'preload'
}

requestFullscreen

Method to switch to fullscreen.

{
  method: 'requestFullscreen'
}

exitFullscreen

Method to exit fullscreen.

{
  method: 'exitFullscreen'
}

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.

Contact support

Previous
Mobile player
Next
Prohibit showing videos in search results