Events Reference

Event Usage

The Vertical Player emits events when user actions or playback state changes occur. These events can be listened to using a single event listener and distinguished by the returned eventName.

Supported Listener

LISTENER	DESCRIPTION
on(eventName, callback)	Attaches callback to the event identified by eventName. The callback is invoked every time the player emits that event.

Basic Usage Example

<script>
    vpVerticalPlayer("divId")
        .setup(config)
        .then(() => {
            vpVerticalPlayer("divId").on("vp-video-started", (event) => {
                // ...
            });
        });
</script>

Native Video Events

EVENT NAME	DESCRIPTION
waiting	Playback is ready but waiting for more data (buffering).
ended	Playback has finished.
play	User initiated playback.
pause	Playback has been paused.
playing	Playback has started or resumed.
volumechange	Volume level or mute state changed.
stalled	No data is being loaded during a playback attempt.
canplay	Enough data is available to begin playback.
progress	Media buffering progress has been updated.
timeupdate	Current playback time has changed.
loadeddata	First frame of the media has been loaded.
loadedmetadata	Media metadata loaded (duration, dimensions, etc.).
loadstart	Media loading has started.
seeking	A seek operation is in progress.
seeked	A seek operation has completed.
suspend	Browser has intentionally halted media loading.
ratechange	Playback rate has changed.
error	The video element failed to load or decode the source.

Player State Events

EVENT NAME	DESCRIPTION
vp-subtitle-change	Subtitle track was changed.
vp-seeked	Seeking operation has finished.
vp-finished	Video playback has finished.
vp-state-playing	Player entered the playing state.
vp-state-paused	Player entered the paused state.
vp-first-frame	First video frame was loaded.
vp-ready	Player is ready for API calls.
vp-video-switch	Active video was changed.
vp-time	Emitted every 5 seconds with time and duration.
vp-user-interaction	Any user interaction with the player.
vp-video-locked	Video is locked and cannot be played.
vp-muted	Mute state changed through the player. The event detail includes muted and currentTime.
vp-fullscreen	Player entered or left fullscreen. The event detail includes fullscreen.
vp-quality-change	The viewer picked a different quality level. The event detail includes qualityIndex.
vp-resize	The player container was resized. The event detail includes width and height.
vp-viewable	The player entered or left the viewport. The event detail includes viewable.
vp-buffer-change	Buffered amount changed. The event detail includes percentage of the video buffered ahead.
vp-buffer-full	The whole video is buffered.
vp-video-error	A video source failed to load and the feed skipped past it. The event detail includes videoIndex and file.
vp-sharing-open	The share panel was opened.
vp-activation-gesture	The viewer's first interaction anywhere on the page, which browsers require before audio can play.
vp-playlist-appended	Videos were added to the playlist with addVideos(). The event detail includes addedCount, totalCount, and startIndex.
vp-playlist-near-end	The viewer is approaching the end of the playlist, which is the cue to append more videos. The event detail includes videoIndex, remaining, and totalCount.

Timed Link Events

EVENT NAME	DESCRIPTION
vp-timed-link-show	A timed link became visible. The event detail carries the link: title, url, time, and duration when one is set.
vp-timed-link-click	The viewer clicked a timed link. The event detail carries the same fields as vp-timed-link-show.

Playback Health Events

EVENT NAME	DESCRIPTION
vp-play-attempt	Fired once per view when playback is first requested, or backfilled if a failure implies an attempt that was never recorded. The event detail adds autoStart (false only when the viewer started playback) to the shared payload below.
vp-fatal-error	Fired at most once per view when the player gives up on the current video. Always implies an attempt. See the fields below.
vp-error-recovered	Fired when a fatal-class error was survived by a fallback and playback resumed. The event detail adds recoveryReason and recoveryMethod.
vp-autoplay-blocked	Fired when the browser blocks autoplay, after both the unmuted and the muted attempt were rejected. The event detail includes autoStart.
vp-video-interrupted	Fired once when a livestream already in playback is disrupted. The event detail includes reason (networkError, mediaError, or otherError), multiStream, and currentTime. Livestreams only.
vp-video-recovered	Fired once after a livestream recovers from an interruption. The event detail includes currentTime. Livestreams only.

A view is one video. The feed rotates the view on every switch, so swiping through ten videos produces up to ten attempts and up to ten fatal errors, joined by uniqueViewId. Ads ride the current video's view and never produce their own attempt. Geo-blocked videos, videos that are not published yet, and paywall locks are intentional outcomes and are not reported here.

vp-play-attempt, vp-fatal-error and vp-error-recovered share this payload:

FIELD	DESCRIPTION
event	attempt, fatal-error, or error-recovered.
uniqueViewId	Join key for the current view.
userId	Viewer identifier used by analytics.
videoId	Identifier of the current video.
playerId	Configuration identifier of the player instance.
projectId	Project the player belongs to.
file	Source URL of the current video, with any query string removed.
isLive	true when the current video is a livestream.
currentTime	Playback position when the event fired.
isVertical	Always true for the Vertical Player.

vp-fatal-error adds:

FIELD	DESCRIPTION
category	Broad class of the failure: network, media, unsupported, or other.
fatalReason	Machine-readable reason, see the table below.
location	Numeric code matching fatalReason, useful for grouping in dashboards.
phase	start if playback had not begun yet, playback if the video was already playing.
details	Underlying error detail as reported by the streaming library or the browser.
httpCode	HTTP status of the failed request, when the failure was a network response.
extraDetails	JSON string with additional context, including recoveredErrors for this view.

Reasons the Vertical Player reports:

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.
networkError	106	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.
keyError	401	An encryption key could not be loaded or applied.
browserUnsupported	501	The browser cannot play the source at all.
playRejected	502	The browser rejected the play request for a non-policy reason.
otherError	503	Unrecoverable failure that fits none of the above.

The reason vocabulary is shared with the Web Player, so not every value appears in every situation. vp-error-recovered reports recoveryReason (networkError or mediaError) with the recoveryMethod that worked (retry or recoverMediaError).

Ad Events

EVENT NAME	DESCRIPTION
vp-ad-click	User clicked the ad.
vp-ad-first-quartile	Ad reached 25% playback.
vp-ad-second-quartile	Ad reached 50% playback.
vp-ad-third-quartile	Ad reached 75% playback.
vp-ad-complete	Ad finished playback (not skipped).
vp-ad-skip	Ad was skipped by the user.
vp-ad-progress	Ad playback progress update.
vp-ad-impression	Ad impression was registered.
vp-ad-error	Error occurred during ad playback.
vp-ad-time-update	Ad playback time was updated.
vp-ad-ready	The ad finished loading and is ready to play.
vp-ad-play	The ad started or resumed playing.
vp-ad-pause	The ad was paused.
vp-ad-mute	The ad's mute state changed. The event detail includes muted.
vp-ad-skippable	The ad became skippable, or its skip state changed. The event detail includes skippable.

Analytics Events

EVENT NAME	DESCRIPTION
vp-embed	Player was embedded.
vp-video-started	Video playback started.
vp-video-completed	Video playback completed.
vp-first-quartile	25% of the video was watched.
vp-second-quartile	50% of the video was watched.
vp-third-quartile	75% of the video was watched.
vp-video-state	Periodic playback state emitted every 10s.
vp-twenty-view	20 seconds of the video were watched.
vp-true-view	Valid view based on user interaction.
watchedtime	Total watch time tracked.

Generic Event (vp-event / vpEvent)

The Vertical Player emits a generic event called vp-event (vpEvent) that captures all player events, including playback, state, analytics, ad, and native video events.

EVENT NAME	ALIAS	DESCRIPTION
vp-event	vpEvent	Generic event for custom player events.

Listening to All Vertical Player Events

You can listen to all Vertical Player events using the vp-event listener and filter by the eventName property.

vpVerticalPlayer("player").on("vp-event", (e) => {
  console.log("Vertical Player Event:", e.eventName, e);
});