Track App Crashes

Information about how crashes are tracked and best practices to handle false crashes.

App crashes are tracked as part of lifecycle metrics. To track crashes, add the library to your project and implement lifecycle.

When lifecycle metrics are implemented, a call is made to Config.collectLifecycleData in the OnResume method of each activity. In the onPause method, a call is made to Config.pauseCollectingLifeCycleData.

Inside of the pauseCollectingLifeCycleData, a flag is set to indicate a graceful exit. When the app is relaunched or resumed, collectLifecycleData checks this flag for a graceful exit. If the app did not exit successfully (as determined by the flag status), an a.CrashEvent context data is sent with the next call and a crash event is reported.

To ensure accurate crash reporting, you must call the pauseCollectingLifeCycleData inside of the onPause method of each activity. To understand why this is essential, it is helpful to understand the Android activity lifecycle:

(See for more information on Android activity lifecycle. The Android lifecycle image that appears on this page was created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License)

What can cause a false crash to be reported?

  1. If you are debugging using Android Studio (or another IDE), re-launching the app from the IDE while the app is in the foreground causes a crash.

    Note: You can avoid this crash by backgrounding the app prior to relaunching from the IDE.
  2. If the last foreground Activity of your app is backgrounded and does not call Config.pauseCollectingLifecycleData(); in onPause, and your app is manually closed or killed by the OS, the next launch results in a crash.

How should Fragments be handled?

Fragments have application lifecycle events similar to Activities. However, a Fragment cannot be active without being attached to an Activity. Therefore, we want to rely on the lifecycle events for the containing activities to run our code against. DO NOT call collectLifecycleData() or pauseCollectingLifecycleData() in your Fragments.

(Optional) Implement Activity lifecycle callbacks

Starting with API Level 14, Android allows global lifecycle callbacks for activities. See the Android Developers Guide for more information.

You can use these callbacks to ensure all of your Activities call collectLifecycleData() and pauseCollectingLifecycleData() properly. You need to only add this code in your main Activity and any other Activity into which your app may be launched:

public class MainActivity extends Activity {
    protected void onCreate(Bundle savedInstanceState) {
        getApplication().registerActivityLifecycleCallbacks(new Application.ActivityLifecycleCallbacks() {
            public void onActivityResumed(Activity activity) {
            public void onActivityPaused(Activity activity) {				
            // the following methods aren't needed for our lifecycle purposes, but are required to be implemented
            // by the ActivityLifecycleCallbacks object
            public void onActivityCreated(Activity activity, Bundle savedInstanceState) {}
            public void onActivityStarted(Activity activity) {}
            public void onActivityStopped(Activity activity) {}
            public void onActivitySaveInstanceState(Activity activity, Bundle outState) {}
            public void onActivityDestroyed(Activity activity) {}

If you want to send additional context data with your lifecycle call via Config.collectLifecycleData(Activity activity, Map<String, Object> contextData), you must override the onResume method for that Activity and make sure that you call super.onResume() after calling collectLifecycleData manually.

protected void onResume() {
    HashMap<String, Object> cdata = new HashMap<>();
    cdata.put("someKey", "someValue");
    Config.collectLifecycleData(this, cdata);

Parent topic: Analytics