1. Home
  2. Language Guides
  3. React Native
  4. Crash Reporting
  5. Installation

Installation

The Raygun4ReactNative provider allows you to automatically capture and report on unhandled runtime errors within your project by setting up event listeners for the JavaScript and platform-native (Android/iOS) sides of your project.

The provider also allows for manual error capturing using the RaygunClient.sendError(...) function. This allows you to customize the data being reported on and capture use cases specific to your project.

Installation

Installing and integrating the provider is simple and instantly begins working in the background so that you can get back to developing quickly.

"react-native": ^0.60.0

Navigate to your project and install the package and its peer dependencies using npm:

npm:

npm install raygun4reactnative
#Peer dependencies as well
npm install react react-native @react-native-async-storage/async-storage

yarn:

yarn add raygun4reactnative
#Peer dependencies as well
yarn add react react-native @react-native-async-storage/async-storage

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

Modify Podfile

platform :ios, '10.0'

then run

cd ios && pod install
# OR
npx pod-install ios

Modify the app's android/app/src/main/AndroidManifest.xml to include the following line to enable the background Crash Reporting Service & Real-time User monitoring


<application ...>
    ...
    <service
            android:name="com.raygun.raygun4android.services.CrashReportingPostService"
            android:exported="false"
            android:permission="android.permission.BIND_JOB_SERVICE"
            android:process=":crashreportingpostservice"
    />
    <service
            android:name="com.raygun.raygun4android.services.RUMPostService"
            android:exported="false"
            android:permission="android.permission.BIND_JOB_SERVICE"
            android:process=":rumpostservice"
    />
    ...
</application>

From here you can import the package into your project and initialize the RaygunClient using the API key displayed when you created your Raygun application (or can be viewed in the application settings).

import RaygunClient from 'raygun4reactnative';

const options: RaygunClientOptions = {
  apiKey: 'paste_your_api_key_here',
  enableCrashReporting: true
}

RaygunClient.init(options);

This will enable Raygun Crash Reporting and immediately start transmitting errors to your Raygun dashboard. See Advanced Initialisation Options to further customize your RaygunClient.

In order for Raygun4ReactNative to work with Expo you have to build and run you application using the expo CLI npx expo run:android and or npx expo run:ios. Using npm start or similar will not work as it does not generate the necessary native code that Raygun4ReactNative needs to function. A sign that you may be encountering this issue is if your program is throwing a DEVICE_ID is null exception.

Expo by default abstracts platform specific information from the user, as a result there is typically no Manifest file to edit. There are two main ways to get around this

  1. Using npx expo prebuild. This will create Android and iOS directories with the native code for your project, allowing you to modify the Android Manifest file.
  2. Using Config Plugins. These allow you to extend and modify your projects configuration file, including the AndroidManifest.xml file.

Once the RaygunClient has been initialized it will capture unhandled runtime errors within your project and transmit them to Raygun to be displayed on your Raygun dashboard.

The captured errors include JavaScript errors and promise rejections as well as native errors occurring on the Android/iOS platform side of your app (see Advanced Initialisation Options to disable native side error capturing).

On top of automatic Crash Reporting, you can implement manual error sending within your project to capture custom errors or unhandled exceptions. This is accomplished using the RaygunClient.sendError(...) function:

import RaygunClient, {CustomData} from "raygun4reactnative"

const error = new Error("Custom Message"); // This error can be any Error

RaygunClient.sendError(error);

You can also append Tags and Custom Data to manual crash reports (See Customize Manual Crash Reports).

Deploy Raygun into your production environment for best results, or raise a test exception. Once we detect your first error event, the Raygun app will automatically update.

Source Maps

Source map support for the Hermes Engine is untested and my not work as expected

React Native source maps can be generated manually using the React Native CLI

  1. Generate the source map and bundle Android
react-native bundle --dev false \
    --platform android \
    --entry-file index.js \
    --reset-cache \
    --bundle-output index.android.bundle \
    --sourcemap-output index.android.bundle.map \
    --minified false

iOS

react-native bundle --dev false \
    --platform ios \
    --entry-file index.js \
    --reset-cache \
    --bundle-output index.ios.bundle \
    --sourcemap-output index.ios.bundle.map \
    --minified false

What do these options mean?

  • --platform: The platform you are generating the source maps for. This will either be android or ios
  • --dev: If you are testing a development build set this to true, otherwise this should be false
  • --entry-file: The entry file into you application. This tends to be an index.js or an index.{platform}.js
  • --bundle-output: The output name of your bundled js, this is one of the files Raygun needs to be able to desymbolicate stack traces
  • --sourcemap-output: This is the output name of your sourcemap, this is the other important file that Raygun uses.
  • --minified: Set this to true if your bundle file is being minified, otherwise set this to false.
  1. Upload the source maps to Raygun Your source maps are now ready to be uploaded to Raygun! See the following guide for more information: Uploading source maps to Raygun

This provider is open source and available at the Raygun4ReactNative repository.

On this page: