Migration

From 2.4.x to 2.5.x

The breaking changes are relevant only to Android. There are no breaking changes for other platforms.

Android Specific Changes

Sentry React Native version 2.5.0 depends on Sentry Android 5.0.0. Please refer to the Android migration guide for Android-specific changes.

Settings.Secure.ANDROID_ID has been removed and replaced with a randomly-generated installationId. This may affect the number of unique users displayed on the the Issues page and Alerts. If you always set a custom user using Sentry.setUser(customUser), the behavior has not changed. While you don't have to make any update, if you want to maintain the old behavior, use the following code snippet which makes use of the react-native-device-info library.

Copied
import { Platform } from "react-native";
import DeviceInfo from "react-native-device-info";

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

Sentry.init({
  // ...
});

// Only add the event processor on Android
if (Platform.OS === "android") {
  Sentry.addGlobalEventProcessor(event => {
    // Get the ANDROID_ID
    const id = DeviceInfo.getUniqueId();

    // If the user does not exist, set the id to be the unique id.
    if (!event.user) {
      event.user = { id };
    }

    return event;
  });
}

React Navigation Instrumentation from <2.3.0

We changed the initialization method for the React Navigation V5 routing instrumentation to avoid a potential issue when using linking. You now register the navigation container inside the onReady prop passed to the NavigationContainer.

From:

Copied
// Old Functional Component Example
const App = () => {
  const navigation = React.useRef();

  React.useEffect(() => {
    routingInstrumentation.registerNavigationContainer(navigation);
  }, []);

  return <NavigationContainer ref={navigation}>...</NavigationContainer>;
};

// Old Class Component Example
class App extends React.Component {
  navigation = React.createRef();

  componentDidMount() {
    routingInstrumentation.registerNavigationContainer(navigation);
  }

  render() {
    return <NavigationContainer ref={this.navigation}>...</NavigationContainer>;
  }
}

To:

Copied
// Functional Component Example
const App = () => {
  const navigation = React.useRef();

  return (
    <NavigationContainer
      ref={navigation}
      onReady={() => {
        // Register the navigation container with the instrumentation inside onReady
        routingInstrumentation.registerNavigationContainer(navigation);
      }}
    >
      ...
    </NavigationContainer>
  );
};

// Class Component Example
class App extends React.Component {
  navigation = React.createRef();

  render() {
    return (
      <NavigationContainer
        ref={this.navigation}
        onReady={() => {
          // Register the navigation container with the instrumentation inside onReady
          routingInstrumentation.registerNavigationContainer(navigation);
        }}
      >
        ...
      </NavigationContainer>
    );
  }
}

From 1.x to 2.x

Sentry's most recent version of our React Native SDK enables release health tracking and native stack traces by default.

This version of the SDK uses the envelope endpoint. If you are using self-hosted Sentry, the SDK requires Sentry version 20.6.0 and above. If you are using our SaaS product (sentry.io), no changes or actions needed.

iOS/MacOS

While the migration does not introduce breaking changes for iOS/MacOS on the React Native side, we recommend running pod install after the upgrade.

On iOS/MacOS, we now cache events in envelopes on the disk. As a result, you might lose a few cached events during the migration. Due to the effort involved, the migration from 5.x to 6.x does not move these few cached events into envelopes.

Android

If you are on React Native <0.60, you will need to update this line in your MainApplication.java:

From (earlier version):

Copied
import io.sentry.RNSentryPackage;

New:

Copied
import io.sentry.react.RNSentryPackage;

Other than the one line change noted above, the migration should not cause breaking changes on the React Native side.

From 0.x to 1.x

If you are upgrading from an earlier version of Sentry's React Native SDK, you should unlink the package to ensure the generated code is updated to the latest version:

Copied
react-native unlink react-native-sentry

After that remove react-native-sentry from your package.json:

Copied
npm uninstall react-native-sentry --save
# or
yarn remove react-native-sentry

From there you can follow the standard installation instructions for @sentry/react-native.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").