No results for ""
EXPAND ALL
  • Home
  • API docs

Roku SDK reference

Read time: 4 minutes
Last edited: Oct 02, 2024
Version 2 of the Roku SDK replaces users with contexts

A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. To learn more about upgrading, read Roku SDK 1.x to 2.0 migration guide.

Overview

This topic documents how to get started with the client-side Roku SDK, and links to reference information on all of the supported features. The Roku SDK is written in BrightScript.

SDK quick links

LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:

ResourceLocation
SDK API documentationNone
GitHub repositoryroku-client-sdk
Sample applicationRoku
Published moduleavailable through GitHub releases

Get started

After you complete the Get started process, follow these instructions to start using the LaunchDarkly SDK in your Roku Application:

  • Install the SDK
  • Initialize the client
  • (Optional) Initialize an interface to SceneGraph
  • Evaluate a flag

Install the SDK

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.

Initialize the client

To create a client instance, you need your environment's mobile key. This authorizes your application to connect to a particular environment within LaunchDarkly.

The Roku SDK uses a mobile key

The Roku SDK uses a mobile key. Keys are specific to each project and environment. They are available from the Environments list for each project. To learn more about key types, read Keys.


Mobile keys are not secret and you can expose them in your client-side code without risk. However, never embed a server-side SDK key into a client-side application.

Here's how to create the client:

' get a reference to the task
launchDarklyNode = m.top.findNode("my-node-name")
' create configuration
config = LaunchDarklyConfig("mobile-key-123abc", launchDarklyNode)
' create a context
context = LaunchDarklyCreateContext({"key": "user-key-123abc", "kind": "user"})
' create message port
messagePort = createObject("roMessagePort")
' initialize the client
LaunchDarklySGInit(config, context)

To learn more about the specific configuration options available in this SDK, read Configuration.

Use a single instance

It's important to create a single client instance. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.

Initialize an interface to SceneGraph

If you are working with SceneGraph, then for each SceneGraph component in which you want to use the Roku SDK, you need to initialize an interface to talk to the SceneGraph. This interface provides all the expected client functionality, such as evaluation.

Here's how:

' create the scenegraph communication wrapper
launchDarkly = LaunchDarklySG(launchDarklyNode)

Evaluate a flag

After you initialize the client, you can use it to check which variation a particular context will receive for a feature flag.

Here's how:

' use the client
value = launchDarkly.boolVariation("flag-key-123abc", false)

If you are not using the SceneGraph, then you need to poll events to drive the client in your standard event loop:

while (true)
' do not wait forever or timers will break
msg = wait(3000, messagePort)
if launchDarkly.handleMessage(msg) then
' this message was for the client
else
' handle non client messages
end if
end while
Making feature flags available to this SDK

You must make feature flags available to mobile SDKs before the SDK can evaluate those flags. If an SDK tries to evaluate a feature flag that is not available, the context will receive the fallback value for that flag.

To make a flag available to this SDK, check the SDKs using Mobile key checkbox during flag creation, or on the flag's settings page. To make all of a project's flags available to this SDK by default, check the SDKs using Mobile key checkbox on your project's Flag settings page.

Supported features

This SDK supports the following features: