Install (preview)

Preview. The Vega OS SDK reports JavaScript errors in apps built with React Native for Vega. It has no native module, so it cannot see native or C++ crashes, Hermes engine aborts, ANRs or watchdog kills; Vega OS records those in its own crash reports. There is no in-app reporter, screenshot or session replay on Vega OS. Team members can still file quick captures from a linked device with the remote.

It is verified on Vega OS 1.1 (React Native 0.72, Hermes 0.12). React Native 0.83 on Vega OS 1.2 is untested.

Install

Create a Vega OS (preview) integration in the dashboard to get an SDK key, then add the package to your app:

npm install @everframe/vega

There is nothing to link: the package is plain JavaScript and needs only react-native 0.72 or later.

Start the SDK

Call init() at the top of index.js, before AppRegistry.registerComponent, so errors during startup are caught too:

// index.js
import AsyncStorage from '@amazon-devices/react-native-async-storage__async-storage';
import * as Everframe from '@everframe/vega';
import { AppRegistry } from 'react-native';
import { App } from './src/App';
import { name as appName } from './app.json';

Everframe.init({
  sdkKey: 'evf_live_…',
  storage: AsyncStorage,
  appVersion: '1.4.0',
});

AppRegistry.registerComponent(appName, () => App);

Pass storage. A fatal JavaScript error ends a Vega OS app a few milliseconds after the SDK sees it. The SDK writes the report to storage first, holds the crash for up to 1.5 seconds while it tries to send it, and sends it on the next launch if it could not. Without storage that report is lost.

Release health

Release health starts automatically when you supply a valid appVersion. Open Release health on a release in the dashboard and select Vega OS to see foreground sessions, crash-free rates and version details. Vega sessions use an anonymous subject, so user-based rates are unavailable.

Each observed foreground period is a session. A background transition completes it. A fatal JavaScript error reported through ErrorUtils marks the exact session as crashed, even when the loaded bundle ID is unknown. Caught errors, non-fatal errors and promise rejections remain error reports and do not lower the crash-free session rate. Native or C++ crashes, Hermes aborts, ANRs, out-of-memory kills and watchdog kills are outside this coverage; a session without a completion or matching fatal JavaScript report stays unknown.

Set releaseHealth: false to disable health collection and clear its pending records. debugBuild: true also disables collection. The SDK requires an explicit nonempty app version of at most 64 characters, and an optional build of at most 64 characters. Health records use the same SDK key and endpoint as the session that created them. Pass storage to preserve queued records across launches; without it, delivery is best effort within the current process.

Apps running the Web SDK in a Vega browser continue to report page sessions under a Web integration. The native Vega SDK uses a Vega OS integration and foreground sessions.

Report a caught error

try {
  await player.load(assetId);
} catch (error) {
  Everframe.captureException(error, {
    severity: 'warning',
    context: 'PlayerScreen',
    metadata: { assetId },
  });
}

metadata is flat: strings, numbers, booleans and null. Nested values are dropped and the report is marked truncated. A key that names a credential (password, token, secret, apiKey, authorization, cookie, in any case or spelling) keeps its name and gets [REDACTED] before the report is stored or sent. This is lighter than the other SDKs’ captureException details, which keep nested metadata, and an error’s cause chain is not reported on Vega OS: the preview keeps the SDK small and free of a schema library, and Hermes 0.12 has no new Error(message, { cause }).

setUser({ id, email, displayName }) labels later reports, and addBreadcrumb({ message, kind, level, data }) adds to the trail (the latest 100) that rides on every report. There are no automatic console, network or navigation breadcrumbs on Vega OS.

Readable stack traces

A release build’s frames point into the compiled bundle. The Vega CLI names each bundle by its SHA-256 and writes its source map next to it; every report carries that bundle id, so a map always applies to exactly the build it came from. Upload the maps after each release build:

npm install -D @everframe/cli
export EVERFRAME_API_TOKEN='<masked artifacts:write token>'
export EVERFRAME_APP_ID='<app id>'
npx react-native build-vega --build-type Release
npx @everframe/cli sourcemaps upload-vega --dir build/lib/rn-bundles/Release

upload-vega uploads each <id>.bundle.map whose bundle is still in the folder and skips maps left over from earlier builds. The token and the app ID are described in Symbols & source maps. Debug builds load the bundle from Metro and are not mapped.

Quick capture

A teammate’s Vega OS device can file quick captures with the remote, the same way phones and other TVs do; see Quick capture on real devices. It needs no code beyond init(), and your users see no change.

1. In the dashboard, open Project settings → Devices and click Link a device.
2. On the device, open the app and hold Play/Pause for about 1.5 s. The device shows “Linking to Everframe · 47”; click the same number in the dashboard.
3. From then on, holding Play/Pause files a draft for you, and the device shows “Captured · {your name}”. A debug build that isn’t linked files a shared draft.

A Vega OS capture has breadcrumbs and the device, app and user details, but no screenshot and no replay: the SDK is JavaScript only. The SDK only listens to remote keys and never keeps one from your app, so a long press of Play/Pause also reaches your app, which typically toggles playback once.

An admin can change the gesture in the app’s Quick capture card, under TV gesture, or click Record on device to press the keys on a linked Vega OS device. A Vega remote has Play/Pause, Select, Back, Menu, the arrows, Fast-forward, Rewind and the number keys. A gesture that uses a colored key, a letter or Shift can’t fire on Vega OS, so the device turns the gesture off and can’t link or capture until the gesture changes; the card warns you.

The device’s link token is kept in the storage you pass (the app’s AsyncStorage; React Native for Vega has no secure storage for JavaScript), bound to the endpoint and SDK key it was issued for. Set quickCaptureEnabled: false to turn quick capture off in the app.

Configuration

Dashboard settings such as session replay, vitals and network bodies do not apply. The SDK reads only the quick capture switches and the TV gesture from server config: one request per launch (a linked device also re-reads it when the app comes to the foreground, at most every 10 seconds), and none with quickCaptureEnabled: false.

Delivery and limits

Reports go to Everframe as JSON, because Vega OS networking drops multipart request bodies. Each report is stored before it is sent, retried with backoff while the app runs and on later launches (up to 8 attempts or 7 days), and removed once Everframe accepts or permanently rejects it. A resend carries the same report ID, so it is stored once. A stored report goes only to the endpoint and under the SDK key it was captured with: if a later launch uses another key or endpoint, it is dropped, not sent. At most 10 reports wait at a time; non-fatal ones are dropped first.

In one launch, an automatic error from the same place is reported once, and at most 10 distinct automatic and 10 distinct handled errors are reported. Fatal errors are always reported. Reports from one error in different builds are grouped together. An error thrown straight in an anonymous function (a timer or promise callback) has a stack that names no function, so its message is part of its group as well.

Check it works

Everframe.getStatus() returns { enabled, bundleId, rejections, pending }. In a release build bundleId is the 64-character bundle id and rejections is observed. Call captureException(new Error('Everframe test')) and the report appears in the dashboard within a few seconds.