Logo

Application collectors

Native Roku Media Player

Roku collector

The Native roku 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.

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

Stop

Triggered when: 1. A playback error results in the termination of content playback. 2. The context (or the logical equivalent) corresponding to a specific player is destroyed: 2(a). The application may destroy the context when playback is stopped by the user. 2(b). The application may destroy the context after playback has reached the end of content (and the player isn’t going to be reused any further). 2(c). The collector (in certain cases) may be able to detect when the application is terminated (e.g., user closes the browser tab) and destroy all player contexts automatically. 3. If a change in the content URL is detected by the collector, a new content session should begin and a `stop` event should be triggered for the previous content session.

Supported Media Types
Content
Notes
Notable condition where the `stop` events is not triggered: When playback reaches the end of the content timeline (i.e., the same condition for triggering `playback_complete`), the content session remains open, unaffected by the fact that playback has reached the end of content so if post-roll ads are played or play-head is rewinded afterward, the subsequent events belong to the same content session.

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

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

CMCD

Content ID (CMCD)

A unique string identifying the current content.

Data type
string
Number Type
Not set

Measured throughput (CMCD)

The throughput between client and server, as measured by the client and MUST be rounded to the nearest 100 kbps. This value, however derived, SHOULD be the value that the client is using to make its next Adaptive Bitrate switching decision. If the client is connected to multiple servers concurrently, it must take care to report only the throughput measured against the receiving server. If the client has multiple concurrent connections to the server, then the intent is that this value communicates the aggregate throughput the client sees across all those connections.

Data type
number
Number Type
Int
Unit
kbps

Next Object Request (CMCD)

Relative path of the next object to be requested. This can be used to trigger pre-fetching by the CDN. This MUST be a path relative to the current request. This string MUST be URLEncoded [5]. The client SHOULD NOT depend upon any pre-fetch action being taken - it is merely a request for such a pre-fetch to take place.

Data type
string
Number Type
Not set

Object Duration (CMCD)

The playback duration in milliseconds of the object being requested. If a partial segment is being requested, then this value MUST indicate the playback duration of that part and not that of its parent segment. This value can be an approximation of the estimated duration if the explicit value is not known.

Data type
number
Number Type
Int
Unit
milliseconds

Object Type (CMCD)

The media type of the current object being requested: m = text file, such as a manifest or playlist a = audio only v = video only av = muxed audio and video i = init segment c = caption or subtitle tt = ISOBMFF timed text track k = cryptographic key, license or certificate. o = other If the object type being requested is unknown, then this key MUST NOT be used.

Data type
string
Number Type
Not set
Permitted Values
value list

Request ID (CMCD)

A unique identifier that is established to track an individual media object request made from the client to a CDN.

Data type
string
Number Type
Not set

Requested Maximum Throughput (CMCD)

The requested maximum throughput that the client considers sufficient for delivery of the asset. Values MUST be rounded to the nearest 100kbps. For example, a client would indicate that the current segment, encoded at 2Mbps, is to be delivered at no more than 10Mbps, by using rtp=10000. Note: This can benefit clients by preventing buffer saturation through over-delivery and can also deliver a community benefit through fair-share delivery. The concept is that each client receives the throughput necessary for great performance, but no more. The CDN may not support the rtp feature.

Data type
number
Number Type
Int
Unit
kbps

Session ID (CMCD)

A GUID identifying the current playback session. A playback session typically ties together segments belonging to a single media asset. Maximum length is 64 characters. It is RECOMMENDED to conform to the UUID specification [7].

Data type
string
Number Type
Not set

Stream Type (CMCD)

Describes if the content being streamed is Live or On Demand.

Data type
string
Number Type
Not set
Permitted Values
value list

Streaming Format (CMCD)

The streaming format that defines the current request. d = MPEG DASH h = HTTP Live Streaming (HLS) s = Smooth Streaming o = other If the streaming format being requested is unknown, then this key MUST NOT be used.

Data type
string
Number Type
Not set
Permitted Values
value list

Top Bitrate (CMCD)

The highest bitrate rendition in the manifest or playlist that the client is allowed to play, given current codec, licensing and sizing constraints.

Data type
number
Number Type
Int
Unit
kbps

Version (CMCD)

The version of the CMCD specification used for interpreting the defined key names and values.

Data type
number
Number Type
Short

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

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

Subtitles

Whether subtitles are currently enabled.

Data type
bool
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

Current Audio Track

The active audio track

Device Platforms
Browser,Console,DTV,Mobile

Current Subtitles

The active subtitle or closed captioning track

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 - 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 Seek Start

Time since last "Seek Start" event.

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_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. 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

  3. This project contains the base and native-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.

IMPORTANT!

To confirm Datazoom SDK is successfully initialized and can be safely attached to player and start collecting data or fire custom events you MUST use following callback:

m.DzLib.observeField("connectionSuccess", "datazoomSDKInitialized")

or check following field:

m.DzLib.connectionSuccess '(true/false)

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 
End Sub

DzPlayer() will call the above function when initialized.

Optionally, m.DzLib.playerInit can include a noContentObserver field which, if set to true, will prevent the collector from observing the video node’s content metadata for the purpose of creating content sessions automatically. This may be useful for apps who prefer to manage content sessions explicitly through the setting of m.DzLib.initiatePlayer. The following demonstrates such a use case:

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

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

Roku RAF

If Roku RAF is enabled and implemented in your app please use following method to pass CTX object to DZ SDK:

m.DzLib.callFunc("generateAdEvent",adCtx)

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
Bitmovin Media Player
Next
Freewheel Ad Framework