Snowplow media tracking
This plugin is the recommended way to manually track media events from video players. This plugin allows you to implement media tracking for any player.
The plugin is available since version 3.12 of the tracker.
Snowplow media events and entities must be manually tracked.
Install plugin
- JavaScript (tag)
- Browser (npm)
Tracker Distribution | Included |
---|---|
sp.js | ❌ |
sp.lite.js | ❌ |
Download:
Download from GitHub Releases (Recommended) | Github Releases (plugins.umd.zip) |
Available on jsDelivr | jsDelivr (latest) |
Available on unpkg | unpkg (latest) |
window.snowplow(
'addPlugin',
'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-media@3/dist/index.umd.min.js',
['snowplowMedia', 'SnowplowMediaPlugin']
);
npm install @snowplow/browser-plugin-media@3
yarn add @snowplow/browser-plugin-media@3
pnpm add @snowplow/browser-plugin-media@3
import { newTracker, trackPageView } from '@snowplow/browser-tracker';
import { SnowplowMediaPlugin } from '@snowplow/browser-plugin-media';
newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
plugins: [ SnowplowMediaPlugin() ],
});
Usage
- JavaScript (tag)
- Browser (npm)
The Snowplow media tracking APIs enable you to track events from media playback on the Web as well as mobile apps. The trackers provide a set of tracking APIs that enable you to track changes in the media playback (e.g., play, pause, seek events), playback position (ping and percentage progress events), or ad playback events (e.g., ad breaks, ad progress, ad clicks).
While the trackers provide integrations with a few media players, the media tracking APIs are designed to be player agnostic to enable users to implement tracking for any media player.
Tracked events and entities
The media tracking works with a set of out-of-the-box event and entity schemas. Additionally, you can track custom entities along with the events.
To illustrate the tracked events and entities, you can visit a React example app that showcases the tracked media events and entities live as you watch a video.
Visit the app here. Source code for the app is available here.
Media player events
Each media player event is a self-describing event with a unique schema.
The schema URIs have the format:
iglu:com.snowplowanalytics.snowplow.media/{EVENT_TYPE}/jsonschema/1-0-0
.
You can see the schemas listed under the event tracking methods below.
Media player entity
The media player entity is attached to all media events and gives information about the current state of the media player.
It contains the current playback position (currentTime
) as well as the paused or muted state.
Media player entity properties
Schema:
iglu:com.snowplowanalytics.snowplow/media_player/jsonschema/2-0-0
.
Media session entity
The media session entity is used to identify the playback using the mediaSessionId
.
It also contains statistics about the media playback computed on the tracker (e.g., timePlayed
, timeBuffering
, adsClicked
).
Media player session entity properties
It is an optional entity that is enabled by default.
Schema:
iglu:com.snowplowanalytics.snowplow.media/session/jsonschema/1-0-0
.
Media ad and ad break entities
These entities give information about the currently playing ad and ad break.
Media ad break entity properties
Schema for the ad break entity:
iglu:com.snowplowanalytics.snowplow.media/ad_break/jsonschema/1-0-0
.
Media player ad entity properties
Schema for the ad entity:
iglu:com.snowplowanalytics.snowplow.media/ad/jsonschema/1-0-0
.
Starting and ending media tracking
The tracker keeps track of ongoing media tracking instances in order to manage entities that are tracked along with the media events.
Media tracking instances are identified by a unique ID (that is tracked in the media session entity as mediaSessionId
).
You provide the identifier in the startMediaTracking
call that initializes the media tracking instance.
All subsequent media track calls will be processed within this media tracking if given the same ID.
Make sure that each media player and content tracked have a different ID.
const id = 'XXXXX'; // randomly generated ID
window.snowplow('startMediaTracking', { id });
Use the endMediaTracking
call to end media tracking. This will clear the local state for the media tracking and stop any background updates.
window.snowplow('endMediaTracking', { id });
Configuration
You can provide additional configuration to the startMediaTracking
call to configure the tracking or give initial information about the media played.
Media player properties
The media
property lets you provide information about the media playback that will be used to populate the media player entity tracked with media events.
window.snowplow('startMediaTracking', {
id,
player: {
currentTime: 0, // The current playback time
duration: 150, // A double-precision floating-point value indicating the duration of the media in seconds
ended: false, // If playback of the media has ended
livestream: false, // If the media is live
label: 'Sample video', // A human-readable title for the media
loop: false, // If the video should restart after ending
mediaType: 'video', // The type of media
muted: false, // If the media element is muted
paused: false, // If the media element is paused
pictureInPicture: false, // If the media is in picture-in-picture mode
playerType: 'html5', // The type of player
playbackRate: 1.0, // Playback rate (1 is normal)
quality: '1080p', // The quality level of the playback
volume: 100, // Volume level
}
});
Media ping events
Media ping events are events sent in a regular interval while media tracking is active. They inform about the current state of the media playback.
Media ping events are different events from the page ping events tracked by activity tracking in the tracker. See the following section to read how page ping events are tracked during media playback.
By default, ping events are sent every 30 seconds. This can be configured as follows:
window.snowplow('startMediaTracking', {
id,
pings: { pingInterval: 30 }, // Interval in seconds for sending ping events. Defaults to 30s.
});
The ping events are sent in an interval that is unrelated to the media playback. However, to prevent sending too many events while the player is paused in background (e.g., in a background tab), there is a limit to how many ping events can be sent while the media is paused. By default, this is set to 1, but it is configurable:
window.snowplow('startMediaTracking', {
id,
pings: { maxPausedPings: 3 }, // Maximum number of consecutive ping events to send when playback is paused. Defaults to 1.
});
You can disable ping events as follows:
window.snowplow('startMediaTracking', { id, pings: false });
Media ping events have the following schema:
iglu:com.snowplowanalytics.snowplow.media/ping_event/jsonschema/1-0-0
.
Page ping events
Page ping events are tracked when activity tracking is enabled in the tracker as long as the user engages with the page (clicks, moves the cursor, scrolls, ...). In contrast with the media ping events, page ping events don't contain any information about the media playback (e.g., the player or session entity).
However, when the user watches a video on the page, they might not be interacting with it, causing page ping events not to be tracked. The media tracking plugin addresses this problem and automatically keeps the page pings alive while the video is being played. On the background, it calls the updatePageActivity
function in activity tracking every time the media tracking is updated or a media event is tracked.
The behavior is enabled by default. In case you don't want the page activity to be automatically updated when the video is playing, you can disable it as follows:
window.snowplow('startMediaTracking', { id, updatePageActivityWhilePlaying: false });
Media player session
Tracking the media player session entity with all media events is enabled by default, you can disable it as follows:
window.snowplow('startMediaTracking', { id, session: false });
Percentage progress events
Percentage progress events are tracked when the playback reaches some percentage boundaries. To send percentage progress events, set the percentage boundaries when they should be tracked:
window.snowplow('startMediaTracking', { id, boundaries: [10, 25, 50, 75] });
Percentage progress events have the following schema:
iglu:com.snowplowanalytics.snowplow.media/percent_progress_event/jsonschema/1-0-0
.
Filter captured events
In case you want to discard some of the events that are tracked during the media tracking, you can set the `captureEvents` property to a list of event types that are allowed (all other event types will be ignored):
window.snowplow('startMediaTracking', { id, captureEvents: ['play'] });
Filter repeated events
Some media players produce a large number of subsequent seek start and seek end (or volume change) events when the user is scrubbing the slider controls (e.g, the Vimeo or HTML5 players). The large number of repeated events is usually not desirable and it's preferable to only keep the first and the last of those events. The media plugin has the ability to do that for seek start, seek end and volume change events.
The algorithm to filter out the repeated events keeps tracked seek (or volume change) events in a buffer until an event other than a seek event is tracked or until the media tracking ends (endMediaTracking
is called). At that point, it takes the first seek start and the last seek end from the buffer and tracks them.
So if the following events are tracked:
- play
- seek start 1
- seek end 2
- seek start 2
- seek end 2
- pause
By filtering events, the result will be:
- play
- seek start 1
- seek end 2
- pause
Filtering out repeated seek and volume change events is enabled by default, but it is possible to disable as follows:
window.snowplow('startMediaTracking', { id, filterOutRepeatedEvents: false });
Or separately for the seek and volume events like this:
window.snowplow('startMediaTracking', { id, filterOutRepeatedEvents: { seekEvents: false, volumeChangeEvents: false } });
There is also an internal timeout after which the buffer with events waiting to be filtered is processed even if no other events are tracked. The default timeout is 5s but is configurable:
window.snowplow('startMediaTracking', { id, filterOutRepeatedEvents: { flushTimeoutMs: 1000 } }); // sets the timeout to 1s
Add context entities to all events
You can provide custom context entities to describe the media playback. They will be added to all events tracked in the media tracking.
window.snowplow('startMediaTracking', {
id,
context: [
{
schema: 'iglu:org.schema/video/jsonschema/1-0-0',
data: { creativeId: '1234' }
}
]
});
Updating playback properties
Updates stored attributes of the media player such as the current playback. Use this function to continually update the player attributes so that they can be sent in the background ping events. We recommend updating the playback position every 1 second.
window.snowplow('updateMediaTracking', {
id,
player: { currentTime: 10 }
});
Tracking media events
Having started a media tracking instance, you can use it to track media events as you receive them from the media player.
Typically, you would subscribe to notifications from the media player (e.g., user clicks play, volume changes, content is buffering) with callbacks that would track the Snowplow events. For an example, see the code that subscribes for events from an HTML5 media player here.
Providing additional information
This section explains how to update information in the media entities along with tracked events.
Update media player properties
You can update properties for the media player entity as events are tracked. The updated properties will apply for the current and all following events.
window.snowplow('trackMediaSeekEnd', {
id,
player: { currentTime: 30.0 }
});
Update ad and ad break properties
When tracking ad events, you can attach information about the currently playing ad or ad break. It is only necessary to attach this information once – at the start of the ad break for ad break properties, or at the start of an ad for ad properties. The tracker will remember the information and attach it to all following ad events until the next ad complete or ad break end event.
window.snowplow('trackMediaAdStart', {
id,
ad: {
name: 'Podcast Ad', // Friendly name of the ad
adId: '1234', // Unique identifier for the ad
creativeId: '4321', // The ID of the ad creative
duration: 15, // Length of the video ad in seconds
skippable: true, // Indicating whether skip controls are made available to the end user
}
});
window.snowplow('trackMediaAdBreakStart', {
id,
adBreak: {
name: 'pre-roll', // Ad break name
breakId: '2345', // An identifier for the ad break
podSize: 2, // The number of ads to be played within the ad break
breakType: 'linear', // Type of ads within the break
}
});
Add context entities to tracked event
You can add custom context entities to tracked events. This will only apply to the currently tracked event.
window.snowplow('trackMediaPlay', {
id,
context: [
{
schema: 'iglu:org.schema/video/jsonschema/1-0-0',
data: { creativeId: '1234' }
}
]
});
Available event types
Events for controlling the playback
Ready
Tracks a media player ready event that is fired when the media tracking is successfully attached to the player and can track events.
window.snowplow('trackMediaReady', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ready_event/jsonschema/1-0-0
.
Play
Tracks a media player play event sent when the player changes state to playing from previously being paused.
Tracking this event will automatically set the paused
property in the media player entity to false
.
window.snowplow('trackMediaPlay', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/play_event/jsonschema/1-0-0
.
Pause
Tracks a media player pause event sent when the user pauses the playback.
Tracking this event will automatically set the paused
property in the media player entity to true
.
window.snowplow('trackMediaPause', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/pause_event/jsonschema/1-0-0
.
End
Tracks a media player end event sent when playback stops when end of the media is reached or because no further data is available.
Tracking this event will automatically set the ended
and paused
properties in the media player entity to true
.
window.snowplow('trackMediaEnd', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/end_event/jsonschema/1-0-0
.
Seek start
Tracks a media player seek start event sent when a seek operation begins.
window.snowplow('trackMediaSeekStart', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/seek_start_event/jsonschema/1-0-0
.
Seek end
Tracks a media player seek end event sent when a seek operation completes.
window.snowplow('trackMediaSeekEnd', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/seek_end_event/jsonschema/1-0-0
.
Events for changes in playback settings
Playback rate change
Tracks a media player playback rate change event sent when the playback rate has changed.
The event schema has two properties:
Request Key | Required | Type/Format | Description |
---|---|---|---|
previousRate | N | number | Playback rate before the change (1 is normal) |
newRate | Y | number | Playback rate after the change (1 is normal) |
The previousRate
is set automatically based on the last playbackRate
value in the player
entity.
The newRate
is passed when tracking the event and is automatically updated in the player
entity.
window.snowplow('trackMediaPlaybackRateChange', { id, newRate: 1.5 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/playback_rate_change_event/jsonschema/1-0-0
.
Volume change
Tracks a media player volume change event sent when the volume has changed.
The event schema has two properties:
Request Key | Required | Type/Format | Description |
---|---|---|---|
previousVolume | N | integer | Volume percentage before the change |
newVolume | Y | integer | Volume percentage after the change |
The previousVolume
is set automatically based on the last volume
value in the player
entity.
The newVolume
is passed when tracking the event and is automatically updated in the player
entity.
window.snowplow('trackMediaVolumeChange', { id, newVolume: 80 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/volume_change_event/jsonschema/1-0-0
.
Fullscreen change
Tracks a media player fullscreen change event fired immediately after the browser switches into or out of full-screen mode.
The event schema has one property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
fullscreen | Y | boolean | Whether the video element is fullscreen |
The fullscreen
value is passed when tracking the event and is automatically updated in the player
entity.
window.snowplow('trackMediaFullscreenChange', { id, fullscreen: true });
Schema:
iglu:com.snowplowanalytics.snowplow.media/fullscreen_change_event/jsonschema/1-0-0
.
Picture-in-picture change
Tracks a media player picture-in-picture change event fired immediately after the browser switches into or out of picture-in-picture mode.
The event schema has one property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
pictureInPicture | Y | boolean | Whether the video element is showing picture-in-picture |
The pictureInPicture
value is passed when tracking the event and is automatically updated in the player
entity.
window.snowplow('trackMediaPictureInPictureChange', { id, pictureInPicture: true });
Schema:
iglu:com.snowplowanalytics.snowplow.media/picture_in_picture_change_event/jsonschema/1-0-0
.
Events for ad events
Ad-break start
Tracks a media player ad break start event that signals the start of an ad break.
Tracking this event will increase the counter of adBreaks
in the session entity.
window.snowplow('trackMediaAdBreakStart', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_break_start_event/jsonschema/1-0-0
.
Ad-break end
Tracks a media player ad break end event that signals the end of an ad break.
window.snowplow('trackMediaAdBreakEnd', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_break_end_event/jsonschema/1-0-0
.
Ad start
Tracks a media player ad start event that signals the start of an ad.
Tracking this event will increase the counter of ads
in the session entity.
window.snowplow('trackMediaAdStart', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_start_event/jsonschema/1-0-0
.
Ad skip
Tracks a media player ad skip event fired when the user activated a skip control to skip the ad creative.
The event schema has one optional property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | N | integer | The percent of the way through the ad |
Tracking this event will increase the counter of adsSkipped
in the session entity.
window.snowplow('trackMediaAdSkip', { id, percentProgress: 60 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_skip_event/jsonschema/1-0-0
.
Ad first quartile
Tracks a media player ad first quartile played event fired when a quartile of ad is reached after continuous ad playback at normal speed.
The event schema has one required property – it is set automatically to 25%:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | Y | integer | The percent of the way through the ad |
window.snowplow('trackMediaAdFirstQuartile', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_quartile_event/jsonschema/1-0-0
.
Ad midpoint
Tracks a media player ad midpoint played event fired when a midpoint of ad is reached after continuous ad playback at normal speed.
The event schema has one required property – it is set automatically to 50%:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | Y | integer | The percent of the way through the ad |
window.snowplow('trackMediaAdMidpoint', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_quartile_event/jsonschema/1-0-0
.
Ad third quartile
Tracks media player ad third quartile played event fired when a quartile of ad is reached after continuous ad playback at normal speed.
The event schema has one required property – it is set automatically to 75%:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | Y | integer | The percent of the way through the ad |
window.snowplow('trackMediaAdThirdQuartile', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_quartile/jsonschema/1-0-0
.
Ad complete
Tracks a media player ad complete event that signals the ad creative was played to the end at normal speed.
window.snowplow('trackMediaAdComplete', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_complete/jsonschema/1-0-0
.
Ad click
Tracks a media player ad click event fired when the user clicked on the ad.
The event schema has one optional property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | N | integer | The percent of the way through the ad |
Tracking this event will increase the counter of adsClicked
in the session entity.
window.snowplow('trackMediaAdClick', { id, percentProgress: 30 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_click_event/jsonschema/1-0-0
.
Ad pause
Tracks a media player ad pause event fired when the user clicked the pause control and stopped the ad creative.
The event schema has one optional property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | N | integer | The percent of the way through the ad |
window.snowplow('trackMediaAdPause', { id, percentProgress: 30 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_pause_event/jsonschema/1-0-0
.
Ad resume
Tracks a media player ad resume event fired when the user resumed playing the ad creative after it had been stopped or paused.
window.snowplow('trackMediaAdResume', { id, percentProgress: 30 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_resume_event/jsonschema/1-0-0
.
Events for data quality
Buffer start
Tracks a media player buffering start event fired when the player goes into the buffering state and begins to buffer content.
The tracker will calculate the time since this event until either the buffer end event or play event or a change in playback position and add the duration to the timeBuffering
property in the session entity.
window.snowplow('trackMediaBufferStart', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/buffer_start_event/jsonschema/1-0-0
.
Buffer end
Tracks a media player buffering end event fired when the the player finishes buffering content and resumes playback.
window.snowplow('trackMediaBufferEnd', { id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/buffer_end_event/jsonschema/1-0-0
.
Quality change
Tracks a media player quality change event tracked when the video playback quality changes.
The event schema has the following properties:
Request Key | Required | Type/Format | Description |
---|---|---|---|
previousQuality | N | string | Quality level before the change (e.g., 1080p) |
newQuality | N | string | Quality level after the change (e.g., 1080p) |
bitrate | N | integer | The current bitrate in bits per second |
framesPerSecond | N | integer | The current number of frames per second |
automatic | N | boolean | Whether the change was automatic or triggered by the user |
The previousQuality
is set automatically based on the last quality
value in the player
entity.
The newQuality
is passed when tracking the event and is automatically updated in the player
entity.
window.snowplow('trackMediaQualityChange', {
id,
newQuality: '1080p',
bitrate: 1000,
framesPerSecond: 30,
automatic: false,
});
Schema:
iglu:com.snowplowanalytics.snowplow.media/quality_change_event/jsonschema/1-0-0
.
Error
Tracks a media player error event tracked when the resource could not be loaded due to an error.
The event schema has the following properties:
Request Key | Required | Type/Format | Description |
---|---|---|---|
errorCode | N | string | Error-identifying code for the playback issue. E.g. E522 |
errorName | N | string | Name for the type of error that occurred in the playback. E.g. forbidden |
errorDescription | N | string | Longer description for the error occurred in the playback |
window.snowplow('trackMediaError', {
id,
errorCode: '500',
errorName: 'forbidden',
errorDescription: 'Failed to load media',
});
Schema:
iglu:com.snowplowanalytics.snowplow.media/error_event/jsonschema/1-0-0
.
Custom self-describing events
You may also define your custom event schemas to address your specific needs not covered by the events above. When tracked within the context of a media tracking, the tracker will attach the player, session, ad, and ad break entities to these events.
window.snowplow('trackMediaSelfDescribingEvent', {
id,
event: {
schema: 'iglu:com.acme/event/jsonschema/1-0-0',
data: { foo: 'bar' },
},
});
The Snowplow media tracking APIs enable you to track events from media playback on the Web as well as mobile apps. The trackers provide a set of tracking APIs that enable you to track changes in the media playback (e.g., play, pause, seek events), playback position (ping and percentage progress events), or ad playback events (e.g., ad breaks, ad progress, ad clicks).
While the trackers provide integrations with a few media players, the media tracking APIs are designed to be player agnostic to enable users to implement tracking for any media player.
Tracked events and entities
The media tracking works with a set of out-of-the-box event and entity schemas. Additionally, you can track custom entities along with the events.
To illustrate the tracked events and entities, you can visit a React example app that showcases the tracked media events and entities live as you watch a video.
Visit the app here. Source code for the app is available here.
Media player events
Each media player event is a self-describing event with a unique schema.
The schema URIs have the format:
iglu:com.snowplowanalytics.snowplow.media/{EVENT_TYPE}/jsonschema/1-0-0
.
You can see the schemas listed under the event tracking methods below.
Media player entity
The media player entity is attached to all media events and gives information about the current state of the media player.
It contains the current playback position (currentTime
) as well as the paused or muted state.
Media player entity properties
Schema:
iglu:com.snowplowanalytics.snowplow/media_player/jsonschema/2-0-0
.
Media session entity
The media session entity is used to identify the playback using the mediaSessionId
.
It also contains statistics about the media playback computed on the tracker (e.g., timePlayed
, timeBuffering
, adsClicked
).
Media player session entity properties
It is an optional entity that is enabled by default.
Schema:
iglu:com.snowplowanalytics.snowplow.media/session/jsonschema/1-0-0
.
Media ad and ad break entities
These entities give information about the currently playing ad and ad break.
Media ad break entity properties
Schema for the ad break entity:
iglu:com.snowplowanalytics.snowplow.media/ad_break/jsonschema/1-0-0
.
Media player ad entity properties
Schema for the ad entity:
iglu:com.snowplowanalytics.snowplow.media/ad/jsonschema/1-0-0
.
Starting and ending media tracking
The tracker keeps track of ongoing media tracking instances in order to manage entities that are tracked along with the media events.
Media tracking instances are identified by a unique ID (that is tracked in the media session entity as mediaSessionId
).
You provide the identifier in the startMediaTracking
call that initializes the media tracking instance.
All subsequent media track calls will be processed within this media tracking if given the same ID.
Make sure that each media player and content tracked have a different ID.
import { startMediaTracking } from "@snowplow/browser-plugin-media";
const id = 'XXXXX'; // randomly generated ID
startMediaTracking({ id });
Use the endMediaTracking
call to end media tracking. This will clear the local state for the media tracking and stop any background updates.
import { endMediaTracking } from "@snowplow/browser-plugin-media";
endMediaTracking({ id });
Configuration
You can provide additional configuration to the startMediaTracking
call to configure the tracking or give initial information about the media played.
Media player properties
The media
property lets you provide information about the media playback that will be used to populate the media player entity tracked with media events.
import { MediaType } from "@snowplow/browser-plugin-media";
startMediaTracking({
id,
player: {
currentTime: 0, // The current playback time
duration: 150, // A double-precision floating-point value indicating the duration of the media in seconds
ended: false, // If playback of the media has ended
livestream: false, // If the media is live
label: 'Sample video', // A human-readable title for the media
loop: false, // If the video should restart after ending
mediaType: MediaType.Video, // The type of media
muted: false, // If the media element is muted
paused: false, // If the media element is paused
pictureInPicture: false, // If the media is in picture-in-picture mode
playerType: 'html5', // The type of player
playbackRate: 1.0, // Playback rate (1 is normal)
quality: '1080p', // The quality level of the playback
volume: 100, // Volume level
}
});
Media ping events
Media ping events are events sent in a regular interval while media tracking is active. They inform about the current state of the media playback.
Media ping events are different events from the page ping events tracked by activity tracking in the tracker. See the following section to read how page ping events are tracked during media playback.
By default, ping events are sent every 30 seconds. This can be configured as follows:
startMediaTracking({
id,
pings: { pingInterval: 30 }, // Interval in seconds for sending ping events. Defaults to 30s.
});
The ping events are sent in an interval that is unrelated to the media playback. However, to prevent sending too many events while the player is paused in background (e.g., in a background tab), there is a limit to how many ping events can be sent while the media is paused. By default, this is set to 1, but it is configurable:
startMediaTracking({
id,
pings: { maxPausedPings: 3 }, // Maximum number of consecutive ping events to send when playback is paused. Defaults to 1.
});
You can disable ping events as follows:
startMediaTracking({ id, pings: false });
Media ping events have the following schema:
iglu:com.snowplowanalytics.snowplow.media/ping_event/jsonschema/1-0-0
.
Page ping events
Page ping events are tracked when activity tracking is enabled in the tracker as long as the user engages with the page (clicks, moves the cursor, scrolls, ...). In contrast with the media ping events, page ping events don't contain any information about the media playback (e.g., the player or session entity).
However, when the user watches a video on the page, they might not be interacting with it, causing page ping events not to be tracked. The media tracking plugin addresses this problem and automatically keeps the page pings alive while the video is being played. On the background, it calls the updatePageActivity
function in activity tracking every time the media tracking is updated or a media event is tracked.
The behavior is enabled by default. In case you don't want the page activity to be automatically updated when the video is playing, you can disable it as follows:
startMediaTracking({ id, updatePageActivityWhilePlaying: false });
Media player session
Tracking the media player session entity with all media events is enabled by default, you can disable it as follows:
startMediaTracking({ id, session: false });
Percentage progress events
Percentage progress events are tracked when the playback reaches some percentage boundaries. To send percentage progress events, set the percentage boundaries when they should be tracked:
startMediaTracking({ id, boundaries: [10, 25, 50, 75] });
Percentage progress events have the following schema:
iglu:com.snowplowanalytics.snowplow.media/percent_progress_event/jsonschema/1-0-0
.
Filter captured events
In case you want to discard some of the events that are tracked during the media tracking, you can set the `captureEvents` property to a list of event types that are allowed (all other event types will be ignored):
import { MediaEventType } from "@snowplow/browser-plugin-media";
startMediaTracking({ id, captureEvents: [MediaEventType.Play] });
Filter repeated events
Some media players produce a large number of subsequent seek start and seek end (or volume change) events when the user is scrubbing the slider controls (e.g, the Vimeo or HTML5 players). The large number of repeated events is usually not desirable and it's preferable to only keep the first and the last of those events. The media plugin has the ability to do that for seek start, seek end and volume change events.
The algorithm to filter out the repeated events keeps tracked seek (or volume change) events in a buffer until an event other than a seek event is tracked or until the media tracking ends (endMediaTracking
is called). At that point, it takes the first seek start and the last seek end from the buffer and tracks them.
So if the following events are tracked:
- play
- seek start 1
- seek end 2
- seek start 2
- seek end 2
- pause
By filtering events, the result will be:
- play
- seek start 1
- seek end 2
- pause
Filtering out repeated seek and volume change events is enabled by default, but it is possible to disable as follows:
startMediaTracking({ id, filterOutRepeatedEvents: false });
Or separately for the seek and volume events like this:
startMediaTracking({ id, filterOutRepeatedEvents: { seekEvents: false, volumeChangeEvents: false });
There is also an internal timeout after which the buffer with events waiting to be filtered is processed even if no other events are tracked. The default timeout is 5s but is configurable:
startMediaTracking({ id, filterOutRepeatedEvents: { flushTimeoutMs: 1000 }); // sets the timeout to 1s
Add context entities to all events
You can provide custom context entities to describe the media playback. They will be added to all events tracked in the media tracking.
startMediaTracking({
id,
context: [
{
schema: 'iglu:org.schema/video/jsonschema/1-0-0',
data: { creativeId: '1234' }
}
]
});
Updating playback properties
Updates stored attributes of the media player such as the current playback. Use this function to continually update the player attributes so that they can be sent in the background ping events. We recommend updating the playback position every 1 second.
import { updateMediaTracking } from "@snowplow/browser-plugin-media";
updateMediaTracking({
id,
player: { currentTime: 10 }
});
Tracking media events
Having started a media tracking instance, you can use it to track media events as you receive them from the media player.
Typically, you would subscribe to notifications from the media player (e.g., user clicks play, volume changes, content is buffering) with callbacks that would track the Snowplow events. For an example, see the code that subscribes for events from an HTML5 media player here.
Providing additional information
This section explains how to update information in the media entities along with tracked events.
Update media player properties
You can update properties for the media player entity as events are tracked. The updated properties will apply for the current and all following events.
import { trackMediaSeekEnd } from "@snowplow/browser-plugin-media";
trackMediaSeekEnd({
id,
player: { currentTime: 30.0 }
});
Update ad and ad break properties
When tracking ad events, you can attach information about the currently playing ad or ad break. It is only necessary to attach this information once – at the start of the ad break for ad break properties, or at the start of an ad for ad properties. The tracker will remember the information and attach it to all following ad events until the next ad complete or ad break end event.
import { trackMediaAdStart } from "@snowplow/browser-plugin-media";
trackMediaAdStart({
id,
ad: {
name: 'Podcast Ad', // Friendly name of the ad
adId: '1234', // Unique identifier for the ad
creativeId: '4321', // The ID of the ad creative
duration: 15, // Length of the video ad in seconds
skippable: true, // Indicating whether skip controls are made available to the end user
}
});
import { trackMediaAdBreakStart, MediaPlayerAdBreakType } from "@snowplow/browser-plugin-media";
trackMediaAdBreakStart({
id,
adBreak: {
name: 'pre-roll', // Ad break name
breakId: '2345', // An identifier for the ad break
podSize: 2, // The number of ads to be played within the ad break
breakType: MediaPlayerAdBreakType.Linear, // Type of ads within the break
}
});
Add context entities to tracked event
You can add custom context entities to tracked events. This will only apply to the currently tracked event.
import { trackMediaPlay } from "@snowplow/browser-plugin-media";
trackMediaPlay({
id,
context: [
{
schema: 'iglu:org.schema/video/jsonschema/1-0-0',
data: { creativeId: '1234' }
}
]
});
Available event types
Events for controlling the playback
Ready
Tracks a media player ready event that is fired when the media tracking is successfully attached to the player and can track events.
trackMediaReady({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ready_event/jsonschema/1-0-0
.
Play
Tracks a media player play event sent when the player changes state to playing from previously being paused.
Tracking this event will automatically set the paused
property in the media player entity to false
.
trackMediaPlay({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/play_event/jsonschema/1-0-0
.
Pause
Tracks a media player pause event sent when the user pauses the playback.
Tracking this event will automatically set the paused
property in the media player entity to true
.
trackMediaPause({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/pause_event/jsonschema/1-0-0
.
End
Tracks a media player end event sent when playback stops when end of the media is reached or because no further data is available.
Tracking this event will automatically set the ended
and paused
properties in the media player entity to true
.
trackMediaEnd({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/end_event/jsonschema/1-0-0
.
Seek start
Tracks a media player seek start event sent when a seek operation begins.
trackMediaSeekStart({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/seek_start_event/jsonschema/1-0-0
.
Seek end
Tracks a media player seek end event sent when a seek operation completes.
trackMediaSeekEnd({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/seek_end_event/jsonschema/1-0-0
.
Events for changes in playback settings
Playback rate change
Tracks a media player playback rate change event sent when the playback rate has changed.
The event schema has two properties:
Request Key | Required | Type/Format | Description |
---|---|---|---|
previousRate | N | number | Playback rate before the change (1 is normal) |
newRate | Y | number | Playback rate after the change (1 is normal) |
The previousRate
is set automatically based on the last playbackRate
value in the player
entity.
The newRate
is passed when tracking the event and is automatically updated in the player
entity.
trackMediaPlaybackRateChange({ id, newRate: 1.5 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/playback_rate_change_event/jsonschema/1-0-0
.
Volume change
Tracks a media player volume change event sent when the volume has changed.
The event schema has two properties:
Request Key | Required | Type/Format | Description |
---|---|---|---|
previousVolume | N | integer | Volume percentage before the change |
newVolume | Y | integer | Volume percentage after the change |
The previousVolume
is set automatically based on the last volume
value in the player
entity.
The newVolume
is passed when tracking the event and is automatically updated in the player
entity.
trackMediaVolumeChange({ id, newVolume: 80 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/volume_change_event/jsonschema/1-0-0
.
Fullscreen change
Tracks a media player fullscreen change event fired immediately after the browser switches into or out of full-screen mode.
The event schema has one property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
fullscreen | Y | boolean | Whether the video element is fullscreen |
The fullscreen
value is passed when tracking the event and is automatically updated in the player
entity.
trackMediaFullscreenChange({ id, fullscreen: true });
Schema:
iglu:com.snowplowanalytics.snowplow.media/fullscreen_change_event/jsonschema/1-0-0
.
Picture-in-picture change
Tracks a media player picture-in-picture change event fired immediately after the browser switches into or out of picture-in-picture mode.
The event schema has one property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
pictureInPicture | Y | boolean | Whether the video element is showing picture-in-picture |
The pictureInPicture
value is passed when tracking the event and is automatically updated in the player
entity.
trackMediaPictureInPictureChange({ id, pictureInPicture: true });
Schema:
iglu:com.snowplowanalytics.snowplow.media/picture_in_picture_change_event/jsonschema/1-0-0
.
Events for ad events
Ad-break start
Tracks a media player ad break start event that signals the start of an ad break.
Tracking this event will increase the counter of adBreaks
in the session entity.
trackMediaAdBreakStart({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_break_start_event/jsonschema/1-0-0
.
Ad-break end
Tracks a media player ad break end event that signals the end of an ad break.
trackMediaAdBreakEnd({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_break_end_event/jsonschema/1-0-0
.
Ad start
Tracks a media player ad start event that signals the start of an ad.
Tracking this event will increase the counter of ads
in the session entity.
trackMediaAdStart({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_start_event/jsonschema/1-0-0
.
Ad skip
Tracks a media player ad skip event fired when the user activated a skip control to skip the ad creative.
The event schema has one optional property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | N | integer | The percent of the way through the ad |
Tracking this event will increase the counter of adsSkipped
in the session entity.
trackMediaAdSkip({ id, percentProgress: 60 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_skip_event/jsonschema/1-0-0
.
Ad first quartile
Tracks a media player ad first quartile played event fired when a quartile of ad is reached after continuous ad playback at normal speed.
The event schema has one required property – it is set automatically to 25%:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | Y | integer | The percent of the way through the ad |
trackMediaAdFirstQuartile({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_quartile_event/jsonschema/1-0-0
.
Ad midpoint
Tracks a media player ad midpoint played event fired when a midpoint of ad is reached after continuous ad playback at normal speed.
The event schema has one required property – it is set automatically to 50%:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | Y | integer | The percent of the way through the ad |
trackMediaAdMidpoint({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_quartile_event/jsonschema/1-0-0
.
Ad third quartile
Tracks media player ad third quartile played event fired when a quartile of ad is reached after continuous ad playback at normal speed.
The event schema has one required property – it is set automatically to 75%:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | Y | integer | The percent of the way through the ad |
trackMediaAdThirdQuartile({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_quartile/jsonschema/1-0-0
.
Ad complete
Tracks a media player ad complete event that signals the ad creative was played to the end at normal speed.
trackMediaAdComplete({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_complete/jsonschema/1-0-0
.
Ad click
Tracks a media player ad click event fired when the user clicked on the ad.
The event schema has one optional property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | N | integer | The percent of the way through the ad |
Tracking this event will increase the counter of adsClicked
in the session entity.
trackMediaAdClick({ id, percentProgress: 30 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_click_event/jsonschema/1-0-0
.
Ad pause
Tracks a media player ad pause event fired when the user clicked the pause control and stopped the ad creative.
The event schema has one optional property:
Request Key | Required | Type/Format | Description |
---|---|---|---|
percentProgress | N | integer | The percent of the way through the ad |
trackMediaAdPause({ id, percentProgress: 30 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_pause_event/jsonschema/1-0-0
.
Ad resume
Tracks a media player ad resume event fired when the user resumed playing the ad creative after it had been stopped or paused.
trackMediaAdResume({ id, percentProgress: 30 });
Schema:
iglu:com.snowplowanalytics.snowplow.media/ad_resume_event/jsonschema/1-0-0
.
Events for data quality
Buffer start
Tracks a media player buffering start event fired when the player goes into the buffering state and begins to buffer content.
The tracker will calculate the time since this event until either the buffer end event or play event or a change in playback position and add the duration to the timeBuffering
property in the session entity.
trackMediaBufferStart({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/buffer_start_event/jsonschema/1-0-0
.
Buffer end
Tracks a media player buffering end event fired when the the player finishes buffering content and resumes playback.
trackMediaBufferEnd({ id });
Schema:
iglu:com.snowplowanalytics.snowplow.media/buffer_end_event/jsonschema/1-0-0
.
Quality change
Tracks a media player quality change event tracked when the video playback quality changes.
The event schema has the following properties:
Request Key | Required | Type/Format | Description |
---|---|---|---|
previousQuality | N | string | Quality level before the change (e.g., 1080p) |
newQuality | N | string | Quality level after the change (e.g., 1080p) |
bitrate | N | integer | The current bitrate in bits per second |
framesPerSecond | N | integer | The current number of frames per second |
automatic | N | boolean | Whether the change was automatic or triggered by the user |
The previousQuality
is set automatically based on the last quality
value in the player
entity.
The newQuality
is passed when tracking the event and is automatically updated in the player
entity.
trackMediaQualityChange({
id,
newQuality: '1080p',
bitrate: 1000,
framesPerSecond: 30,
automatic: false,
});
Schema:
iglu:com.snowplowanalytics.snowplow.media/quality_change_event/jsonschema/1-0-0
.
Error
Tracks a media player error event tracked when the resource could not be loaded due to an error.
The event schema has the following properties:
Request Key | Required | Type/Format | Description |
---|---|---|---|
errorCode | N | string | Error-identifying code for the playback issue. E.g. E522 |
errorName | N | string | Name for the type of error that occurred in the playback. E.g. forbidden |
errorDescription | N | string | Longer description for the error occurred in the playback |
trackMediaError({
id,
errorCode: '500',
errorName: 'forbidden',
errorDescription: 'Failed to load media',
});
Schema:
iglu:com.snowplowanalytics.snowplow.media/error_event/jsonschema/1-0-0
.
Custom self-describing events
You may also define your custom event schemas to address your specific needs not covered by the events above. When tracked within the context of a media tracking, the tracker will attach the player, session, ad, and ad break entities to these events.
trackMediaSelfDescribingEvent({
id,
event: {
schema: 'iglu:com.acme/event/jsonschema/1-0-0',
data: { foo: 'bar' },
},
});