React Native

On this page, we get you up and running with Sentry's React Native SDK, automatically reporting errors and exceptions in your application.

Install

Sentry captures data by using an SDK within your application’s runtime. These are platform-specific and allow Sentry to have a deep understanding of how your application works.

Add the @sentry/react-native dependency:

npm install --save @sentry/react-native

Linking

Since our SDK also supports native crashes, we need to link the SDK to your native projects.

Above react-native >= 0.60 you need to do:

npx @sentry/wizard -i reactNative -p ios android

cd ios
pod install

Since our SDK supports auto-linking and iOS relies on CocoaPods, you need to install the dependencies.

If you are running a project with react-native < 0.60 you still need to call react-native link.

react-native link @sentry/react-native

The link step or the sentry-wizard call will patch your project accordingly.

The Sentry Wizard will guide you through the process of setting everything up correctly. This has to be done only once, and the files created can go into your version control system.

The following changes will be performed:

• add the sentry-android package for native crash reporting on Android
• add the sentry-cocoa package for native crash reporting on iOS
• enable the Sentry Gradle build step for Android
• patch MainApplication.java for Android
• configure Sentry for the supplied DSN in your index.js/App.js files
• store build credentials in ios/sentry.properties and android/sentry.properties.

iOS Specifics

When you use Xcode, you can hook directly into the build process to upload debug symbols and source maps. However, if you are using bitcode, you will need to disable the “Upload Debug Symbols to Sentry” build phase and then separately upload debug symbols from iTunes Connect to Sentry.

Android Specifics

For Android, we hook into Gradle for the source map build process. When you run react-native link, the Gradle files are automatically updated. When you run ./gradlew assembleRelease source maps are automatically built and uploaded to Sentry.

If you have enabled Gradle's org.gradle.configureondemand feature, you'll need a clean build, or you'll need to disable this feature to upload the source map on every build.

To disable this feature, set org.gradle.configureondemand=false or remove it as its default value is disabled, do this in the gradle.properties file.

Configure

After you’ve completed setting up a project in Sentry, Sentry will give you a value which we call a DSN or Data Source Name. It looks a lot like a standard URL, but it’s just a representation of the configuration required by the Sentry SDKs. It consists of a few pieces, including the protocol, public key, the server address, and the project identifier.

To initialize the SDK, you need to call:

import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
});

The sentry-wizard will try to add it to your App.js

Verify

Great! Now that you’ve completed setting up the SDK, maybe you want to quickly test out how Sentry works. You can trigger a JS exception by throwing one in your application:

throw new Error("My first Sentry error!");

You can even try a native crash with:

Sentry.nativeCrash();

Capturing Errors

In most situations, you can capture errors automatically with captureException().

try {
  aFunctionThatMightFail();
} catch (err) {
  Sentry.captureException(err);
}

Release Health

Monitor the health of releases by observing user adoption, usage of the application, percentage of crashes, and session data. Release health will provide insight into the impact of crashes and bugs as it relates to user experience, and reveal trends with each new issue through the release details, graphs, and filters.

To benefit from the health data you must use at least version 1.4.0 of the React Native SDK, and enable the collection of release health metrics when initializing the SDK:

import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  enableAutoSessionTracking: true,
});

The SDK automatically manages the start and end of sessions when the application is started, goes to background, returns to the foreground, etc. By default, the session terminates once the application is in the background for more than 30 seconds. To change the timeout, use the option sessionTrackingIntervalMillis. For example:

import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  enableAutoSessionTracking: true,
  // Sessions close after app is 10 seconds in the background.
  sessionTrackingIntervalMillis: 10000,
});

For more details, see the full documentation on Release Health.

Identify the User

By default, we don't apply the user identification provided to the SDK via the API. Instead, we use the installation ID generated with the first use of the application. The ID doesn't contain any private or public data of your users or any public or shared data of their device.

More options

Under the hood the SDK relies on our Browser JavaScript SDK. That means that all functions available for JavaScript are also available in this SDK.