Hide

Google Analytics SDK v4 for Android - Getting Started

This document describes how to get started using the Google Analytics SDK v4 for Android.

Before you Begin

Before implementing the SDK, make sure you have the following:

Getting Started

There are three steps to getting started with the SDK:

  1. Update AndroidManifest.xml
  2. Initialize Trackers
  3. Create a Configuration XML file

This guide uses code snippets from the Hello World Android app sample application. The complete source for this project is available on GitHub, under the hello-world-android-app repo.

After completing these steps, you'll be able to measure the following with Google Analytics:

  • App installations
  • Active users and demographics
  • Screens and user engagement
  • Crashes and exceptions

1. Updating AndroidManifest.xml

Analytics requires INTERNET and ACCESS_NETWORK_STATE permissions. Optionally a WAKE_LOCK permission can be requested to improve dispatching on non-Google Play devices. To use a custom application class such as MyApp, it needs to be set in the AndroidManifest as the application name attribute. The following is a snippet for common GoogleAnalytics configuration in ApplicationManifest.xml:

<manifest>
  <!-- Google Analytics required permissions -->
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

  <!-- Optional permission for reliable local dispatching on non-Google Play devices -->
  <uses-permission android:name="android.permission.WAKE_LOCK" />

  <application
    name="com.example.MyApp"> <!-- Replace with the custom app class when applicable -->

    <!-- Add the following meta-data for devices running Google Play service. -->
    <meta-data
      android:name="com.google.android.gms.version"
      android:value="@integer/google_play_services_version" />

    <!-- Optionally, register AnalyticsReceiver and AnalyticsService to support background
         dispatching on non-Google Play devices -->
    <receiver android:name="com.google.android.gms.analytics.AnalyticsReceiver"
              android:enabled="true">
      <intent-filter>
        <action android:name="com.google.android.gms.analytics.ANALYTICS_DISPATCH" />
      </intent-filter>
    </receiver>
    <service android:name="com.google.android.gms.analytics.AnalyticsService"
             android:enabled="true"
             android:exported="false"/>

      <!-- Optionally, register CampaignTrackingReceiver and CampaignTrackingService to enable
           installation campaign reporting -->
      <receiver android:name="com.google.android.gms.analytics.CampaignTrackingReceiver"
                android:exported="true">
        <intent-filter>
          <action android:name="com.android.vending.INSTALL_REFERRER" />
        </intent-filter>
      </receiver>
      <service android:name="com.google.android.gms.analytics.CampaignTrackingService" />

      <!-- ... -->
  </application>
</manifest>

Applications can optionally provide a metadata reference to a global configuration XML resource file in the <application> element of the AndroidManifest.xml. For example:

<manifest>
  <application>
    <!-- ... -->

    <meta-data
      android:name="com.google.android.gms.analytics.globalConfigResource"
      android:resource="@xml/analytics_global_config" />

    <!-- ... -->
  </application>
</manifest>

2. Initialize Trackers

GoogleAnalytics is the top level Google Analytics singleton that provides methods for configuring Google Analytics and creating Tracker objects.

Applications can get an instance of this class by calling getInstance(Context). getInstance(Context) is thread safe and can be called from any thread. It is recommended that Google Analytics be initialized early in the application lifecycle to correctly report unhandled exceptions. Application. onCreate() is the recommended place for configuring Google Analytics.

A basic configuration of Google Analytics look like this:

package com.example;

class MyApp extends Application {
  public static GoogleAnalytics analytics;
  public static Tracker tracker;

  @Override
  public void onCreate() {
    analytics = GoogleAnalytics.getInstance(this);
    analytics.setLocalDispatchPeriod(1800);

    tracker = analytics.newTracker("UA-XXXXX-Y"); // Replace with actual tracker/property Id
    tracker.enableExceptionReporting(true);
    tracker.enableAdvertisingIdCollection(true);
    tracker.enableAutoActivityTracking(true);
  }
}

Enabling Advertising Features

Enabling Advertising Features in Google Analytics allows you to take advantage of Remarketing, Demographics & Interests reports, and more.

To enable advertising features requires a single addition to your Google Analytics tracking code to collect the advertising id. Call the enableAdvertisingIdCollection method on the tracker for which you want to enable advertising features. For example:

// Get tracker.
Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);

// Enable Advertising Features.
t.enableAdvertisingIdCollection(true);

The feature works by collecting the advertising identifier. Please make sure to review and adhere to all applicable SDK policies when using this feature.

3. Create a configuration XML file

Configuration settings can be managed using resources defined in XML. For example, if you have a global tracker you could create a file called global_tracker.xml in your project's res/xml directory and add the following resources:

<?xml version="1.0" encoding="utf-8" ?>
<resources>
  <!-- The application name. Defaults to name specified for the application label -->
  <string name="ga_appName">My App</string>

  <!-- The application version. Defaults to android:versionName specified in the AndroidManifest.xml -->
  <string name="ga_appVersion">1.0</string>

  <!-- The dispatching period in seconds when Google Play services is
       unavailable. The default period is 1800 seconds or 30 minutes -->
  <integer name="ga_dispatchPeriod">1800</integer>

  <!-- Enable dry run mode. Default is false -->
  <bool name="ga_dryRun">false</bool>
</resources>

See the configuration parameters reference for the complete list of parameters you can use to configure your implementation.

Your app is now setup to send data to Google Analytics.

4. Send an Event

To send an event, set the screen field values on the tracker, then send the hit.

The following example uses the HitBuilders.EventBuilder helper class to build a param map to pass to the send(Map) method:

GoogleAnalytics analytics = GoogleAnalytics.getInstance(context);
Tracker tracker = analytics.newTracker("UA-XXXX-Y"); // Send hits to tracker id UA-XXXX-Y

// All subsequent hits will be send with screen name = "main screen"
tracker.setScreenName("main screen");

tracker.send(new HitBuilders.EventBuilder()
       .setCategory("UX")
       .setAction("click")
       .setLabel("submit")
       .build());

// Builder parameters can overwrite the screen name set on the tracker.
tracker.send(new HitBuilders.EventBuilder()
       .setCategory("UX")
       .setAction("click")
       .setLabel("help popup")
       .setScreenName("help popup dialog")
       .build());

Next steps

You can do much more with Google Analytics, including measuring campaigns, in-app payments and transactions, and user interaction events.

Review the Mobile App Implementation Guide for an overview of how to use Google Analytics to measure user interactions and answer questions about app usage.

The following developer guides provide additional details on how to implement Google Analytics features in your app:

  • Demographics and Remarketing – Use Display Features to understand user demographic data like age/gender and create remarketing audiences for re-engaging users.
  • Measuring Events – Learn how to measure user engagement with interactive content like buttons, videos, and other media using Events.
  • Measuring In-App Payments – Learn how to measure in-app payments and transactions.
  • Measuring Campaigns – Learn how to implement campaign measurement to understand which channels and campaigns are driving app installs.
  • User timings – Learn how to measure user timings in your app to measure load times, engagement with media, and more.
  • Advanced Configuration – Learn more about advanced configuration options, including using multiple trackers.
  • Configuration Parameters – See the complete list of configuration parameters.