Logo

Application collectors

Bitmovin Media Player

Roku collector

The Bitmovin media player is a configuration option for the Roku collector by Datazoom that makes the following additional data points automatically collectable in real time.

Events

Buffer End

When media plays after Buffer Start or when the player state changes during buffer due to user action or an error.

Supported Media Types
Content
Notes
A buffering event has just completed. The player fires this event which returns a value of 1 to indicate that playback has resumed.

Buffer Start

When the player has to wait for the video buffer to fill with video segments.

Supported Media Types
Content
Notes
When the Buffer Start event is thrown and a value received, it is correlated to a specific playback time by comparing it to the playback length within the manifest. Once the Buffer End event has thrown, the delta between the two can be used to forensically analyze a series of chunks to determine the veracity of the content files. If the issue is corrupt chunks, a new encode can be produced.

Error

This event fires if a error causes content or ad playback or retrieval of the video to fail.

Supported Media Types
Content

Heartbeat

When configurable interval of time passes during video playback within a content session, or right after video playback is interrupted within a content session.

Notes
Configure heartbeats by visiting your collector configurations pages from the Collectors page, scroll to the Heartbeats setting in the Event Control section. By default, heartbeats fire every 60 seconds.

Media Loaded

Triggered when player is ready to begin playback after playback is invoked.

Supported Media Types
Content

Media Object Request

Fired after the player has requested an object related to video playback. This object may be a manifest, audio / video segment or subtitle file. The player will fire this event after the full roundtrip of request and response has completed.

Supported Media Types
Content
Notes
Primarily intended for open tracing via CMCD.

Media Request

When media type is 'content', this is triggered when playback is invoked. When the media type is 'ad', this is triggered when VAST request is made.

Supported Media Types
Content
Notes
Identify problems that may be occurring in the video player which prevent successful playback after a user requests playback.

Milestone

When the playhead position plays through a customer configurable percentile milestone of the video's duration (seeking through the milestone does not trigger the event). The event fires no more than once per ad or content session.

Supported Media Types
Content
Notes
Configure milestones by visiting your collector configurations pages from the Collectors page, scroll to the Milestones setting in the Event Control section. By default, for content, milestones fire when the user passes 5%, 10%, 25%, 50%, 75%, 90%, & 95% point in the content playback timeline and, for ads, when the user passes 25%, 50%, & 75% point in the ad playback timeline.

Mute

When the player volume has been reduced to zero. If observable, mute is also triggered when the device volume is muted.

Pause

When playback is intentionally halted.

Supported Media Types
Content

Playback Complete

When the video player reaches the end of the currently playing content. The event can be triggered multiple times if the user reaches the end of the currently playing content, scrubs back and then reaches the end of the content again.

Supported Media Types
Content

Playback Start

When the video starts playing for the user, also known as "first frame".

Supported Media Types
Content

Player Ready

Signifies when the player instance is made available to Datazoom, independent of any media selection.

Notes
“player has been initialized” independent of any media selection and when the player instance is handed over to us. A player can remain idle waiting for the next event which may or may not happen.

Playing

The media is no longer blocked from playback, and has started playing. Fired when playback resumes from Stall, Buffering or Seek.

Supported Media Types
Content

Qualified View

When playback duration surpasses customer configurable thresholds of time in seconds.

Supported Media Types
Content
Notes
Configure qualified view thresholds by visiting your collector configurations pages from the Collectors page, scroll to the Qualified View setting in the Event Control section. By default, for content, qualified view thresholds are 30 seconds and 60 seconds and, for ads, the qualified view threshold is 5 seconds.

Rendition Change

When the player's Adaptive Bitrate Streaming upshifts or downshifts during playback to a different quality level available in the manifest. This event includes absShift attribute identifying the direction of the change.

Supported Media Types
Content

Resume

When the user begins playing again after pausing the video during playback.

Supported Media Types
Content

Seek End

When a user stops seeking.

Supported Media Types
Content
Notes
This event includes attributes Seek Start Point & Seek End Point to mark the starting & ending points of a seek event.

Seek Start

When a user begins seeking.

Supported Media Types
Content

Stall End

Event fired when video starts playing again after a stall

Supported Media Types
Content

Stall Start

When there is an unexpected playback interruption because the buffer has been depleted.

Supported Media Types
Content

Metadata

Attributes

ABS Shift

The direction of the rendition change relative to the previous rendition. An attribute of the Rendition Change event.

Data type
string
Number Type
Not set
Required
true
Permitted Values
value list

Error Code

Error code emitted by the player

Data type
string
Number Type
Not set
Required
true

Error Message

Error message emitted by the player

Data type
string
Number Type
Not set
Required
true

Heartbeat Count

Count of Heartbeat events per content session.

Data type
number
Number Type
Int
Unit
count
Required
true

Milestone Percent

The point represented by the customer configurable percentage relative to the duration. Attribute of the Milestone event.

Data type
number
Number Type
Short
Unit
percentage
Required
true

Qualified View Trigger

The point represented by the customer configurable duration of playback. Attribute of the Qualified View event.

Data type
number
Number Type
Not set
Unit
seconds
Required
true

Seek End Point

The point within in the content timeline at which the Seek End event is triggered.

Data type
number
Number Type
Not set
Unit
milliseconds
Required
true

Seek Start Point

The point within in the content timeline at which the Seek Start event is triggered.

Data type
number
Number Type
Not set
Unit
milliseconds
Required
true

Startup Duration - Content

The total time a user spent waiting for content to begin playback excluding any time related to requesting, loading or playing pre-roll ads.

Data type
number
Number Type
Not set
Unit
milliseconds
Required
true

Startup Duration - Total

The total time a user spent waiting for content to begin playback excluding any time spent viewing pre-roll ads.

Data type
number
Number Type
Not set
Unit
milliseconds
Required
true

Video

Asset ID

Unique identifier of the content shown according to the player. This may be produced by the CMS or publishing system.

Data type
string
Number Type
Not set

Duration

The length of VOD content or ad media. Value is absent for live content.

Data type
number
Number Type
Double
Unit
seconds

Media Type

Whether the event relates to an Ad or Content asset.

Data type
string
Number Type
Not set
Required
true
Permitted Values
value list

Player Height

Height of the display port.

Data type
number
Number Type
Not set
Unit
pixels

Player Width

Width of the display port.

Data type
number
Number Type
Not set
Unit
pixels

Source

The URL of the current media file

Data type
string
Number Type
Not set
Permitted Values
URL

Title

The title of the content as reported by the media player.

Data type
string
Number Type
Not set

User

Content Session ID

A unique id for the current video playback session.

Data type
string
Number Type
Not set
Required
true
Permitted Values
UUID

Player

Muted

Whether the player is muted or if the device volume is muted and observable.

Data type
bool
Number Type
Not set
Permitted Values
value list

Player Name

The name of the media player.

Data type
string
Number Type
Not set
Required
true

Player Version

The version of the media player.

Data type
string
Number Type
Not set

Streaming Protocol

The streaming protocol used to deliver the content; if not collectable, then it is the container type.

Data type
string
Number Type
Not set
Permitted Values
value list

Streaming Type

Whether the content is Live, VOD or DVR as reported by the media player.

Data type
string
Number Type
Not set
Permitted Values
value list

FluxData

Bandwidth

Estimated network bandwidth as derived from the player

Device Platforms
Browser,Console,DTV,Mobile

Buffer Duration

Cumulative buffering time during a content session

Device Platforms
Browser,Console,DTV,Mobile

Buffer Duration - Content

Cumulative buffering time during a content session when 'media type' equals 'content'

Device Platforms
Browser,Console,DTV,Mobile

Content Session Start Timestamp

Start time of a new content session within an app session.

Device Platforms
Browser,Console,DTV,Mobile

Number of Content Plays

Count of 'playback start' events where 'media type' equals 'content' during an app session

Device Platforms
Browser,Console,DTV,Mobile

Number of Content Requests

Count of 'media request' events where 'media type' equals 'content' during an app session

Device Platforms
Browser,Console,DTV,Mobile

Number of Errors

Count of errors during an app session.

Device Platforms
Browser,Console,DTV,Mobile

Number of Errors - Content

Count of errors during an app session where 'media type' equals 'content'

Device Platforms
Browser,Console,DTV,Mobile

Pause Duration

The cumulative amount of time elapsed where the player was in a paused state during a content session.

Device Platforms
Browser,Console,DTV,Mobile

Pause Duration - Content

The cumulative amount of time elapsed where the player was in a paused state during content playback of content session.

Device Platforms
Browser,Console,DTV,Mobile

Playback Duration

Elapsed time spent watching content and ads, regardless of playback rate, excluding stalls, buffers or pauses.

Device Platforms
Browser,Console,DTV,Mobile

Playback Duration - Content

Cumulative playback time where media type equals 'content' during the current content session regardless of playback rate, excluding stalls, buffers or pauses.

Device Platforms
Browser,Console,DTV,Mobile

Player State

The player's playback state (idle, buffering, playing, paused, seeking)

Device Platforms
Browser,Console,DTV,Mobile
Permitted Values
value list

Playhead Position

The point in the video timeline in seconds.

Device Platforms
Browser,Console,DTV,Mobile
Required
true

Rendition Audio Bitrate

The current audio bitrate

Device Platforms
Browser,Console,DTV,Mobile

Rendition Height

Height in pixels of the current video rendition

Device Platforms
Browser,Console,DTV,Mobile

Rendition Name

Name of the current rendition from the player if available. If not, "[height]p".

Device Platforms
Browser,Console,DTV,Mobile

Rendition Video Bitrate

Target bitrate of the current video rendition from the manifest.

Device Platforms
Browser,Console,DTV,Mobile

Rendition Width

Width in pixels of the current video rendition

Device Platforms
Browser,Console,DTV,Mobile

Stall Count

Count of stall events in a content session

Device Platforms
Browser,Console,DTV,Mobile

Stall Count - Content

Count of stall events in a content session where 'media type' equals 'content'

Device Platforms
Browser,Console,DTV,Mobile

Stall Duration

Cumulative stall time during a content session

Device Platforms
Browser,Console,DTV,Mobile

Stall Duration - Content

Cumulative stall time during a content session when 'media type' equals 'content'

Device Platforms
Browser,Console,DTV,Mobile

Time Since Content Request

Time since "Media Request" event where "Media Type" equals "content"

Device Platforms
Browser,Console,DTV,Mobile

Time Since Content Started

Time since "Playback Start" event where "Media Type" equals "content"

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Buffer Start

Time since last "Buffer Start" event for the current content session

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Buffer Start - Ad

Time since last "Buffer Start" event where "Media Type" equals "ad" for the current content session

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Buffer Start - Content

Time since last "Buffer Start" event where "Media Type" equals "content" for the current content session

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Heartbeat

Time since last "Heartbeat" event for the current content session.

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Milestone - Ad

Time since last "Milestone" event where "Media Type" equals "ad".

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Milestone - Content

Time since last "Milestone" event where "Media Type" equals "content"

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Pause

Time since last "Pause" event

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Rendition Change

Time since last "Rendition Change" event

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Seek Start

Time since last "Seek Start" event.

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Stall Start

Time since last "Stall Start" event.

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Stall Start - Ad

Time since last "Stall Start" event where "Media Type" equals "ad"

Device Platforms
Browser,Console,DTV,Mobile

Time Since Last Stall Start - Content

Time since last "Stall Start" event where "Media Type" equals "content"

Device Platforms
Browser,Console,DTV,Mobile

Ad frameworks

Freewheel Ad Framework

Google IMA Ad Framework

Google IMA DAI Ad Framework

MediaTailor Ad Framework

Yospace Ad Framework

Player Default Ad Framework

Adding dependencies to your project

Roku Plugin for Eclipse IDE
For Roku plugin installation and usage in Eclipse IDE
https://sdkdocs.roku.com/display/sdkdoc/Roku+Plugin+for+Eclipse+IDE

Installation Instructions

Clone the latest version of the repository:

git clone https://gitlab.com/datazoom/roku/dz_collector_roku_bitmovin_release.git

Extract the components folder from latest version of the cloned repository

Copy the components folder in your channel project.

We assume that:

  1. The developer had already created a Roku project (in Eclipse IDE).

  2. Roku project has Roku Bitmovin Player implemented following instructions from Bitmovin: https://bitmovin.com/docs/player/api-reference/roku/roku-sdk-api-reference-v1#/player/roku/1/docs/index.html#seeked_property

  3. The project does not have a components folder. If there is already a components folder, then copy the content of the components directory(DzLib folder) into your project's components directory.
    eg: /<your project>/components/DzLib

  4. This project contains the base and bitmovin-collector library (inside DzLib folder).

Configuring collector library in channel

Copy the following in MainScene.brs (in components folder) or in the brs file you intend to configure the collector library.
In Sub/function init(), add the following

m.player = m.top.findNode("<Player ID>")
m.DzLib = m.top.findNode("DzLib")
DzCollector()

Once the collector is successfully instantiated we can set desired console log level for the collector instance:

m.DzLib.callFunc("setLogLevel","info")

Valid log levels are: "off", "error", "warning", "info", "debug", or "verbose"

Default log level is set to “warning”

Also add the following function for initializing SDK

Sub DzCollector()
m.DzLib.libConfiguration = {
configURL : "<url given by Datazoom>",
configId: "<configuration id from Datazoom>"
}
m.DzLib.initiateCollector = true
End Sub

DzCollector() will call the above function when initialized.

Change the configURL, configId, and <Player ID> as per the requirement.

Copy the following inside <children> in MainScene.xml or in the xml file you intend to configure the collector library.

<DzLib id="DzLib" />

At this point the Datazoom SDK is initialized. We can send Custom Events, Custom Metadata, user data, device data and geo location data.

Custom Events and Custom Metadata

We can set Custom Metadata for the Datazoom SDK independently for the app session and/or for player. Custom Metadata that is set for app session will be available during entire app session if not changed or removed. Custom Metadata that is set for player will be reset with each new player session.

To set Custom Metadata for app session we use following method:

 m.DzLib.callFunc("setDZSessionMeta","DataZoom SESSION Metadata Key", "DataZoom SESSION Metadata Value")
 or
 m.DzLib.callFunc("setDZSessionMeta","AnotherCustomSESSIONMetaKey","AnotherCustomSESSIONMetaValue")
 or
 m.DzLib.callFunc("setDZSessionMeta",{customMetaKeyDict1 : "CustomSESSIONMetaValueDict1", customMetaKeyDict2 : "CustomSESSIONMetaValueDict2", customMetaKeyDictNth : "CustomSESSIONMetaValueDictNth" })

To set Custom Metadata for player session we use following method:

m.DzLib.callFunc("setDZPlayerMeta","DataZoom PLAYER Metadata Key", "DataZoom PLAYER Metadata Value")
or
m.DzLib.callFunc("setDZPlayerMeta","AnotherPLAYERCustomMetaKey","AnotherPLAYERCustomMetaValue")
or
m.DzLib.callFunc("setDZplayerMeta",{customMetaKeyDict1 : "CustomPLAYERMetaValueDict1", customMetaKeyDict2 : "CustomPLAYERMetaValueDict2", customMetaKeyDictNth : "CustomPLAYERMetaValueDictNth" })

Change "CustomMetaKey" and "CustomMetaValue" to any text or variable you want to send to collector service

To read Custom Metadata that are set using previous methods we use following methods:

For session Custom Metadata:

 customSessionMeta = m.DzLib.callFunc("getDZSessionMeta")

For player Custom Metadata:

 customSessionMeta = m.DzLib.callFunc("getDZPlayerMeta")

We delete Custom Metadata that are set for session and player by using this methods:

For session Custom Metadata:

m.DzLib.callFunc("rmDZSessionMeta")

For player Custom Metadata:

m.DzLib.callFunc("rmDZPlayerMeta")

Also, we can send Custom Events to the Datazoom SDK using following methods:

  m.DzLib.callFunc("generateDatazoomEvent","SOME CUSTOM EVENT")

We can also add Custom Metadata to generated Custom Event. Metadata sent using this method will be sent with the custom event only.

m.DzLib.callFunc("generateDatazoomEvent", "SOME CUSTOM EVENT", {customEventMetaKeyDict1 : "CustomEventMetaValueDict1", customEvemtMetaKeyDict2 : "CustomEventMetaValueDict2", customEventMetaKeyDictNth : "CustomEventMetaValueDictNth"})

Now, after we create player instance we can add player to Datazoom SDK
Add the following inside <children> in MainScene.xml or in the xml file you intend to configure the collector library.

<Video id="<Player ID>" />

and your xml file should look like this:

<children>
<DzLib id="DzLib" />
<Video id="<Player ID>" />
</children>

Change <Player ID> as per the requirement.

Now add the following function for initializing player to Datazoom SDK:

Sub DzPlayer()
        m.DzLib.playerInit = {
        player: m.video
        }
        m.DzLib.initiatePlayer = true 
'       m.DzLib.initiateCollector = true
End Sub

DzPlayer() will call the above function when initialized.

At this point Datazoom SDK is fully initialized with player. Selected data points will be collected from player and sent to collector service.

You can download Datazoom Roku DEMO app which demonstrates above methods from here :

git clone https://gitlab.com/datazoom/roku/roku-native-demo.git

Follow instructions in provided Readme.md file for importing demo project to Eclipse.

Instructions to create a compiled zip file

  1. Your-Project(Right click) > Export > BrightScript > BrightScript Deployment >[Change File name/path, if needed (.zip)] > Finish

  2. Open browser and go to Roku's local network IP address.(eg: 192.168.0.9). Provide username and password of developer mode.

  3. Click upload and select the newly created zip file. Click install.

  4. The channel will automatically start playing. This channel can also be played by-> go to Roku menu, select the Roku developer channel and play.

  5. To view the data points generated by Roku, go to Linux terminal and type

           telnet <Roku's Local IP> 8085
           eg: - telnet 192.168.0.9 8085

Reference: https://sdkdocs.roku.com/display/sdkdoc/Debugging+Your+Application

Previous
Roku Collector
Next
Freewheel Ad Framework