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)