Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Frum%2Fsdk-installation%2Froku.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Frum%2Fsdk-installation%2Froku.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.) # Official Coralogix Roku SDK [![npm version](https://img.shields.io/npm/v/@coralogix/roku.svg)](https://www.npmjs.com/package/@coralogix/roku) [Real User Monitoring](https://coralogix.com/docs/user-guides/rum/getting-started/real-user-monitoring.md) for Roku channels: sessions, logs, errors, crashes, views and network requests, sent to Coralogix. See the [changelog](https://coralogix.github.io/cx-roku-sdk/CHANGELOG.html) for what changed in each release. ## What you need[​](#what-you-need "Direct link to What you need") * A Roku device or emulator running Roku OS 11 or later. [Crash reporting](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/features/logs-and-errors.md#crashes) requires Roku OS 13 or later. * [ropm](https://github.com/rokucommunity/ropm), the Roku package manager. * Your Coralogix RUM public key, and the region your Coralogix account is in. ## Installation[​](#installation "Direct link to Installation") [ropm](https://github.com/rokucommunity/ropm) is a package manager for Roku, based on npm. If your channel doesn't use ropm yet, follow its [installation guide](https://github.com/rokucommunity/ropm#installation). Then install the SDK: ``` ropm install @coralogix/roku ``` ropm prefixes the SDK's functions with `coralogix_roku_`, as used throughout this page. ## Usage[​](#usage "Direct link to Usage") Call `coralogix_roku_initialize()` in `main.brs`, right after `screen.show()`: ``` sub Main() ... screen.show() coralogix_roku_initialize({ public_key: "your-rum-public-key", application: "my-channel", coralogixDomain: "EU2", version: "1.4.0", environment: "production", labels: { tier: "premium" }, user_context: { user_id: "user-1", user_name: "Jane", user_email: "jane@example.com" }, sessionConfig: { sessionSampleRate: 100, inactivityTimeoutMinutes: 120 } }, screen.getGlobalNode()) ' ...the rest of your channel setup end sub ``` `coralogix_roku_initialize()` returns `true` when the SDK starts. If an option is invalid, it returns `false`, sends nothing, and the console names the option. The SDK skips a label with an unsupported value, or a pattern that doesn't compile, and warns on the console. After `coralogix_roku_initialize()`, every component reaches the SDK as `m.global.cxRum`. For example, the [`reportInfo`](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/features/api-reference.md#reportinfo) function records a line at Info severity: ``` m.global.cxRum.callfunc("reportInfo", "home screen shown") ``` In a Task, read it once and keep the reference: ``` sdk = m.global.cxRum sdk.callfunc("reportInfo", "catalog loaded") ``` `m.global.cxRum` is `invalid` before `coralogix_roku_initialize()` and after [`shutdown`](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/features/api-reference.md#shutdown), and a `callfunc` on `invalid` crashes the thread. Guard every call that can run outside that window: ``` if m.global.cxRum <> invalid then m.global.cxRum.callfunc("reportInfo", "home screen shown") ``` A scene's `init()` runs during `CreateScene`, before `coralogix_roku_initialize()`, so it always sees `invalid`. Report from `init()` only after `Main` signals that the SDK is ready, for example through an interface field your scene observes and `Main` sets after `coralogix_roku_initialize()` returns. A reference kept in a Task stays safe after `shutdown`: report calls on it do nothing. Every call returns immediately; the SDK sends records in batches from its own thread. The [API reference](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/features/api-reference.md#calling-the-sdk) lists every call, its arguments and what it returns. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") Every row below is read from the device's debug console, so set that up first. By default, the SDK prints only warnings and errors to the console, such as an option it rejected, a call it ignored, or a batch that failed. Set `debug: true` to also see `initialized` with the session ID when the SDK starts, every record exactly as the SDK sends it, and each batch with its HTTP status, such as `post ok` or `post failed`. What the SDK sends to Coralogix doesn't change. Watch the console with: ``` nc 8085 ``` | Symptom | Cause | What to do | | ------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `coralogix_roku_initialize()` returned `false` | An option failed validation | Read the console. It names the option it rejected. See [Configuration options](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/configuration/options.md#options) | | No data in Coralogix, console shows `post failed` with a 4xx or 5xx status | Coralogix refused the batch | Check `public_key` and `coralogixDomain` | | No data in Coralogix, console shows `post failed` with a status of `0` or below | No response arrived at all (`-28` a timeout, `-6` a DNS failure) | Check the device's network, not the key | | Console shows `post ok` and data still doesn't appear | Coralogix accepted the batch and dropped its records | Check the device's date and time, then `sessionSampleRate`, [`ignoreUrls`](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/features/network-requests.md#ignore-urls) and [`ignoreErrors`](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/features/logs-and-errors.md#ignore-errors) | | Nothing printed at all | The SDK never started | Check that `coralogix_roku_initialize()` runs after `screen.show()` and gets `screen.getGlobalNode()` | | You cannot find a session in Coralogix | - | The `initialized` console line carries its ID, or call `getSessionId`. It returns `""` once the session has ended. See [When a session ends](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/features/sessions.md#when-a-session-ends) | ## License[​](#license "Direct link to License") Apache-2.0