• Introduction
• Setting-up your project
• Is that all?

Introduction

All ACRA bug reports should be filed in the Issues Tracker. You can also post your questions or suggestions to the Discussion Group.

ACRA allows your Android application to send Crash Reports to various destinations:

• a Google Docs spreadsheet (default and original behavior)
• an email (new in 4.0)
• your own server-side HTTP POST script (parameter names changed in 4.0)
• any other possible destination by implementing your own report sender (new in 4.0)

When a crash occurs, you can choose and configure 3 different ways of interacting with the user:

• Silent (default): ACRA actions are not visible. The crash report is sent and then the default android crash system does its job (Force Close dialog)
• Toast: When the crash occurs, ACRA displays a toast and simultaneously sends the report.
• Notification: An optional toast is displayed on application crash, but the report is not sent immediately. A status bar notification is published warning the user that he should send a report. When selected, the notification displays a dialog asking for the authorization to send the report, with an optional user comment.

This tutorial will guide you through installing ACRA in your application project.

If you have any question or comment regarding ACRA, post a message on the Discussion Group.

Setting-up your project

Step by step installation of the ACRA library in an existing application project, with the simplest settings:

• Get http://acra.googlecode.com/files/acra-4.2.3.zip and open the archive
• Login to your Google Docs account
• Import the CrashReports-template.csv contained in the archive (acra-4.2.3/CrashReport/doc), with conversion enabled
• Open the imported document
• Rename it as you like
• In the Google Docs menu, click on Tools / Form / Create a form
• Add anything in the form description just to enable the Save button
• If you are using a private Google Apps domain, make sure to uncheck the option "Require yourdomain.com sign-in to view this form."
• Save the form
• Copy the formkey value displayed in the link at the bottom of the form creation page
• Open your Eclipse project
• Create a libs folder
• Add the acra-4.2.3.jar from the archive (acra-4.2.3/build) in the libs folder
• Right-click on the jar file / add to build path
• Create a new class in your package root If your app already contains an Application subclass, add ACRA to this class.
• Give it a name like: MyApplication, make it extend android.app.Application
• Above the declaration of the MyApplication class, add the @ReportsCrashes annotation with your Google Docs formKey as a parameter

    import org.acra.*;
    import org.acra.annotation.*;

    @ReportsCrashes(formKey = "dGVacG0ydVHnaNHjRjVTUTEtb3FPWGc6MQ") 
    public class MyApplication extends Application {
    }

• In the MyApplication class, override the onCreate() method to add the ACRA init statement

    @Override
    public void onCreate() {
        // The following line triggers the initialization of ACRA
        ACRA.init(this);
        super.onCreate();
    }

• Open the android manifest editor (AndroidManifest.xml)
• In the Application tab, click on the Browse button next to the Name field
• Select your newly created Application class (MyApplication).

This adds an android:name attribute to your application element like this (put the full name with package if the application class package is not the same as manifest root element declared pakage):

<application android:icon="@drawable/icon" android:label="@string/app_name"
                android:name="MyApplication">

• In the Permissions tab, add a Uses Permission object with value android.permission.INTERNET.

This adds the following element as a child of the manifest element:

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

• THE END - next time your application crashes, it adds a line to your Google Docs spreadsheet :-).

Bonus : Google Docs spreadsheet allow to configure notifications on changes. Just set your preferences in : Share (Top right button) / Set notification rules and get notified by mail when reports are sent !

Spreadsheet default cells alignment is bottom left... select all cells and choose top left alignment:

Is that all?

First of all, you should read ReportContent for an explanation of the data collected by ACRA.

ACRA is designed to work with the simplest possible setup. But there are lots of configurable items, all described in the Advanced Usage Guide:

• User interaction mode:
• SILENT (default): with the basic setup, ACRA sends reports silently, without warning your users, and lets the system display the native Force Close dialog (which may include Android Market Send Report button on android 2.1+ devices... if your app has been downloaded from the market).
• TOAST: displays a Toast with the text of your choice when the app crashes but doesn't allow your user to prevent reports from being sent (but you can setup a SharedPreference item).
• NOTIFICATION: displays a Toast when the app crashes, then a notification in the status bar asking your user to send a report. When the notification is selected, a Dialog asks for authorization + optional user comment.
• Reports destination:
• GoogleDocs Form (default): the most used (and default) destination for crash reports with ACRA is a GoogleDocs Form. The data is stored in a GoogleDocs spreadsheet. This allows you to setup crash reporting without having to care about implementing a server-side script and find good quality (cheap) hosting. You use Google's infrastructure, for free.
• Custom server script: if you want to have better control over the reports, you can implement your own server-side script to handle reports and host it somewhere else. Then you can configure ACRA to send reports to this script.
• E-mail: if your application does not require internet permission and you don't want to add it only for crash reporting, you can configure ACRA to send reports by e-mail. This means that when a crash occurs, the user has to choose the e-mail app he prefers before reviewing the crash report and sending it.
• Any destination you can imagine: there is a simple Interface you can implement to provide your own report sender to ACRA. ACRA gives your class the report data, you do whatever you want with it.
• Reports content: ACRA provides extensive device information and state data in default reports. In addition, you can:
• Add custom variable states or traces
• Add logcat, eventlog or radiolog extracts
• Add DropBoxManager events
• Add Device unique ID
• Choosing which fields to be included in reports
• User preferences: you can add to your app preferences screen some items to let users control ACRA's behavior and reports content:
• Enable/disable sending reports
• Enable/disable sending system logs
• Enable/disable sending device unique id
• Add an e-mail address to allow the developer to contact the user
• Always accept sending reports (for NOTIFICATION mode)