Features

The Raygun4ReactNative provider offers a range of features to further customize the Crash Reporting experience for your project's specifications.


The RaygunClient offers some advanced features during initialization to configure the Crash Reporting experience. When you initialise the RaygunClient you will pass a RaygunClientOptions object to specify how your client will function:

export type RaygunClientOptions = {
  apiKey?: string;
  version?: string;
  enableCrashReporting?: boolean;
  disableNativeCrashReporting?: boolean;
  enableRealUserMonitoring?: boolean;
  disableNetworkMonitoring?: boolean;
  customCrashReportingEndpoint?: string;
  customRealUserMonitoringEndpoint?: string;
  onBeforeSendingCrashReport?: BeforeSendHandler;
  ignoredURLs?: string[];
};

This structure offers a wide range of customization options. Crash Reporting related customization is outlined below (See here for Real User Monitoring related advanced initialisation options).

You can specify the version of your application by providing a version identifier string during initialization and this will be reflected on your Raygun Dashboard.

const options: RaygunClientOptions = {
  enableCrashReporting: true,
  version: "_YOUR_PROJECT_VERSION_"
};

RaygunClient.init(options);

If you do not wish to receive native Android/iOS errors then you can disable native Crash Reporting on initialization.

const options: RaygunClientOptions = {
  enableCrashReporting: true,
  disableNativeCrashReporting: true
};

RaygunClient.init(options);

If you want to reroute the crash reports being captured to a custom endpoint you can provide a URL for crash reports to be transmitted to instead of Raygun.

const options: RaygunClientOptions = {
  enableCrashReporting: true,
  customCrashReportingEndpoint: "https://myCrashReportingEndpoint.com"
};

RaygunClient.init(options);

This options allows you to define some intermediate logic to be applied to each crash report before it is sent to Raygun. The function provided must take a CrashReportPayload type as its only argument and return a CrashReportPayload or null:

//Applying some transformation function to each crash report
const options1: RaygunClientOptions = {
  enableCrashReporting: true,
  onBeforeSendingCrashReport: (crashReport : CrashReportPayload) => FOO(crashReport)
};

//Culling crash reports based on tags
const options2: RaygunClientOptions = {
  enableCrashReporting: true,
  onBeforeSendingCrashReport: (crashReport : CrashReportPayload) => {
    if(crashReport.Details.Tags && crashReport.Details.Tags.includes("Ignore_Me")) {
      return null;
    }
    return crashReport;
  }
};

RaygunClient.init(options1);

If you provide null as the BeforeSendingCrashReport attribute then no crash reports will sent.


Breadcrumbs can be implemented to create an accurate trail of events through your system leading up to the moment a report was generated. This helps to gain more insight into why the application crashed when it did, making prioritization of fixes much easier:

type Breadcrumb = {
  message: string;
  category?: string;
  level?: 'debug' | 'info' | 'warning' | 'error';
  customData?: CustomData;
  timestamp?: number;
};

You can Record Breadcrumbs throughout the user experience in your application using the RaygunClient.recordBreadcrumb(...) function:

const breadcrumb1: Breadcrumb = {
  message: "_YOUR_MESSAGE_",
};
RaygunClient.recordBreadcrumb(breadcrumb1);

//Extra optional customizations
const breadcrumb2: Breadcrumb = {
  message: "_ANOTHER_MESSAGE_",
  category: "_YOUR_CATAGORY_STRING_",
  level: "debug",
  customData: {"_SOME_KEY_": "_SOME_DATA_"}
};
RaygunClient.recordBreadcrumb(breadcrumb2);

Then if you want to read your current breadcrumbs from within your app you can access them using the RaygunClient.getBreadcrumbs() function:

RaygunClient.recordBreadcrumb({message: "MY BREADCRUMB"});
console.log(JSON.stringify(RaygunClient.getBreadcrumbs()));
//Prints: ["{\"0\":{\"message\":\"MY BREADCRUMB\"}}"]

And finally you can clear your breadcrumbs so that they will not be applied to any future crash reports using the RaygunClient.clearBreadcrumbs() function:

RaygunClient.clearBreadcrumbs();

Tags allow you to attach an array of strings to each report to provide more context. Tags are displayed on the Raygun dashboard so that errors can be better categorized and filtered.

Sometimes you may want global tags to be sent with all errors regardless of if they are manually or automatically reported. This can be done using the RaygunClient.setTags(...) function to attach the specified tags to every crash report sent from that point onwards. You can also access the current global tags using the RaygunClient.getTags() method.

RaygunClient.setTags("_YOUR_FIRST_TAG_", "_ANOTHER_TAG_");
console.log(RaygunClient.getTags()); //["_YOUR_FIRST_TAG_", "_ANOTHER_TAG_"]

These global tags are shared between Crash Reporting reports and Real User Monitoring timing events.

The provider also allows you to append unique tags data to manual crash reports created using the RaygunClient.sendError(...) function (See Customizing Manual Crash Reports).


When crash reports are sent the RaygunClient will automatically identify the user being affected as an anonymous User object:

type User = {
  identifier: string;
  isAnonymous?: boolean;
  email?: string;
  firstName?: string;
  fullName?: string;
  uuid?: string;
};

However, if you want to customize this data, you can using the RaygunClient.setUser(...) function to specify more information about each user. The current user can also be accessed using the RaygunClient.getUser() function.

const user: User = {
  identifier: 'Ronald Raygun',
  isAnonymous: false,
  email: 'ronald@raygun.com',
  firstName: 'Ronald',
  fullName: 'raygun',
  uuid: 'uuid'
}

RaygunClient.setUser(user);
console.log(RaygunClient.getUser()); 
//{"email": "ronald@raygun.com", "firstName": "Ronald", "fullName": "raygun", "identifier": "Ronald Raygun", "isAnonymous": false, "uuid": "uuid"}

// Alternatively
RaygunClient.setUser({identifier: "_NEW_IDENTIFIER_"});
console.log(RaygunClient.getUser()); 
//{"identifier": "_NEW_IDENTIFIER_"}

// Reset to an anonymous user
RaygunClient.setUser(null);
console.log(RaygunClient.getUser()); 
//{"identifier": "_UNIQUE_DEVICE_GUID_", "isAnonymous": true}

This user value is shared between Crash Reporting reports and Real User Monitoring timing events.


Any other data you want to attach to your crash reports can be achieved using custom data:

type BasicType = string | number | boolean;

type CustomData = {
  [key: string]: BasicType | CustomData | BasicType[] | CustomData[];
};

Sometimes you may want to create global custom data to be sent with all errors regardless of if they are manually or automatically reported. This can be done using the RaygunClient.setCustomData(...) function to ensure that all crash reports from that point on will contain that custom data. You can also use RaygunClient.getCustomData() to access the current global custom data.

const customData: CustomData = {
  "Key_1": "Value",
  "Key_2": 2,
  "Key_3": ["Value", "Another Value", true],
  "Key_4": [42, 65],
  "Key_5": {"Sub_Key_1" : "Sub_Value_1"}
};
RaygunClient.setCustomData(customData);

//This crash report will now contain all of the custom data above
RaygunClient.sendError(new Error("New Error"));

console.log("Current Custom Data: " + RaygunClient.getCustomData());

note: We do allow circular dependencies with custom data so be careful not to create excessive recursion by self containing (e.g const foobar: CustomData = {"Uh Oh": foobar}; etc).

The provider also allows you to append unique custom data to manual crash reports created with the RaygunClient.sendError(...) function (See Customizing Manual Crash Reports).


If your user loses connection to Raygun while using your application the errors they create will be stored locally on the device to be resent once connection is re-established. The provider allows you to set the size of this cache using the RaygunClient.setMaxReportsStoredOnDevice(...) function:

const n : number = 32; //Where (0 < n < 64)
RaygunClient.setMaxReportsStoredOnDevice(n); 

If the cache size is reduced then the provider will delete any excess cached reports starting with the newest.


When you manually send a crash report you can append Tags and Custom Data which will be specific to that report. This is done using the ManualCrashReportDetails type.

type ManualCrashReportDetails = {
  customData?: CustomData,
  tags?: string[]
}

This data can be passed as an argument when calling the RaygunClient.sendError(...) method:

const customData: CustomData = {"Key": "Value"};
const tags: string[] = ["Error", "Caught", "Test"];

const details_1: ManualCrashReportDetails = {customData: customData, tags: tags};
RaygunClient.sendError(new Error("Manual crash report containing both"), details_1);

const details_2: ManualCrashReportDetails = {customData: customData};
RaygunClient.sendError(new Error("Manual crash report containing custom data"), details_2);

const details_3: ManualCrashReportDetails = {tags: tags};
RaygunClient.sendError(new Error("Manual crash report containing tags"), details_3);

This data will not be shared with other crash reports to allow you to better distinguish the manual data you are capturing.


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