Would you like to contribute to the Titanium docs? To get started, sign up for an account on the Appcelerator Wiki and sign our CLA.

Skip to end of metadata
Go to start of metadata

Enterprise Subscription Required!

Icon

This Appcelerator Platform feature requires an Enterprise Subscription. 

 

This page describes how to use the Appcelerator Performance Management module API to help track crashes in your application.

Introduction

The Appcelerator Performance service, powered by Apteligent, monitors your application's health, crashes and overall performance. Using Appcelerator Performance, developers are able to analyze crash reports to see why applications crashed and focus on the specific problems on user feedback.

Currently, the Appcelerator Performance service only supports the Android and iOS platforms.

Icon

When you log into the Appcelerator Performance dashboard, you may encounter a gray navigation bar across the top, right below the Appcelerator Platform service navigation bar, and an orange "Contact us!" pop-up when you navigate to certain areas of the dashboard. These items are for Apteligent customers using native SDKs and are invalid for Appcelerator mobile applications.

For support with Appcelerator Performance, visit http://support.appcelerator.com.

For additional documentation, see the "Further Reading" section below.

Using Appcelerator Performance

To use the Appcelerator Performance service, enable Appcelerator Services for your project, then use the Appcelerator Performance module API to add breadcrumbs, user metadata and error handling code to log events leading up to a crash.  Login to the Appcelerator Dashboard and use the Appcelerator Performance dashboard to monitor application performance and analyze crash reports.

Setup Your Project

When creating a new application in Appcelerator Studio, make sure the Enable Appcelerator Services checkbox is enabled.

For a previously created project, if Appcelerator Services were not previously enabled, open your tiapp.xml file, then click the Enable Services button under the Appcelerator Service section.

Appcelerator Studio injects code in to the tiapp.xml file to setup the Appcelerator Performance Management module ( com.appcelerator.apm ).   See Platform Services for the code modifications.  Do not modify these changes made by Appcelerator Studio or else you will disable the Appcelerator Performance service .

 

Initialize the Module

Icon

Prior to Release 3.3.0, Appcelerator Studio would inject the code to load and initialize the module. The application could make API calls to module using the apm object for classic mobile projects or Alloy.Globals.apm for Alloy projects.

Before making API calls to the Performance module, the application needs to load the module and initialize it.  Load the module using the require() method and pass the name of the module ( com.appcelerator.apm ) to the method, then initialize the module by call the init() method.

For Alloy projects, you can keep a global reference to the module in the Alloy.Globals namespace.

app/alloy.js

Make Performance Management module API calls using the  apm  object.  For complete API information, see Performance Module API.

By default, the init() method uses the value of the com-appcelerator-apm-id key in the tiapp.xml file to initialize the Performance service.  You can optionally pass a different ID by passing it as an argument to the  init  method .  The app ID passed to the  init  method takes precedence over the com-appcelerator-apm-id  key.  

To get your APM App ID either:

  • Open your tiapp.xml file (in the Overview view) and click the Show ID link next to the Performance service or look for the com-appcelerator-apm-id key in the raw view.
  • Go to the Appcelerator Dashboard, select your application, click Performance and click Settings in the left pane.  In the right pane, select the Basics tab and locate Crittercism App ID.

Create a Breadcrumb Trail

To make it easier to track the events leading up to a crash, 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.  Append variables to your breadcrumbs to track their state.  For example:

These breadcrumbs are collected and passed to the Appcelerator Performance service.  To view the breadcrumbs, in the Appcelerator Performance dashboard, when viewing a specific application, click either Crash Reports or Handled Exceptions.  In the list of crashes or handled errors in the right pane, click on the crash or error to view its details.  Click the Breadcrumbs tab to view the breadcrumb trails leading up to the crash or error.

The most recent 100 breadcrumbs are displayed before the crash occurred.  A breadcrumb can be up to 140 characters.

Add User Metadata

Use the  setUsername  and  setMetadata methods to differentiate users of your application when viewing reports on the Appcelerator Performance dashboard.  For example:

By default, a guest profile is created to differentiate users if a username is not specified.  The username appears with the crash or error reports.

To access the user metadata, either click on a username in a crash or error report to open a detailed view, or in the Appcelerator Peformance dashboard, when viewing a specific application, click Search by User in the left pane then in the right pane, enter a user's name to find information about them.

Log An Error

You can track handled errors in your application by passing a JavaScript Error object to the  logHandledException method, which can help identify and analyze potential errors and hot spots.  For example:

Error logs are useful for tracking crashes in third-party SDKs, code that syncs data between services, or detecting bad data that is returned from a server.

To view handled errors, in the Appcelerator Peformance dashboard, when viewing a specific application, click Handled Exceptions in the left pane.  A list of handled errors and statistics appears in the right pane.  Click an error to view it in more detail.

Appcelerator Performance limits the logging of handled errors to one per minute. Up to five  errors are buffered and are subsequently sent after the one minute limit.

Allow the User to Opt-Out

Use the  setOptOutStatus method to allow the user NOT to send any information to the Appcelerator Performance service.  Passing true to this method disables sending data to Appcelerator Performance.

Check for a Crash

Use the  didCrashOnLastAppLoad method to check if the application crashed in a previous session.  If the method returns true, the application crashed on the last session.

Android-Specific Features

Most of the Android features below are specified by passing a dictionary object as the second parameter to the init() method:

See the topics below for a description of each dictionary key.

Capture Logcat Data

To include Android system log data with your crash reports, you must do the following:

For Google API Level 15 and earlier , add the following line to the Android manifest section of your tiapp.xml file:

For Google API Level 16 and later, when initializing the module, specify {shouldCollectLogcat: true}  as a second parameter when calling the init method:

Set a Custom Notification Title

To include a custom notification title for alerts, specify the notificationTitle key as a second parameter when calling the init method:

Further Reading

For complete API information, see Performance Module API.