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

Introduction

Appcelerator Analytics collects and presents information in real time about how your application's user acquisition, engagement and usage. By default, it provides the number of applications installs, the number of sessions, and the average application session length organized by application name, platform and geography. Your application can send custom analytic  events, which are collected and logged by Analytics, to learn how users use your application. You can also create  event funnels —ordered sets of custom events that correspond to a business process or application flow you want to track as a whole.

This document provides an overview of the features provided by Analytics, and how to use them using the Titanium SDK. If you are developing an iOS application with Objective-C or Swift or an Android application with Java, see APS Analytics for iOS or APS Analytics for Android for details on using Analytics.

See also:

Terminology

Analytics refers to data about how your application has been used, as well as information about how users interact with your application. Analytics data is transmitted in the form of events

Events  are operational milestones in the application. Some events are generated automatically, such as those that mark an installation, or the beginning and end of a session. Others may be  custom events, which have a meaning specific to an application, such as tapping a specific button, or opening a certain window.  

There are two types custom events:  feature events and  navigation events   feature event  represents an action a user could take in an application, such as 'liking an item' or launching a video'.   navigation event  is used to track a users's navigation from one area of the UI to another. Applications use the Titanium or APSAnalytics API to create custom events.

Event funnels let you define custom, ordered event sequences that let you track a specific user process, such as finding a product and making a purchase.

The Analytics dashboard organizes, analyzes, and presents analytics data captured for your applications. You also use the Analytics dashboard to create and view event funnels.

Icon

Navigation events are not currently available through the Analytics UI, only through raw data export.

Getting Started with Analytics

To collect analytics data on your application, you enable Appcelerator Services in the project's tiapp.xml, and and deploy your application to begin collecting basic analytics data.

To enable analytics in a new Appcelerator project:

  1. In Appcelerator Studio, create a new Mobile Application (File > New Mobile App Project...).
  2. Make sure the Enable Appcelerator Services option in enabled in the New Mobile App Project dialog, and select the appropriate organization from the Organization pop-up menu. The application is tied to the account and organization used to create it.
     
  3. Enter the rest of the required project information and click Finish.
  4. Build your application and deploy to devices to begin collecting analytics data.

Next steps:

  • Once deployed, you can begin to view data captured for your application in the Analytics dashboard
  • Instrument your application with custom events  to track basic usage and navigation patterns.
  • Create event funnels to better analyze a specific process.
Icon

Enabling Appcelerator Services modifies your project's  tiapp.xml file and other applications files. Do not modify these code changes as it may break your project. See Platform Services for details on what changes are made to your code.

 

Creating Custom Events

You use the the Titanium.Analytics API to log and report custom events. There are two main types of events you can capture: Feature Events and Navigation Events . Feature events are for capturing a user action, such as selecting a specific menu option, or launching a video. Navigation events track a user's movement through an application, such as going from the application's home screen, and then to a search screen.

Icon

Currently, the optional data parameter of the Titanium.Analytics methods, which is used to log a dictionary object, cannot be accessed through the Dashboard.

Feature Events

You use the Titanium.Analytics.featureEvent() method to generate a feature event that captures a specific application or user activity. A feature event should represent an action,such as launching a video, or 'new item', 'launch video', and so forth. The name you assign to a feature event should incorporate the application state into the event name, rather than long descriptive names. The following naming convention is suggested, where group.event refers to the parent event:

group.event.sub-event

Feature event names should be as generic as possible. For instance, if you want to track when users select a certain menu option, use a name like "user.menu.selection", not "joeuser.menu.selection". The first option is better because it groups all the same types of event into a single metric that's easy to view on Dashboard. The person analyzing the data only has to look at a single number to get an overview of how many users have selected that menu option. The second might be fine for very small user bases, but if you have more than 100 users it means that the person analyzing the data would have to look through 100 different event names to be able to generate any useful data. 

For example, to track a user's menu selection you might use the following code, where the 10 digit number uniquely identifies the selection in your code: 

Good Practice: Track the State with the Naming Syntax

You should avoid using long, descriptive event names, as shown below:

Bad Practice: Avoid Long Descriptions

Navigation Events

Use the Titanium.Analytics.navEvent() method to track a user's navigation within your application from one screen to another. The method's first and second parameters are strings that specify the "from" and "to" locations, respectively. It's third parameter is the name you want to assign to the event.

Icon

Currently, navigation events do not appear in Dashboard. As a workaround, consider using transition events.

In the following example, an event is generated when the user navigates from the application's home screen to an edit message screen:

Best Practice: Track User Navigations Using a navEvent

Avoid passing a single long, descriptive string to navEvent(), for example:

Bad Practice: Do Not Track User Navigations Using featureEvent

Transition events

Currently, navigation events are not collected and presented in the Appcelerator Dashboard . As a workaround to this temporary issue, you can create "transition" events that serve the same purpose. A transition event is a  feature event whose name uniquely identifies the user's navigation ("screen1-to-screen2", for example). You can create an  event funnel in Dashboard from these events to analyze navigation within your application. 

For example, suppose you wanted to track user navigation between pages of a multi-step sign-up process. As the user moves from one step to the next, the application generates a feature event whose name follows the pattern "stepN-to-stepN+1", where N is the step number.

When you create the funnel you order the events in their logical order to mirror the process.

Creating and Viewing Event Funnels

You use Appcelerator Dashboard to create and view event funnels. Using event funnels involves the following basic steps:

  1. Identify the process to track, such as a user sign-up, or product purchase flow.
  2. Identifying the custom events to be recorded and when they should be captured in the process. For instance, if you are tracking a multi-step sign-up process you would likely want to generate a transition event when the user visits each step in the process.
  3. Instrumenting the custom events in your application, as described in Creating Custom Events
  4. Deploying the application to devices and begin collecting custom event data. Until the application has been deployed to a device, simulator, or emulator, the custom events won't appear in Dashboard.
  5. Creating the  event funnel in Dashboard (see Creating an Event Funnel).

Creating an Event Funnel

When you create an event funnel in Dashboard, you select the events you want to track, in the order that defines the process you want to track and analyze. For instance, in the following example the user has created an event funnel named "Buy Flow" that tracks the progress of a retail customer through three basic phases: visiting the home screen, browsing for products, and making a purchase.

Note:

  • An event funnel must contain at least two events.

To create an event funnel:

  1. In the Analytics Dashboard, make sure your application is selected.
  2. Select Event Funnels from the left navigation menu. Your application's current event funnels are displayed, if any exist.
  3. Click New Event Funnel.
  4. Enter a name for your event funnel.
  5. Drag two or more custom events from the left column to the right column. Enter the name of an event in the Custom Events text field to filter available events by name.

    Icon

    To get custom events to appear in this list, you must build your application and trigger each event to ensure that the events are registered with the analytics engine.

  6. To re-order an event drag its reorder control  up or down in the event list. Keep in mind that the order of the events you include is significant in terms of how the event funnel data is analyzed and presented.
  7. Remove an event by clicking the 'X' next to its name.
  8. Click Submit to save the event funnel.

Viewing Event Funnels

Once you've created an event funnel, you can being analyzing the funnel results. The screenshot below shows the current results of the "Buy Flow" event funnel created above. As you can see, of all visitors to the home page, 43% of those browsed for products, and 30% of those who browsed made a purchase.

To view an event funnel:

  1. In the Analytics Dashboard, make sure your application is selected.
  2. Click Event Funnels in the left navigation menu to view a list of your application's event funnels.
  3. To filter data by version, environment or custom date range, use the drop-down lists located right below the main navigation bar.  See Data Filters.

To edit an event funnel:

  1. In the Analytics Dashboard, make sure your application is selected.
  2. Click Event Funnels in the left navigation menu to view a list of your event funnels.
  3. Locate the event funnel you want to edit, then click its Edit button in the top-right corner.
  4. From the edit screen you can:
    1. Move new custom events you want to track from the left column to the right column.
    2. Reorder events in the funnel.
    3. Remove events from the funnel by clicking the × next to the event.
    4. Rename the event funnel.
  5. Click Submit to save your changes.

To remove an event funnel:

  1. In the Analytics Dashboard, make sure your application is selected.
  2. Click Event Funnels in the left navigation menu.  This list your application's current event funnels.
  3. Locate the event funnel you want to remove, then click its Edit button in the top-right corner.
  4. Click Remove to delete the event funnel.
  5. A dialog appears asking to confirm the deletion. Click Continue.