Docs Platforms React Native React Native Configuration
bugsnag.com Start Free Trial

Configuration options

BugSnag has many configuration options that can be set to customize the content of events and sessions and how they are sent.

These docs are for the @bugsnag/react-native package, which supports React Native v0.60 and above.

If you’re using the previous bugsnag-react-native package, we recommend upgrading to the latest release, unless you’re using a version of React Native older than 0.60. Documentation for bugsnag-react-native can be found on our legacy pages.

Setting configuration options

Most of BugSnag’s behavior in a React Native app is configured through the native BugSnag Cocoa and Android libraries that are linked to your app’s Android and iOS projects. This ensures that your desired behavior is present from startup and does not change when the JavaScript runtime starts.

See the Configuration options guides for iOS and Android for more information on setting these values using a AndroidManifest.xml, Info.plist or in configuration code.

Configuration options that are available for the React Native package can be set by creating a configuration object and passing it into Bugsnag.start:

Bugsnag.start({
  onError: function (event) {
    // ...
  }
})

Available options

addFeatureFlag

See featureFlags.

addMetadata

See metadata.

addOnBreadcrumb

See onBreadcrumb.

addOnError

See onError.

addOnSession

Add callbacks to modify or discard sessions before they are sent to BugSnag — see Capturing sessions for more information.

addOnSendError

See onError.

apiKey

The API key used for events sent to BugSnag.

appHangThresholdMillis

Enables reporting of non-fatal app hangs (see iOS guide) from which your app recovered before being terminated by the user or the iOS watchdog.

appType

If your app’s codebase contains different entry-points/processes, but reports to a single BugSnag project, you might want to add information denoting the type of process the error came from.

This information can be used in the dashboard to filter errors and to determine whether an error is limited to a subset of appTypes.

By default, BugSnag sets the appType to either “iOS” or “Android” for React Native apps.

appVersion

The version of the application. This is really useful for finding out when errors are introduced and fixed. Additionally BugSnag can re-open closed errors if a later version of the app has a regression.

When using @bugsnag/react-native-cli to upload source maps, appVersion is read from the AndroidManifest.xml or Info.plist so shouldn’t be overridden in code.

autoDetectErrors

By default, we will automatically notify BugSnag of any uncaught errors that we capture. Use this flag to disable all automatic detection.

autoTrackSessions

By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.

bundleVersion

The bundle version of the application.

When using @bugsnag/react-native-cli to upload source maps, bundleVersion is read from Info.plist so shouldn’t be overridden in code.

clearFeatureFlag

See featureFlags.

clearFeatureFlags

See featureFlags.

clearMetadata

Clears diagnostic metadata from being sent in subsequent events – see Customizing error reports for more information.

codeBundleId

A user-defined unique identifier for a JavaScript code deployment. There can be multiple deployments for a given appVersion. This is most useful when using a tool like App Center CodePush to update your app.

Bugsnag.start({ codeBundleId: "1.0-15" })

See the using CodePush guide guide for more information.

context

The “context” is a string that indicates what the user was doing when an error occurs and is given high visual prominence in the dashboard. Set an initial context that you want to send with events – see Setting context for more information.

Bugsnag.start({ context: 'ctx-id-1234' })

Context can also be set on the native configuration objects:

delivery

The Delivery implementation used to make network calls to the BugSnag Error Reporting and Sessions API.

This may be useful if you have requirements such as certificate pinning and rotation, which are not supported by the default implementation.

discardClasses

Allows you to specify which events should be automatically discarded based on their errorClass.

enabledBreadcrumbTypes

By default BugSnag will automatically add breadcrumbs for common application events whilst your application is running. Set this option to configure which of these are enabled and sent to BugSnag.

enabledErrorTypes

BugSnag will automatically detect different types of error in your application. Set this option if you wish to control exactly which types are enabled.

enabledReleaseStages

By default, BugSnag will be notified of events that happen in any releaseStage. Set this option if you would like to change which release stages notify BugSnag.

endpoints

By default we will send error reports to notify.bugsnag.com and sessions to sessions.bugsnag.com.

If you are using BugSnag On-premise you’ll need to set these to your Event Server and Session Server endpoints. If the notify endpoint is set but the sessions endpoint is not, session tracking will be disabled automatically to avoid leaking session information outside of your server configuration, and a warning will be logged.

featureFlags

Declare feature flag and experiment usage.

Bugsnag.start({
  featureFlags: [
    { name: 'Checkout button color', variant: 'Blue' },
    { name: 'Special offer', variant: 'Free Coffee' },
    { name: 'New checkout flow' },
  ]
})

launchDurationMillis

The amount of time (in milliseconds) after starting BugSnag that should be considered part of the app’s launch.

By default this value is 5000 milliseconds.

Events that occur during app launch will have their app.isLaunching property set to true.

Setting this to 0 will cause BugSnag to consider the app to be launching until Bugsnag.markLaunchCompleted() has been called.

logger

By default, log messages from the BugSnag JavaScript library are prefixed with [bugsnag] and output to the console (if the platform has a useful console object). You can supply your own logger instead, or switch off logging completely by setting logger: null.

If you supply a logger, it must have the following methods: debug, info, warn and error.

// switch off logging
Bugsnag.start({ logger: null })

// supply a custom logger
var myCustomLogger = {
  debug: function () {},
  info: function () {},
  warn: function () {},
  error: function () {}
}
Bugsnag.start({ logger: myCustomLogger })

For control of the log messages that are output by the native BugSnag libraries, see the logger configuration option in Android and the BSG_LOG_LEVEL define in iOS.

maxBreadcrumbs

Sets the maximum number of breadcrumbs which will be stored. Once the threshold is reached, the oldest breadcrumbs will be deleted.

By default, 100 breadcrumbs are stored; this can be amended up to a maximum of 500.

maxReportedThreads

Sets the maximum number of threads that will be captured and sent with an error event.

metadata

Set diagnostic metadata that you want to send with all captured events – see Customizing error reports for more information.

Bugsnag.start({
  metadata: {
    company: {
      name: 'Acme Co.',
      country: 'uk'
    }
  }
})

The top-level keys of the supplied map are section names that are displayed as tabs in the BugSnag dashboard.

Metadata can also be added to the native configuration objects and will be merged with metadata added in JavaScript:

onBreadcrumb

Add callbacks to modify or discard breadcrumbs before they are recorded — see Customizing breadcrumbs for more information.

Bugsnag.start({
  onBreadcrumb: function (breadcrumb) {
    if (breadcrumb.type === 'request') {
      if (breadcrumb.metadata.request === '/home') return false
      breadcrumb.metadata.request = stripQueryString(breadcrumb.metadata.request)
    }
  }
})

If log breadcrumbs are enabled, do not log within an onBreadcrumb callback to avoid an infinite loop.

Callbacks can also be added to the native configuration objects:

onCrashHandler

See onError.

onError

Add callbacks to modify or discard error events before they are sent to BugSnag — see Customizing error reports for more information.

Bugsnag.start({
  onError: function (event) {
    // Adjust event here
  }
})

Callbacks can also be added to the native configuration objects:

In iOS, the “on send” callback is executed in a subsequent launch to the crash. See the onCrashHandler option in iOS for information about writing a crash-time handler.

persistUser

Set whether or not BugSnag should persist user information between application launches.

By default this is set to false on Android and true on iOS.

projectPackages

Sets which package names BugSnag should consider as a part of the running application. We mark stacktrace lines as in-project if they originate from any of these packages and this allows us to improve the visual display of the stacktrace on the dashboard.

redactedKeys

Sets which values should be removed from any metadata before sending them to BugSnag. Use this if you want to ensure you don’t transmit sensitive data such as passwords and credit card numbers.

Any property whose key matches a redacted key will be filtered and replaced with [REDACTED]. By default, any key that contains “password” will be redacted. Be aware that if you set this configuration option, it will replace the default, so you may want to replace “password” in your own set if you want to filter that.

releaseStage

Allows you to distinguish between errors that happen in different stages of the application release process (development, production, etc).

sendLaunchCrashesSynchronously

Determines whether launch crashes should be sent synchronously whilst BugSnag starts.

If this option is enabled and the previous run terminated due to a crash during app launch, BugSnag will block the calling thread when it starts for up to 2 seconds while the crash report is sent.

This behavior is enabled by default.

sendThreads

Controls whether we should capture and serialize the state of all threads at the time of an exception.

session

To customize the configuration or delegate used when sending error reports, create a custom NSURLSession (Objective-C) / URLSession (Swift).

setUser

See user.

user

Set global user data that you want to send with all captured events – see Adding user data for more information.

Bugsnag.start({ 
  user: {
    id: '3',
    name: 'Bugs Nag',
    email: 'bugs.nag@bugsnag.com'
  }
})

User information can also be set on the native configuration objects:

telemetry

Internal errors

Internal errors are sent when an error is detected within BugSnag, for example when a crash report cannot be processed.

Usage

Usage telemetry helps us improve BugSnag by providing information on how you are configuring the SDK. We record:

  • when your config differs from the defaults
  • BugSnag functionality utilized

We collect only bools, ints and enums. We do not collect any information personal to you or your users. The information is sent as part of error events; there is no additional network call made.

versionCode

We’ll automatically pull the versionCode field from your app manifest file. If you’d like to override this you can set this option manually.

When using @bugsnag/react-native-cli to upload source maps, versionCode is read from the AndroidManifest.xml so shouldn’t be overridden in code.