Enhanced native integration

Additional integration steps for applications using React Native as a part of a larger native application

This documentation is for the original BugSnag React Native SDK. We recommend upgrading to the React Native package that is now part of the Universal JavaScript SDK using our Upgrade guide. Documentation for the latest release can be found here.

For apps which use React Native components as a part of a larger native application rather than the primary entry point, capturing native crashes which occur before React Native initializes is critical to understanding application stability.

The following steps ensure that all application crashes are detected and reported.

Native configuration

After completing the Installation and Basic configuration steps, all JavaScript errors and native crashes which occur once React Native has initialized will be reported. Any native crashes which occur before this point require additional steps.

Android native installation

Specify Google’s maven repository in android/build.gradle:

allprojects {
    repositories {
        maven { url 'https://maven.google.com' }

Set your API key in your AndroidManifest.xml:

<meta-data android:name="com.bugsnag.android.API_KEY"

You can find your API key in Project Settings from your BugSnag dashboard.

Initialize BugSnag in the onCreate function of MainApplication.java. Add the class if it does not yet exist.

// MainApplication class
public void onCreate() {
    SoLoader.init(this, /* native exopackage */ false);

Android NDK installation

If you want to capture C/C++ crashes from the Android NDK in addition to JavaScript and JVM crashes, enable NDK crash detection in your AndroidManifest.xml:

<application ...>
  <meta-data android:name="com.bugsnag.android.DETECT_NDK_CRASHES"

See the NDK installation guide for further integration steps if you compile your own native code.

iOS native installation

Set your API key in the primary Info.plist file for your app (generally ios/[app name]/Info.plist).


You can find your API key in Project Settings from your BugSnag dashboard.

Initialize BugSnag in the application:didFinishLaunchingWithOptions: method of your app delegate file (generally AppDelegate.m).

#import <BugsnagReactNative/BugsnagReactNative.h>
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [BugsnagReactNative start];

Further configuration

To customize the native initialization such as adding additional diagnostic data to reports, configuring the app release stage (such as beta, production or development), or identifying users, use startWithConfiguration instead of the start method to create and configure additional options.

Android example

Configuration config = new Configuration();
BugsnagReactNative.startWithConfiguration(this /* app context */, config);

iOS example

#import "BugsnagConfiguration.h"

BugsnagConfiguration *config = [BugsnagConfiguration new];
config.releaseStage = @"beta";
[BugsnagReactNative startWithConfiguration:config];

See the configuration options references for Android and iOS for more information.

Note: Options configured natively will be overridden by options set later during JavaScript initialization.

Session tracking

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

Sessions are captured and reported by default and BugSnag will report a session each time:

  • The React Native layer is initialized (generally app launch)
  • The app enters the foreground for the first time in 60 seconds

If this definition is incompatible with how your app stability is calculated, disable automatic session tracking when configuring the React Native JavaScript layer and use startSession when a new engagement with your app begins.

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

const configuration = new Configuration();
configuration.autoCaptureSessions = false;
const bugsnag = new Client(configuration);
// start a new sesssion from JavaScript:
// start a new session from native Android code:
// start a new session from native iOS code:
[BugsnagReactNative startSession];

Next steps

Once complete, continue the React Native integration guide to customize your integration, configure source maps, and learn how to report handled errors and promise rejections.