Analytics

An overview of the events used for analytics

---

When viewers interact with an audio player on your site, their actions trigger player events. Some of the player events return audio metrics that you can use to analyze and improve your viewers' audio experiences.

Events

VP Player's analytics section is comprised of events that return audio metrics about the audio and events that return audio metrics about the ads. This section gives you an example of how to use each and every one of these events as well as the description to what each event does.

Audio Events

---

beforeComplete

vpAudioPlayer().on(“beforeComplete”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
beforeComplete	Fired just before the player completes playing. Unlike the onComplete event, the player will not have moved on to advancing to the next playlist item.

pause

vpAudioPlayer().on(“pause”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
pause	Fired when the player enters the paused state.

play

vpAudioPlayer().on(“play”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
play	Fired when the player enters the playing state.

mute

vpAudioPlayer().on(“mute”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
mute	Fired when the player changes the muted state.

time

vpAudioPlayer().on(“time”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
time	Fired every five seconds while the audio is playing.

ready

vpAudioPlayer().on(“ready”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
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.

error

vpAudioPlayer().on(“error”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
error	Fired when an error occurs in the audio playback.

playlistOpen

vpAudioPlayer().on(“playlistOpen”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
playlistOpen	Listens for the opening of the playlist interface.

playlistItem

vpAudioPlayer().on(“playlistItem”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
playlistItem	Fires when the playlist item being played is changed.

nextClick

vpAudioPlayer().on(“nextClick”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
nextClick	Fires when the "next" button is pressed.

previousClick

vpAudioPlayer().on(“previousClick”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
previousClick	Fires when the "previous" button is pressed.

infoOpen

vpAudioPlayer().on(“infoOpen”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
infoOpen	Listens for the opening of the info interface.

seek

vpAudioPlayer().on(“seek”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
seek	Fired when a seek happens and it shows the start point and the end point of the seek.

seeked

vpAudioPlayer().on(“seeked”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
seeked	Fired after a seek occurs.

complete

vpAudioPlayer().on(“complete”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
completed	Fired when the audio is completed.

started

vpAudioPlayer().on(“started”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
started	Fired when the audio starts.

viewable

vpAudioPlayer().on(“viewable”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
viewable	When the player is viewable, a viewable event is fired with a viewable value of 1. When hidden, it fires with a value of 0.

firstQuartile

vpAudioPlayer().on(“firstQuartile”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
firstQuartile	Fired when the audio is quarter-way completed.

secondQuartile

vpAudioPlayer().on(“secondQuartile”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
secondQuartile	Fired when the audio is halfway completed.

thirdQuartile

vpAudioPlayer().on(“thirdQuartile”, (e) => {
    // Start making API calls
});

EVENT	DESCRIPTION
thirdQuartile	Fired when the audio is a quarter away from being completed.

Playback Health Events

These events report whether playback worked, so a page can monitor stream health. Only unexpected failures are reported. Locked audio and ads that fail are not counted. They can be switched off together with the analytics rows they mirror through config.playbackHealth.

vpAudioPlayer().on("vp-fatal-error", (e) => {
    // e.fatalReason, e.category, e.uniqueViewId ...
});

EVENT	DESCRIPTION
vp-play-attempt	Fired once per view when playback is first requested, right before the browser is asked to play. A request deferred by a preroll counts when it actually reaches the audio element. Adds autoStart to the shared payload below.
vp-fatal-error	Fired at most once per view, when the player has exhausted its recovery ladder and gives up on the audio. A fatal error always implies an attempt, so the player backfills vp-play-attempt if it was never fired.
vp-error-recovered	Fired every time an error that would have been fatal was survived by a retry, a media error recovery or an audio codec swap, and audio is flowing again. Adds recoveryReason and recoveryMethod.
vp-autoplay-blocked	Fired when the browser refuses to start playback under its autoplay policy. This is not a playback failure and produces no fatal error.

A view is one play of one audio. Moving to another item in a playlist and replaying a finished audio each start a new view. All events from the same view share the same uniqueViewId.

vp-play-attempt, vp-fatal-error and vp-error-recovered 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 listener identifier used by analytics.
videoId	The ID of the current audio. The field keeps the name shared with the video players.
playerId	The configuration ID of the player.
projectId	The project the player belongs to.
playerType	Always audio. This is how audio rows are told apart from the video players in the shared table.
file	The source URL of the current audio, with the query string removed.
isLive	Whether the current audio is a live stream.
currentTime	The playback position when the event was fired.
playerSdkVersion	The version of the player that produced the event.

vp-fatal-error adds category (network, media, unsupported or other), fatalReason and its numeric location code, phase (start before playback began, playback after), the underlying details, the httpCode when the failure was a network response, and extraDetails. The reason vocabulary is shared with the Web Player. vp-error-recovered reports recoveryReason (networkError or mediaError) with the recoveryMethod that worked: retry, recoverMediaError or codecSwap.