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

Pro or Enterprise Subscription Required

Icon

This Appcelerator Platform feature requires a Pro or Enterprise Subscription. 

This page describes how to use the Appcelerator Platform Service (APS) Analytics for native Android applications, built with Java and the Android APIs.

Not developing a native Android application with Java?

See the following topics to use the Appcelerator Analytics Service on other platforms:

For native iOS applications built with Objective-C, see APS Analytics for iOS.

For Titanium Applications, see Appcelerator Analytics.

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

To integrate the Analytics service with a new or existing Android application:

  1. Go to the Appcelerator Dashboard and create a new native Android application.
  2. Download the Services SDK and get your Analytics application key.
  3. Unpack the Services SDK ZIP file.
  4. Copy the appcelerator-sdk-android-<VERSION>.jar  to the  lib folder of your Android project.
  5. Modify the project's  AndroidManifest.xml  file to include the following permissions and to add the APSAnalytics package as a service: 

    AndroidManifest.xml
  6. Add the following import statements to the main Activity of the project: 

    MainActivity.java
  7. In the main Activity's  onCreate()  method, enable the service by calling the APSServiceManager's enable  method. Pass the method the application context as the first argument and the APS application key as the second argument.  

    Icon

    To get your APS App key:

    1. Go to the Appcelerator Dashboard.
    2. Select your application from the Apps drop-down menu.
    3. Click the Overview tab.
    4. Click the Services button.
    5. Click Show Key under the Analytics, Performance and Cloud section.

The Android application can now make additional method calls using the  APSAnalytics class.  Before making API calls to the APSAnalytics class, you need to retrieve a shared instance using the getInstance() method. Make APSAnalytics API calls using the shared instance.

For the Android platform, you need to setup the application to send user session events

Advanced Initialization Options

Session Timeout

By default, after the application has been backgrounded for 30000 milliseconds (30 seconds), the Analytics service ends the current user session and starts a new one when the application enter the foreground again.  To adjust the timeout, use the APSAnalytics's setSessionTimeout()  method.

Setup User Session Events

On the Android platform, user session events are not automatically sent, unlike the iOS and Titanium platforms.  You need to add three APSAnalyitcs method calls in the main Activity of your application in order to capture user session data.

  1. Call the sendAppEnrollEvent()  method right after the application calls the  APSServiceManager.getInstance().enable () in the  onCreate() method. The enroll event indicates application installs or upgrades.
  2. Call the sendAppForegroundEvent()  method inside the main Activity's onResume() method.  The foreground event indicates when the application is being used.
  3. Call the  sendAppBackgroundEvent() method inside the main Activity's onPause() method.  The background event indicates when the application has been dismissed.
MainActivity.java

Creating Custom Events

You use the the A PSAnalytics 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 APSAnalytics' sendAppFeatureEvent()  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 APSAnalytics' sendAppNavEvent()  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.

Geo Events

Use the APSAnalytics' sendAppGeoEvent()  method to send real-time geographic data to the Analytics service.  Pass the method an Android  Location  object.

In the following example, the application uses a default location provider to get location information from the device.  The application sends the location data to the Analytics service.

MainActivity.java