Events Reference

Event Usage

Certain events are triggered when the player does something. Certain events also return information. You will find the plethora of events listed and divided based on their function down below.

Currently, VP Player events support the following event triggers:

LISTENER	DESCRIPTION	EXAMPLE
on(event)	Using an on listener will continually listen for an event for a specified player. If this player is removed and set up again, the listener will also need to be reinstated.	vpPlayer().on(event, [callback])
once(event)	Listens for an event a single time. The listener removes itself once it has fired.	vpPlayer().once(event, [callback])
off(event)	Removes a listener that was added with on(). Pass the same callback reference you passed to on().	vpPlayer().off(event, callback)
offAll(event)	Removes every listener registered for an event on this player.	vpPlayer().offAll(event)

You can see an example of this code being used below. The below event triggers every time a volume change is initiated and will return a number called "volume" within an object.

vpPlayer().on("play", (e) => {
    vpPlayer().setVolume(0.7);
});

The tables of events below are divided into Playback Events, Player State Events, Timed Link Events, Playback Health Events, Ad Events, and Analytics Events.

Playback Events

EVENT	DESCRIPTION
beforeComplete	Fired just before the player completes playing. Unlike the onComplete event, the player will not have moved on to either showing the replay screen or advancing to the next playlistItem.
bufferChange	Fired when the currently playing item loads additional data into its buffer.
bufferFull	Fired when buffer is full.
cast	Triggered when a cast property changes.
complete	Fired when an item completes playback.
error	Signals a critical error in the playback process.
firstFrame	Triggered by a video's first frame event (or the instant an audio file begins playback). This event pinpoints when content playback begins.
levelsChanged	Fired when the active quality level is changed.
mute	Triggered when the player has gone in or out of a mute state.
pause	Fired when the player enters the paused state.
play	Fired when the player enters the playing state.
playlistItem	Fired when the playlist index changes to a new playlist item. This event occurs before the player begins playing the new playlist item.
ready	Signifies when the player has been initialized and is ready for playback. This is the earliest point at which any API calls should be made.
seek	Fired immediately when a seek action starts.
seeked	Fired immediately when a seek action ends.
subtitleChange	Sent when the user changes the subtitle for this video.
time	While the player is playing, this event is fired as the playback position gets updated. This may occur every 5 seconds.
visualQuality	Fired when the active quality level is changed for HLS. This is different from levelsChanged since this will trigger when adaptive streaming automatically shifts quality.

Player State Events

EVENT	DESCRIPTION
float	Triggered when the player has gone in or out of a float state.
fullscreen	Fired when the player toggles to/from fullscreen.
nextClick	Fired when user click on next video.
relatedOpen	Triggers when the recommendations videos list is opened.
sharingOpen	Listens for the opening of the share interface.
viewable	Fired when the viewable property of the player changes.
interrupted	Fired once when a livestream is disrupted by a sustained buffer stall or a network or media error. The event detail includes reason (bufferStall, networkError, mediaError or otherError), multiStream, and currentTime. Livestreams only.
recovered	Fired once after a livestream recovers from an interruption. The event detail includes currentTime.

Timed Link Events

EVENT	DESCRIPTION
timedLinkShow	Fired when a timed link becomes visible or switches to another link. The event detail carries the link: title, url, time, and duration when one is set.
timedLinkClick	Fired when the viewer clicks a timed link. The event detail carries the same fields as timedLinkShow.

Playback Health Events

These events report whether playback worked, so integrations can monitor stream health from the page. Only unexpected failures are reported here — geo-blocked videos, videos that are not published yet, password prompts and paywall locks are intentional outcomes and are not counted as failures.

EVENT	DESCRIPTION
playAttempt	Fired once per view when playback is first requested, either by autoplay or by the viewer. The event detail adds autoStart (true when the player started playback on its own) to the shared payload below.
fatalError	Fired at most once per view, when the player gives up on the video and shows the error screen. A fatal error always implies an attempt, so the player backfills playAttempt if it was never fired.
errorRecovered	Fired every time an error that would have been fatal was survived by a fallback and playback resumed. The event detail adds recoveryReason and recoveryMethod.
autoplayBlocked	Fired when the browser blocks autoplay, after both the unmuted and the muted attempt were rejected. The event detail includes autoStart. This is a browser policy, not a playback failure, so no fatal error is reported.

A view is one watch of one video: moving to the next video in a playlist, setting a new video through the API, and replaying a finished video each start a new view. All events from the same view share the same uniqueViewId, which is the property to join them on. Ads belong to the view of the video they play in and never produce an attempt of their own.

playAttempt, fatalError and errorRecovered share the following payload:

PROPERTY	DESCRIPTION
event	attempt, fatal-error or error-recovered.
uniqueViewId	The identifier shared by all events of the current view.
userId	The viewer identifier used by analytics.
videoId	The ID of the current video.
playerId	The configuration ID of the player.
projectId	The project the player belongs to.
file	The source URL of the current video, with the query string removed.
isLive	Whether the current video is a live stream.
currentTime	The playback position when the event was fired.
playerSdkVersion	The version of the player that produced the event, so attempt and error rows can be grouped by player version.

fatalError adds the following properties:

PROPERTY	DESCRIPTION
category	The broad class of the failure: network, media, drm, unsupported or other.
fatalReason	The specific reason, see the table below.
location	A numeric code matching fatalReason, useful for grouping in dashboards.
phase	start when playback had not begun yet, playback when the video was already playing.
details	The underlying error detail as reported by the streaming library or the browser.
httpCode	The HTTP status of the failed request, when the failure came from a network response.
extraDetails	A JSON string with additional context, including recoveredErrors — the number of errors recovered in this view.

The reasons and their codes are grouped by the nature of the failure: 1xx the source could not be reached, 2xx the content was unusable, 3xx the browser could not decode it, 4xx encryption or DRM, 5xx the environment or anything else.

REASON	CODE	MEANING
fileMissing	101	No source URL was provided for the video.
fileUnreachable	102	The manifest or file could not be loaded.
levelUnreachable	103	A quality rendition could not be loaded.
preparingFailed	104	The video never became available while the preparing screen was polling.
failoverExhausted	105	Every configured stream was tried and none of them played.
networkError	106	A network failure without a more specific reason.
manifestEmpty	201	The manifest loaded but contained no streams.
streamEmpty	202	The stream loaded but contained no segments.
segmentError	203	A segment failed to load or parse.
codecUnsupported	301	The browser cannot decode the codecs in the stream.
decodeError	302	The browser failed to decode the media.
mediaRecoveryExhausted	303	Media recovery was attempted repeatedly and playback still did not resume.
keyError	401	An encryption key could not be loaded or applied.
drmError	402	The DRM license could not be obtained or was rejected.
browserUnsupported	501	The browser cannot play the source at all.
playRejected	502	The browser rejected the play request for a reason other than its autoplay policy.
otherError	503	An unrecoverable failure that fits none of the above.

errorRecovered reports recoveryReason (networkError, mediaError, bufferStall or otherError) together with the recoveryMethod that worked: streamSwitch, recoverMediaError, codecSwap, levelDrop or retry.

note

Live streams keep retrying instead of giving up on network failures, so the reasons a live stream can report are not the same as the ones a VOD video can report. When you build health dashboards, split them on isLive — the two are not comparable. The interrupted and recovered events in Player State Events cover live streams that break and come back while already playing.

Ad Events

EVENT	DESCRIPTION
adClick	VAST and IMA. Fired whenever a user clicks an ad to be redirected to its landing page.
adComplete	VAST and IMA. Fired whenever an ad has completed playback.
adError	VAST and IMA. Fired whenever an error prevents the ad from playing.
adImpression	The time indicated by the video element's currentTime attribute has changed.
adMute	Triggered when the player has gone in or out of a mute state during ad played.
adPause	Fired whenever an ad is paused.
adPlay	Fired whenever an ad starts playing or when an ad is unpaused.
adSkippable	Fired the instant the ad can be skipped.
adSkipped	VAST and IMA. Fired whenever an ad has been skipped.
adTime	Fired while ad playback is in progress.
analytic-ad-25%-completed	Fired when the ad is quarter-way completed.
analytic-ad-50%-completed	Fired when the ad is halfway completed.
analytic-ad-75%-completed	Fired when the ad is a quarter away from being completed.

Analytics Events

EVENT	DESCRIPTION
video-completed	Fired when the video is completed.
video-started	Fired when the video starts.
video-state	Fired every 10 seconds. Its duty is to check whether the video at the moment is paused, playing, whether it is muted or not, its volume etc.
analytics-25%-completed	Fired when the video is quarter-way completed.
analytics-50%-completed	Fired when the video is halfway completed.
analytics-75%-completed	Fired when the video is a quarter away from being completed.
twenty-view	Fired once 20 seconds of the video have been watched.
true-view	Fired when the view is counted as a true view, meaning the viewer interacted with the player.
embed-loaded	Fired when the player embed is loaded on the page.
watchedtime	Fired with the accumulated watch time of the current view.

All Events

You can setup a listener on all events for a specific player, by listening on vp-event events, and get all properties for a specified event based on its name eventName property:

vpPlayer().on("vp-event", (e) => {
    // Check for specific eventName
    if (e.eventName == "play") {
        console.log("Event play was just triggered on VP Player events");
    }
});