Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Library to report unhandled exceptions in android projects

branch: master
README.mkdn

Android Error-Reporter

Integration

To integrate Android Error-Reporter just follow four simple steps:

  1. Download android-error-reporter.jar and add it to your build path

  2. Inherit from one of the base classes Reporting* (e.g. ReportingActivity, ReportingService or ReportingIntentService) or register your context in every onCreate() of your activity or context, e.g.:

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ExceptionReporter reporter = ExceptionReporter.register(this);
        super.onCreate(savedInstanceState);
    }
    
  3. Add the ExceptionReportService to your AndroidManifest.xml (within the <application/> node):

    <service
        android:name="de.quist.app.errorreporter.ExceptionReportService"
        android:process=":exceptionReporter"/>
    
  4. Configure the target URL where to send the errors by adding the following line to your AndroidManifest.xml (within the <application/> node):

    <meta-data
        android:name="de.quist.app.errorreporter.targetUrl"
        android:value="http://foo.bar/error.php" />
    

Usage

Report catched exceptions

Unhandled exceptions are automatically handled by the ExceptionReportService. You can also report catched exceptions by calling exceptionHandler.reportException(thread, e) or exceptionHandler.reportException(thread, e, extraMessage) on the ExceptionReporter object returned by ExceptionReporter.register(context). If your activity/service inherits from one of the supplied base classes (de.quist.app.errorreporter.Reporting*), you can access the ExceptionReporter via getExceptionReporter().

User approved error reporting

By default errors are sent to the server automatically without asking the user for permission. This can be changed by adding the ExceptionReportActivity to your AndroidManifest.xml. To do so, add the following line:

<activity
    android:name="de.quist.app.errorreporter.ExceptionReportActivity"
    android:process=":exceptionReporter"
    android:theme="@android:style/Theme.NoDisplay"/>        

The exception reporter will automatically detect the defined activity and instead of automatically sending the report a notification is created which will ask the user for permission to send the notification when clicked. You have full control over the texts and icons of both, the notification and the report-dialog. All resources can be specified by adding meta-data tags to your AndroidManifest.xml (within the <application/> node) which reference to a string/drawable in their android:resource-attribute, e.g.:

<meta-data
    android:name="de.quist.app.errorreporter.dialogMessageHint"
    android:resource="@string/error_reporting_message_hint"/>

See attributes de.quist.app.errorreporter.dialog* and de.quist.app.errorreporter.notification* in the section Configuration for more information abouth how to control the notification and dialog.

Retry-Rules

The ExceptionReportService tries to send the error to the URL specified in your AndroidManifest.xml. If it fails it retries with an exponential back-off. The default configuration will increase the back-off up to 2^12 sec (about 1h8m) and will retry it 17 times until it gives up (this will result in a total time span of 1s+2s+4s+8s+...2^12 s*5=8h). You can change these values by adding specific meta-data nodes to your AndroidManifest.xml (see Configuration)

Configuration

You can add the following name/value pairs as a meta-data node to your AndroidManifest.xml (within the <application/> node).

All names need to have de.quist.app.errorreporter. as a prefix!!!:

Name Type Default Description
maximumRetryCount int 17 Maximum number of tries to send an error report
maximumBackoffExponent int 12 Maximum exponent for the back-off
reportOnFroyo boolean false Defines whether unhandled exception are reported on Android 2.2 (Froyo) and above or not, since Froyo has its own error-reporting system
includeFields String all Comma-separated list of fields to send (field names as of section Server). If the list contains all, all available fields will be included
dialogIcon int @android:drawable/ic_dialog_alert The icon of the dialog for user approved error reports. (Use the android:resource attribute and reference to an existing resource)
dialogTitle int ^1 crashed The dialog title for user approved error reports. You can use a template style text (^1) where the first placeholder will be replaced by the application name. (Use the android:resource attribute and reference to an existing resource)
dialogText int ^1 crashed because of an unexpected error. Please help fixing the error by sending an error report. The text shown in the dialog for user approved error reports. You can use a template style text (^1) where the first placeholder will be replaced by the application name. (Use the android:resource attribute and reference to an existing resource)
dialogMessageHint int Undefined If you specify this value, an additional text-input field will be shown in the dialog with the specified message as hint. The content will be sent as additional information in the extraMessage field (see section Server). (Use the android:resource attribute and reference to an existing resource)
dialogSendButton int @android:string/ok Text on the send-button of the dialog for user approved error reports. (Use the android:resource attribute and reference to an existing resource)
dialogCancelButton int @android:string/cancel Text on the cancel-button of the dialog for user approved error reports. (Use the android:resource attribute and reference to an existing resource)>
notificationIcon int @android:drawable/stat_notify_error Icon of the notification for user approved error reports. (Use the android:resource attribute and reference to an existing resource)
notificationTitle int ^1 crashed The notification title for user approved error reports. You can use a template style text (^1) where the first placeholder will be replaced by the application name. (Use the android:resource attribute and reference to an existing resource)
notificationText int Click here to help fixing the issue The notification text for user approved error reports. You can use a template style text (^1) where the first placeholder will be replaced by the application name.(Use the android:resource attribute and reference to an existing resource)
notificationTickerText int Empty The notification ticker text for user approved error reports. You can use a template style text (^1) where the first placeholder will be replaced by the application name.(Use the android:resource attribute and reference to an existing resource)

Server

The server will receive error reports via HTTP-post requests. They will contain the following fields:

exStackTrace The stack trace
exClass The exception class
exMessage The exceptions message
exDateTime The date and time when the exception happend in the format "yyyy-MM-dd HH:mm:ssZ" (SimpleDateFormat)
extraMessage A custom message which can be added to manual error reports
exThreadName The name of the thread the error has been thrown in
appVersionCode The version code (as defined in your AndroidManifest.xml)
appVersionName The version name (as defined in your AndroidManifest.xml)
appPackageName The package name (as defined in your AndroidManifest.xml)
devAvailableMemory The devices available memory in bytes
devTotalMemory The devices total memory in bytes
devModel The phones model name (android.os.Build.MODEL)
devSdk The phones sdk version (android.os.Build.VERSION.SDK)
devReleaseVersion The phones release version (android.os.Build.VERSION.RELEASE)
Something went wrong with that request. Please try again.