Vega OS integration guide

Add BugSnag to your Vega OS apps to report JavaScript errors.

New to BugSnag? Create an account

Installation

Add the BugSnag package to your dependencies in package.json:

npm install --save @bugsnag/vega

The latest available version of @bugsnag/vega is v1.0.0.

Basic configuration

In index.js, import and start the BugSnag client. The simplest way to configure BugSnag is to provide your API key as a string:

import Bugsnag from '@bugsnag/vega'

Bugsnag.start('YOUR_API_KEY')

You can find your API key in your project’s settings (shortcut: gs) in the dashboard.

To specify any additional configuration options, supply an object instead:

Bugsnag.start({
  apiKey: 'YOUR_API_KEY',
  otherOptions: value
})

For information on values that can be set in the configuration object, see configuration options.

Capturing React render errors

The BugSnag ErrorBoundary allows you to capture React render errors in your application. You can also use the FallbackComponent to display a custom error screen to your users:

// Start BugSnag first...
Bugsnag.start({...})

// Create the error boundary...
const ErrorBoundary = Bugsnag.getPlugin('react').createErrorBoundary(React)

const ErrorView = () =>
  <View>
    <Text>Inform users of an error in the component tree.</Text>
  </View>

const App = () => {
  // Your main App component
}

export default () =>
  <ErrorBoundary FallbackComponent={ErrorView}>
    <App />
  </ErrorBoundary>

See our guide on capturing render errors to learn more about the ErrorBoundary and FallbackComponent.

If you use React Navigation in your app, you can automatically capture your users’ navigation history.

See Navigation libraries for integration instructions.

TypeScript support

Type definitions are provided and will be picked up automatically by the TypeScript compiler when you import @bugsnag/vega.

Further configuration

If you’d like to configure BugSnag further, check out the Configuration options reference.

Showing full stacktraces

The JavaScript code in your app is minified in a release build and so is not visible in the stacktraces of errors from your users devices. Uploading source maps enables you to see the original method names, file paths, and line numbers in stacktraces.

It is also necessary to upload symbol files for any Turbo Module C or C++ code that is included in your app.

See the showing full stacktraces guide to configure uploading files during your release process.

Reporting unhandled errors

After completing the installation and basic configuration steps above, unhandled errors and promise rejections in JavaScript will be reported automatically and appear on your BugSnag dashboard.

Reporting handled errors

Sometimes it is useful to manually notify BugSnag of a problem. To do this, call Bugsnag.notify(). For example:

try {
  something.risky()
} catch (e) {
  Bugsnag.notify(e)
}

When reporting handled errors, it’s often helpful to send custom diagnostic data or to adjust the severity of particular errors.

For more information, see reporting handled errors.

Reporting native errors

BugSnag provides a handler for crashes originating in the native C++ Turbo Modules. Native crash detection is enabled by default as part of the basic configuration steps. If you wish to disable it, see the enabledErrorTypes configuration option.

Unhandled C++ exceptions thrown inside a Turbo Module are captured by Vega SDK and so will not be reported. However C++ exceptions from spawned threads will be reported.

Sending diagnostic data

Automatically captured diagnostics

BugSnag will automatically capture and attach the following diagnostic data:

  • Full stack traces.
  • Build information including version and release stage.
  • Device specification including runtime versions.

For more information see Automatically captured data.

Attaching custom diagnostics

It can often be helpful to attach application-specific diagnostic data to error reports. This can be accomplished by setting a callback which will be invoked before any reports are sent.

The following adds a map of data to the “company” tab on your dashboard for all captured events:

Bugsnag.start({
  onError: function (event) {
    event.addMetadata('company', {
      name: "Acme Co.",
      country: "uk"
    })
  }
})

You can also attach metadata that comes from native code in your iOS and Android projects using the addMetadata functions on the native BugSnag client.

For more information, see Customizing error reports.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your dashboard.

You can set the user information of an error report using the user configuration property when the Bugsnag client is started or via an onError callback.

Bugsnag.start({
  onError: function (event) {
    event.setUser('3', 'bugs.nag@bugsnag.com', 'Bugs Nag')
  }
})

If your user data is located in native code, you can also set this information using the setUser function on the native BugSnag client.

For more information, see Adding user data.

Logging breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

Automatically captured breadcrumbs

By default, BugSnag captures common events including:

  • Errors
  • HTTP requests
  • Console logs, warnings, and errors

Attaching custom breadcrumbs

You can use the leaveBreadcrumb method to log potentially useful events in your own applications:

Bugsnag.leaveBreadcrumb('Button clicked')

The SDK will keep track of the time and order of the breadcrumbs and show them on your dashboard. Additional data can also be attached to breadcrumbs by providing the optional metadata parameter.

For more information and examples for how custom breadcrumbs can be integrated, see Customizing breadcrumbs.

Session tracking

The BugSnag SDK tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases on your dashboard and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behavior can be disabled using the autoTrackSessions configuration option.

BugSnag will automatically report a session each time the app is launched or enters the foreground for the first time in 30 seconds.

For more information about controlling session tracking, see Capturing sessions.

Declaring feature flags and experiments

Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the BugSnag SDK. You can use the Features dashboard to identify whether these features have introduced errors into your app.

Bugsnag.addFeatureFlag('Checkout button color', 'Blue')
Bugsnag.addFeatureFlag('New checkout flow')

For more information, see Feature flags & experiments.

Next steps