Getting started

Designing how and what to track in your app is an important decision. Check out our docs about tracking design here.

The following steps will guide you through setting up the Roku tracker in your project and tracking a simple event.

Installation

There are two options to install the Roku tracker package to your project:

1. using Roku package manager (ropm),
2. by manually copying package files.

Using Roku Package Manager (ropm)

ropm is a package manager for the Roku platform. If you are using ropm in your project, you may install the Roku tracker using the following command:

ropm install snowplow@npm:@snowplow/roku-tracker

Manual Installation

The Roku tracker may be installed by simply copying source files to your Roku project. You may download and unpack the dist.zip or dist.tar.gz package from the latest release build on Github. Copy the following folders and files to your Roku project:

1. Contents of dist/source into your source directory
2. Contents of dist/components into your components directory

Implementation

It is recommended that you instantiate Snowplow and add it to the global scope. In this way, it will be accessible from anywhere within your SceneGraph application. You may create the instance in the init function of your main scene.

If you installed the package using ropm, mount the component as follows:

m.global.AddField("snowplow", "node", false)
m.global.snowplow = CreateObject("roSGNode", "snowplow_Snowplow")

If you installed the package manually, mount the component as follows:

m.global.AddField("snowplow", "node", false)
m.global.snowplow = CreateObject("roSGNode", "Snowplow")

Initialization

Trackers are initialized by setting the init property with configuration of the tracker. This configuration takes the form of a roAssociativeArray. At its most basic, the configuration takes a Snowplow collector endpoint like so:

m.global.snowplow.init = {
    network: {
        collector: "http://..."
    }
}

To learn more about configuring how events are sent, check out this page.

Tracking events

To track an event, simply assign its properties as a roAssociativeArray to a field corresponding to the event type. For instance, to track a structured event, assign the structured property:

m.global.snowplow.structured = {
    se_ca: "category",
    se_ac: "action",
    se_la: "label",
    se_pr: "property",
    se_va: 10
}

Visit documentation about tracking events to learn about other supported event types. You may also want to read about adding more data to tracked events.

Testing

Testing that your event tracking is properly configured can be as important as testing the other aspects of your app. It confirms that you are generating the events you expect.

We recommend using Snowplow Micro for testing and debugging — you can even use it for automated tests.

Check out the example Roku channel to see the tracker used with Snowplow Micro.