Open in ChatGPTOpen in Claude

Official Coralogix Roku SDK

Real User Monitoring for Roku channels: sessions, logs, errors, crashes, views and network requests, sent to Coralogix. See the changelog for what changed in each release.

What you need

• A Roku device or emulator running Roku OS 11 or later. Crash reporting requires Roku OS 13 or later.
• ropm, the Roku package manager.
• Your Coralogix RUM public key, and the region your Coralogix account is in.

Installation

ropm is a package manager for Roku, based on npm. If your channel doesn't use ropm yet, follow its installation guide. Then install the SDK:

ropm install @coralogix/roku

ropm prefixes the SDK's functions with coralogix_roku_, as used throughout this page.

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: "[email protected]" },
        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 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, 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 lists every call, its arguments and what it returns.

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 <roku-ip> 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
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 and ignoreErrors
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

License

Apache-2.0