Logo

Application collectors

Roku Native Media Player

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

Installation Guide

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:

  1. 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" })
  1. 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" })
  1. 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
Previous
Roku Collector
Next
Player Default Ad Framework