API Development

Using Crash Analytics With Titanium Apps

Using Crash Analytics with Titanium Apps

In this post, I will be running through how to implement Axway Crash Analytics (ACA) into both a new and existing Titanium app—we’ll set up the native module and require it in our code, then create some sample breadcrumbs and simulate some crashes, then view these in the reporting portal.

Using Crash Analytics with Titanium Apps

ACA is unique amongst crash analytics product in that it easily integrates with Titanium apps and provides you with the actual lines of JavaScript code that are causing the problem straight from your Classic or Alloy-based Titanium app. In other words, you don’t see Objective-C code or anything on the native side — you see your actual JavaScript, with line numbers you can relate back to your own code just like you’d see in the red error screen if you were running on a simulator or device with a development build.

You may think ACA is only available to Pro and Enterprise Axway accounts when it’s actually available to all accounts—including Indie.

ACA is $19.99 a month—you can add it to an existing Mobile Backend Services plan which is $6 a month which includes 1 million analytic events, 1GB of storage, 10GB of file storage and 100,000 API calls. ACA will store your crash reports for 30 days.

READ MORE: Creating custom tags in Titanium with Alloy.

To add ACA to your existing account:

  1. login to the Axway platform
  2. Go to Mobile Backend Services in the “Adjust Plan” section of billing.
  3. Turn on the checkbox called “Crash Analytics”.
  4. Slide “API Calls” and “Push Calls” to the minimum.

Once you’ve done all that you should see $25.99 per month, you can continue to add this to your cart and purchase.

Getting started with ACA for a new app.

To add ACA to a new app, you can activate it when creating a new project using Studio, click theEnable Axway Appcelerator Platform Services checkbox. Once the app has been created, you can see that analytics is set in the tiapp.xml file.

Once ACA has been added to the tiapp.xml file, the module will initialize automatically on startup.

To access module methods, you will need to require the module:

const aca = require(‘com.appcelerator.aca’);

If you want to just track application crashes, that’s all you have to do — once you build the app and check the portal you’ll see any crashes pop up there with all the details including the exact code that failed.

If you add the following to your code under the require:

Ti.crash();

The app will crash with an error — and head to the dashboard and click your app and go to crashes — you’ll see recent crashes listed there and can view the crash and see the code you’ve just written.

(note this isn’t a real method, because it doesn’t exist it causes a crash)

To make it easier to track the events leading up to a crash, you can use the leaveBreadcrumb method to add breadcrumbs in your code. Place breadcrumbs near events and application state changes to track problematic paths that can lead to an application crash. You can also add additional data to your breadcrumbs to track the state.

Here’s a quick example:

const win = Ti.UI.createWindow({ backgroundColor: ‘gray’, layout: ‘vertical’ });

const aca = require(‘com.appcelerator.aca’);

add(‘Breadcrumb’, () => {
aca.leaveBreadcrumb(‘example breadcrumb #1’);
// do stuff…
aca.leaveBreadcrumb(‘example breadcrumb #2’);
});

add(‘Username’, () => {
aca.setUsername(‘Tester’);
});

add(‘Metadata’, () => {
// specify metadata using key, value
aca.setMetadata(‘testKey’, ‘testKeyValue’);

// specify metadata using object
aca.setMetadata({
testObj: ‘testObjValue’
});
});

add(‘Log Exception’, () => {
try {
throw new Error(‘example exception’);
} catch (e) {
aca.logHandledException(e);
}
});

add(‘Opt Out’, () => {
aca.setOptOutStatus(!aca.getOptOutStatus());
console.log(‘set optOutStatus: ‘ + aca.getOptOutStatus());
});

function add(name, callback) {
const btn = Ti.UI.createButton({ title: name, left: 5, right: 5 });
btn.addEventListener(‘click’, callback);
win.add(btn);
}

These breadcrumbs are collected and passed to the ACA.

(breadcrumbs will only be reported in the case of a handled exception or a crash so they won’t be found in the Dashboard otherwise. Breadcrumb events will be sent to the platform only when a crash occurs or when the crash event is sent to the platform).

In addition to logging crashes and breadcrumbs, you can also set user data to make it easier to associate issues with a particular user using the .setUsername method as well as additional metadata:

aca.setUsername(username);
aca.setMetadata(‘lastLogin’, datetime);
aca.setMetadata(‘userLevel’, 0);

To log your own errors within ACA (for tracking issues without showing a crash error message to users) use the .logHandledException method for example:

try {
var err = new Error(‘FATAL ERROR: Value cannot be null or undefined!’);
if (value === null || value === undefined) throw err;
} catch (err) {
aca.logHandledException(err);
}

Finally, you can give users the option to opt out of crash logging using the .setOptOutStatus method:

aca.setOptOutStatus(true);

Once you’ve built the app, head over to the dashboard and click on your app, then skip to the section below on viewing crash reports.

Getting started with ACA for an existing app.

To enable ACA for en existing app you need to add the app to the Axway portal:

  1. Head to the dashboard and click the + symbol at the top of the screen.
  2. Enter a name for your app, select a type of “Other”, add enter “iOS” or “Android” for the platform then enter the GUID of your app which you’ll find in the tiapp.xml file.
  3. Click Save and leave that page open.

(If you have any issues adding an app, it might be because the GUID has been used already so in this case, generate a new one by changing your GUID in the tiapp.xml to 1234 and build the app — Titanium will give you four new GUID suggestions to use — replace the 1234 with one of these).

Leave that web page open and next let’s download the ACA module from the portal downloads page and add this to your project, ensuring you reference it in the tiapp.xml file:


com.appcelerator.aca
com.appcelerator.aca

Next, assuming you’re using Alloy, add a reference to the ACA module in alloy.js:

Alloy.Globals.aca = require(‘com.appcelerator.aca’);

At this point you’re all set for detecting crashes — build the app and force a crash by dropping Ti.crash() just after the requirements above.

We can also add some sample code before that to leave a breadcrumb and set the user:

Alloy.Globals.aca.leaveBreadcrumb(‘App started, alloy.js loaded’);
Alloy.Globals.aca.setUsername(‘test user’);

This additional data should now appear when we cause our Ti.crash() in the “Occurrences” section of the “Crash Details” screen — we’ll show this in the next section.

Viewing crash reports

Once you’ve built your app and forced a crash, you’ll see the usual “red screen of death” error screen — head over to the app page in the portal for the app you just created and click the app and you should see results appear immediately:

Click on the “Crashes” box and you’ll see the crash listed, and if you click that, you’ll see the details including the JavaScript code:

You can drill down further by clicking the error message itself, in which case you’ll get more details, including any breadcrumbs you might have left along the way before the crash:

If you added any breadcrumbs or added the code I showed above in alloy.js, click on “Occurrences” to see the session details and click the + symbol:

As you can see you get all the details of the session from start through the crash report, and in-between is our breadcrumb which we dropped in the alloy.js file.

Imagine for a much larger app you might have a very detailed trail of breadcrumbs that could lead up to a crash and so this session section will give you a detailed timeline of what the user was doing, and when so you’re able to provide a detailed trail that could help pinpoint the exact reason for the error.

As you can see, ACA is simple to implement but incredibly powerful in giving you real, accurate and detailed session logs and error reports of your actual Titanium JavaScript code, helping you trace and pinpoint errors and hopefully fix them.

If you’re using ACA, let us know in the comments how you’re using it and how it’s helped you and if there’s anything we can add to it to help and improve it.

Find out more about ACA.

MORE INFORMATION

Check out the [ACA Module demo] or the [app demo].

We have built it to show it in action.

Codestrong!