This guide shows how to add Tealium to your Roku app to track user activity. Before you begin, here's a video introduction to the platform:
Before proceeding, ensure you have satisfied the following requirements:
We recommend developing in Eclipse with the Roku plugin.
The code for the Tealium Roku library is stored on Github. You must download and install the library.
We recommend cloning the library (instead of downloading) to make it easier to update to future releases.
The code is organized as a sample app. The Tealium code files are located in
sample_app/source/tealium. The following files must be imported into your project's source folder:
If you are using Eclipse, refresh your project to access the Tealium components.
The code for a sample app is available in the sample_app/source/application/main.brs file. Here you will see examples of adding button tracking and defining a callback function.
Watch this video for an overview of the installation and setup of the code:
Once the Tealium components are added to your project you are ready to start coding. The Tealium instance must be invoked with the following parameters before you can begin tracking:
teal = createTealium("tealium", "main", "dev", 3)
Be sure to set an appropriate log level when you app is released to production.
Once the Tealium instance has been defined you can begin tracking events with the method
TrackEvent(), which takes the following parameters:
data = CreateObject("roAssociativeArray") data.someKey = "someValue" cb = CreateObject("roAssociativeArray") cb.callBack = Function (event) responseHeaders = event.GetResponseHeaders() responseKeys = responseHeaders.Keys() responseCode = event.GetResponseCode() for each key in responseKeys value = responseHeaders[key] print key + " : " + value End for End Function teal.TrackEvent("someEvent", data, cb)
The callback function can be used for a number of purposes, such as:
Follow these steps to create a Stream for Roku events:
tealium_library_nameequals (Custom Value) "roku"
Now you can easily filter events using the "Roku Events" Stream.
Follow these steps to add a Trace to your app:
tealium_trace_idvariable to the data object of your tracking calls and assign it the Trace ID.
Watch this video for a demonstration of using and Trace to validate your implementation:
This section specifies the syntax of the functions available in the Tealium for Roku library. Apps for Roku are written in BrightScript, a powerful scripting language. For more information read Roku's BrightScript Language Reference.
Creates a Tealium object that will be used to track events.
teal = createTealium("account", "profile", "env", 3)
|account||String||Tealium account name|
|profile||String||Tealium profile name (usually "main")|
|env||String||Tealium environment: "dev", "qa", or "prod"|
|log level||Integer||Log level: 0=None, 1=Errors, 2=Warnings, 3=All|
Tracks an event with associated data and, optionally, triggers a callback function.
|eventName||String||Name of event (becomes the
|data||Object||Contextual event data, an "roAssociativeArray" Object containing keys and values|
|callback||Object||An Object with a function property named 'callback' that accepts a "roEvent" argument. The callback function will be triggered upon completion of the TrackEvent call.|
data = CreateObject("roAssociativeArray") data.testKey = "testValue" cb = CreateObject("roAssociativeArray") cb.callBack = Function(event) print "Callback called!" End Function teal.trackEvent("someEvent", data, cb)
Resets and returns a new session ID. The session ID identifies the current user session, similar to a website session, but it does not expire. A new session ID is created each time
createTealium() is called.
Returns a readable string containing the configuration details of the current Tealium instance eg. "Tealium instance for account: ACCOUNT profile: PROFILE environment: ENV"