Roku Integration Guide

Introduction

This is a guide to help you integrate Streamlyzer ROKU plug-in to your service.

Requirements

  1. Eclipse with ROKU SDK plugin
  2. ROKU firmware version 2.6 or later

Components and Properties

Overview

There are 4 types of events to track (aka Observer components),

  • playbackObserver for tracking media playback.
  • userDefinedObserver for tracking user defined events.
  • sharedContentObserver for tracking sharing contents.
  • pageReferrerObserver for tracking page referrer.

There are number of properties that you should provide in order to initialize Observers.

Prior to initialization of Observers, you need to set properties as it needs. For your convenience, we group them into 5 categories. Depending on which observers you use, some of properties are required and some of them could be optional.

  • Audience properties
  • Content properties
  • Service properties
  • Platform properties
  • Customer properties

Properties

Audience properties
Variables Default Required Description
userId ‘Unset’ O User Unique ID. You should specify user unique id for each users. It shall be unique string or e-mail address or user id. It should be unique string so that data can be grouped by user id.
userType ‘Unset’ User Type. You can define the type of user. For example, “free user”, “non-free user” or “premium”.
gender ‘Unset’ User’s Gender. For example, “male” or “female”.
yearOfBirth ‘Unset’ User’s year of birth. This is for calculate user’s age. For example, “1995”.
Content properties
Variables Default Required Description
thumbnailImage ‘Unset’ URL of thumbnail image. You can specify thumbnail image of the contents. This thumbnail url will be used for displaying thumbnail image on Dashboard
seriesName ‘Unset’ Series name of movie. You can define series name of asset. For example, “Heroes”, “House of Cards”
episodeName ‘Unset’ Season/Episode name of movie. User can define Episode information into log. For example, Season 1 Episode 10 shall be “S1:E10”.
liveChannelName ‘Unset’ O Live channel Name. If the media is not a live channel, you can input the movie id.
movieId’ Unset’ O Movie ID. The tile of movie. This should be unique string so that metrics will be grouped by movie id.
movieCategory ‘Unset’ O Movie Category. You can define unique key string for grouping movie category. For example, this value can be “drama”, “comedy”, “horror” or “anime”.
movieSubcategory ‘Unset’ Movie Subcategory. You can define unique key string for grouping movie subcategroy. For example, this value can be “romantic drama”,”crime drama”, classic drama” or “teen drama”.
movieContentsProvider ‘Unset’ Movie Content providers. User can define unique key string for grouping contents providers. For example, this value can be “abc”, “desiney”, “time wanner”, “kbs” and so on.
movieRate ‘Unset’ Movie Rate. You can define movie rate. For example, “R”, “PG-13”, “PG”
bitRate 0 O Display bitrates. (unit: kbps)
resolution ‘Unset’ O Display resolutions. For example, “720×480”, “360×240”, “1080×900”, “720p”, “1080p”,”480p”
Service properties
Variables Default Required Description
live false O Is Live Service or not. If the service is Live, it shall be true, If not, it shall be false. For example, the content is VOD, it shall be “false”.
serviceType ‘Unset’ Serivce Type. You can define the type of service. For example, “TV” or “Radio”.
sessionId ‘Unset’ O Session ID. You could set session id based on each session.
streamingServerName ‘Unset’ O You can specify streaming server URL or CDN urls. It can be used for metrics grouped by streaming edge.
abTestMark ‘Unset’ O A/B test mark. This for A/B testing. You can put “A” or “B” or other unique string for A/B testing.
Platform properties
Variables Default Required Description
playerPlatformName ‘Unset’ O The named platform name. For example, “ROKU”, “ROKU2”
playerPlatformVersion ‘Unset’ O Player Platform Version. You can define user specific version information to group data. For example, you can specify ROKU player version information such as 5.4, 5.5.319 or 6.2.3467
mediaPlayerVersion ‘Unset’ O Media Player Version. You can define user specific version information to group data. For example, you can specify player version information such as MediaPlayer 6.
applicationName ‘Unset’ O The application name. For example, “Streamlyzer Plug-in App”
applicationVersion ‘Unset’ O The application version. For example, “1.0.0”
Customer properties
Variables Default Required Description
customerKey ‘Unset’ O Customer Key. This value is given by Streamlyzer. It is used for identifying logs you send. The log which one has invalid key value will be rejected.

Observers

Common

Description

For all observers, below three steps should be taken to set up properties.

  1. Initialize plug-in
  2. setProperties
  3. Close plug-in

' Initialize plug-in
initSZRPlugin()

' Set properties
szrEvent.setProperties(roAssociativeArray)

' Call plug-in update method on all event waiting loops
SZRPluginTimerUpdate()

' close plug-in
szrEvent.closeObserver()

playbackObserver

Description

Playback Observer will be attached with media player, and monitor playback event based on user’s interaction.

How to initialize

To initialize PlaybackObserver, you should set up 3 things,
1. Initialize plug-in
2. Initialize playbackObserver
3. Set proper properties on the Observer.

First, initialize plug-in and the observer and provide all of the required properties:


 Initialize plug-in
initSZRPlugin()

' Initialize playbackObserver
szrEvent = newSZRPlaybackObserver().init()

' Set properties
properties = {}

' key provided by Streamlyzer
properties[m.SZR_CUSTOMER_KEY] = "<Key Provided by Streamlyzer>"

' end user related properties
properties[m.SZR_USER_ID] = "<User ID>"
properties[m.SZR_USER_TYPE] = "<User Type>"
properties[m.SZR_GENDER] = "<User Gender>"     ' m.SZR_GENDER_FEMALE or m.SZR_GENDER_MALE
properties[m.SZR_YEAR_OF_BIRTH] = "<User Year of Birth>"

' service related properties                           
properties[m.SZR_SERVICE_TYPE] = "<Service Type>"
properties[m.SZR_SESSION_ID] = "<Session ID>"         
properties[m.SZR_STREAMING_SERVER_NAME] = "<Streaming Server Name>" ' Server name or source URL
properties[m.SZR_ABTEST_MARK] = "<AB Test Marking>"

' platform related properties
properties[m.SZR_PLATFORM_NAME] = "<ROKU>"

properties[m.SZR_LIVE] = true    ' true or false
properties[m.SZR_MOVIE_ID] = "<Movie ID>"
properties[m.SZR_MOVIE_CATEGORY] = "<Movie Category>"
properties[m.SZR_BIT_RATE] = "320"   ' bitrate in kbs
properties[m.SZR_RESOLUTION] = "720p"    ' resolution
properties[m.SZR_LIVE_CHANNEL_NAME] = "<Liv Channel Name>"

properties[m.SZR_MOVIE_SUBCATEGORY] = "<Movie Subcategory>"
properties[m.SZR_MOVIE_CONTENTS_PROVIDER] = "<Movie Contents Provider>"
properties[m.SZR_MOVIE_RATE] = "<Movie Rate>"
properties[m.SZR_SERIES_NAME] = "<Series Name>"
properties[m.SZR_EPISODE_NAME] = "<Episode Name>"
properties[m.SZR_THUMBNAIL_NAME] = "<Movie Thumbnail Image>"   ' Thumbnail URL

szrEvent.setProperties(propreties)

Implement protocol playback plug-in delegate method

The plug-in will call these methods to collect right media status.

Function Signiture Default Return Description
getPosition 0 It gets called to get the current position of media file. It can be the absolute position in millisecond unit. The return value should be Number, not String.
getBitrate 0 If there is any bitrate or video quality info available, this has to return current video bitrate in kbps (kilobits per seconds). For example, if current bitrate is “256kbps”, you should return “256”. The return value should be Number, not String.
getResolution “0” It returns video resolution. this method works with setProperty.
getDuration 0 It returns the total length in millisecond of the viewed media file. The return value should be Number, not String.

Event tracking API

Function Signiture Description
updateVideoScreenEvent Call this method on roVideoScreenEvent with message.
onPlayerLoad Call this method when roVideoScreen is starting.
onChannelChange Call this method when channel is changed.
onBitrateChange Call this method when bitrate is changed.

Example for Video

Here is full example. here, we use video for example.


' Initialize plug-in
initSZRPlugin()

' Initialize playbackObserver
szrEvent = newSZRPlaybackObserver().init()

' Set properties
szrEvent.setProperties(roAssociativeArray)

' Update plug-in state methods
' Call updateVideoScreenEvent and SZRPluginTimerUpdate to check playback status

while true
    msg = wait(1, port)            
    if type(msg) = "roVideoScreenEvent" then           
        szrEvent.updateVideoScreenEvent(msg)
        ' YOUR CODE HERE
    end if
    SZRPluginTimerUpdate()
end while               

userDefinedObserver

Description

userDefinedObserver allows you to define any events that is specific to your application and your business.

  • Event group is for classifying your User Defined Event.
  • All properties, keys and values should be string. If value is number, you should pass as number. For example, 120, “Mike”, “false”, “true”, 14.23
  • All should not include any spaces or special characters. For example,
    • “Media Player” – Wrong Expression (x)
    • “Media_Player” – Wrong Expression (x)
    • “MediaPlayer” – Correct Expression (o)

Please notice this, If you include any spaces or special characters, then plug-in will delete spaces and special characters. for example, plug-in send all keys as “MediaPlayer” when you try to send above properties.

How to initialize

To initialize UserDefinedEventObserver, you should set up proper properties. you can initialize observer like:


' Initialize plug-in
initSZRPlugin()

' Initialize userDefinedObserver
szrEvent = newSZRUserDefinedObserver().init()

' Set properties
properties = {}

' key provided by Streamlyzer
properties[m.SZR_CUSTOMER_KEY] = "<Key Provided by Streamlyzer>"

' end user related properties
properties[m.SZR_USER_ID] = "<User ID>"
properties[m.SZR_USER_TYPE] = "<User Type>"
properties[m.SZR_GENDER] = "<User Gender>"     ' m.SZR_GENDER_FEMALE or m.SZR_GENDER_MALE
properties[m.SZR_YEAR_OF_BIRTH] = "<User Year of Birth>"

' service related properties                           
properties[m.SZR_SERVICE_TYPE] = "<Service Type>"
properties[m.SZR_SESSION_ID] = "<Session ID>"         
properties[m.SZR_STREAMING_SERVER_NAME] = "<Streaming Server Name>" ' Server name or source URL
properties[m.SZR_ABTEST_MARK] = "<AB Test Marking>"

' platform related properties
properties[m.SZR_PLATFORM_NAME] = "<ROKU>"

szrEvent.setProperties(propreties)

Event API

Function Signiture Description
postUserDefinedCountEvent Count Event is an event that you want to count the number of event. group: Group name of the event. cntEvtName : Count event name
postUserDefinedSumEvent Sum Event is an event that you want to sum sumProperty of event. group: Group name of the event. sumEvtName: The key name to be summed. sumValue: The value to be summed. This should be Number, not String.
postUserDefinedRevenueEvent Revenue Event is an event that you want to analyze revenue you make from individual users. By associating with users, you can analyze revenue across different user segment and calculate key business metrics such as lifetime value. group: Group name of the event revEvtName: The key name of Revenue type revValue: The value of Revenue. This should be Number, not String.

Example


' trigger UserDefinedEvent
szrEvent.postCountableEvent("EventGroupName", "CountName")

szrEvent.postSumEvent("EventGroupName", "SumEvent", 12345)

szrEvent.postRevenueEvent("EventGroupName", "RevenueEvent", 123.45)


pageReferrerObserver

Description

pageReferrerObserver analyzes your service traffic as well as in-site moving.

How to initialize

To initialize pageReferrerObserver, you should set up proper properties. you can initialize observer like:


```
' Initialize plug-in
initSZRPlugin()

' Initialize pageReferrerObserver
szrEvent = newSZRPageReferrerObserver().init()

' Set properties
properties = {}

' key provided by Streamlyzer
properties[m.SZR_CUSTOMER_KEY] = "<Key Provided by Streamlyzer>"

' end user related properties
properties[m.SZR_USER_ID] = "<User ID>"
properties[m.SZR_USER_TYPE] = "<User Type>"
properties[m.SZR_GENDER] = "<User Gender>"     ' m.SZR_GENDER_FEMALE or m.SZR_GENDER_MALE
properties[m.SZR_YEAR_OF_BIRTH] = "<User Year of Birth>"

' service related properties                           
properties[m.SZR_SERVICE_TYPE] = "<Service Type>"
properties[m.SZR_SESSION_ID] = "<Session ID>"         
properties[m.SZR_STREAMING_SERVER_NAME] = "<Streaming Server Name>" ' Server name or source URL
properties[m.SZR_ABTEST_MARK] = "<AB Test Marking>"

' platform related properties
properties[m.SZR_PLATFORM_NAME] = "<ROKU>"

szrEvent.setProperties(propreties)

Event API

Function Signiture Description
postPageReferrerEvent Count Event is an event that you want to count the number of event. referrerHostName : Referrer Host Name referrerPagePath : Referrer Page Path currentPagePath : Current Page Path

Example


' trigger pageReferrerEvent
szrEvent.postPageReferrerEvent("<referrer host name>", "<referrer page path>", "<current page path>")
sharedContentObserver

Description

sharedContentObserver analyzes your service out-bound traffic.

How to initialize

To initialize sharedContentObserver, you should set up proper properties. you can initialize observer like:


' Initialize plug-in
initSZRPlugin()

' Initialize sharedContentObserver
var _szrEvent:SZRSharedContentsObserver = new SZRSharedContentsObserver()

' Set properties
properties = {}

' key provided by Streamlyzer
properties[m.SZR_CUSTOMER_KEY] = "<Key Provided by Streamlyzer>"

' end user related properties
properties[m.SZR_USER_ID] = "<User ID>"
properties[m.SZR_USER_TYPE] = "<User Type>"
properties[m.SZR_GENDER] = "<User Gender>"     ' m.SZR_GENDER_FEMALE or m.SZR_GENDER_MALE
properties[m.SZR_YEAR_OF_BIRTH] = "<User Year of Birth>"

' service related properties
properties[m.SZR_SERVICE_TYPE] = "<Service Type>"
properties[m.SZR_SESSION_ID] = "<Session ID>"
properties[m.SZR_STREAMING_SERVER_NAME] = "<Streaming Server Name>" ' Server name or source URL
properties[m.SZR_ABTEST_MARK] = "<AB Test Marking>"

' platform related properties
properties[m.SZR_PLATFORM_NAME] = "<ROKU>"

properties[m.SZR_LIVE] = true    ' true or false
properties[m.SZR_MOVIE_ID] = "<Movie ID>"
properties[m.SZR_MOVIE_CATEGORY] = "<Movie Category>"
properties[m.SZR_LIVE_CHANNEL_NAME] = "<Live Channel Name>"

szrEvent.setProperties(propreties)

Event API

Function Signiture Description
postSharedContentsEvent evtGroup: Group name of the event.destination: Shared Destination. with this property. you can send any string, however, we strongly recommend to use below list. Twitter: “twitter”Facebook: “facebook” Google+: “googleplus” Blogger: “blogger” Tumblr: “tumblr” reddit: “reddit” Pinterest: “pinterest” LiveJournal: “livejournal”

Example


' trigger SharedEvent
szrEvent.postSharedContentsEvent("EventGroupName", "twitter")