Installation

Raygun4Android supports all devices that match the following requirements.

  • minSdkVersion 16+
  • compileSdkVersion 28

Ensure jcenter() or mavenCentral() are present in your project’s build.gradle:

allprojects {
    repositories {
        jcenter()
        mavenCentral()
    }
}

Then add the following to your module’s build.gradle:

dependencies {
    implementation 'com.raygun:raygun4android:4.0.0'
}

Initialisation

In your app’s AndroidManifest.xml, make sure you have granted Internet permissions. Beneath the <manifest> element add:

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

Inside the <application> element, add the following:

<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"/>
<meta-data android:name="com.raygun.raygun4android.apikey"
           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.

In a central activity (we suggest to use your common launch activity), call the following:

RaygunClient.init(application);
RaygunClient.enableCrashReporting();

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

For an actual usage example, check out the sample application in the app module of the GitHub repository.

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.

Documentation for ProGuard support can be found here.

Unique user tracking

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

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

String userIdentifier = "12345";

RaygunUserInfo user = new RaygunUserInfo(userIdentifier);
user.setFirstName("User");
user.setFullName("User Name");
user.setEmail("a@b.com");

RaygunClient.setUser(user);

Any of the properties but identifier and isAnonymous are optional. The property isAnonymous will be set to true if the identifier is null or an empty string. There is also a constructor overload if you prefer to specify all in one statement and a convenience constructor to only set an identifier.

The 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 user identifier. If a user logs out and you want to use the default device identifier again, just create an empty RaygunUserInfo object without an identifier. In this case isAnonymous will be set to true.

Version tracking

If you want track the version of your app with a crash report, you can do that in different ways:

  1. Set the versionName attribute on <manifest> in your AndroidManifest.xml to be of the form x.x.x.x, where x is a positive integer
  2. Set the version in the overloaded init method when initialising RaygunClient: public static void init(Application application, String apiKey, String version)
  3. Use the static setVersion method on RaygunClient class

The app’s version will then be sent with each message and you can then filter by version in the Raygun dashboard.

Modifying or cancelling error reports

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 CrashReportingOnBeforeSend interface. Your class needs a public onBeforeSend method that takes a RaygunMessage parameter, and returns the same.

By example:

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

public class SomeActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // Initialize the activity as normal
        ...
        // Initialize Raygun
        ...
        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:

@Override
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:

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

    return null;
}

Custom error grouping

You can override Raygun’s default grouping logic for Android exceptions by setting the grouping key manually in onBeforeSend (see above):

@Override
public RaygunMessage onBeforeSend(RaygunMessage message) {
    RaygunMessageDetails details = message.getDetails();
    details.setGroupingKey("foo");

    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.

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