Analytics for Roku

You can start by downloading a copy of the library here: https://github.com/segmentio/analytics-roku.

Unzip the contents and you should see the following structure:

1
SegmentAnalytics
2
  -- components
3
    -- SegmentAnalyticsTask.brs
4
    -- SegmentAnalyticsTask.xml
5
  -- source
6
    -- SegmentAnalytics.brs
7
    -- SegmentAnalyticsConnector.brs
8

The library consists of three parts:

1. source/SegmentAnalyticsConnector.brs: Connector object used by SceneGraph components to make calls (Identify, Track, Screen, Group or Alias). Public interface of the library for usage throughout the app. Abstracts away interaction with SegementAnalyticsTask SceneGraph Task node directly.
2. source/SegmentAnalytics.brs: Implementation responsible for making HTTP requests to Segment REST API for Identify, Track, Screen, Group or Alias. Includes handling for batching, error handling. Must be used within context of SceneGraph Task node. Cannot be used directly within context of SceneGraph UI components.
3. components/SegmentAnalyticsTask.brs/xml: SceneGraph Task node that will be running for the entire lifecycle of the app. Responsible for delegating calls to SegmentAnalytics.brs to make requests to Segment REST API.

The components folder contains SceneGraph components and the source folder contains BrightScript files. The content of each folder must be included in the respective folder of the application. Depending on the application folder structure and where the library files are included, SegmentAnalyticsTask.xml might need to be updated to reflect the file paths.

To instantiate the library, you first need to update the application scene .xml file with the following two changes:

1. Include SegmentAnalyticsConnector.brs BrightScript file:

<script type="text/brightscript" uri="pkg:/source/analytics/SegmentAnalyticsConnector.brs" />

2. Include SegmentAnalyticsTask node component under the children tag:

<SegmentAnalyticsTask id="segmentAnalyticsTask" />

3. Once you have those tags in place you can initialize the library in your "init()" function of your scene as follows:

1
task =  m.top.findNode("segmentAnalyticsTask")
2
m.library = SegmentAnalyticsConnector(task)
3

4
config = {
5
  "writeKey": "WRITE KEY"
6
  "debug": true
7
  "queueSize": 3
8
  "retryLimit": 0
9
}
10

11
m.library.init(config)

The "config" object in the example has four values that you can set:

writeKey (required): A string type field that is the write key to the source of your workspace hosted on Segment.

debug (optional): A boolean flag that if set to true that logs all the operations of the library. Omit this field entirely on the release of your app.

queueSize (optional): An integer that indicates how many tracking calls you want queue before sending out the request. If omitted or a value of less than one is used then this field will default to one.

retryLimit (optional): An integer that indicates how many times you want the system to retry request calls if they do end up failing. If omitted or a value of less than zero is used then this field will default to one.

You can begin to use the library by invoking the Identify call as it allows you to let you identify the user in your app. It also lets you record traits about the user, like their email, name, account type, and so on.

When you call this method that is ultimately up to you. It is recommended that you try to call it as early as possible in a block of code that already has your user information instantiated and ready to populate. If however, you're doing an anonymous tracking you can omit this call entirely and supply an anonymousId field to the Track calls.

This is what an Identify call looks like in BrightScript with your library instantiated with the example:

1
exampleTraitsObject = {
2
  "email": test@test.com
3
  "name": "TestName"
4
}
5

6
exampleOptionsObject = {
7
  "extraInformation": "test"
8
}
9

10
m.library.identify("exampleUserId", exampleTraitsObject, exampleOptionsObject)

After identifying the user you can start to invoke the other methods calls library (Track, Screen, Group and Alias) with the same userID to associate them within the segment analytics system.

Identify lets you tie a user to their record trait about them. It includes a unique user ID and any optional traits you know about them. We recommend calling Identify a single time when the user's account is first created, and only identifying again later when their traits change.

An example of the method call would be as follows:

1
userId = "1sdf1fw4xgafs"
2
 
3
traits = {
4
  "email": testEmail@example.com
5
  "name": "John Doe"
6
  "accountType" : "tier-1"
7
}
8

9
options = {
10
  "timeStamp": "2019-04-23T19:24:13+00:00"
11
}
12

13
m.library.identify(userId, traits, options)

The Identify call has the following fields:

userId (required): A string that is the database ID for the user.

traits (optional): An object that has property fields inside it such as name, email, address, for example, that are associated with the userID.

options (optional): An object that has extra options for the call.

The Track event lets you record actions users perform. Every action triggers what we call an "event", which can also have associated properties.

For this call in particular we suggest tracking events that are successful such as page loaded, click action performed and so on.

This is an example of how you would invoke the Track call in the Roku library:

1
eventName = "fast forward button press"
2
 
3
properties = {
4
  "timeSkipped": "60"
5
  "mediaType": "movie"
6
  "timeInMovie": "35:20"
7
}
8

9
options = {
10
  "userId": "1sdf1fw4xgafs"
11
  "timeStamp": "2019-04-23T19:24:13+00:00"
12
}
13

14
m.library.track(eventName, properties, options)

The Track call has the following fields:

eventName (required): A string for the name of the event that is being tracked.

properties (optional): An object that has property fields associated with the event name for example, what page has been loaded, what type of button was clicked and so on.

options (required): An object that has extra options for the call. The property needed for this parameter is a valid string userId or anonymousId.

The Screen method lets you track which screen the user sees when it is loaded. In the case of Roku it would be the equivalent of when a SceneGraph page component loads onto the scene.

Example of a Screen call:

1
name = "Main Screen"
2
 
3
category = "All"
4
 
5
properties = {
6
  "hasCarousel": "false"
7
  "isLoggedIn": "false"
8
  "showingMovies": "true"
9
}
10

11
options = {
12
  "userId": "1sdf1fw4xgafs"
13
  "timeStamp": "2019-04-23T19:24:13+00:00"
14
}
15

16
m.library.screen(name, category, properties, options)

name : A string that denotes the name of the screen the user is on.

category : A string that denotes the category of the screen the user is on.

properties (optional): An object that has property fields associated with the screen.

options (required): An object that has Extra options for the call. The property needed for this parameter is a valid string userId or anonymousId.

Note: For this call in particular you either need the name or category for the request to send.

Helps associate an identified user with a Group. Groups can be companies, organizations, companies and so on.

An example of a Group call would be:

1
userId = "1sdf1fw4xgafs"
2
 
3
groupId = "1s2s3d2sd2a"
4
 
5
traits = {
6
  "company": "trackers.inc"
7
  "field":  "advertising"
8
  "specialty": "media tracking"
9
}
10
 
11
options = {
12
    "timeStamp": "2019-04-23T19:24:13+00:00"
13
}
14

15
m.library.group(userId, groupId, traits, options)

userId (required): A string that is the database ID for the user.

groupId (required): A string that is the database ID for the group.

traits (optional): An object that has traits fields associated with the group. For example, industry, employees and so on.

options (optional): Extra options for the call.

Allows you to associate one identity with another.

An example of an Alias call would be:

1
userId = "1sdf1fw4xgafs"
2
 
3
options = {
4
  "previousId": "123c-dsad-2da2-da2ds"
5
  "timeStamp": "2019-04-23T19:24:13+00:00"
6
}
7

8
m.library.alias(userId, options)

userId (required): The new ID to associate new Track calls with the current user with.

options (optional): Extra options for the call.

Currently, this library uses the Segment batch API endpoint, which is why you are able to set a queue limit on the config object before a method gets sent out as a request. You simply set the queueSize to 1 on config object to get the same effect for a message sending a single request.

The size limit is 500k characters on the data body per request as noted on Segment batch API, which would be the parameters you're using for each message (Identify, Track, Screen, Group, Alias). The size limit takes precedence over the queue limit in determining when a request gets sent out.

So for example, in the case you add a Track message that is just below 500k characters, then add a Group message that tips the data size over 500k, the system will send out the message that has been queued before (Track) and then queue in the next message (Group) call. Single messages that are over 500k characters in size will be rejected from the library.

If you want to see how big your request is getting you can use set the debug property to true on the config object before initializing our library. This will output a log on how big each request is getting when you queue/send them out.

You can follow this guide to set your device into developer mode and this one to debug and surface logs out of your app. There are currently two levels of debugging which are "DEBUG" and "ERROR".

The Roku library only supports cloud-mode destinations. If you have a need for a device-mode integration in your Roku application contact us.