Developer Quick Start

This guide walks you through the steps to implement the Android library and start sending measurement data.

Get the Library

Visit Measuring and Optimizing Mobile Applications on Developer Connection to download the Android library.

After unzipping the download file, you'll have the following software components:

  • admsAppLibrary.jar: Library designed for use with Android devices and simulators. Requires Android 2.0 or later.
  • Examples\TrackingHelper.java: Optional class that is designed to keep tracking code separate from your application logic.

Add the Library to your Project

  1. In the Eclipse IDE, right-click on the project name.
  2. Select Build Path > Add External Archives.
  3. Select admsAppLibrary.jar.
  4. Click Open.
  5. Right-click the project again, then select Build Path > Configure Build Path.
  6. Click the Order and Export tab.
  7. Ensure that admsAppLibrary.jar is selected.

Your application can import the classes/interfaces from the admsAppLibrary.jar library by using import com.adobe.ADMS.*;

Add App Permissions

The AppMeasurement Library requires the following permissions to send data and record offline tracking calls:

  • INTERNET
  • ACCESS_NETWORK_STATE

To add these permissions, add the following lines to your AndroidManifest.xml file (in the application project directory):

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

A Quick Word on the TrackingHelper

The SDK includes an additional, optional class, called TrackingHelper. TrackingHelper provides a way to separate your measurement code from your application logic.

Consider the following example: In your application, you want to send an event that tracks each login. You could add the following code directly after your login code to send this event (don't worry about the code details, we'll get to those later):

Hashtable<String, Object> contextData = new Hashtable<String, Object>();
		contextData.put("username", "username_value");
		measure.trackEvents("event1", contextData);

This direct approach is OK, but wouldn't you rather put this code somewhere else so it is out of your way while you are developing your application? The TrackingHelper is that "somewhere else".

Inside of TrackingHelper, you could place this code in a method called trackLogonEvent:

public static void trackLogonEvent (String username_value) {
Hashtable<String, Object> contextData = new Hashtable<String, Object>();
		contextData.put("username", username_value);
		measure.trackEvents("event1", contextData);
}

Now, in your application code, you can track a logon event with a simple call to trackLogonEvent:

TrackingHelper.trackLogonEvent("username");

The measurement call in your application code is down to a single line. Plus, if the underlying measurement logic needs to change, you'll need to update only the TrackingHelper. If another developer adds to your code, he or she can use the simplified methods you've defined without taking a crash course in the AppMeasurement library.

We think you'll prefer using the TrackingHelper for new implementations, even though setup requires an extra minute or two. The remaining steps in this guide walk you through the steps to set up TrackingHelper and start sending measurement data.

Be sure to copy TrackingHelper.java to a directory that contains class files for your app, and replace the package name at the top of this file to match your package structure (com.company.application). If you'd rather implement without TrackingHelper, you can find several samples inside of TrackingHelper that you can copy to your application.

Implementation

  1. Open TrackingHelper.java and update TRACKING_RSID and TRACKING_SERVER with your report suite ID and tracking server. For example:
    private static final String TRACKING_RSID = "rsid";
    private static final String TRACKING_SERVER = "server";

    These values are required, and must be correct or measurement won't work. If you are unsure about these values, ask your SiteCatalyst expert.

  2. Find the configureAppMeasurement method. This is where you enable SSL, enable offline tracking, and make other global changes to your configuration. For now, uncomment the line to enable debugLogging until things are working the way you'd expect.
  3. Add a call to configureAppMeasurement from the root activity in your application.
    @Override
    public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.main);
      TrackingHelper.configureAppMeasurement(this);
    }

That is all the code you need to start tracking custom metrics. However, with a few additional lines of code, you can enable lifecycle tracking to automatically send lifecycle metrics, including launches, upgrades, crashes, and daily and monthly users. The AppMeasurement library does all of the heavy lifting, all you need to do is add two method calls to each of your application's Activity classes.

(Recommended) Track Lifecycle Events

When lifecycle tracking is enabled, each time your app is launched, a single hit is sent to track installs, upgrades, engaged days, and the other Lifecycle Metrics.

To start tracking lifecycle events, In your app, add calls to the onResume() and onPause() methods in each Activity inside of your application, as shown in the following example. We also recommend passing the Activity or Service as the context object instead of the global Application context.

@Override
protected void onResume() {
   super.onResume();
   TrackingHelper.startActivity(this);
}
@Override
protected void onPause() {
   super.onPause();
   TrackingHelper.stopActivity();
}

That's it! You've now implemented basic lifecycle tracking in your Android app. After your Web Analyst configures SiteCatalyst to process the AppMeasurement metrics you are reporting, your SiteCatalyst report suite will contain the default lifecycle metrics.

Where to go from here:

  • (Optional) Track Custom Events. Add custom methods to TrackingHelper to track all of the events you want to measure in your application. You might add methods to track logons, in-app purchases, and so on.
  • (Optional) Track App States. An application state is similar to a page view. This section shows you how to add a custom method to TrackingHelper to track an app state.
  • Video Measurement Quick Start. Add code to track video metrics including video views, total time played, and most popular videos.

(Optional) Track Custom Events

Custom events are success metrics that are unique to your application. You might send a custom event when a user logs in, initiates an in-app purchase, or clicks a link to your Facebook page. The tracking helper class contains an example that shows how to track a custom event. You can use this method as a template to add additional event tracking methods.

In TrackingHelper.java, define a custom event track method:

public static void trackCustomEvents () {
		Hashtable<String, Object> contextData = new Hashtable<String, Object>();
		contextData.put("contextKey", "value");
		measure.trackEvents("event1, event2", contextData);
	}

Throughout your code, you can call this method to track a custom event:

TrackingHelper.trackCustomEvents();

Use this process to add as many event tracking methods as you need. A Quick Word on the TrackingHelper contains an example method to track a login event.

(Optional) Track App States

The tracking helper class also contains an example that shows how to track an application state. Tracking a custom state is very similar to tracking an event, the only difference is you use the trackAppState method instead of trackEvents.

measure.trackAppState("name", contextData);

From a reporting standpoint, trackAppState increments page views, while trackEvents does not.