|
ACRA3HowTo
This document is deprecated. It is related to ACRA v3.X which is not supported anymore. Please use ACRA v4.X.PreambleThe main goal of this new version is to avoid the need of subclassing an ACRA-specific android Application class. This previous requirement was preventing developers to use both ACRA and other rich-featured libs/frameworks like GreenDroid, RoboGuice, Droid-Fu and others. This goal has been achieved by moving the configuration of ACRA to a new ACRA-specific annotation @ReportsCrashes. IntroductionACRA allows your Android application to send Crash Reports in a Google Docs spreadsheet. This tutorial will guide you in installing ACRA in your application project. Setting-up your projectStep by step installation of the ACRA library in an existing application project:
import org.acra.*;
import org.acra.annotation.*;
@ReportsCrashes(formKey = "dGVacG0ydVHnaNHjRjVTUTEtb3FPWGc6MQ")
public class MyApplication extends Application {
}
@Override
public void onCreate() {
// The following line triggers the initialization of ACRA
ACRA.init(this);
super.onCreate();
}
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):
This adds the following element as a child of the manifest element:<uses-permission android:name="android.permission.INTERNET"></uses-permission> 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: Advanced UsageUser notificationThe default behaviour of ACRA is to send crash reports silently. From the application user point of view, the application has crashed with the usual "Force Close" dialog, and that's all. As a developer, you might prefer notifying your users that a crash report has been sent, or even ask him the authorization so send one... and why not ask him to describe what he was doing during the crash... ACRA offers all these options, and allow you to customize your application crash reporting notifications. 2 main notification modes are available:
   Enabling user notification only requires you to add parameters to the @ReportsCrashes annotation :
@ReportsCrashes(formKey="dGVacG0ydVHnaNHjRjVTUTEtb3FPWGc6MQ",
mode = ReportingInteractionMode.TOAST,
resToastText = R.string.crash_toast_text)
public class MyApplication extends Application {
...In your 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 {
...In your 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> In your 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>May I send reports to my own php/java/python/whateveryouwant self-hosted script ?Just use the formUri parameter of the @ReportsCrashes annotation in your Application class : @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 {
...Then your script has to follow the fields mapping exposed in the ErrorReporter class. Can I add my own variables content in the crash report ?Absolutely ! Simply use the following method in key places in your code : ErrorReporter.getInstance().putCustomData("myVariable", myVariable);All your custom data (only latest value for each one) will be added in the column "custom" just before the stack trace, one key = value pair per line. You can also use getCustomData("myVariable") and removeCustomData("myVariable") to get/remove data from the custom data map. Can I let the user disable error reporting ?Yes, you can ! All you have to do is add to your preferences xml file a 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"/> Or if you prefer to allow your user to check the box to enable reporting: <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"/> Then add to your strings.xml files the 3 corresponding string resources. If your SharedPreferences are not the application default SharedPreferences, you can provide ACRA with your own SharedPreferences name using the following @ReportsCrashes parameters:
Can I send reports for caught exceptions ? or for unexpected application state without any exception ?As a good programmer, your code is full of try/catch statements, and sometimes an interesting (unexpected) exception might be caught in one of these. You could also want your application to send a report without any Exception thrown, just because you know that your application is in an unexpected state. Both of these needs can be covered by this : ErrorReporter.getInstance().handleException(caughtException); You can provide any caught or custom Exception, or even null if you don't have any to provide. If you need to add silent trace reports whatever notification mode you configured for your application, you can also use: ErrorReporter.getInstance().handleSilentException(caughtException); | |
► Sign in to add a comment
I'm just tested and it works perfectly. It is included from now in my beta to report crashes (hope that Google Doc remains near empty :-) ) Thanks a lot !
Does not work if the crash occurs in native code.
@KinkyMunkey?> I have never used NDK. Did ACRA v2 work with native code crashes ?
Everything works using the NOTIFICATION mode except that I wasn't seeing the toast message. Then I realized that in your documentation above you left out what I assume should be resDialogOkToast, correct?
@gordonwd> you're right! I just updated the doc to fix this. Thanks!
I didn't try acra2, Not sure how you would go about trapping them- they print out a stack trace in the "DEBUG" level logs - and the application just stops.
This is not limited to NDK apps - I also had a libSkia.so crash in the core android libraries that also did not send a bug report (that was related to null pointer-memory issues w/ loading a png file - but the crash occurred in the native android code and spit out a stack trace)
these are SIGs as opposed to traditional java crashes- SIGSEV and SIGILL are the two I experienced (SIGILL is a bad instruction - i.e. using NEON instructions on a phone that does not support the ARM/NEON instruction set, SIGSEV is the aforementioned memory issues)
you can NOT try/catch SIGS either...
BTW, great work, thanks :-) saved me a bunch of time.
Ok, I don't think we can do anything to catch native crashes if they don't result in a Java Exception.
In a future release, I'm planning to add an option to (optionaly) upload a short logcat extract + DropBoxManager? system items. This should allow to get some of these traces, but only if an exception triggers the report... or if you detect an unexpected state and trigger a report yourself.
My users are generally not too techie (average age 40+), so I'm afraid with mode NOTIFICATION they might be confused by the app suddenly just disappearing and then miss the notification, and with TOAST the toast message might not be noticed (text is kinda small, too). What I'd like is a combo, where CrashReportDialog? comes up immediately when the app crashes, similar to the default Force Close dialog. Any way to do this now?
@gordonwd> This is what we would have implemented first if it was possible. Unfortunately, when an uncaught exception goes up to the UncaughtExceptionHandler?, the process seems to be put in a state which prevents it from starting new activities (and the dialog is one).
We are investigating some workarounds but they are complex to implement and require, from the moment, too much modifications on the application lifecycle.
If we ever find a usable solution, we will provide it.
Thanks for ACRA. I'm using it since a few month to monitor crashes in a beta app (in automatic mode) and it's been a real life saver to catch odd crashes.
A suggestion: when a OutOfMemory? exception happens, it would be nice to include and estimate of the RAM used by the app at that time, and the memory limit for an app on that particular device for which the dalvik VM won't allocate more memory (if doable).
I'm trying out ACRA, and have one question. What does the Google Doc template Visibility have to be set to?
@pujos.michael: I'll try to include more data about application process memory status in v3.2.
@JohnLussmyer?: The visibility setting does not matter, you may want to change it only if you want to share the spreadsheet with other people.
Except that when visibility was Private, the report didn't seem to work.
@JohnLussmyer?> Strange, all my spreadsheets are private, it works.
Yeah, it started working for me as well. Who knows, maybe it was just a network hiccup. I have noticed during Development that the app sometimes crashes without sending a report or notifying the user - and then when Eclipse reloads the Emulator with the app - it THEN puts up the crash notification box.
Thanks for this great tool. For me the reports are not written into the google spreadsheat until the user restarts the app. Maybe that was the same issue with JohnLussmyer??
Greetings from Lucerne Stephan Wiesner
Seems to me that the report is send every time the crash occures - except for the first time! On first run a crash report file is written, but not send to spreadsheet?
this works great, many thanks for all your work.
If there is a crash and the report is not send and the user restarts the app, acra again displays an error message - even if there is none now...
Stephan Wiesner
I don't know if this is an error or not, so I didn't open an issue:
A report with "a" is generated.
A report with "b" AND with "a" is generated. If I only want "b", I have to do
I assumed that handleSilentException would clean out all custom data since it is sent now.
Thank you so much for making this, it has been incredibly helpful.
You are a saint!
Kevin, what an impressive effort! joining others - please put donation link so we can thank you and buy your a beer!
one question for you, I want to add my code if error happens to free up some resources (wake lock and keyguard), can I do that and how?
Thank you!
one more question...I've got reports from my test app and I can see them in google docs, but the only field filled is stack one - the rest are blank. Do you know why?
or sorry, no, they are not blank, just not shown for some reason. if a click on a cell, I can see the content.
What about offline crashes?
Ex.: I'm using an online app (all data are in the cloud) but a connection loss causes a crash. As ACRA uses the same connection to send errors, these crashes will be lost. Could these errors be saved in files permanently or to be sent later? Android Error Reporter (https://github.com/tomquist/Android-Error-Reporter) defines a good strategy to this.
Is there some expectation to treat these situations?
I'm searchingo for a crash report and ACRA is the best until now but it can be excluded because this gap...
Thanks in advance.
@Boris> As explained by mail, there will be some pluggable custom code possible in ACRA 3.2. But this is called either on crash time or after an application restart. Though, as apps are killed and restarded after a crash there should be no need to release anything. If other needs of hooks appear we will implement them in a further release.
About the data not appearing in the spreadsheet cells, I'll add a paragraph in the doc about configuring the spreadsheet to align it's data on top left instead of the default (weird) bottom left. There's a button for this in the toolbar (it took me months to find it too ;-)
@jaulo> Even if it is not explained in the doc, ACRA supports resending unsent reports since the earliest version. If this does not work for you please file an issue in the issue tracker.
MESSAGE TO EVERYONE:
I created a Google Group for discussions about acra: https://groups.google.com/group/acra-discuss
This should be a good place for both support and discussions about next features to be implemented.
Thanks kevin.gaudin! I've not tested properly. It really works offline.
Thanks and good job!
@Boris, that caught me as well for a moment. The template is formatted so that all cells are bottom justified. The data is there (as you saw), it's just that stacktrace makes rows incredibly high :)
Btw - Just added Acra support to my app. Hopefully it will prove to be useful :)
I will add a few tips to configure the layout in the spreadsheet to get rid of the default 'align to bottom' behavior.... it's simple but it took me months to find out...
Kevin, there is a missed step in "Setting-up your project" section. Developer must add following lines to an application class:
Added. Thanks ;-) (I was assuming that the IDE adds needed imports almost automatically. But you're right, it's better to list write them here.)
Kevin, can you let us know those tips to configure the layout? It would be really helpful. Thanks!
I already added all I know... which fits in this picture:
kevin i am getting the following error
java.io.FileNotFoundException?: http://spreadsheets.google.com/formResponse?formkey=dGVacG0ydVHnaNHjRjVTUTEtb3FPWGc6MQ&ifq
if i copy paste the URL into browser i am unable to find the document. but when i remove amp; from &ifq then the link works. Could you let me know if i am doing something wrong from my end or is this an issue.
Wow! This library is so good and helpful, can't believe it! Thanks a lot!
Works inside of my application without any problems yet.
I only have one wish: I would like to have a combination of the notification and toast mode. I think, the notification mode is perfect, but some users might not notice that there was a crash (or to late for knowing, where it was produced). A toast aside of the notification informing about the crash would make this more visible.
But: Thanks a lot!
The TOAST + NOTIFICATION will be possible in v3.2.0. Actually I added this feature because there could be some time (~2 or 3 seconds) between the crash and the notification due to data collection, so there is a need to give some feedback to the user right on crash time. ETA... as soon as I find the time to test and update the documentation.
To aliasgha...@gmail.com> please post to http://groups.google.com/group/acra-discuss or open an issue, this comments page is not the better tool for support ;-)
Hi, I have the user notification enabled. If there is a crash, the notification will come every time the app is started, until the message is send. The user often does not see the notification/does not react to it and gets a crash message on each start. This looks to him as if my app crashed each time :-( Anyway around this problem? Without a workaround I will have to remove acra from my project whicht would be a real shame :-(
Thanks, Stephan
Great work !!
Amazing work! Incredibly useful!
I'm missing something: I don't see how providing the formkey for a skeleton form allows the API to access/update the imported spreadsheet from CrashReports?-template.csv?
Resolved my error. I want back to the main page and took the "Create New" to make the Form. Should have stayed in the imported spreadsheet and taken the Tools->Form->"Create a form" path to make the entry form.
Fantastic and works like a charm. Thanks for the helpful instructions on how to use.
Great !!!
hi for my app it prompt me that UnknownHostException?: ,please help me
03-17 22:26:52.049: ERROR/ACRA(304): Failed to send crash report for 1332001447000-approved.stacktrace