# Roku Client SDK

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

- **Repository:** [roku-sdk](https://github.com/statsig-io/roku-sdk)

## Set up the SDK

1. **Install the SDK**

   Start by downloading [the GitHub repository](https://github.com/statsig-io/roku-sdk). Roku doesn't have a package manager, so you copy the implementation files from this repository to integrate Statsig in your Roku app.

   You need the following files:

   ```plaintext
   Statsig
     -- components
       -- statsigsdk
         -- StatsigTask.brs
         -- StatsigTask.xml
     -- source
       -- DynamicConfig.brs
       -- Statsig.brs
       -- StatsigClient.brs
       -- StatsigUser.brs
   ```

   The library consists of two main parts:

   - **source/Statsig**: an object used by SceneGraph components that connects a StatsigClient with the background StatsigTask.
   - **components/StatsigTask**: a SceneGraph Task that runs in the background to batch events and fetch values from Statsig servers.

   The `components` folder contains SceneGraph components and the `source` folder contains BrightScript files. You must include all of these files in their respective folders of the application. If you change the file paths, you must update the file references in `StatsigTask.xml` and include those references in your main XML file.
2. **Initialize the SDK**

   Initialize the SDK with a client SDK key from the ["API Keys" tab on the Statsig console](https://console.statsig.com/api_keys). These keys are safe to embed in a client application.

   Along with the key, pass in a [User Object](#statsig-user) with the attributes you'd like to target later on in a gate or experiment.

   To initialize the SDK, first integrate the SDK files into your application.

   Include `StatsigClient.brs`, `StatsigUser.brs`, `DynamicConfig.brs`, and `Statsig.brs`:

   ```xml
   <script type="text/brightscript" uri="pkg:/source/Statsig.brs" />
   <script type="text/brightscript" uri="pkg:/source/StatsigClient.brs" />
   <script type="text/brightscript" uri="pkg:/source/StatsigUser.brs" />
   <script type="text/brightscript" uri="pkg:/source/DynamicConfig.brs" />
   ```

   Next, initialize the library in your `init()` function and add a listener for when the SDK has fetched gates/experiments:

   ```xml
   <!-- in component xml -->
   <StatsigTask id="statsigTask" />
   ```

   ```brightscript
       statsigTask = m.top.findNode("statsigTask")
       statsigTask.observeField("initializeValues", "onStatsigReady")
       m.statsig = Statsig(statsigTask)

       user = StatsigUser()
       user.setUserID("456")
       m.statsig.initialize("<STATSIG_CLIENT_SDK_KEY>", user)
   ```

   For more information on all of the user fields you can use, refer to the [StatsigUser docs](https://docs.statsig.com/sdks/user).

   Before the SDK has loaded the updated values, all APIs return default values (false for gates, empty configs and experiments).

   To implement a callback handler for Statsig being ready, and tell the SDK to load the updated values in the `onStatsigReady` function you registered with `observeField`:

   ```brightscript
   function onStatsigReady() as void
       m.statsig.load()

       // Check gates, log events, check experiments, etc
       gate = m.statsig.checkGate("gate_id")
       config = m.statsig.getConfig("config_id")
       experiment = m.statsig.getExperiment("experiment_id")
       m.statsig.logEvent("event_name", "event_value", {metadata: "event_metadata"})
   end function
   ```

   To update the user, `m.statsig.updateUser(newUser)` triggers the same `onStatsigReady` callback after the SDK fetches the new gate/config/experiment values from Statsig servers.