Skip to content
Everframe Docs
Documentation

Install

Load one component library, call start(), and add a few lines to Main(). Crashes are reported on the next launch.

Updated

The Roku SDK reports crashes, errors and release health. There is no in-channel reporter, no screenshot and no session replay on Roku yet; a report is the error, its stack when one is available, the breadcrumb trail, the screen, and the device.

Create a Roku integration in the dashboard to get an SDK key, then install the package as a dev dependency of your channel project:

npm i -D @everframe/roku

Add the component library

Copy node_modules/@everframe/roku/dist/everframe-roku-<version>.zip into your channel’s components/ folder and declare it in your main scene. <version> is the installed package version — the exact file name is whatever ls node_modules/@everframe/roku/dist/*.zip shows. Update the uri when you upgrade the package.

<!-- MainScene.xml: replace <version> with the installed version -->
<children>
  <ComponentLibrary id="Everframe" uri="pkg:/components/everframe-roku-<version>.zip" />
</children>

Start the SDK

Start Everframe once the library has loaded:

' MainScene.brs
sub init()
    m.efLib = m.top.findNode("Everframe")
    m.efLib.observeField("loadStatus", "onEverframeLoad")
    ' A bundled library can already be "ready" here; the observer only sees later changes.
    onEverframeLoad()
end sub

sub onEverframeLoad()
    if m.efLib.loadStatus <> "ready" or m.efStarted <> invalid then return
    m.efStarted = true
    ef = CreateObject("roSGNode", "Everframe:Everframe")
    ef.callFunc("start", {
        sdkKey: "evf_live_…",
        releaseHealthLaunch: ReadAsciiFile("tmp:/everframe-health-launch.json")
    })
end sub

start() returns true when the SDK is running and publishes the node as m.global.everframe, so any component can reach it afterwards. See Configuration for the other keys it accepts.

Record the last exit in Main()

Roku hands the previous launch’s exit record (GetLastExitInfo, Roku OS 13.0+) only to your channel’s own code. Called from inside the component library it always answers EXIT_UNKNOWN, so the SDK cannot read it itself. Install the current channel-side bridge from the same SDK package as the component library:

mkdir -p source/everframe
cp node_modules/@everframe/roku/hook/everframe_hook.brs source/everframe/
for name in ef_util ef_health ef_version ef_frames ef_record ef_queue ef_fingerprint; do
  cp "node_modules/@everframe/roku/library/components/Everframe/lib/$name.brs" source/everframe/
done

Call it first in Main(), before creating the screen:

sub Main()
    Everframe_RecordLastExit()
    screen = CreateObject("roSGScreen")
    ' ... your existing Main() ...
end sub

The build-step instrumentation installs and calls the bridge automatically. Pass releaseHealthLaunch from your scene in both manual and instrumented integrations. Re-run instrumentation when upgrading the SDK. For a manual integration, replace the copied bridge and support files on upgrade. Older inline pendingExit snippets can report errors but do not support release health; replace them with this bridge.

On Roku OS 13.0+, the bridge and an enabled, configured start() with releaseHealthLaunch monitor one launch. Its completion or exit is delivered on a later launch. Development builds and launches without a working bridge are excluded from release health. See Crash reporting for which exits count as crashes. A recovered exception alone does not mark a launch crashed.

Calling GetLastExitInfo() elsewhere in your own code is fine — reading it does not consume the record. Call it from Main() or a Task only, never from the render thread: roAppManager cannot be created there.

Loading the library remotely

You can host the same zip and point the library at it instead of bundling it:

<ComponentLibrary id="Everframe" uri="https://<your host>/everframe-roku-<version>.zip" />

Bundling is the better default. A remote library is downloaded on every launch, makes your channel depend on that host being available, and a crash that happens before the library has loaded is only reported on the next launch where it does load.

Requirements

WhatRequires
Release health and next-launch exit detectionRoku OS 13.0+
Build-step instrumentationRoku OS 9.4+ (try / catch), Node.js 22.5+ on the build machine

Next