Advanced Configuration - Android SDK v2 (Legacy)

This document provides an oveview of some of the advanced configuration features of the Google Analytics SDK for Android v2.

Overview

The Google Analytics SDK for Android uses two classes to manage the global state of the implementation and sending data to Google Analytics servers. EasyTracker wraps these classes to provide simplified configuration and session management:

  • GoogleAnalytics – a singleton that handles the global state of your implementation, including getting Tracker objects.
  • Tracker – the class with which you send data to Google Analytics.

For example, to measure a view of a simple Activity:

import android.app.Activity

import com.google.analytics.tracking.android.GoogleAnalytics
import com.google.analytics.tracking.android.Tracker

/**
 * A simple Activity that sends a screen view to Google Analytics
 * when it is displayed to the user.
 */
public class HomeScreen extends Activity {

  private Tracker mGaTracker;
  private GoogleAnalytics mGaInstance;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Get the GoogleAnalytics singleton. Note that the SDK uses
    // the application context to avoid leaking the current context.
    mGaInstance = GoogleAnalytics.getInstance(this);

    // Use the GoogleAnalytics singleton to get a Tracker.
    mGaTracker = mGaInstance.getTracker("UA-XXXX-Y"); // Placeholder tracking ID.
    ... // The rest of your onCreate() code.
  }

  @Override
  public void onStart() {
    super.onStart();

    // Send a screen view when the Activity is displayed to the user.
    mGaTracker.sendView("/HomeScreen");
  }
}

Using Multiple Trackers

As of version 2 of the SDK, you can use multiple trackers in a single implementation, one per unique tracking ID. All trackers share the same global state held by your GoogleAnalytics singleton.

In the following example, a screen view is sent to two separate properties by using two trackers, each with its own unique property ID:

import android.app.Activity

import com.google.analytics.tracking.android.GoogleAnalytics
import com.google.analytics.tracking.android.Tracker

/**
 * A simple Activity that sends a screen view to Google Analytics
 * when it is displayed to the user.
 */
public class HomeScreen extends Activity {

  private GoogleAnalytics mGaInstance;
  private Tracker mGaTracker1;
  private Tracker mGaTracker2;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Get the GoogleAnalytics singleton.
    mGaInstance = GoogleAnalytics.getInstance(this);

    // Use the GoogleAnalytics singleton to get two Trackers with
    // unique property IDs.
    mGaTracker1 = mGaInstance.getTracker("UA-XXXX-Y");
    mGaTracker2 = mGaInstance.getTracker("UA-XXXX-Z");

    ... // The rest of your onCreate() code.
  }

  @Override
  public void onStart() {
    super.onStart();

    // Send a screen view to "UA-XXXX-Y" the Activity is displayed to the user.
    mGaTracker1.sendView("/HomeScreen");

    // Send another screen view to the second property, "UA-XXXX-Z".
    mGaTracker2.sendView("/Home");
  }
}

Keep in mind that automated measurement features provided by EasyTracker will only use the default tracker to make their calls. If you are using these EasyTracker features and want to send data using other trackers, you will need to do so manually.

Default Tracker

Though an implementation may use multiple trackers, globally it has one default tracker. The first Tracker retrieved becomes the default tracker.

To get the default tracker, use:

// Get singleton.
GoogleAnalytics myInstance = GoogleAnalytics.getInstance(this);

// Get default tracker.
Tracker myDefault = myInstance.getDefaultTracker();

To set the default tracker, use:

// First get a tracker using a new property ID.
Tracker newTracker = myInstance.getTracker("UA-XXXX-2");

// Then make newTracker the default tracker globally.
myInstance.setDefaultTracker(newTracker);

Dispatching

Dispatch settings are managed by the GAServiceManager singleton. To set the dispatch period:

// Set dispatch period to 30 seconds.
GAServiceManager.getInstance().setDispatchPeriod(30);

To manually dispatch outside of the scheduled interval:

// Manually dispatch any queued hits.
GAServiceManager.getInstance().dispatch();

Sampling

You can enable client-side sampling to limit the number of hits sent to Google Analytics. If your app has a large number of users or otherwise sends a large volume of data to Google Analytics, enabling sampling will help ensure un-interrupted reporting.

For example, to enable client-side sampling at a rate of 50% via EasyTracker and XML, use the following parameter in your analytics.xml file:

<string name="ga_sampleFrequency">50.0</string>

You can also enable client-side sampling programmatically:

// Get tracker from singleton.
GoogleAnalytics gaInstance = GoogleAnalytics.getInstance(this);
Tracker tracker = gaInstance.getTracker("UA-XXXX-Y"); // Placeholder property ID.

// Set a sample rate of 50%.
tracker.setSampleRate(50.0d);

App-level Opt Out

You can enable an app-level opt out flag that will disable Google Analytics across the entire app. Once set, the flag will persist for the life of the app or until it is reset.

To get the app-level opt out setting, use:

// Get singleton.
GoogleAnalytics myInstance = GoogleAnalytics.getInstance(this);

// Get the app opt out preference using an AppOptOutCallback.
myInstance.requestAppOptOut(new AppOptOutCallback() {
   @Override
   public void reportAppOptOut(boolean optOut) {
     if (optOut) {
     ... // Alert the user that they've opted out.
     }
   });
}

To set the app-level opt out flag, use:

myInstance.setAppOptOut(appPreferences.userOptOut);

Testing and Debugging

The Google Analytics SDK for Android provides a debug mode that will print useful information about what data is being sent to Google Analytics in your logs.

To enable debug mode using EasyTracker, add the following to your analytics.xml resource file:

<bool name="ga_debug">true</bool>

To enable debug mode programmatically, use:

// Get singleton using application context.
GoogleAnalytics myInstance = GoogleAnalytics.getInstance(this);

// Enable debug mode.
myInstance.setDebug(true);

The output will be printed to logcat using the tag GAV2.