Advanced Setup

If the device can't connect, Raygun4Android will save the crash report to disk. At the next start of the application (and therefore the provider) 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 and you can change the amount by calling:


note: You cannot increase the amount beyond the maximum of 64. If you decrease the amount, any currently stored cached reports will be deleted.

Raygun4Android supports tracking the version of your application that a crash occurred on in a few different ways.

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.

Set the version in the overloaded init method when initialising the Raygun client.

RaygunClient.init(this, "YOUR_RAYGUN_API_KEY", "YOUR_APP_VERSION");

Use the static setVersion method on RaygunClient class.


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

tip: Read more information about filtering in Crash Reporting here.

Raygun supports attaching tags and custom data for specific errors. You can read more about Tags and custom data here.

Tags can be set using the following method:

RaygunClient.setTags(List tags)

Custom data can be set using the following method:

RaygunClient.setCustomData(Map customData)

Raygun4Android automatically captures and send all unhandled exceptions. However, there may be times you will want to send custom handled errors manually. The following methods are available for sending errors manually:

RaygunClient.send(Throwable throwable)

// Include a list of tags with the error.
// This is in *addition* to any tags set via the `setTags` method
RaygunClient.send(Throwable throwable, List tags)

// Include a list of tags and custom data with the error. 
// This is in *addition* to any tags or custom data set by the `setTags` and `setCustomData` methods
RaygunClient.send(Throwable throwable, List tags, Map customData)

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.

Override the onBeforeSend method and log an info message every time an error is sent.

class BeforeSendImplementation implements CrashReportingOnBeforeSend {
    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 {
    protected void onCreate(Bundle savedInstanceState) {
        // Initialize the activity as normal
        // Initialize Raygun
        RaygunClient.setOnBeforeSend(new BeforeSendImplementation());

Mutate the error payload, changing 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;

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

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.

With breadcrumbs, you can attach 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.

The easiest way to record a breadcrumb is by calling the recordBreadcrumb method on the Raygun client:

RaygunClient.recordBreadcrumb("User entered screen");

Alternatively you can provide more details by constructing a RaygunBreadcrumbMessage object and passing it to the Raygun client:

WeakHashMap customData = new WeakHashMap<String, Object>();
customData.put("someKey", "someValue");

RaygunBreadcrumbMessage crumb = new RaygunBreadcrumbMessage.Builder("Entered another screen")


For debugging purposes the provider will log information alongside the system messages. These messages can be viewed with Logcat under the tag Raygun4Android.

Raygun4Android uses Timber for internal logging. This requires some language features that are only available with Java 8. Make sure that your project using the library has set compilation compatibility to Java 8. Google's documentation has more information on the reasons and implications of this requirement.

android {  
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8

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