Skip to main content

Media tracking (v1)

Media tracking has multiple versions of schema available. This document is for version 1 of the schemas, it is recommended to migrate to v2 tracking.

Usage

To start media tracking for an Audio/Video node, assign a roAssociativeArray with the node to the enableVideoTracking property:

m.global.snowplow.enableVideoTracking = {
video: m.Video
}

From tracker version 0.3.0:

  • You can also use enableAudioTracking and pass the node via audio instead of video
  • The v2 enableMediaTracking call and media option will also work, the tracker will use v1 tracking if the optional version option is defined as 1

In addition to the node and version selector, the enableVideoTracking property accepts several optional attributes listed in the tables below.

AttributeTypeDescriptionRequired?
media / audio / videoAudio / VideoAudio/Video node to be trackedyes
versionIntegerTracking schema version to use; defaults to 1 if not provided for enableVideoTracking and enableAudioTrackingno
label / options.labelStringAn identifiable custom label sent with the eventno
options.captureEventsString[]Types of events to captureno, defaults to all events except for position
options.boundariesInteger[]Percentage boundaries in playback for which events will be sentno, defaults to [10, 25, 50, 75]
options.positionIntervalIntegerInterval in seconds in which position events should be reportedno, defaults to 5
context / entitiesSelfDescribingJSON[]Array of custom entities to include with all generated media eventsno

To stop tracking events from the node, set the disableVideoTracking/disableAudioTracking property. The tracker will then stop observing and tracking events from the node. The property should be set with an roAssociativeArray with exactly one attribute, video (or audio/media), like so:

m.global.snowplow.disableVideoTracking = {
video: m.video
}

Media Player Events

Media Events

All playback events are tracked automatically and conform to the media_player_event schema. The schema has two properties:

PropertyDescriptionRequired?
typeType of eventYes
labelIdentifiable custom labelNo

The events are enriched with two context entities. The first is the media_player context entity that provides the following properties:

PropertyDescriptionRequired?
currentTimeThe current playback timeYes
durationA double-precision floating-point value indicating the duration of the media in secondsNo
endedIf playback of the media has endedYes
isLiveIf the media is liveYes
loopIf the video should restart after endingYes
mutedIf the media element is mutedYes
pausedIf the media element is pausedYes
percentProgressThe percent of the way through the mediaNo
playbackRatePlayback rate (1 is normal)No
volume .Volume percentYes

The second is the Roku video context with these properties:

PropertyDescriptionRequired?
videoIdID generated when video tracking of the video node was initialized.Yes
contentIdID of video provided in content metadata.No
contentTitleTitle of video provided in content metadata.No
contentUrlURL of video provided in content metadata.No
contentTypeCategory of video (e.g., movie, season, series) provided in content metadata.No
streamFormatContainer format of video (e.g., mp4, wma, mkv) provided in content metadata.No
streamUrlURL of the current stream.No
measuredBitrateMeasured bitrate (bps) of the network when the stream was selected.No
streamBitrateCurrent bitrate of the stream.No
isUnderrunIndicates whether the stream was downloaded due to an underrun.No
isResumedIndicates whether the playback was resumed after trickplay.No
videoFormatVideo codec of the currently playing video stream (e.g., hevc, mpeg2, mpeg4_15).No
timeToStartStreamingTime in seconds from playback being started until the video actually began playing.No
widthWidth of the video play window in pixels. 0 if the play window is set to the width of the entire display screen.Yes
heightHeight of the video play window in pixels. 0 if the play window is set to the height of the entire display screen.Yes
errorStrA diagnostic message indicating a video play error. Refer to the Roku Video documentation for the format of the string.No

Captured Types of Events

The tracker automatically captures several types of events. You may configure which types of events to track by passing a list of the types into the options.captureEvents property during tracker initialization:

m.global.snowplow.enableVideoTracking = {
video: m.Video,
options: {
captureEvents: ["playing", "paused"]
}
}

Overall, the types of events can be grouped into two categories: playback position events, and state change events.

Playback Position Events

These "ping" events report changes in the playback position of the video while playing. There are two types of the events:

  1. percentprogress events report when the playback reaches certain boundaries defined as percentages of the total playback duration.
  2. position events are regular events sent when the playback changes by a certain number of seconds.

Event Type: percentprogress

Percent progress events are sent when predefined percentage boundaries in playback are reached. The boundaries may be configured using a boundaries list when initializing video tracking:

m.global.snowplow.enableVideoTracking = {
video: m.Video,
options: {
captureEvents: ["percentprogress"],
boundaries: [25, 50, 75, 100]
}
}

The tracker sends percent progress events by default for the following percentage boundaries: 10%, 25%, 50%, and 75% of total playback.

These events can not be reported for live streams since they assume that the total duration of the video is known.

Event Type: position

Position events report the current playback position in regular intervals. These events are not reported by default. They can be activated using the options.captureEvents property.

The events are sent whenever the playback head changes by more than the predefined position interval. The interval defaults to 5 seconds. It can be configured using the options.positionInterval property:

m.global.snowplow.enableVideoTracking = {
video: m.Video,
options: {
captureEvents: ["position"],
positionInterval: 15 ' seconds
}
}

These events do not require the total duration of the video to be known and can be reported for live streams as well.

State Change Events

State change events are sent when the state of the video node changes due to interaction from the user, changes in the playback, or through any other influence. Transitions between the following states are captured:

  • playing
  • paused
  • buffering
  • stopped
  • finished
  • error
    • Error occured in the playback. The errorStr property in the video context will provide more details on the error.

The event type of the events (type property) reflects the current state.

All of the state changes are reported by default. In order to capture only selected states, use the options.captureEvents property:

m.global.snowplow.enableVideoTracking = {
video: m.Video,
options: {
captureEvents: ["playing", "paused"]
}
}