Backtrace offers integration with Android apps using the backtrace-android library. Your apps written in Kotlin or Java can easily start submitting error reports to your Backtrace instance. 

The backtrace-android library is available here.

Setup and Installation

Configure your Backtrace Instance

If you don't have a Backtrace instance yet, create one here. 

You will be provided a Backtrace instance with a domain in the following form:

https://yourcompany.sp.backtrace.io

Once you log into your instance, you will need to create a project and a submission token in that project in order to start submitting error reports. Your submission token is accessible under your Project Settings - Error Submission:

You'll use the submission token information to submit error reports to your Backtrace instance and specific project.

Configure your Application

Find more information about using the library in the README file. Use gradle or maven to install the reporting library into your application. You will need to set Internet and File Access permissions in your AndroidManifest.xml file.

You'll find details on how to:

• Use BacktraceClient to initialize and submit simple error reports to your Backtrace instance, including unhandled exceptions
• Configure the offline database and submission retry settings using BacktraceDatabaseSettings
• Make use of Breadcrumbs, which help you track device events leading up to your crash
• Use the BacktraceReport class to populate and submit custom attributes or file attachments alongside the error report
• Make use of advanced settings such as asynchronous Send, custom event handlers

Submit your first Error

Following the information in the README, you should be able to use a BacktraceClient object to send an error report to your Backtrace instance upon encountering an error or crash. 

Review the Error in Backtrace

Review the error you submitted using the Backtrace Triage, Explore or Debug tools.

Index Additional Attributes

backtrace-android submits about 25 system level attributes about the device and the application that you can index and make use of in Backtrace.

Goto your Project Settings - Attributes tab to view Attributes. You will see a list of Recommended Attributes based on what's been submitted with crash reports in this project. Learn more about how to setup these Attributes in the Attribute documentation.

Once you create these Attributes, you will need to Reprocess Objects (Project Settings - Object Reprocessing) in order to reindex any crash report that was submitted before these Attributes were added. 

You'll notice in the Triage - Details page, you can now add the additional attributes to view, or in the Explore page you'll be able to use those attributes for filtering or aggregation.

ProGuard Deobfuscation

If you use ProGuard to optimize and obfuscate your app, you can configure Backtrace to deobfuscate your crashing callstacks.

What You'll Need

• A Backtrace account (log in or sign up for a free trial license).
• Your subdomain name (used to connect to your Backtrace instance). For example, https://example-subdomain.sp.backtrace.io.
• A Backtrace project and a symbol access token.

Setup

If the symbolication_id from the submitted crash matches a symbolication_id of a submitted ProGuard mapping file, the Backtrace Client will use that mapping file to deobfuscate the symbols from the submitted crash.

To do this, you need to upload the ProGuard mapping file corresponding to the build. Because the ProGuard file format does not offer any way to identify its corresponding build, it needs to be done by the programmer. For Backtrace, a UUID needs to be generated for each build.

1. Add the following to the proguard_rules.pro file for your app.

   -keep class com.google.gson.**.* { *; }
   -keep class backtraceio.library.**.* { *; }

2. Enable ProGuard mode in the BacktraceClient.

   backtraceClient.enableProguard();

3. Generate a UUID and set it as the value for the symbolication_id attribute. You will upload your ProGuard mapping file with this same UUID later.

   final UUID proguardMappingUUID = UUID.fromString("f6c3e8d4-8626-4051-94ec-53e6daccce25");
   final Map<String, Object> attributes = new HashMap<String, Object>() {{
   put("symbolication_id", proguardMappingUUID.toString());
   }};

   You can use the uuidgen command to generate UUID's for each version of your software, for example:

   $ uuidgen -N '1.0.0-beta' --namespace "f615d933-702b-5c5f-913d-18223dc80788" --sha1 6e5552ef-cca0-578f-8259-bef23a9566d3
   $ uuidgen -N '1.0.0' --namespace "f615d933-702b-5c5f-913d-18223dc80788" --sha1 5a4d2886-fb5d-5d2e-80d8-4bcdf5f5c11b
   $ uuidgen -N '1.0.1' --namespace "f615d933-702b-5c5f-913d-18223dc80788" --sha1 39642ed9-5a75-5186-9649-71a893e00340

4. Upload your ProGuard mapping.txt file with the UUID from the previous step.

   To do so, you can use a tool like Postman or cURL to construct an HTTP POST request with the following parameters, and submit the mapping file as the request body.

   --data-binary @proguard-example/mapping.txt -X POST -H "Expect:" "https://submit.backtrace.io/{your-subdomain}/{symbol-access-token}/proguard?symbolication_id={symbolication_id}"

   Where{your-subdomain} is the name of subdomain, {symbol-access-token} is the symbol access token for your project, and symbolication_id is the symbolication ID that you generated in the previous step.

   NOTE FOR WINDOWS:

   Make sure your ProGuard mapping file has Unix line endings before submitting to Backtrace.

Advanced Configuration of backtrace-android

Once you confirm that simple errors are being submitted, you can go back to the backtrace-android README and setup additional reporting settings, such as modifying the offline settings, enabling breadcrumbs, attaching additional custom attributes, or attaching file attachments.