[翻译]ACRA3介绍

前言

这一版本的主要目的是为了避免定制ACRA的Application子类。此前的规定是为了防止开发者同时使用其他的类库，例如 GreenDroid, RoboGuice, Droid-Fu 等。

通过配置ACRA的@ ReportsCrashes，已经很好的解决了此问题。

介绍

ACRA 允许你的Android应用将崩溃报告以谷歌文档电子表的形式进行发送。本教程将引导您在应用程序项目中安装ACRA。

设置好你的项目

按照以下步骤在现有的应用程序项目中安装ACRA库：

• 下载acra库（ http://acra.googlecode.com/files/acra-3.1.2.zip）并打开压缩包
• 登录到您的谷歌文档帐户
• 导入压缩包中的 CrashReports-template.csv  (acra-3.1.2/CrashReport/doc)
• 打开导入的文档
• 按照自己的喜好重命名
• 在菜单上，单击窗体/创建表单
• 为了启动“保存”按钮，请添加描述信息
  • 如果您使用谷歌应用服务的私人领域，一定要取消选择"Require yourdomain.com sign-in to view this form."
• 保存表单
• 复制在表单创建页面底部的链接中的formkey
• 打开eclipse项目
• 创建一个 lib 目录
• 在lib目录中添加 acra-3.1.2.jar 
• 右击 jar文件，并且添加到build path
• 在package的root目录创建一个新的类
  • 继承android.app.Application，并命名如: MyApplication
  • 在MyApplication类声明之上，添加annotation@ReportsCrashes，并指定谷歌文档的formkey

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

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

• 在 MyApplication 类中, 覆盖 onCreate() 方法并添加ACRA初始化代码

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

• 打开android配置文件AndroidManifest.xml
  • 设置项目的Application为MyApplication
  • 添加权限声明android.permission.INTERNET

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">

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

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

• 结束THE END - 下次应用崩溃的时候，ACRA会将崩溃报告添加到谷歌文档电子表中 :-).

建议 : 可以在谷歌文档电子表格的preferences页面，设置通知规则，那么当有报告发送的时候，就会受到邮件通知了!

高级用法

用户通知

默认情况，ACRA仅仅是将崩溃报告发送到服务端。从使用应用的用户来看，应用崩溃的时候仅仅是"Force Close"对话框是不够的。

作为开发者，你可能更喜欢通知用户崩溃报告已经发送了...... 为什么不允许他描述一下崩溃之时他正在所操作的动作呢？

ACRA 提供了这些选项，并且允许定制崩溃报告通知。

有两种通知模式:

• 显示定制内容的Toast

• 显示一个状态栏通知，然后显示一个对话框询问用户是否将崩溃报告发送到服务端，并且允许用户增加补充说明.

开启用户通知仅仅需要给@ReportsCrashes添加几个参数 :

• Toast 通知:

@ReportsCrashes(formKey="dGVacG0ydVHnaNHjRjVTUTEtb3FPWGc6MQ",
                                mode = ReportingInteractionMode.TOAST,
                                resToastText = R.string.crash_toast_text)
public class MyApplication extends Application {
...

在 strings.xml 中 :

<string name="crash_toast_text">Ooooops ! I crashed, but a report has been sent to my developer to help him fix the issue !</string>

• 状态栏通知:

@ReportsCrashes(formKey="dGVacG0ydVHnaNHjRjVTUTEtb3FPWGc6MQ",
                                mode = ReportingInteractionMode.NOTIFICATION,
                                resNotifTickerText = R.string.crash_notif_ticker_text,
                                resNotifTitle = R.string.crash_notif_title,
                                resNotifText = R.string.crash_notif_text,
                                resNotifIcon = android.R.drawable.stat_notify_error, // optional. default is a warning sign
                                resDialogText = R.string.crash_dialog_text,
                                resDialogIcon = android.R.drawable.ic_dialog_info, //optional. default is a warning sign
                                resDialogTitle = R.string.crash_dialog_title, // optional. default is your application name
                                resDialogCommentPrompt = R.string.crash_dialog_comment_prompt, // optional. when defined, adds a user text field input with this text resource as a label
                                resDialogOkToast = R.string.crash_dialog_ok_toast // optional. displays a Toast message when the user accepts to send a report.
                                )
public class MyApplication extends Application {
...

在 strings.xml 中:

<string name="crash_notif_ticker_text">Unexpected error, please send a report...</string>
<string name="crash_notif_title">CrashTest has crashed...</string>
<string name="crash_notif_text">Please click here to help fix the issue.</string>
        
<string name="crash_dialog_title">CrashTest has crashed</string>
<string name="crash_dialog_text">An unexpected error occurred forcing the
        application to stop. Please help us fix this by sending us error data,
        all you have to do is click \'OK\'.</string>
<string name="crash_dialog_comment_prompt">You might add your comments about the problem below:</string>
<string name="crash_dialog_ok_toast">Thank you !</string>

在 AndroidManifest.xml中

<application ...>

    ....

    <activity android:name="org.acra.CrashReportDialog"
        android:theme="@android:style/Theme.Dialog"
        android:launchMode="singleInstance"
        android:excludeFromRecents="true"
        android:finishOnTaskLaunch="true" />

    ....

</application>

我可以将崩溃报告发送到自定义的服务端么?

仅仅需要给@ReportsCrashes指定 formUri 参数 :

@ReportsCrashes(formKey="", // will not be used
                                formUri="http://yourserver.com/yourscript",
                                mode = ReportingInteractionMode.TOAST,
                                resToastText = R.string.crash_toast_text)
public class MyApplication extends Application {
...

然后你的脚本必须按照 ErrorReporter 类指定字段.

我可以在崩溃报告中添加自定义的补充信息字段么 ?

当然！

仅仅需要使用一下的方法:

ErrorReporter.getInstance().putCustomData("myVariable", myVariable);

所有定制的数据 (only latest value for each one) 将被添加到"custom"字段

可以使用 getCustomData("myVariable") 和 removeCustomData("myVariable") 来增加或删除定制数据.

可以让用户禁用报告么？

是的！

你所需要做的是添加给你的 preferences 文件添加一个CheckBoxPreference :

<CheckBoxPreference android:key="acra.disable"
        android:title="@string/pref_disable_acra"
        android:summaryOn="@string/pref_acra_disabled"
        android:summaryOff="@string/pref_acra_enabled"
        android:defaultValue="false"/>

如果你更喜欢用户允许默认选择发送报告，你可以按照如下配置:

<CheckBoxPreference android:key="acra.enable"
        android:title="@string/pref_disable_acra"
        android:summaryOn="@string/pref_acra_enabled"
        android:summaryOff="@string/pref_acra_disabled"
        android:defaultValue="true"/>

然后在你的 strings.xml 文件中添加3个string资源

我可以将异常也发送报告么？或者当应用处于特殊状态时也发送一份报告么？

作为一个优秀的程序员，你的代码充满了try / catch语句，有时意想不到的异常发生了，这是你可能很想获得当时的异常报告。

你也可能当应用出在某种状态的时候，发送一份报告给开发人员。

你只要按照以下方法就可以实现了 :

ErrorReporter.getInstance().handleException(caughtException);

你可以捕获或提供任何自定义异常。

如果你需要后台发送报告，而不管当前设置的是什么通知模式，你只需要按照以下方法即可:

ErrorReporter.getInstance().handleSilentException(caughtException);

http://code.google.com/p/acra/wiki/ACRA3HowTo?tm=6