Advanced Setup

Storing crash reports on the device

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:

RaygunClient.setMaxReportsStoredOnDevice(amount)

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


Version tracking

Raygun4Android supports tracking the version of your application that a crash occurred on in a few 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 applications’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.


Tags and custom data

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

Adding tags

Tags can be set using the following method:

RaygunClient.setTags(List tags)

Adding custom data

Custom data can be set using the following method:

RaygunClient.setCustomData(Map customData)

Manually sending errors

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)

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.

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

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());
    }
}

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