Roku SDK Reference

Read time: 2 minutes

Last edited: Feb 3, 2020

This reference guide documents basic usage of our Roku SDK, and explains in detail how features work. If you want to dig even deeper, our SDKs are open source. To learn more, read Roku Client Github repository. The complete API reference is available here. Additionally you can clone and run a sample application using this SDK.

The Roku SDK is written in BrightScript.

Getting started

Building on top of our Getting Started guide, the following steps will get you started with using the LaunchDarkly SDK in your Roku Application.

We provide releases on GitHub. Download the latest release and extract the provided files into your source tree. You may need to rename the paths inside LaunchDarklyTask.xml depending on your project structure.

For SceneGraph usage add a LaunchDarklyTask node to your scene and then:

1REM get a reference to to task
2launchDarklyNode = m.top.findNode("my-node-name") 
3
4REM create configuration
5config = LaunchDarklyConfig("MY_MOBILE_KEY", launchDarklyNode) 
6
7REM create a user
8user = LaunchDarklyUser("user-key") 
9
10REM initialize the client
11LaunchDarklySGInit(config, user)

For each SceneGraph component you want to use the SDK in you need to initialize an interface to talk to the SceneGraph. This interface provides all the expected client functionality such as evaluation.

1REM create the scenegraph communication wrapper
2launchDarkly = LaunchDarklySG(launchDarklyNode) 
3
4REM use the client
5value = launchDarkly.boolVariation("MY_FLAG_KEY", false)

Creating a client outside of the SceneGraph API is similar. In the legacy API you do not need LaunchDarklySGInit or the LaunchDarklySG functions.

1REM get a reference to the task
2launchDarklyNode = m.top.findNode("MY_NODE_NAME") 
3
4REM create configuration
5config = LaunchDarklyConfig("MY_MOBILE_KEY", launchDarklyNode) 
6
7REM create a user
8user = LaunchDarklyUser("user-key") 
9
10
11REM create message port
12messagePort = createObject("roMessagePort") 
13
14REM initialize the client
15launchDarkly = LaunchDarkly(config, user, messagePort) 
16
17
18REM use the client
19value = launchDarkly.boolVariation("MY_FLAG_KEY", false)

If not using the SceneGraph you need to poll events to drive the client in your standard event loop.

1while (true) 
2
3    REM do not wait forever or timers will break
4    msg = wait(3000, messagePort) 
5
6
7    if launchDarkly.handleMessage(msg) then
8        REM this message was for the client
9    else
10        REM handle non client messages
11    end if
12end while

Variations

The *variation methods determine which variation of a feature flag a user receives.

1REM typed variations
2myInt = launchDarkly.intVariation("MY_FLAG_KEY", 123) 
3
4myBool = launchDarkly.boolVariation("MY_FLAG_KEY", false) 
5
6myString = launchDarkly.stringVariation("MY_FLAG_KEY", "hello world!") 
7
8myObjectOrArray = launchDarkly.jsonVariation("MY_FLAG_KEY", {"value": 123}) 
9
10REM generic variation
11myValue = launchDarkly.variation("MY_FLAG_KEY", false)

*variation calls take a feature flag key and a default value.

The default value will only be returned if an error is encountered—for example, if the feature flag key doesn't exist or the user doesn't have a key specified.

Evaluation explanations

For each variation type there is also an associated version that returns the reason a particular value was returned. For example:

1details = launchDarkly.intVariationDetail("MY_FLAG_KEY", 123)

These variation methods return an object containing the keys value, reason, and variationIndex. The value field is the result of the evaluation. The reason field is an object that explains why the result happened, for example details about a rule match. The reason object will always contain a kind field. Lastly the (potentially null) variationIndex field contains the id of the particular value returned.

Customizing your client

You can create a client configuration object with:

1REM for a legacy Roku application
2config = LaunchDarklyConfig("YOUR_MOBILE_KEY") 
3
4REM for a SceneGraph Roku Application
5config = LaunchDarklyConfig("YOUR_MOBILE_KEY", CLIENT_SCENEGRAPH_NODE)

We support the following configuration options for both SceneGraph and non SceneGraph usage:

1config.setAppURI(String) 
2
3config.setEventsURI(String) 
4
5config.setStreamURI(String) 
6
7
8config.setPollingIntervalSeconds(Integer) 
9
10config.setOffline(Boolean) 
11
12
13config.addPrivateAttribute(String) 
14
15config.setAllAttributesPrivate(Boolean) 
16
17
18config.setEventsCapacity(Integer) 
19
20config.setEventsFlushIntervalSeconds(Integer) 
21
22config.setStreaming(Boolean)

Logging

Log levels

You can configure the SDK log level. For example to set the level to info:

1config.setLogLevel(LaunchDarklyLogLevels().info)

The SDK supports the following Levels:

1LaunchDarklyLogLevels().error
2LaunchDarklyLogLevels().warn
3LaunchDarklyLogLevels().info
4LaunchDarklyLogLevels().debug
5LaunchDarklyLogLevels().none

A custom logging backend can be provided. This will be different depending on if you are using the SceneGraph API or the Legacy API.

Legacy API Custom Logger

1function CustomLogger() as Object
2    return {
3        log: function(level as Integer, message as String) 
4
5            print level message
6        end function
7    }
8end function
9
10config.setLogger(CustomLogger())

SceneGraph API Custom Logger

1<!-- /components/CustomLogger.xml -->
2
3<component name="CustomLogger" extends="Task">
4    <interface>
5        <field id="log" type="assocarray" alwaysNotify="true"/>
6    </interface>
7
8    <script type="text/brightscript" uri="pkg:/components/CustomLogger.brs"/>
9</component>

1REM /components/CustomLogger.brs
2
3function init() 
4
5    m.messagePort = createObject("roMessagePort") 
6
7
8    m.top.observeField("log", m.messagePort) 
9
10end function
11
12function mainThread() as Void
13    while (true) 
14
15        msg = wait(0, m.messagePort) 
16
17
18        if type(msg) = "roSGNodeEvent" then
19            if field = "log" then
20                value = msg.getData() 
21
22                print value.level value.message
23            end if
24        end if
25    end while
26end function

To use the logger create the SceneGraph logger node and then:

1config.setLoggerNode(myLoggerNode)

Users

You can create a user object with:

1user = LaunchDarklyUser("my-user-key")

User objects can be customized with:

1user.setFirstName(String) 
2
3user.setLastName(String) 
4
5user.setEmail(String) 
6
7user.setName(String) 
8
9user.setAvatar(String) 
10
11user.setCustom(AssociativeArray)

A user can be marked as anonymous with:

1user.setAnonymous(Boolean)

Users can have specific fields marked as private with:

1user.addPrivateAttribute(String)

Track

The track method allows you to record custom events in your application with LaunchDarkly:

1REM without optional data
2launchDarkly.track("YOUR_EVENT_KEY") 
3
4REM with optional data
5launchDarkly.track("YOUR_EVENT_KEY", {"customField": 123}) 
6
7REM with optional numeric metric
8launchDarkly.track("YOUR_EVENT_KEY", invalid, 52.3)

Flush

Internally, the LaunchDarkly SDK keeps an event buffer for analytics events. These are flushed periodically in a background thread. In some situations (for example, if you're testing out the SDK in a simulator), you may want to manually call flush to process events immediately.

1launchDarkly.flush()

Changing the user context

If your app is used by multiple users on a single device, you may want to change users and have separate flag settings for each user. To achieve this, the SDK supports switching between different user contexts.

1user = LaunchDarklyUser("abc") 
2
3launchDarkly.identify(user)

The identify call will load any saved flag values for the new user and immediately trigger an update of the latest flags from LaunchDarkly. Since this method re-fetches flag settings for the new user, it should not be called at high frequency. The intended use case for switching user contexts is the login / logout flow.

Getting all flags

You can get an associative array of flagKey -> flagValue for all flags from the client with:

1allFlags = launchDarkly.allFlags()