For the Roku Collector

The Roku Native Media Player Extension is a configuration option for the Roku Collector by Datazoom that makes the following additional data points automatically collectable in real time.

Integration Instructions

Prerequisites

We assume that:

The developer had already created a Roku project.
Only one instance of the library is created (Singleton)
The project has a components folder. If there is none - it should be created in the same folder where the source folder and manifest file for the channel are.
m.global is set and accessible from everywhere:

m.global = screen.GetGlobalNode()
m.global.id = "GLOBAL_NODE"
' https://developer.roku.com/en-gb/docs/references/brightscript/interfaces/ifsgscreen.md#getglobalnode-as-rosgnode

1. Preparatory Steps

Clone the latest version of the repository:

git clone https://gitlab.com/datazoom/roku/collector-release.git Copy the datazoom folder into your channel components folder. eg: //components/datazoom

2. Create the DataZoom Library After Render Thread Initialization

Copy the following in MainScene.brs or in the brs file you intend to configure the collector library. In sub init(), add the following

datazoom = CreateObject("roSGNode", "DataZoom")
datazoom.callFunc("setLogLevel", "info")
datazoom.callFunc("setup", "...ADD_CONFIG_KEY_HERE...")

m.global.AddField("datazoom", "node", false)
m.global.datazoom = datazoom

NOTE: Events are sent only after datazoom.callFunc("setup", ...) succeeds.

3. Hook Up the Video Node to Start Generating Events

m.datazoom = m.global.datazoom
m.datazoom.callFunc("setupVideoObservers", m.videoPlayer)

IMPORTANT! A reference to the Video Node is stored when setupVideoObservers is called. To avoid memory leaks and ensure the content session ends properly, always call videoClosed when the video player is closed.

m.datazoom.callFunc("videoClosed")

4. Forward RAF Events to Generate Ad-Related Events

raf = Roku_Ads()
raf.setTrackingCallback(_rafCallback, m.global.datazoom)

sub _rafCallback(datazoom, eventType, ctx)
  datazoom.rafEvent = ctx
end sub

5. Logging

Once the collector is successfully instantiated we can set desired console log level for the collector instance. Valid log levels are: "off", "error", "warning", "info", "debug", or "verbose" Default log level is set to “warning”

6. Custom Events and Metadata

To send a custom event, call the generateEvent method with the event name as the first parameter. This will send an event with the type/name Custom_AppLaunched, with whatever metadata is enabled in the dashboard. NOTE: Calling this before setup will result in no events being sent, and a warning being logged.

m.datazoom.callFunc("generateEvent", "AppLaunched")

There are three ways to pass custom metadata to the event:

Calling setGlobalMetadata or appendGlobalMetadata on any Datazoom node. This data will be included in all events sent from any Datazoom node.

m.datazoom.callFunc("setGlobalMetadata", { "key": "value" })

Calling setMetadata or appendMetadata. This will add metadata only to this specific node/context and it overwrites the values set "globally".

m.datazoom.callFunc("setMetadata", { "key": "value" })

The third argument of the generateEvent method. This will add metadata only to this specific event and it overwrites the values set "globally" and "locally".

m.datazoom.callFunc("generateEvent", "AppLaunched", { "key": "value" })

NOTE: To avoid name collisions, metadata set with the above methods will be appended under a custom key/node.

{
  "device": {},
  "geo_location": {},
  ...
  "custom": {
    "key": "value"
  }
}

Overwriting metadata defined in the dashboard is not supported for now.

Data Storage Notes

The library is designed to be instantiated only once (singleton pattern).
Configs are cached and do not change after setup.
All data is sourced from Video player fields and Ad RAF events
Derived context
Calling videoClosed destroys most data, except for some session-level metadata.
The session is closed after the timeout defined in: app_session_timeout_mins

Ad Frameworks Extensions

If your Roku application has a media player with an ad framework, Datazoom’s Roku Collector with a Roku Native Media Player can be extended with the following ad framework extensions.

Player Default Ad Framework

Supported Data Points

Events

Discrete occurrences driven by user interactions or system actions

Metadata

Player

Video

Attributes

User

Content Session ID

Fluxdata

Metrics measuring changing parameters over time