Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Trackers – collecting data from your own applications
  5. Roku Tracker
  6. Video tracking

Video tracking

Video tracking enables collecting events about video playback from the Video node provided in the Roku SceneGraph SDK for media playback. Once enabled for a Video node, the tracker subscribes to selected events and tracks them automatically. This makes adding video tracking into your Roku channels really simple.

Usage

To start video tracking for a Video node, assign a roAssociativeArray with the video node to the enableVideoTracking property:

m.global.snowplow.enableVideoTracking = { label: "videoLabel", ' optional video: m.Video }
Code language: PHP (php)

In addition to the video node, the enableVideoTracking property accepts several optional attributes listed in the table below.

AttributeTypeDescriptionRequired?
videoVideoVideo node to be trackedyes
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

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

m.global.snowplow.disableVideoTracking = { video: m.video }
Code language: PHP (php)

Media Player 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"] } }
Code language: PHP (php)

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] } }
Code language: PHP (php)

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 } }
Code language: PHP (php)

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"] } }
Code language: PHP (php)

If you’d like to learn more about Snowplow BDP you can book a demo with our team, or if you’d prefer, you can try Snowplow technology for yourself quickly and easily.