Google Analytics SDK for Android: Migrating to v3

This guide describes how to upgrade to V3 of the Google Analytics SDK for Android.

At a Glance: What's New in V3

APIs in V3 have been refactored to be more consistent across native and web platforms. All V2 users should note these changes:

  • Hits are now sent using a single send(Map<String, String> parameters) method.
  • Debug mode has been replaced with a Logger
  • EasyTracker now subclasses Tracker, resulting in some changes to interface.
  • New: a dryRun flag has been added to prevent dispatched data from appearing in reports.

For the complete list of changes, see the Android Changelog.

Before you Begin

Before beginning the upgrade to v3, you will need the following:

Upgrade Paths

To get started, select an upgrade path to v3 from your current implementation:

EasyTracker: v1.x to v3

It is recommended that EasyTracker v1.x users follow the v3 Getting Started Guide to begin using v3 with EasyTracker.

EasyTracker: v2.x to v3

v2.x EasyTracker users should follow these steps to complete the upgrade to v3:

  1. Update calls to EasyTracker.getInstance() to provide a Context:
    // v2 (Old)
    // EasyTracker.getInstance().activityStart(this);
    
    // v3:
    EasyTracker.getInstance(this).activityStart(this);
    
  2. EasyTracker now subclasses Tracker -- remove calls to EasyTracker.getTracker():
    // v2 (Old)
    Tracker v2Tracker = EasyTracker.getInstance().getTracker();
    
    // v3
    Tracker v3Tracker = EasyTracker.getInstance(this);
    
  3. Replace all send<hit-type> convenience methods with the new send(Map<String, String> parameters) method:
    // v2 (Old)
    Tracker v2EasyTracker = EasyTracker.getInstance().getTracker(this);
    v2EasyTracker.sendView("Home Screen");
    
    // v3
    Tracker v3EasyTracker = EasyTracker.getInstance(this);
    
    // Set the screen name on the tracker so that it is used in all hits sent from this screen.
    v3EasyTracker.set(Fields.SCREEN_NAME, "Home Screen");
    
    // Send a screenview.
    v3EasyTracker.send(MapBuilder
      .createAppView()
      .build()
    );
    
    Learn more about sending data in v3.


  4. Replace the ga_debug EasyTracker parameter with ga_logLevel, and one of these verbosity values: verbose, info, warning, error:
    <!-- res/values/analytics.xml -->
    
    <?xml version="1.0" encoding="utf-8"?>
    <resources>
      <string name="ga_trackingId">UA-XXXX-Y</string>
      <!-- REMOVE: <bool name="ga_debug">true</bool> -->
      <string name="ga_logLevel">verbose</string>
    </resources>
    
    See the EasyTracker Parameter Reference for more details.


  5. GoogleAnalytics.requestAppOptOut() is deprecated, use GoogleAnalytics.getAppOptOut() instead:
    // v2 (Old)
    GoogleAnalytics.getInstance(this).requestAppOptOut(new AppOptOutCallback() {
       @Override
       public void reportAppOptOut(boolean optOut) {
         if (optOut) {
         ... // Alert the user that they've opted out.
         }
       });
    }
    
    // v3
    boolean optOutPreference = GoogleAnalytics.getInstance(this).getAppOptOut();
    
  6. (Optional) Add ga_dryRun EasyTracker parameter and set to true when testing your implementation to prevent test data from appearing in your production reports:
  7. <!-- res/values/analytics.xml -->
    
    <?xml version="1.0" encoding="utf-8"?>
    
    <resources>
      <string name="ga_trackingId">UA-XXXX-Y</string>
      <string name="ga_logLevel">verbose</string>
    
      <!-- Prevent data from appearing in reports. Useful for testing. -->
      <bool name="ga_dryRun">true</bool>
    
    </resources>
    

Custom Implementation: v1.x to v3

v1.x users who do not use EasyTracker should follow the V3 Getting Started Guide and consult the Advanced Configuration Developer Guide as needed.

Custom Implementation: v2.x to v3

v2.x users who do not use EasyTracker should follow the steps below to complete the upgrade to v3:

  1. Replace all 'send<hit-type>' convenience methods with the new send(Map<String, String> parameters) method:
    // v2 (Old)
    Tracker v2Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
    v2Tracker.sendView("Home Screen");
    
    // v3
    Tracker v3Tracker = GoogleAnaytics.getInstance(this).getTracker("UA-XXXX-Y");
    
    // This screen name value will remain set on the tracker and sent with
    // hits until it is set to a new value or to null.
    v3Tracker.set(Fields.SCREEN_NAME, "Home Screen");
    
    v3Tracker.send(MapBuilder
      .createAppView()
      .build()
    );
    
  2. Remove calls to GoogleAnalytics.setDebug(), replace with GoogleAnalytics.getLogger().setLogLevel():
    // V2 (Old)
    GoogleAnalytics.getInstance(this).setDebug(true);
    
    // V3
    GoogleAnalytics.getInstance(this)
        .getLogger()
        .setLogLevel(LogLevel.VERBOSE);  // VERBOSE | INFO | DEBUG | WARNING
    
    Learn more about Logger

  3. The v3 SDK no longer automatically starts a new session when the app opens (except when using EasyTracker). If you want to preserve this behavior from a v2 custom implementation, you need to implement your own session control logic when a user starts the app:
  4. package com.example.app;
    
    import com.google.analytics.tracking.android.GoogleAnalytics;
    import com.google.analytics.tracking.android.Tracker;
    
    import android.app.Application;
    
    public class MyApp extends Application {
    
      private static Tracker mTracker;
      private static final String GA_PROPERTY_ID = "UA-XXXX-Y";
    
      @Override
      public void onCreate() {
        super.onCreate();
        mTracker = GoogleAnalytics.getInstance(this).getTracker(GA_PROPERTY_ID);
    
        // CAUTION: Setting session control directly on the tracker persists the
        // value across all subsequent hits, until it is manually set to null.
        // This should never be done in normal operation.
        //
        // mTracker.set(Fields.SESSION_CONTROL, "start");
    
        // Instead, send a single hit with session control to start the new session.
        mTracker.send(MapBuilder
          .createEvent("UX", "appstart", null, null)
          .set(Fields.SESSION_CONTROL, "start")
          .build()
        );
      }
    }
    
    
  5. (Optional) Set the dryRun flag while testing to prevent test data from being processed with your production reports:
  6. // When true, dryRun flag prevents data from being processed with reports.
    GoogleAnalytics.getInstance(this).setDryRun(true);
    

Reference

The following sections provide reference examples of how to set and send data using the V3 SDK.

Sending Data using Maps in v3

In V3, data is sent using a single send() method that takes a Map of Google Analytics fields and values as an argument. A MapBuilder utility class is provided to simplify the process of building hits:

// Sending a screenview in v3 using MapBuilder.
Tracker tracker = GoogleAnalytics.getInstance(this).getTracker("UA-XXXX-Y");
tracker.set(Fields.SCREEN_NAME, "Home Screen");

tracker.send(MapBuilder
  .createAppView()                           // Creates a Map of hit type 'AppView' (screenview).
  .set(Fields.customDimension(1), "Premium") // Set any additional fields for this hit.
  .build()                                   // Build and return the Map to the send method.
);

The MapBuilder class can be used to build any of the supported hit types, like events:

// Sending an event in v3 using MapBuilder.createEvent()
tracker.send(MapBuilder
    .createEvent("UX", "touch", "menuButton", null)
    .build()
);

Learn more about Sending Data in v3.

Setting Data on the Tracker in v3

Values may also be set directly on a Tracker using the set() method. Values set directly are applied to all subsequent hits from that Tracker :

// Values set directly on a tracker apply to all subsequent hits.
tracker.set(Fields.SCREEN_NAME, "Home Screen");

// This screenview hit will include the screen name "Home Screen".
tracker.send(MapBuilder.createAppView().build());

// And so will this event hit.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

To clear a value that's been set on the Tracker , set the property to null:

// Clear the previously-set screen name value.
tracker.set(Fields.SCREEN_NAME, null);

// Now this event hit will not include a screen name value.
tracker.send(MapBuilder
  .createEvent("UX", "touch", "menuButton", null)
  .build()
);

Learn more about Setting Data in v3