--- title: Monitor your React Native mobile app source: https://docs.newrelic.com/docs/mobile-monitoring/new-relic-monitoring-react-native/monitor-your-react-native-application --- Our New Relic React Native agent monitors your React Native mobile app and provides deep insights into your app's performance, errors, and user experience. Written in JavaScript, the React Native agent includes all New Relic mobile monitoring features we offer for native mobile apps. Once you install and configure the React Native agent, you'll be able to: - **Capture JavaScript errors** Identify and fix problems quickly. - **Track network requests:** See how your app interacts with the backend. - **Use distributed tracing:** Drill down into handled exceptions and find the root cause. - **Create custom events and metrics:** Understand how your users interact with your app. ![This is an image of a the Summary UI populated with React Native app data.](https://docs.newrelic.com/images/mobile_screenshot-full_react-native-summary.webp "UI Summary page") **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select an app) > Summary**: The React Native agent sends data to New Relic, where you can analyze crash data, network traffic, and other info on your hybrid app. The agent allows your team to understand the health of your hybrid app regardless of the platform. We empower your team to make more informed development choices by providing insight into Javascript errors, distributed tracing, network instrumentation, and more. > #### ⚠️ BREAKING CHANGE IN ERROR REPORTING (1.9.0) > > Starting with React Native agent version 1.9.0, JavaScript errors are reported through a new event type: `MobileJSError`. With the new Mobile Errors Protocol, React Native JavaScript errors are no longer stored in the `MobileHandledException` event type. > > If you use version 1.9.0 or higher, update any alert conditions and dashboards that query `MobileHandledException` for JavaScript-layer errors to use `MobileJSError` instead. For example, replace `SELECT count(*) FROM MobileHandledException WHERE platform = 'reactnative'` with `SELECT count(*) FROM MobileJSError`. Also update your build scripts to the latest version so [source maps upload correctly](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-monitoring-react-native/react-native-agent-js-error-reporting) for the new event type. ## Compatibility and requirements [#requirements] Before you install the React Native agent, ensure your app meets these requirements: - [iOS native requirements](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-ios/get-started/new-relic-ios-compatibility-requirements) - [Android native requirements](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/get-started/new-relic-android-compatibility-requirements) Native support levels are based on [React Native requirements](https://github.com/facebook/react-native#-requirements). ## (Recommended) Guided installation [#guided-install] To install the React Native agent, follow our [guided install](https://onenr.io/01wZvXb8Bw6), located directly in the UI. ## Manual installation [#manual-installation] If you need to install the agent manually, follow these steps: ### Add the React Native agent [#install] Run the following: ````shell npm i newrelic-react-native-agent ``` ```` ### Configure your application [#add-code] Open your `index.js` and add the following code to launch New Relic: ````js import NewRelic from "newrelic-react-native-agent"; import { name, version } from "./package.json"; import { Platform } from "react-native"; let appToken; if (Platform.OS === "ios") { appToken = "IOS-APP-TOKEN"; } else { appToken = "ANDROID-APP-TOKEN"; } const agentConfiguration = { // Android Specific // Optional:Enable or disable collection of event data. analyticsEventEnabled: true, // Optional:Enable or disable crash reporting. crashReportingEnabled: true, // Optional:Enable or disable interaction tracing. Trace instrumentation still occurs, but no traces are harvested. // This will disable default and custom interactions. interactionTracingEnabled: true, // Optional:Enable or disable reporting successful HTTP requests to the MobileRequest event type. networkRequestEnabled: true, // Optional:Enable or disable reporting network and HTTP request errors to the MobileRequestError event type. networkErrorRequestEnabled: true, // Optional:Enable or disable capture of HTTP response bodies for HTTP error traces, and MobileRequestError events. httpRequestBodyCaptureEnabled: true, // Optional:Enable or disable agent logging. loggingEnabled: true, // Optional:Specifies the log level. Omit this field for the default log level. // Options include: ERROR (least verbose), WARNING, INFO, VERBOSE, AUDIT (most verbose). logLevel: NewRelic.LogLevel.INFO, // iOS Specific // Optional:Enable/Disable automatic instrumentation of WebViews webViewInstrumentation: true, // Optional:Set a specific collector address for sending data. Omit this field for default address. collectorAddress: "", // Optional:Set a specific crash collector address for sending crashes. Omit this field for default address. crashCollectorAddress: "", // Optional:Enable or disable reporting data using different endpoints for US government clients fedRampEnabled: false, // Optional: Enable or disable offline data storage when no internet connection is available. offlineStorageEnabled: true, // iOS Specific // Optional: Enable or disable Background Reporting. backgroundReportingEnabled: false, // iOS Specific // Optional: Enable or disable to use our new, more stable event system for iOS agent. newEventSystemEnabled: false, }; NewRelic.startAgent(appToken, agentConfiguration); NewRelic.setJSAppVersion(version); AppRegistry.registerComponent(name, () => App); ``` ```` ### Copy/paste your app token(s) In the code above, paste your application token(s) into `appToken = ""` in the code above. If you deployed your hybrid app to both iOS and Android platforms, you'll need to add two separate tokens: one for iOS and one for Android. If you use the same app token, you won't be able to compare app performance between platforms. To copy/paste your app token(s): 1. Go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Mobile > (select your mobile app) > Settings**. 2. Copy the application token. In the code above, replace `` and/or `` with your app token. If you're deploying to both Android and iOS, repeat this process to get the second app token. ### (Android-native apps only) Install the Android agent [#android-install] 1. [Install the New Relic native Android agent](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile-android/install-configure/install-android-apps-gradle-android-studio). 2. Add the following changes to apply the Gradle plugin: If your project is using plugin DSL, make the following changes: In android/app/build.gradle: ````groovy plugins { id "com.android.application" id "kotlin-android" id "com.newrelic.agent.android" version "7.5.1" //<-- include this } ``` Or, if your project is older, you can use the legacy `newrelic` plugin ID by adding this snippet: ```groovy buildscript { ... repositories { ... mavenCentral() } dependencies { ... classpath "com.newrelic.agent.android:agent-gradle-plugin:7.5.1" } } ``` Apply the `NewRelic plugin` to the top of the `android/app/build.gradle` file: ```groovy apply plugin: "com.android.application" apply plugin: 'newrelic' // <-- include this ``` ```` ### (iOS-native apps only) Install the iOS agent [#ios-install] To ensure that the React Native agent is compatible with all iOS frameworks, install the New Relic iOS agent: ````shell npx pod-install ``` ```` ### Configure autolinking and rebuilding [#autolinking-and-rebuilding] The React Native New Relic library must be linked to your project and your application needs to be rebuilt. If you use React Native 0.60+, you automatically have access to autolinking, requiring no further manual installation steps. For Android: ````shell npx react-native run-android ``` For iOS: ```shell cd ios/ pod install --repo-update cd .. npx react-native run-ios ``` In order to make sure that the React Native application functioning properly, you can run following commands, and fatal JS errors will show up as a crash in the New Relic UI. For Android: ```shell npx react-native run-android --variant=release ``` For iOS: ```shell npx react-native run-ios --configuration Release ``` ```` ### (Optional) Integrate with Expo [#optional-expo-integration] After installing the React Native agent, integration with Expo is automatic with [bare workflow](https://docs.expo.dev/introduction/managed-vs-bare/#bare-workflow) but requires some extra steps for [custom managed workflow](https://docs.expo.io/workflow/customizing/) via [config plugins](https://docs.expo.io/guides/config-plugins/). To set up [custom managed workflow](https://docs.expo.dev/introduction/managed-vs-bare/#bare-workflow), after installing our package, add the config plugin to the plugins array of your `app.json` or `app.config.js`. ````json { "name": "my app", "plugins": ["newrelic-react-native-agent"] } ``` For the managed work flow, use the `expo prebuild --clean` command as described in the [Adding custom native code](https://docs.expo.dev/workflow/customizing/) guide to rebuild your app with the plugin changes. If this command is not running, you'll get errors when starting the New Relic agent. For Expo Go users, the agent will require using native code. Since Expo Go does not support sending custom native code over-the-air, you can follow Expo's documentation on [how to use custom native code in Expo Go](https://docs.expo.dev/bare/using-expo-client/). If you build with [EAS Build](https://docs.expo.dev/build/introduction/), see [Configure the React Native agent for EAS Build](/docs/mobile-monitoring/new-relic-monitoring-react-native/configure-eas-build-react-native) to also set up automatic source map, dSYM, and Android mapping file upload. ```` ### (Optional) Configure instrument routing and navigation To instrument routing and navigation for your React Native apps: **React Navigation** - For [react-navigation v5](https://github.com/react-navigation/react-navigation): Set the `onStateChange` to `NewRelic.onStateChange` in your `NavigationContainer` as follows: ```javascript ``` - For react-navigation v4 and below: Set the `onNavigationStateChange` to `NewRelic.onNavigationStateChange` in your `App` wrapper as follows: ```javascript export default () => ( ); ``` **React Native Navigation** For [react-native-navigation](https://github.com/wix/react-native-navigation), you can either: Register `NewRelic.componentDidAppearListener` listener using: ````javascript Navigation.events().registerComponentDidAppearListener( NewRelic.componentDidAppearListener ); ``` Or, you can report your screen changes manually using the following API: ```js var params = { screenName: "screenName", }; NewRelic.recordBreadcrumb("navigation", params); ``` ```` ## Customize the agent instrumentation [#mobile-sdk] Need to customize your agent instrumentation? Our public mobile SDK API methods let you collect custom data, configure default settings, and more. The following customizations are available for the React Native agent. | If you want to... | Use this method | | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Record breadcrumbs to track app activity that may be helpful for troubleshooting crashes. | [Record breadcrumbs](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-breadcrumb) | | Track a method as an interaction. | [Start interactions](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/start-interaction) [Stop interactions](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/stop-interaction) | | Record custom metrics. | [Record custom metrics](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-metrics/) | | Record custom errors. | [Record custom errors](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-errors/#react) | | Record custom attributes and events. | There are several ways to report custom attributes and events: - [Record custom attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute) - [Increment session attribute count](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/increment-session-attribute-count) - [Remove an attribute](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/remove-attribute) - [Remove all attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/remove-all-attributes) - [Record custom events](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-events) - [Set the maximum size of an event pool](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-max-event-pool-size) - [Set maximum time the agent stores events in memory](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-max-event-buffer-time) - [Get a current session's ID](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/current-session-id) - [Set a custom user ID to associate with events and attributes](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-custom-user-id) For more about which would be the best method to use and why, see [Report mobile monitoring custom events and attributes](https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/report-mobile-monitoring-custom-events-attributes/). | | Track custom network requests and failures. | [Track HTTP requests](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/network-request-success) [Track failing HTTP requests](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/network-request-failures) | | Shut down the agent. | [Shut down the agent](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/shut-down-agent) | | Enable/disable default mobile monitoring settings. | [Enable/disable monitoring features](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/configure-settings) | | Run a test crash report. | [Test crash reporting](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/test-crash-reporting) | ## Troubleshoot JavaScript errors [#javascript-errors] **React Native agent version 1.9.0 and higher** JavaScript errors and promise rejections are recorded as `MobileJSError` events. You can see the event trail, attributes, and stack trace for each JavaScript error in New Relic. You can also find these errors by running this query: ````sql SELECT * FROM MobileJSError SINCE 24 hours ago ``` ```` **React Native agent version 1.2.0 to 1.8.x** JavaScript errors and promise rejections can be seen in the `Handled Exceptions` tab in New Relic. You will be able to see the event trail, attributes, and stack trace for each JavaScript error recorded. You can also find these errors by running this query: ````sql SELECT * FROM MobileHandledException SINCE 24 hours ago ``` ```` **React Native agent version 1.1.0 and lower** The React Native agent creates custom events for JavaScript errors and reports them to New Relic. In the UI, you can track these JavaScript error events with a custom dashboard. To create a custom dashboard: 1. Go to [one.newrelic.com](https://one.newrelic.com/all-capabilities). 2. Click **Query your data**. 3. Run this query: ```sql SELECT * FROM `JS Errors` ``` 4. Click **Add to dashboard**. ![This is an image of a sample query in the Query builder.](https://docs.newrelic.com/images/mobile_screenshot-full_query-example.webp "Query your data") **[one.newrelic.com](https://one.newrelic.com/all-capabilities) > Query your data**: Use the **Query builder** to create a custom dashboard for tracking JavaScript errors from your React app. If you need help getting started with dashboards, see [Introduction to dashboards](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/introduction-dashboards/#get-started). ## JavaScript console logs [#javascript-logs] **React Native agent version 1.4.1 and higher** Starting with React Native agent version 1.4.1, JavaScript console logs are reported as log events. You can view them in the [Logs UI](https://docs.newrelic.com/docs/logs/ui-data/use-logs-ui) or query them by going to **[one.newrelic.com](https://one.newrelic.com/all-capabilities) > Query your data** and running: ````sql SELECT * FROM Log SINCE 24 HOURS AGO ``` ```` **React Native agent version 1.4.0 and lower** To view JavaScript console logs in New Relic, go to **[one.newrelic.com](https://one.newrelic.com/all-capabilities) > Query your data** and add this query to find those JavaScript console logs: ````sql SELECT * FROM consoleEvents SINCE 24 HOURS AGO ``` ````