Configuration options

In addition to configuring a Bugsnag client with an API key, it can also be configured with additional options using a Configuration object.

import { Client, Configuration } from "bugsnag-react-native";

const configuration = new Configuration(),
      bugsnag = new Client(configuration);

Configuration can be instantiated with an API key and has the following options.

apiKey

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

If not set, it will be loaded from your AndroidManifest.xml or Info.plist if available on Android and iOS respectively.

configuration.apiKey = "YOUR-API-KEY";

appVersion

The version of the application. By default, this information is populated from the underlying native app.

configuration.appVersion = "1.4.5";

autoCaptureSessions

By default, session information from your application will be automatically captured. Use this flag to disable all automatic reporting.

configuration.autoCaptureSessions = false;

If you want control over what is deemed a session, you can switch off automatic session tracking with the autoCaptureSessions option, and manage the session lifecycle using startSession(), stopSession() and resumeSession().

automaticallyCollectBreadcrumbs

By default we will automatically add breadcrumbs for common application events at the native layer, such as entering the background and system events. To disable this behavior, set this property to false:

configuration.automaticallyCollectBreadcrumbs = false;

autoNotify

By default, we will automatically notify BugSnag of any fatal exceptions in your application. If you want to stop this from happening, you can set autoNotify to false:

configuration.autoNotify = false;

beforeSendCallbacks

Before a report is sent to BugSnag, a callback can be registered to modify or reject any error report. By default, no callbacks are registered. To prevent a report from being sent, return false from the callback.

configuration.registerBeforeSendCallback(function(report, error) {
  if (report.errorClass === 'UnimportantDeviceError')
    return false;
});

Callbacks can also be removed individually:

configuration.unregisterBeforeSendCallback(callback_to_remove);

or all at once:

configuration.clearBeforeSendCallbacks();

clearUser

Removes customized user information from an error report which was set with setUser.

bugsnag.clearUser();

codeBundleId

Use this option to uniquely identify your JavaScript bundle if your app accepts JavaScript bundle updates, for example, when using CodePush.

When the appVersion remains the same but the JS bundle can change, BugSnag needs to be able to identify exactly which bundle is running in order to apply the correct source map.

As for the value itself, you can use whatever convention you want, as long as it is unique to your bundle. We suggest adding a revision suffix to the value of appVersion, such as 1.0-15. You will need to supply the same value when you upload your source maps. See the showing full stacktraces guide for more information.

configuration.codeBundleId = "1.0-15"

consoleBreadcrumbsEnabled

Leaves a breadcrumb when any console log method is called. This wraps .log(…), .debug(…), .info(…), .warn(…) and .error(…), creating a breadcrumb with the supplied arguments and severity level. The supplied arguments are passed on to the original log function.

Warning: this has an unfortunate side-effect in that all log messages will appear to originate from the BugSnag source rather than original location of the log call. As such the default for this option is false.

configuration.consoleBreadcrumbsEnabled = true

delivery

Delivery contains the configuration for how reports are sent to BugSnag. To change the endpoint used to send error reports and tracked sessions, change the delivery:

import { StandardDelivery } from "bugsnag-react-native";

configuration.delivery = new StandardDelivery("https://notify.example.com",
                                              "https://sessions.example.com");

You should also alter how the Android/iOS components are initialised, by passing a config parameter:

Configuration config = new Configuration("your-api-key-here");
config.setEndpoints("https://notify.example.com", "https://sessions.example.com");
BugsnagReactNative.startWithConfiguration(this, config);

BugsnagConfiguration *config = [BugsnagConfiguration new];
[config setEndpointsForNotify:@"http://notify.example.com"
                     sessions:@"http://sessions.example.com"];
[BugsnagReactNative startWithConfiguration:config];

This ensures that all requests are sent to the correct endpoint immediately after initialisation. Further documentation can be found in the Android and iOS guides.

handlePromiseRejections

By default, unhandled promise rejections are sent to BugSnag when not in dev mode. To change whether rejections are sent, set handlePromiseRejections:

configuration.handlePromiseRejections = false;

Promises can also be captured on an individual basis by using notify as the catch block:

new Promise(function(resolve, reject) {
  /* potentially failing code */
})
.then(function() { /* the promise resolved */ })
.catch(bugsnag.notify);

notifyReleaseStages

By default, we notify BugSnag of all exceptions that happen in your app. If you would like to change which release stages notify BugSnag of exceptions you can set the notifyReleaseStages property:

configuration.notifyReleaseStages = ['beta', 'production', 'testflight'];

releaseStage

In order to distinguish between errors that occur in different stages of the application release process, a release stage is sent to BugSnag when an error occurs. This is automatically configured by the notifier to be production, unless a development environment is detected. In which case it will be set to development. If the app is running on iOS by a TestFlight beta user, it will automatically be set to testflight.

If you wish to override this, you can do so by setting the releaseStage property manually:

configuration.releaseStage = 'beta';

resumeSession

Resumes a session which has previously been stopped, or starts a new session if none exists. If a session has already been resumed or started and has not been stopped, calling this method will have no effect. You should disable automatic session tracking via autoCaptureSessions if you call this method.

It’s important to note that sessions are stored in memory for the lifetime of the application process and are not persisted on disk. Therefore calling this method on app startup would start a new session, rather than continuing any previous session.

You should call this at the appropriate time in your application when you wish to resume a previously started session. Any subsequent errors which occur in your application will be reported to BugSnag and will count towards your application’s stability score.

bugsnag.resumeSession();

Also see startSession and stopSession.

setUser

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 BugSnag dashboard. To set an identifier for a user, use the setUser function:

bugsnag.setUser('1234', 'Jessica Jones', 'jess@example.com');

The user ID, email, and name are searchable on the BugSnag dashboard.

By default, if no user information is provided, BugSnag sends a device- and vendor-specific identifier assigned as the user id for each device.

To remove customized user information, use clearUser.

startSession

Starts tracking a new session. You should disable automatic session tracking via autoCaptureSessions if you call this method.

You should call this at the appropriate time in your application when you wish to start a session. Any subsequent errors which occur in your application will be reported to BugSnag and will count towards your application’s stability score. This will start a new session even if there is already an existing session; you should call resumeSession if you only want to start a session when one doesn’t already exist.

bugsnag.startSession();

Also see resumeSession and stopSession.

stopSession

Stops tracking a session. You should disable automatic session tracking via autoCaptureSessions if you call this method.

You should call this at the appropriate time in your application when you wish to stop a session. Any subsequent errors which occur in your application will still be reported to BugSnag but will not count towards your application’s stability score. This can be advantageous if, for example, you do not wish the stability score to include crashes in a background service.

bugsnag.stopSession();

Also see resumeSession and startSession.