Tealium for Roku

Tealium for Roku

by Community Manager ‎01-12-2017 11:43 AM - edited ‎04-19-2017 10:29 AM (570 Views)

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:

Table of Contents Placeholder

Installation Guide

Requirements

Before proceeding, ensure you have satisfied the following requirements:

We recommend developing in Eclipse with the Roku plugin.

Get the Code

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.

Code Setup

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:

  • tealium.brs
  • tealiumCollect.brs
  • tealiumLog.brs

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:

Initialization

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:

  • account - the name of your iQ account
  • profile - the name of the mobile profile within your iQ account
  • environment - one of "dev", "qa", or "prod"
  • log level - a number 0-3 where 0=None, 1=Errors, 2=Warnings, and 3=Verbose

Brightscript Example

teal = createTealium("tealium", "main", "dev", 3)

Be sure to set an appropriate log level when you app is released to production.

Tracking

Once the Tealium instance has been defined you can begin tracking events with the method TrackEvent(), which takes the following parameters:

  • Event Name (required) - a name to identify the event
  • Event Data (optional) - Object with event data as key/value pairs
  • Callback Function (optional) - Object with a function assigned to the "callback" key
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:

  • building a retry or fallback system for failed calls
  • building a queueing or throttling system
  • customizing the Logger
  • chaining application logic 

Validation

Use LiveEvents or Trace to validate that Tealium is receiving your tracking calls.

Follow these steps to create a Stream for Roku events:

  • Go to Live Events and cilck Add Stream
  • Set the Title to "Roku Events"
  • Set the Condition to tealium_library_name equals (Custom Value) "roku"

    tealium-roku-events-stream.jpg

  • Save the Stream

Now you can easily filter events using the "Roku Events" Stream.

Follow these steps to add a Trace to your app:

  1. Get a Trace ID from Visitor Trace in UDH
  2. Add a tealium_trace_id variable to the data object of your tracking calls and assign it the Trace ID.
  3. Trigger events in your Roku app
  4. Verify those tracking calls in Visitor Trace

Watch this video for a demonstration of using and Trace to validate your implementation:

Function Definitions

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.

createTealium()

createTealium(account as String, profile as String, env as String, logLevel as Integer) as Object

Creates a Tealium object that will be used to track events.

teal = createTealium("account", "profile", "env", 3) 
Parameters Type Description
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

trackEvent()

trackEvent(eventType as String, eventName as String, data as Object, callback as Object) as Void

Tracks an event with associated data and, optionally, triggers a callback function.

Parameters Type Description
eventType String Tealium event type (activity, conversion, derived, interaction, or view)
eventName String Name of event (becomes the event_name attribute in UDH)
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("activity", "someEvent", data, cb) 

resetSessionId()

resetSessionId() as Integer

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. 

teal.resetSessionId()

toStr()

toStr() as String

Returns a readable string containing the configuration details of the current Tealium instance eg. "Tealium instance for account: ACCOUNT profile: PROFILE environment: ENV"

print teal.toStr()

 

Change Log

- 1.1.0

    • Update trackEvent takes an additional String type arg with one of the following values:
      • activity
      • conversion
      • derived
      • interaction
      • view
    • Additional Tealium variable:
      • tealium_event_type

- 1.0.0 Initial Release