Skip to main content

Media playback

The Snowplow media tracking APIs enable you to track events from media playback on the web as well as in mobile apps. Track changes in the media playback e.g., play, pause, seek events, playback position with ping and percentage progress events, or ad playback events e.g., ad breaks, ad progress, or ad clicks.

While some trackers provide additional integrations with media players, the media tracking APIs are designed to be player agnostic.

Use media tracking to answer questions such as:

  • Are users watching videos without sound?
  • Which pieces of audio content do users play to completion?
  • Where do users drop off during playback?
  • How does buffering affect engagement?
  • Which ads do users skip, click, or watch?

The media tracking works with a set of out-of-the-box events and entities. You can add custom entities to the events as required.

Media events fall into three categories: playback lifecycle events, player state changes, and advertising events. For most implementations, you'll need to track these events yourself.

Many media events have no properties of their own. The user behavior is captured in the event type, and the media player, session, ad, or ad break entities that are automatically attached to the event.

The event schema URIs have the format: iglu:com.snowplowanalytics.snowplow.media/{EVENT_TYPE}/jsonschema/1-0-0.

Media API versions​

The current set of media APIs has evolved from an earlier, more limited implementation. We refer to them as v1 and v2 of the media tracking APIs. The Media Player dbt data model supports both versions.

Unless otherwise stated, all documentation refers to v2 of the media tracking APIs.

The newer v2 implementation has many more features than v1, including:

  • Advertising tracking support
  • Media ping events at configurable intervals
  • Session entity with aggregated statistics
  • Quality change tracking for bitrate, FPS, and quality level
  • Buffer and seek start/end event pairs
  • Filtering of repeated events (seek, volume)
  • Page activity updates during playback

Tracker support​

This table shows the support for media tracking across the main client-side Snowplow tracker SDKs. The server-side trackers don't include media tracking APIs.

Auto-tracking means that the tracker can subscribe to and track events from a registered media player, without you needing to manually track each event.

TrackerPluginSupportedSince versionAuto-trackingNotes
WebSnowplow✅3.12.0 (Media v2)❌
WebHTML5✅3.2.0 (Media v1), 4.0.0 (Media v2)✅
WebYouTube✅3.2.0 (Media v1), 4.0.0 (Media v2)✅
WebVimeo✅3.14.0 (Media v2)✅
iOS✅5.3.0 (Media v2)✅/❌Auto-tracking for AVPlayer
Android✅5.3.0 (Media v2)❌
React Native❌Use the media schemas for your own custom events, or the media web tracking plan template
Flutter✅0.7.0 (Media v2)❌
Roku✅0.1.0 (Media v1), 0.3.0 (Media v2)✅
Google Tag Manager❌

The Snowplow media tracking APIs are supported by the Media Player dbt data model.

We recommend using the Media base tracking plan template for media tracking on web.

How to use the media APIs​

Each media player instance needs to be registered with the tracker, using a unique session ID. Set the media session ID to a random string. In the browser, you could generate this with a function such as crypto.randomUUID(). The ID should be unique to a single session within a single player instance.

Diagram showing media session timeline and which events to track

Media example application

Check out our example React application to see tracked media events and entities live as you watch a video.

The source code for the app is available here.

Start a session​

To start tracking user behavior involving that player, call the appropriate startMediaTracking function. The exact API is different for each tracker. Call startMediaTracking as soon as the player has loaded, not when playback begins. This ensures that session tracking begins immediately, and allows for accurate measurement of metrics such as buffering time or time to first frame.

A media session should correspond to a single media playback, including any ads that play before, during, or after the media. Metrics are collected against a media session, so it's important to set it correctly.

Configure the player​

You can provide additional player information and configuration when calling startMediaTracking, as well as in subsequent tracking calls.

We recommend providing a human-readable name for the media content as a label property. It'll be tracked as part of the media player entity. The label helps you quickly identify which content a media session relates to during analysis, and is used in combination with the media type, player type, and player ID to create the media stats table with the Media Player dbt package.

Track playback​

Track user interactions with the appropriate media tracking calls. Call trackMediaPlay when the main media content starts playing, even if there are pre-roll ads. The media session model accounts for both total play time and play time excluding ads.

We recommend continually updating the media player state by calling updateMediaTracking or equivalent update function every second. This function does not send events to the Collector, but updates internal attributes to ensure accurate metrics for the next event.

How you handle livestreams and playlists depends on whether you want to analyze them as a single session or split by content:

  • Analyze as a single session: update the player label using updateMediaTracking when the content changes. This won't split the session in the data model.
  • Analyze as separate sessions per content segment: end and restart the media session each time the content changes. Customize media_session_id to include segments, for example, livestream-1, livestream-2 or playlist-1, playlist-2, and aggregate later using a shared prefix or a custom livestream_id / playlist_id.

Filter events​

You don't need to send the media ping events, or any other tracked media events, to the data warehouse. The media APIs include a configuration option to filter out certain events, or to keep only specified events. Filtered events aren't sent to the Collector.

To drop unwanted tracked events within the pipeline, use a custom JavaScript enrichment.

End a session​

When playback ends, call the endMediaTracking function to end the session, clean up event listeners, and stop any background pings. Call this when you want to reset session stats, even if the media wasn't fully watched. It does not fire any events.

On web, if the user closes the browser or tab, you don't need to call endMediaTracking — pings stop automatically. In single-page applications, if endMediaTracking is missed, you may see one or two additional ping events, up to the maxPausedPings limit.

There's also a trackMediaEnd function that you can call to track when the media reaches 100% progress (fully watched). This is tracked as a media event. It's common to see sessions without a trackMediaEnd event if the user didn't finish the content.

If the content finishes and the user rewinds, continue the same session. Use the timePlayed and contentWatched metrics within the media session entity to understand rewatches compared to how much of the media content they watched.

Playback lifecycle events​

These events track the core playback flow from start to finish.

Media pings​

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, and keep the media session alive.

By default, ping events are sent every 30 seconds. They're sent in an interval that is unrelated to the media playback. However, to prevent sending too many events, there is a limit to how many ping events can be sent while the media is paused. By default, this is set to 1. You can change this by configuring maxPausedPings (not available on Roku).

ping_event

Event
Media player event fired periodically during main content playback, regardless of other API events that have been sent.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ping_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ping_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ping_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Buffer end​

Track a buffering end event when the the player finishes buffering content and resumes playback.

buffer_end_event

Event
Media player event fired when the the player finishes buffering content and resumes playback.
Schema URIiglu:com.snowplowanalytics.snowplow.media/buffer_end_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_buffer_end_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'buffer_end_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Buffer start​

Track a buffering start event when the player goes into the buffering state and begins to buffer content.

The tracker will calculate the time since this event until a buffer end event, play event, or a change in playback position. It will add the duration to the timeBuffering property in the media session entity.

buffer_start_event

Event
Media player event fired when the player goes into the buffering state and begins to buffer content.
Schema URIiglu:com.snowplowanalytics.snowplow.media/buffer_start_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_buffer_start_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'buffer_start_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Pause event​

Track a pause event when the user pauses the playback.

Tracking this event will automatically set the paused property in the media player entity to true.

pause_event

Event
Media player event sent when the user pauses the playback.
Schema URIiglu:com.snowplowanalytics.snowplow.media/pause_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_pause_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'pause_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Playback end​

Track a playback end event when playback stops, either when the 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.

end_event

Event
Media player event sent when playback stops when end of the media is reached or because no further data is available.
Schema URIiglu:com.snowplowanalytics.snowplow.media/end_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_end_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'end_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Percent progress​

The tracker will track percentage progress events automatically, when the playback reaches configured percentage boundaries.

percent_progress_event

Event
Media player event fired when a percentage boundary set in tracking options is reached
Schema URIiglu:com.snowplowanalytics.snowplow.media/percent_progress_event/jsonschema/1-0-0
Properties and schema
PropertyDescription
percentProgress
integer		Optional. The percent of the way through the media
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_percent_progress_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'percent_progress_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Play​

Track a play event 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.

play_event

Event
Media player event sent when the player changes state to playing from previously being paused.
Schema URIiglu:com.snowplowanalytics.snowplow.media/play_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_play_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'play_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Seek end​

Track a seek end event when a seek operation completes.

seek_end_event

Event
Media player event sent when a seek operation completes.
Schema URIiglu:com.snowplowanalytics.snowplow.media/seek_end_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_seek_end_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'seek_end_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Seek start​

Track a seek start event when a seek operation begins.

seek_start_event

Event
Media player event sent when a seek operation begins.
Schema URIiglu:com.snowplowanalytics.snowplow.media/seek_start_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_seek_start_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'seek_start_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Player state change events​

These events track changes to the player's display mode, quality, and settings.

Error​

Track an error event when the resource couldn't be loaded due to an error.

error_event

Event
Media player event tracked when the resource could not be loaded due to an error.
Schema URIiglu:com.snowplowanalytics.snowplow.media/error_event/jsonschema/1-0-0
Example
json
{
  "errorCode": "E522",
  "errorName": "forbidden",
  "errorDescription": "Playback failed"
}
Properties and schema
PropertyDescription
errorCode
string		Optional. Error-identifying code for the playback issue. E.g. E522
errorName
string		Optional. Name for the type of error that occurred in the playback. E.g. forbidden
errorDescription
string		Optional. Longer description for the error that occurred in the playback.
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_error_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'error_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Fullscreen change​

Track a fullscreen change event when the media player fullscreen changes, fired immediately after the browser switches into or out of full-screen mode.

The fullscreen value is passed when tracking the event, and is automatically updated in the player entity.

fullscreen_change_event

Event
Media player event fired immediately after the browser switches into or out of full-screen mode.
Schema URIiglu:com.snowplowanalytics.snowplow.media/fullscreen_change_event/jsonschema/1-0-0
Example
json
{
  "fullscreen": true
}
Properties and schema
PropertyDescription
fullscreen
boolean		Required. Whether the video element is fullscreen after the change
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_fullscreen_change_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'fullscreen_change_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Picture-in-picture change​

Track a picture-in-picture change event immediately after the platform switches into or out of picture-in-picture mode.

The pictureInPicture value is passed when tracking the event, and is automatically updated in the player entity.

picture_in_picture_change_event

Event
Media player event fired immediately after the browser switches into or out of picture-in-picture mode.
Schema URIiglu:com.snowplowanalytics.snowplow.media/picture_in_picture_change_event/jsonschema/1-0-0
Example
json
{
  "pictureInPicture": true
}
Properties and schema
PropertyDescription
pictureInPicture
boolean		Required. Whether the video element is showing picture-in-picture after the change.
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_picture_in_picture_change_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'picture_in_picture_change_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Playback rate change​

Track a playback rate change event when the playback rate has changed.

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.

playback_rate_change_event

Event
Media player event sent when the playback rate has changed.
Schema URIiglu:com.snowplowanalytics.snowplow.media/playback_rate_change_event/jsonschema/1-0-0
Example
json
{
  "previousRate": 1,
  "newRate": 1.5
}
Properties and schema
PropertyDescription
previousRate
number		Optional. Playback rate before the change (1 is normal)
newRate
number		Required. Playback rate after the change (1 is normal)
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_playback_rate_change_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'playback_rate_change_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Quality change​

Track a quality change event when the video playback quality changes.

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.

quality_change_event

Event
Media player event tracked when the video playback quality changes automatically.
Schema URIiglu:com.snowplowanalytics.snowplow.media/quality_change_event/jsonschema/1-0-0
Example
json
{
  "previousQuality": "1080p",
  "newQuality": "720p",
  "bitrate": 1500,
  "framesPerSecond": 30,
  "automatic": true
}
Properties and schema
PropertyDescription
previousQuality
string		Optional. Quality level before the change (e.g., 1080p).
newQuality
string		Optional. Quality level after the change (e.g., 1080p).
bitrate
integer		Optional. The current bitrate in bits per second.
framesPerSecond
integer		Optional. The current number of frames per second.
automatic
boolean		Optional. Whether the change was automatic or triggered by the user.
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_quality_change_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'quality_change_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Ready​

Track a ready event when the media tracking is successfully attached to the player and can track events.

ready_event

Event
Media player event fired when the media tracking is successfully attached to the player and can track events.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ready_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ready_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ready_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Volume change​

Track a volume change event when the user changes the volume.

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.

volume_change_event

Event
Media player event sent when the volume has changed.
Schema URIiglu:com.snowplowanalytics.snowplow.media/volume_change_event/jsonschema/1-0-0
Example
json
{
  "previousVolume": 30,
  "newVolume": 50
}
Properties and schema
PropertyDescription
previousVolume
integer		Optional. Volume percentage before the change.
newVolume
integer		Required. Volume percentage after the change.
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_volume_change_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'volume_change_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Advertising events​

These events track ad playback for monetized content. Ad events include the media ad and media ad break entities.

Tracking only trackMediaAdStart and trackMediaAdComplete, or equivalent API, is sufficient if you don't need to attribute ads to specific ad breaks.

If you skip trackMediaAdBreakStart and trackMediaAdBreakEnd, you won't have details like pod size and break ID to analyze all the ads within a break.

Ad click​

Track an ad click event when a user clicks on an ad.

Tracking this event will increase the counter of adsClicked in the session entity.

ad_click_event

Event
Media player event fired when the user clicked on the ad.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_click_event/jsonschema/1-0-0
Example
json
{
  "percentProgress": 50
}
Properties and schema
PropertyDescription
percentProgress
integer		Optional. The percent of the way through the ad
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ad_click_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ad_click_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Ad break start​

Track an ad break start event at the start of an ad break.

Tracking this event will increase the counter of adBreaks in the media session entity.

ad_break_start_event

Event
Media player event that signals the start of an ad break.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_break_start_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ad_break_start_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ad_break_start_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Ad break end​

Track an ad break end event to signal the end of an ad break.

ad_break_end_event

Event
Media player event that signals the end of an ad break.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_break_end_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ad_break_end_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ad_break_end_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Ad complete​

Track an ad complete event to signal that the ad creative was played to the end, at normal speed.

ad_complete_event

Event
Media player event that signals the ad creative was played to the end at normal speed.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_complete_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ad_complete_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ad_complete_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Ad pause​

Track an ad pause event when a user clicks the pause control to stop the ad creative.

ad_pause_event

Event
Media player event fired when the user clicked the pause control and stopped the ad creative.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_pause_event/jsonschema/1-0-0
Example
json
{
  "percentProgress": 50
}
Properties and schema
PropertyDescription
percentProgress
integer		Optional. The percent of the way through the ad
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ad_pause_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ad_pause_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Ad quartile​

The trackers have dedicated functions to track each ad quartile event: trackMediaAdFirstQuartile, trackMediaAdMidpoint, trackMediaAdThirdQuartile, or equivalent API. These events set the percentProgress property automatically to 25%, 50%, and 75% respectively.

ad_quartile_event

Event
Media player event fired when a quartile of ad is reached after continuous ad playback at normal speed.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_quartile_event/jsonschema/1-0-0
Example
json
{
  "percentProgress": 50
}
Properties and schema
PropertyDescription
percentProgress
integer		Required. The percent of the way through the ad
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ad_quartile_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ad_quartile_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Ad resume​

Track an ad resume event when a user resumes playing the ad creative after it had been stopped or paused.

ad_resume_event

Event
Media player event fired when the user resumed playing the ad creative after it had been stopped or paused.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_resume_event/jsonschema/1-0-0
Example
json
{
  "percentProgress": 50
}
Properties and schema
PropertyDescription
percentProgress
integer		Optional. The percent of the way through the ad
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ad_resume_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ad_resume_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Ad skip​

Track an ad skip event when the user activates a skip control to skip the ad creative.

Tracking this event will increase the counter of adsSkipped in the media session entity.

ad_skip_event

Event
Media player event fired when the user activated a skip control to skip the ad creative.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_skip_event/jsonschema/1-0-0
Example
json
{
  "percentProgress": 50
}
Properties and schema
PropertyDescription
percentProgress
integer		Optional. The percent of the way through the ad
Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ad_skip_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ad_skip_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Ad start​

Track an ad start event at the start of an ad.

Tracking this event will increase the counter of ads in the media session entity.

ad_start_event

Event
Media player event that signals the start of an ad.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_start_event/jsonschema/1-0-0
Properties and schema

This schema has no properties.

Warehouse query
sql
select
unstruct_event_com_snowplowanalytics_snowplow_media_ad_start_event_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'ad_start_event'
and events.event_vendor = 'com.snowplowanalytics.snowplow.media'

Custom events​

Track your own custom events within the media session, using trackMediaSelfDescribingEvent or equivalent API. The tracker will automatically attach the media entities.

Automatically included entities​

Every media event includes entities that describe the current state of the player and session. These entities are attached automatically by the tracker. You don't need to track them yourself.

EntityAttached toPurpose
Media playerAll media eventsCurrent playback state (position, duration, volume, quality)
Media sessionAll media eventsAggregated session metrics (time played, content watched)
Media adAd events onlyInformation about the current ad
Media ad breakAd events onlyInformation about the ad break

You can also add custom entities to all media events, by providing them in the configuration. These entities will be attached to all subsequent media events for that player instance.

As with all Snowplow events, you can also attach custom entities to individual media events when tracking them.

Media player​

The media player entity captures the current state of playback at the moment each event fires. It's required for the Media Player data model.

media_player

Entity
Schema for a context entity for media events that describes the media player and playback state
Schema URIiglu:com.snowplowanalytics.snowplow/media_player/jsonschema/2-0-0
Example
json
{
  "currentTime": 109,
  "duration": 400,
  "ended": false,
  "fullscreen": false,
  "livestream": false,
  "label": "Big Bucks Bunny",
  "loop": false,
  "mediaType": "video",
  "muted": false,
  "paused": true,
  "pictureInPicture": false,
  "playbackRate": 1.5,
  "playerType": "com.vimeo-vimeo",
  "quality": "1080p",
  "volume": 100
}
Properties and schema
PropertyDescription
currentTime
number		Required. The current playback time position within the media in seconds.
duration
number		Optional. A floating-point value indicating the duration of the media in seconds.
ended
boolean		Required. Whether playback of the media has ended.
fullscreen
boolean		Optional. Whether the video element is fullscreen.
livestream
boolean		Optional. Whether the media is a live stream.
label
string		Optional. Human readable name given to tracked media content.
loop
boolean		Optional. Whether the video should restart after ending.
mediaType
string		Optional. Type of media content.
Must be one of: video, audio,
muted
boolean		Optional. Whether the media element is muted.
paused
boolean		Required. Whether the media element is paused
pictureInPicture
boolean		Optional. Whether the video element is showing picture-in-picture.
playbackRate
number		Optional. Playback rate (1 is normal).
playerType
string		Optional. Type of the media player (e.g., com.youtube-youtube, com.vimeo-vimeo, org.whatwg-media_element).
quality
string		Optional. Quality level of the playback (e.g., 1080p).
volume
integer		Optional. Volume percentage at which the media will be played.

Media session​

The media session entity contains metrics calculated based on the tracked media events and the media update calls. It's optional for the Media Player data model.

The table below shows which media player properties and media events are used to calculate the metrics within the media session entity.

Media player entity propertyMedia eventsAffected calculation of metric
pausedplay_event, pause_eventtimePlayed, timePaused, timePlayedMuted, contentWatched
currentTimetimePlayed, timePaused, timePlayedMuted, contentWatched
mutedtimePlayedMuted
playbackRateplayback_rate_change_eventavgPlaybackRate
buffer_start_event, buffer_end_event, play_eventtimeBuffering
ad_start_eventads
ad_skip_eventadsSkipped
ad_click_eventadsClicked
ad_break_start_eventadBreaks
ad_start_event, ad_quartile_event, ad_complete_eventtimeSpentAds
ad_start_event, ad_complete_event, ad_skip_eventtimePlayed, timePlayedMuted*

* Play time stats aren't incremented while ads with type linear (default) are being played. Linear ads take over the video playback. For non-linear and companion ads, play time stats are still incremented while the ad is playing.

session

Entity
Schema for a context entity for media player events that tracks a session of a single media player usage
Schema URIiglu:com.snowplowanalytics.snowplow.media/session/jsonschema/1-0-0
Example
json
{
  "mediaSessionId": "2d9bd9ac-abbd-419a-b934-9a2965cba339",
  "startedAt": "2023-11-03T09:55:29.920Z",
  "pingInterval": 15,
  "timePlayed": 143.12,
  "timePlayedMuted": 0,
  "timePaused": 8.12,
  "contentWatched": 120,
  "timeBuffering": 0.988,
  "timeSpentAds": 14.2,
  "ads": 4,
  "adsClicked": 0,
  "adsSkipped": 1,
  "adBreaks": 2,
  "avgPlaybackRate": 1.21
}
Properties and schema
PropertyDescription
mediaSessionId
string		Required. An identifier for the media session that is kept while the media content is played in the media player.
startedAt
null		Optional. Local date-time timestamp of when the session started.
pingInterval
integer		Optional. Interval (seconds) in which the ping events will be sent. Default (specified in the tracker media docs) is assumed if not specified.
timePlayed
number		Optional. Total seconds user spent playing content (excluding linear ads).
timePlayedMuted
number		Optional. Total seconds user spent playing content on mute (excluding linear ads).
timePaused
number		Optional. Total seconds user spent with paused content (excluding linear ads).
contentWatched
number		Optional. Total seconds of the content played. Each part of the content played is counted once (i.e., counts rewinding or rewatching the same content only once). Playback rate does not affect this value.
timeBuffering
number		Optional. Total seconds that playback was buffering during the session.
timeSpentAds
number		Optional. Total seconds that ads played during the session.
ads
integer		Optional. Number of ads played.
adsClicked
integer		Optional. Number of ads that the user clicked on.
adsSkipped
integer		Optional. Number of ads that the user skipped.
adBreaks
integer		Optional. Number of ad breaks played.
avgPlaybackRate
number		Optional. Average playback rate (1 is normal speed).

Media ad​

The media ad entity describes the currently playing ad. It's attached to ad events.

ad

Entity
Schema for a context entity with information about the currently played ad
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad/jsonschema/1-0-0
Example
json
{
  "name": "Snowplow 5s ad",
  "adId": "2d9bd9ac-abbd-419a-b934-9a2965cba339",
  "creativeId": "fb819c48-5760-4d94-9c5b-4fa52f61a998",
  "podPosition": 2,
  "duration": 5,
  "skippable": true
}
Properties and schema
PropertyDescription
name
null		Optional. Friendly name of the ad.
adId
string		Required. Unique identifier for the ad.
creativeId
string		Optional. The ID of the ad creative.
podPosition
integer		Optional. The position of the ad within the ad break, starting with 1.
duration
number		Optional. Length of the video ad in seconds.
skippable
boolean		Optional. Indicating whether skip controls are made available to the end user.

Media ad break​

The media ad break entity describes a group of ads played together, whether pre-roll, mid-roll, or post-roll. It is attached to ad break events and all ad events within the break.

ad_break

Entity
Schema for a context entity, shared with all ad events belonging to the ad break.
Schema URIiglu:com.snowplowanalytics.snowplow.media/ad_break/jsonschema/1-0-0
Example
json
{
  "name": "pre-roll",
  "breakId": "fb819c48-5760-4d94-9c5b-4fa52f61a998",
  "startTime": 0,
  "breakType": "linear",
  "podSize": 2
}
Properties and schema
PropertyDescription
name
null		Optional. Ad break name (e.g., pre-roll, mid-roll, and post-roll).
breakId
string		Required. An identifier for the ad break.
startTime
number		Required. Playback time in seconds at the start of the ad break.
breakType
string		Optional. Type of ads within the break: linear (take full control of the video for a period of time), nonlinear (run concurrently to the video), companion (accompany the video but placed outside the player).
Must be one of: linear, nonlinear, companion,
podSize
integer		Optional. The number of ads to be played within the ad break.

On this page

Want to see a custom demo?

Our technical experts are here to help.

Book a demo