The Roku SDK reports crashes, out-of-memory kills and runtime errors from BrightScript / SceneGraph channels, with the breadcrumb trail, the screen and the device. It is crash and error reporting only: there is no in-channel reporter, screenshot or replay on Roku yet.
Three steps
1Install and add the library
npm i -D @everframe/roku
<!-- MainScene.xml, after copying the zip into components/ -->
<ComponentLibrary id="Everframe" uri="pkg:/components/everframe-roku-<version>.zip" />
2Start it once the library loads
ef = CreateObject("roSGNode", "Everframe:Everframe")
ef.callFunc("start", { sdkKey: "evf_live_…" }) 3Instrument release builds
everframe-roku instrument ./ --out ./.everframe-build --bundle-library
What it captures
Crashes Abnormal exits of the previous launch — BrightScript crashes, timeouts, system kills detected on the next launch; needs a few lines in Main() and Roku OS 13.0+
Out of memory Memory-limit and low-resource kills, with the last memory reading before the exit
Errors with a stack Errors in wrapped entry points, recorded at the throw and re-thrown needs the instrument build step; without it frames are often missing
Caught exceptions captureException from your own try / catch
Breadcrumbs Your addBreadcrumb calls, screen changes and memory-pressure warnings key presses and scene init are added by the instrument step
Screen The current screen as context.route setScreen, or automatic for *Screen, *View and *Page components when instrumented
Device and app Model, Roku OS version, display size, locale, timezone; channel title, version and build from the manifest
Not captured Screenshot, session replay, console, network, and reports filed by a person not available on Roku yet
What you wire yourself
- The Main() lines that store the previous launch's exit record. Roku gives it only to your channel's own code; the instrument step adds them for you.
- The instrument step in your release and beta deploys. Keep development builds uninstrumented, because the debugger stops at the end of the wrapped function.
- Screens, with setScreen where a screen becomes visible, if your channel reuses screen components instead of creating them.
- Who the viewer is, with setUser, and any breadcrumbs for network or playback.
When to pick it
Any Roku channel written in BrightScript and SceneGraph. The other TV platforms
run one of the JavaScript or native SDKs; Roku is its own runtime, so it has its
own SDK.
What is different about Roku
It is the one SDK that only reports crashes and errors. Everything a person
files on the other platforms — an annotated screenshot, a replay, a
description — needs a reporter, and there is none on Roku yet. What you get is
the failure itself: the exit reason Roku recorded, a stack when the build is
instrumented, the breadcrumbs and screen from the session that ended, and the
memory reading before an out-of-memory kill.
The report is the same envelope as every other SDK, so it lands in the same
error groups, webhooks and triage rules. See Install,
Crash reporting and
Build instrumentation.
For a full run through a test channel, with the reports each crash produced,
read Roku crash logs: capturing BrightScript crashes after the channel is gone.
Questions
Can a viewer or tester file a bug report from a Roku channel?
Not yet. The Roku SDK is crash and error reporting only. There is no reporter UI and no screenshot on Roku; reports are filed by the SDK when the channel crashes or your code calls captureException.
Why does a crash only show up after the channel is opened again?
A channel that has crashed cannot send anything. Roku records why it exited, and the SDK reads that on the next launch and reports it then. The report's occurredAt is the time of the exit.
Do I need the build step?
No, but use it for release builds. Without it, a crash is still reported, but its stack comes from a 20-line console log that is frequently full of other output, so frames are often missing. The instrument step records the backtrace at the throw.
Does instrumenting change how my channel behaves?
No. Each wrapped function records the error and re-throws the original exception, on the same source line, so line numbers and crash behaviour are unchanged. It does change where the debugger stops, which is why development builds stay uninstrumented.
