Raygun4Android is a library that you can easily add to your Android app, which will then allow you to transmit all exceptions to your dashboard. Installation is painless, and configuring your site to transmit errors and crashes takes less than five minutes, so you can start receiving error and crash reports right away.

Raygun4Android supports all devices with Gingerbread and newer installed (2.3/API v9). It can be added as a Gradle or Maven dependency, or manually adding the JAR to your project (if you use Ant or other build tools).



Ensure Maven Central is present in your project’s build.gradle:

allprojects {
    repositories {

Then add the following compile statements to the dependencies section in your module’s build.gradle:

dependencies {
    // Existing dependencies may go here
    implementation ''
    implementation 'com.squareup.okhttp3:okhttp:3.11.0'
    implementation ''

Then sync your project.


To your pom.xml, add:


In your IDE, build your project (or run mvn compile), then see the configuration section below.

With Ant, other build tools, or manually

Download the JAR for the latest version, as well as the Gson library and OkHttp3 library. Place both of these in a /lib folder in your project and add them to your project’s classpath.

Configuration and usage

In AndroidManifest.xml, add the following permissions beneath the manifest element:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

Inside the application element, add the following:

<meta-data android:name=""
           android:value="PASTE_YOUR_API_KEY_HERE" />

Replace the value in meta-data with your API key, available from your Raygun dashboard under Application settings.

Add the following imports to the starting activity of your application:


In a central activity method (such as onCreate()), call the following:


The above exception handler automatically catches & sends all uncaught exceptions. You can create your own or send from a catch block by calling RaygunClient.send() and passing in the Throwable.

A usage example is also available from the GitHub repository and Maven, in /sample-app.

ProGuard support

Raygun includes support for retracing your exception reports that have been obfuscated with ProGuard. This is achieved if you upload the relevant ProGuard mapping.txt file to your application in Raygun. Retracing is done automatically to each report as they come into Raygun so that they are presented to you with readable stacktraces.
All the documentation for ProGuard support can be found here.

Affected user tracking

Raygun supports tracking the unique users who encounter bugs in your apps.

By default the device UUID is transmitted. You can also add the currently logged in user’s data like this:

RaygunUserInfo user = new RaygunUserInfo();
user.setFullName("User Name");
user.setUuid("a uuid");

Any of the properties are optional, for instance you can set just isAnonymous by calling setAnonymous(). There is also a constructor overload if you prefer to specify all in one statement.

identifier should be a unique representation of the current logged in user - we will assume that messages with the same Identifier are the same user. If you do not set it, it will be automatically set to the device UUID.

If the user context changes, for instance on log in/out, you should remember to call SetUser again to store the updated username.

Version tracking

Set the versionName attribute on in your AndroidManifest.xml to be of the form x.x.x.x, where x is a positive integer, and it will be sent with each message. You can then filter by version in the Raygun dashboard.

Getting/setting/cancelling the error before it is sent

This provider has an onBeforeSend API to support accessing or mutating the candidate error payload immediately before it is sent, or cancelling the send outright. This is provided as the public method RaygunClient.setOnBeforeSend(RaygunOnBeforeSend), which takes an instance of a class that implements the RaygunOnBeforeSend interface. Your class needs a public onBeforeSend method that takes a RaygunMessage parameter, and returns the same.

By example:

class BeforeSendImplementation implements RaygunOnBeforeSend {
    public RaygunMessage onBeforeSend(RaygunMessage message) {
        Log.i("OnBeforeSend", "About to post to Raygun, returning the payload as is...");
        return message;

public class FullscreenActivity extends Activity {
    protected void onCreate(Bundle savedInstanceState) {
        // Initialize the activity as normal
        RaygunClient.setOnBeforeSend(new BeforeSendImplementation());

In the example above, the overridden onBeforeSend method will log an info message every time an error is sent.

To mutate the error payload, for instance to change the message:

public RaygunMessage onBeforeSend(RaygunMessage message) {
    Log.i("onBeforeSend", "Changing the message...");

    RaygunMessageDetails details = message.getDetails();
    RaygunErrorMessage error = details.getError();
    error.setMessage("Mutated message");

    return message;

To cancel the send (prevent the error from reaching the Raygun dashboard) by returning null:

public RaygunMessage onBeforeSend(RaygunMessage message) {
    Log.i("onBeforeSend", "Cancelling sending message to Raygun...");
    return null;

Source maps for Android

1. Optional one-time setup action: ensure there is a directory within your project for the JS bundle, e.g mkdir android/app/src/main/assets

2. Run this command from your project’s root directory to build your production app bundle with source maps:

react-native bundle --platform android --dev false --entry-file --bundle-output android/app/src/main/assets/main.jsbundle --assets-dest android/app/src/main/res --sourcemap-output android/app/src/main/assets/

3. Finally, run this command to upload your source map (replacing username, password and your_application_id):

curl \
-u "emailaddress:password" \
-F "url=file://reactnative.local/main.jsbundle" \
-F "file=@./android/app/src/main/assets/" \

Note that if you have placed or want to place your jsbundle file in a different location, you can set this location as the value for --sourcemap-output in step 2 and the file=@./ value in the step 3 cURL command.

Custom error grouping

You can override Raygun’s default grouping logic for Android exceptions by setting the grouping key manually in onBeforeSend

public RaygunMessage onBeforeSend(RaygunMessage message) {
    RaygunMessageDetails details = message.getDetails();

    return message;

Any error instances with a certain key will be grouped together. The example above will place all errors within one group (as the key is hardcoded to ‘foo’). The grouping key is a String and must be between 1 and 100 characters long. You should send all data you care about (for instance, parts of the exception message, stacktrace frames, class names etc) to a hash function (for instance MD5), then pass that to setGroupingKey.


See the GitHub repository for a full list of public initializing, attaching, sending and other methods.

Troubleshooting/Frequently Asked Questions

  • Is there an example project?

Yes! Clone our GitHub repository then load the sample-app project. It has been confirmed to run on the emulator for SDK >= 9, and physical devices (4.1.2).

  • Not seeing errors in the dashboard?

    Raygun4Android outputs Logcat messages - look for the ‘Exception Message HTTP POST result’ message - 403 will indicate an invalid API key, 400 a bad message, and 202 will indicate received successfully.

    Also, ensure that you have called attachExceptionHandler() after init(), or provided your own uncaught exception handler that sends using RaygunClient.

  • Environment data

    A selection of enironment data will be attached and available in the Environment tab in the dashboard, and more in the Raw tab. This data is gathered from android.os.Build - if you wish to see more data you can add them on the userCustomData object.

  • What happens when the phone has no internet connection?

    Raygun4Android will save the exception message to disk. When the provider is later asked to send another message it will check if the internet is now available, and if it is, send the cached messages. A maximum of 64 messages will be cached, then overwritten (using a LRU strategy).

    The provider now attaches the device’s network connectivity state to the payload when the exception occurs. This is visible under the Request tab in the Raygun dashboard.

The provider is open source and available at the Raygun4Android repository.