Media tracking (v2)

Media tracking has multiple versions of schema available. This document is for version 2 of the schemas; tracker versions earlier than v0.3.0 only support v1 tracking.

Configuration

Most tracking of Audio and Video nodes is automatic, so configuration is minimal.

The primary method for configuring media tracking is the enableMediaTracking method, which should include the options below, including the media node to track. It has a corresponding disableMediaTracking method to stop generating events. For events not automatically tracked, trackMediaEvent allows tracking custom events while including media-related entities.

The accepted options include:

Attribute	Type	Description	Required?
`media` / `audio` / `video`	Audio / Video	Audio/Video node to be tracked	yes
`version`	Integer	Tracking schema version to use; defaults to `2` when using `enableMediaTracking`	no
`id`	UUID	A unique ID to use for the media `session` entity to group all tracked events	no; generated by tracker if not provided
`label` / `options.label`	String	An identifiable custom label sent with the event in the `media_player` entity	no
`sessions`	boolean	Whether to attach the media `session` entity on tracked events	no; defaults to `true`
`pings`	boolean	Whether to periodically generate media `ping_event`s while content is playing	no; defaults to `true`
`pingInterval` / `options.positionInterval`	Integer	Interval in seconds in which `ping_event`s should be reported	no, defaults to `30` seconds
`boundaries` / `options.boundaries`	Integer[]	Percentage boundaries in playback for which `percentage_progress_event`s will be sent	no, defaults to `[25, 50, 75]`
`captureEvents` / `options.captureEvents`	String[]	Types of events to capture. If specified, the event names should not have the `_event` suffix	no, defaults to all events
`context` / `entities`	SelfDescribingJSON[]	Array of custom entities to include with all generated events	no

Migrating from v1

If you are migrating from the v1 media tracking, v2 has compatibility options to make the change easier.

For backwards compatibility with the earlier tracking API, you can continue using enableVideoTracking or enableAudioTracking instead of enableMediaTracking, and pass the node via the audio/video option instead of media. For most other options, v2 will accept either v1 or v2 roAssociativeArray formats. The tracking will work with any combination of these method and option names regardless of node type, as long as version: 2 is specified. You can also specifically opt into version 1 by passing version: 1 for any of these methods, though v2 options may not be recognized.

If using specific version values, the same version should also be specified for the corresponding disable*Tracking method. Similarly, mixing enableVideoTracking and disableMediaTracking will not work unless versions are specified consistently.

The additional options differ by version; but version 2 will accept the options from version 1 if it can't find the newer equivalent settings.

v2 Attribute	v1 Fallback	Type	Description
`media` / `audio` / `video`	`media` / `audio` / `video`	Audio / Video	Audio/Video node to be tracked
`version`	`version`	Integer	Tracking schema version to use; should be set to 2 if not using `enableMediaTracking`
`id`	N/A	UUID	A unique ID to use for the media `session` entity to group all tracked events
`label`	`options.label`	String	An identifiable custom label sent with the event in the `media_player` entity
`sessions`	Default enabled	boolean	Whether to attach the media `session` entity on tracked events
`pings`	Default enabled	boolean	Whether to periodically generate media `ping_event`s while content is playing
`pingInterval`	`options.positionInterval`	Integer	Interval in seconds in which `ping_event`s should be reported
`boundaries`	`options.boundaries`	Integer[]	Percentage boundaries in playback for which `percentage_progress_event`s will be sent
`captureEvents`	`options.captureEvents`	String[]	Types of events to capture. If specified, the event names should not have the `_event` suffix
`context` / `entities`	`context`	SelfDescribingJSON[]	Array of custom entities to include with all generated events

Media Player Events

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
Starting and ending media tracking
- Configuration
Tracking media events

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.

Example app

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

The schemas contain a single label property:

Request Key	Required	Type/Format	Description
currentTime	Y	number	The current playback time
duration	N	number	A double-precision floating-point value indicating the duration of the media in seconds
ended	Y	boolean	If playback of the media has ended
fullscreen	N	boolean	Whether the video element is fullscreen
livestream	N	boolean	If the media is live
label	N	string	Human readable name given to tracked media content
loop	N	boolean	If the video should restart after ending
mediaType	N	enum: `audio` or `video`	Type of media content
muted	N	boolean	If the media element is muted
paused	Y	boolean	If the media element is paused
pictureInPicture	N	boolean	Whether the video element is showing picture-in-picture
playbackRate	N	number	Playback rate (1 is normal)
playerType	N	string	Type of the media player (e.g., com.youtube-youtube, com.vimeo-vimeo, org.whatwg-media_element)
quality	N	string	Quality level of the playback (e.g., 1080p)
volume	N	integer	Volume percent

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

Request Key	Required	Type/Format	Description
mediaSessionId	Y	string	An identifier for the media session (can be provided by the user)
startedAt	N	date-time	Date-time timestamp of when the session started.
pingInterval	N	number	Interval (seconds) in which the ping events will be sent. Default (10s) is assumed if not specified.
timePlayed	N	number	Total seconds user spent playing content (excluding ads).
timePlayedMuted	N	number	Total seconds user spent playing content on mute (excluding ads).
timePaused	N	number	Total seconds user spent with paused content (excluding linear ads)
contentWatched	N	number	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	N	number	Total seconds that playback was buffering during the session.
timeSpentAds	N	number	Total seconds that ads played during the session.
ads	N	integer	Number of ads played.
adsClicked	N	integer	Number of ads that the user clicked on
adsSkipped	N	integer	Number of ads that the user skipped
adBreaks	N	integer	Number of ad breaks played.
avgPlaybackRate	N	number	Average playback rate (1 is normal speed).

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

Request Key	Required	Type/Format	Description
name	N	string	Ad break name such as pre-roll, mid-roll, and post-roll.
breakId	N	string	ID of the ad break.
startTime	Y	number	Playback time in seconds at the start of the ad break.
podSize	N	integer	The number of ads to be played within the ad break.
breakType	N	enum: linear, nonlinear, companion	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 |

Schema for the ad break entity: iglu:com.snowplowanalytics.snowplow.media/ad_break/jsonschema/1-0-0.

Media player ad entity properties

Request Key	Required	Type/Format	Description
name	N	string	Friendly name of the ad
adId	Y	string	Unique identifier for the ad.
creativeId	N	string	The ID of the ad creative
podPosition	N	integer	The number position of the ad within the ad break, starting with 1.
duration	Y	number	Length of the video ad in seconds
skippable	N	boolean	Indicating whether skip controls are made available to the end user

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 the Audio/Video scene graph node they are attached to. You provide the node and other options in the enableMediaTracking call that initializes the media tracking instance. Assign a roAssociativeArray to the enableMediaTracking property with the options. The version property must be specified as 2.

m.global.snowplow.enableMediaTracking = {
    media: m.Video,
    version: 2
}

Use the disableMediaTracking call to end media tracking. This will disable any listeners and stop sending events.

m.global.snowplow.disableMediaTracking = {
    media: m.Video
}

Configuration

You can provide additional configuration to the enableMediaTracking call to configure the tracking or give initial information about the media played.

Media player properties

The label configuration specifies the label used in the media player entity. All other properties are automatically tracked from the media node.

m.global.snowplow.disableMediaTracking = {
    media: m.Video,
    label: "Sample video"
}

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.

By default, ping events are sent every 30 seconds. This can be configured as follows:

m.global.snowplow.enableMediaTracking = {
    media: m.Video,
    version: 2,
    id: id,
    pings: true ' Enabled by default, false to disable
    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:

m.global.snowplow.enableMediaTracking = {
    media: m.Video,
    version: 2,
    id: id,
    maxPausedPings: 1 ' Value is disregarded, Roku will only track pings while the video is making progress
}

You can disable ping events as follows:

m.global.snowplow.enableMediaTracking = {
    media: m.Video,
    version: 2,
    id: id,
    pings: false
}

Media ping events have the following schema: iglu:com.snowplowanalytics.snowplow.media/ping_event/jsonschema/1-0-0.

Media player session

Tracking the media player session entity with all media events is enabled by default, you can disable it as follows:

m.global.snowplow.enableMediaTracking = {
    media: m.Video,
    version: 2,
    id: 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:

m.global.snowplow.enableMediaTracking = {
    media: m.Video,
    version: 2,
    id: 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):

m.global.snowplow.enableMediaTracking = {
    media: m.Video,
    version: 2,
    id: id,
    captureEvents: ["play", "pause"]
}

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.

m.global.snowplow.enableMediaTracking = {
    media: m.Video,
    version: 2,
    id: id,
    entities: [
        {
            schema: "iglu:org.schema/video/jsonschema/1-0-0",
            data: {"creativeId": "value"}
        }
    ]
}

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.

Auto-tracked events

The following events are automatically tracked with the Roku Tracker:

ready events
play events
pause events
ping events
seek start events
seek end events
quality change events
percent progress events
buffer start events
buffer end events
end event
error event

Providing additional information

This section explains how to update information in the media entities along with tracked events.

Update ad and ad break properties

When tracking ad events, you can attach information about the currently playing ad or ad break.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_break_start_event/jsonschema/1-0-0",
    data: {},
    adBreak: {
        name: "pre-roll",
        "breakId": "2345",
        "podSize": 2,
        "breakType": "linear"
    },
}

Add context entities to tracked event

You can add custom context entities to tracked events. This will only apply to the currently tracked event.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:org.example/custom_event/jsonschema/1-0-0",
    data: {},
    ad: {},
    adBreak: {},
    entities: [
        {
            schema: "iglu:org.schema/video/jsonschema/1-0-0",
            data: {"creativeId": "value"}
        }
    ]
}

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.

This event automatically fires for Audio/Video nodes, or can be tracked manually via trackMediaEvent if disabled via captureEvents.

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.

This event automatically fires for Audio/Video nodes, or can be tracked manually via trackMediaEvent if disabled via captureEvents.

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.

This event automatically fires for Audio/Video nodes, or can be tracked manually via trackMediaEvent if disabled via captureEvents.

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.

This event automatically fires for Audio/Video nodes, or can be tracked manually via trackMediaEvent if disabled via captureEvents.

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.

This event automatically fires for Video nodes using the native trickplay bar, or can be tracked manually via trackMediaEvent if disabled via captureEvents or using a custom seek implementation.

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.

This event automatically fires for Video nodes using the native trickplay bar, or can be tracked manually via trackMediaEvent if disabled via captureEvents or using a custom seek implementation.

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/playback_rate_change_event/jsonschema/1-0-0",
    data: {
        "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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/volume_change_event/jsonschema/1-0-0",
    data: {
        "newVolume": 50
    }
}

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/fullscreen_change_event/jsonschema/1-0-0",
    data: {
        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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/picture_in_picture_change_event/jsonschema/1-0-0",
    data: {
        pictureInPicture: false
    }
}

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_break_start_event/jsonschema/1-0-0",
    data: {},
    ad: {},
    adBreak: {},
}

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_break_end_event/jsonschema/1-0-0",
    data: {},
    ad: {},
    adBreak: {},
}

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_start_event/jsonschema/1-0-0",
    data: {},
    ad: {},
    adBreak: {},
}

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_skip_event/jsonschema/1-0-0",
    data: {},
    ad: {},
    adBreak: {},
}

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

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_quartile_event/jsonschema/1-0-0",
    data: {
        "percentProgress": 25
    },
    ad: {},
    adBreak: {},
}

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

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_quartile_event/jsonschema/1-0-0",
    data: {
        "percentProgress": 50
    },
    ad: {},
    adBreak: {},
}

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

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_quartile_event/jsonschema/1-0-0",
    data: {
        "percentProgress": 75
    },
    ad: {},
    adBreak: {},
}

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_complete_event/jsonschema/1-0-0",
    data: {},
    ad: {},
    adBreak: {},
}

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_click_event/jsonschema/1-0-0",
    data: {},
    ad: {},
    adBreak: {},
}

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

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_pause_event/jsonschema/1-0-0",
    data: {},
    ad: {},
    adBreak: {},
}

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/ad_resume_event/jsonschema/1-0-0",
    data: {},
    ad: {},
    adBreak: {},
}

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.

This event automatically fires for Audio/Video nodes, or can be tracked manually via trackMediaEvent if disabled via captureEvents.

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.

This event automatically fires for Audio/Video nodes, or can be tracked manually via trackMediaEvent if disabled via captureEvents.

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.

This event automatically fires for Audio/Video nodes, or can be tracked manually via trackMediaEvent if disabled via captureEvents.

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

This event automatically fires for Audio/Video nodes, or can be tracked manually via trackMediaEvent if disabled via captureEvents.

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.

m.global.snowplow.trackMediaEvent = {
    schema: "iglu:com.snowplowanalytics.snowplow.media/quality_change_event/jsonschema/1-0-0",
    data: { }
}

Configuration​

Migrating from v1​

Media Player Events​

Tracked events and entities​

Media player events​

Media player entity​

Media session entity​

Media ad and ad break entities​

Starting and ending media tracking​

Configuration​

Media player properties​

Media ping events​

Media player session​

Percentage progress events​

Filter captured events

Add context entities to all events​

Tracking media events​

Auto-tracked events

Providing additional information​

Update ad and ad break properties​

Add context entities to tracked event​

Available event types​

Events for controlling the playback​

Ready​

Play​

Pause​

End​

Seek start​

Seek end​

Events for changes in playback settings​

Playback rate change​

Volume change​

Fullscreen change​

Picture-in-picture change​

Events for ad events​

Ad-break start​

Ad-break end​

Ad start​

Ad skip​

Ad first quartile​

Ad midpoint​

Ad third quartile​

Ad complete​

Ad click​

Ad pause​

Ad resume​

Events for data quality​

Buffer start​

Buffer end​

Quality change​

Error​

Custom self-describing events​

Configuration

Migrating from v1

Media Player Events

Tracked events and entities

Media player events

Media player entity

Media session entity

Media ad and ad break entities

Starting and ending media tracking

Configuration

Media player properties

Media ping events

Media player session

Percentage progress events

Add context entities to all events

Tracking media events

Providing additional information

Update ad and ad break properties

Add context entities to tracked event

Available event types

Events for controlling the playback

Ready

Play

Pause

End

Seek start

Seek end

Events for changes in playback settings

Playback rate change

Volume change

Fullscreen change

Picture-in-picture change

Events for ad events

Ad-break start

Ad-break end

Ad start

Ad skip

Ad first quartile

Ad midpoint

Ad third quartile

Ad complete

Ad click

Ad pause

Ad resume

Events for data quality

Buffer start

Buffer end

Quality change

Error

Custom self-describing events