Android

Raygun4Android - Android Crash Reporting

The Raygun4Android provider

Raygun4Android is a library that you can easily add to your Android app, which will then allow you to transmit all exceptions to your Raygun.io 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).

Setup instructions

Gradle and Android Studio

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

allprojects {
    repositories {
        mavenCentral()
    }
}

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

dependencies {
    // Existing dependencies may go here
    compile 'com.google.code.gson:gson:2.1'
    compile 'com.mindscapehq.android:raygun4android:3.0.0'
}

Then sync your project. You may need to add the following specific imports to your class, where you wish to use RaygunClient:

import main.java.com.mindscapehq.android.raygun4android.RaygunClient;
import main.java.com.mindscapehq.android.raygun4android.messages.RaygunUserInfo;

Then see the configuration section below.

With Maven

To your pom.xml, add:

<dependency>
    <groupId>com.mindscapehq.android</groupId>
    <artifactId>raygun4android</artifactId>
    <version>[1.0.0,2.0.0)</version>
</dependency>

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 (if you do not already use it). Place both of these in a /lib folder in your project, add them to your project's classpath, then see below.

Configuration and Usage

  1. In your 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" />
  2. Inside the application element, add:

    <service   android:name="main.java.com.mindscapehq.android.raygun4android.RaygunPostService"
               android:exported="false"
               android:process=":raygunpostservice"/>
    <meta-data android:name="com.mindscapehq.android.raygun4android.apikey"
               android:value="PASTE_YOUR_API_KEY_HERE" />

    And replace the value in meta-data with your API key, available from your Raygun dashboard.

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

    RaygunClient.init(getApplicationContext());
    RaygunClient.attachExceptionHandler();

    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.

Unique user tracking

Raygun supports tracking the unique users who encounter bugs in your apps. You can transmit the current user who was affected by the exception by calling setUser(string) and passing in their user name or email address. A count of affected users will then appear in the error statistics in Raygun. If you provide an email address, you will see it on the error page in Raygun, and if they have an associated Gravatar you will see that too. If the user context changes, for instance on log in/out, you should remember to call setUser again to store the updated username. This feature is optional if you wish it disabled for privacy purposes.

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 {
    @Override
    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 {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // Initialize the activity as normal
        RaygunClient.init(getApplicationContext());
        RaygunClient.attachExceptionHandler();
        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

@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.

API

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

Troubleshooting

  • 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).

Documentation missing?

If we don't have documentation about your desired topic, send us a message and we'll create it for you.