Campaign Measurement - Android SDK v2 (Legacy)

This document provides an overview of how to measure campaigns and traffic sources with the Google Analytics SDK for Android v2.

Overview

Measuring campaigns in Google Analytics can help you improve the value of your marketing channels by enabling the attribution of campaigns and traffic sources to user activity within your application.

There are several kinds of campaign measurement available in the Google Analytics SDK for Android:

The following sections will describe when and how to implement each type of campaign measurement in your app.

Google Play Campaign Measurement

Google Play Campaign Measurement allows you to see which campaigns and traffic sources are sending users to download your app from the Google Play Store. We recommend that all developers implement Google Play Store Campaign Measurement.

How Google Play Campaign Measurement works

Google Play Store Campaign Measurement relies on the use of Campaign Parameters to pass campaign and traffic source information into your app at the time that it is downloaded from the Google Play Store.

The following is an end-to-end description of how Google Play Campaign Measurement works:

  1. A user clicks on a link, from an ad, website, or app, that takes them to your app's Google Play Store page. The link is tagged with Campaign Parameters.
  2. After the user downloads and installs your app, the Google Play Store will broadcast an INSTALL_REFERRER intent on the device that includes those same campaign parameters.
  3. Your app will then respond to that intent, using the BroadcastReceiver object provided below, reading the campaign parameters and using them to update the Google Analytics campaign information.

Implementing Google Play Campaign Measurement

To implement Google Play Store Campaign Measurement:

1. Add a new BroadcastReceiver to your AndroidManifest.xml file

The following BroadcastReceiver allows your app to respond to the INSTALL_REFERRER intent broadcast by the Google Play Store when your app is installed. Add it to your AndroidManifest.xml file as follows:

<!-- Used for install referral measurement-->
<service android:name="com.google.analytics.tracking.android.CampaignTrackingService"/>
<receiver android:name="com.google.analytics.tracking.android.CampaignTrackingReceiver" android:exported="true">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

2. Add campaign parameters to your Google Play Store links

Campaign Parameters are used to pass information about the campaign or traffic source that referred a user to your app's Google Play Store page into your app's Google Analytics implementation.

To learn how to build a campaign parameter string, use the Google Play URL Builder, or consult the Campaign Parameters reference section.

Once you've built your campaign parameter string, add it to your Google Play Store URLs as the value of the referrer parameter, as in this example:

https://play.google.com/store/apps/details?id=com.example.app
&referrer=utm_source%3Dgoogle
%26utm_medium%3Dcpc
%26utm_term%3Drunning%252Bshoes
%26utm_content%3DdisplayAd1
%26utm_campaign%3Dshoe%252Bcampaign

The Google Play Store will only pass the value of the referrer parameter to your app's Google Analytics implementation, so it's important to make sure it is present in your Google Play Store links.

Measuring General Campaigns

General campaign measurement can be used to associate a campaign or traffic source with a user after they've already installed your app.

For example, if you were running a paid campaign to reach existing users who have already installed your app, you could use general campaign measurement to measure which app launches were the result of that campaign.

Implementing General Campaign Measurement

To set campaign values for a general campaign, call setCampaign() and pass a campaign parameter string as an argument.

A typical implementation might call setCampaign() when the app is launched and check the intent that launched it to see if there are valid campaign parameters present:

public class SampleActivity extends Activity {

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

    // Get the intent that started this Activity.
    Intent intent = this.getIntent();
    Uri uri = intent.getData();

    // Call setContext() here so that we can access EasyTracker
    // to update campaign information before calling activityStart().
    EasyTracker.getInstance().setContext(this);

    if (intent.getData() != null) {
      EasyTracker.getTracker().setCampaign(uri.getPath());
    }
    ... // The rest of your onCreate() code.
  }

  @Override
  public void onStart() {
    super.onStart();
    EasyTracker.getInstance().activityStart(this);
    ... // The rest of your onStart() code.
  }


  @Override
  public void onStop() {
    super.onStop();
    EasyTracker.getInstance().activityStop(this);
    ... // The rest of your onStop() code.
  }
}

Measuring Referrals

Referral measurement is similar to other types of campaign measurement in that it allows you to measure a referring source that launched your app on a user's device. However, referral measurement uses a simple string like "google.com" or "myOtherApp", rather than a string of campaign parameters.

When you set a referring source, like "google.com", the source dimension is set to "google.com", while the medium dimension is implicitly set to "referrer"

As with campaign measurement, set a referring source will, by default, cause the next send call to start a new session.

In the following code snippet, we assume that you have tagged any links that would open your app with either Google Analytics campaign parameters, or with a simple referrer parameter describing the referring source. If the referrer parameter is present in the absence of other campaign parameters, the user's campaign information is updated with new referring source:

public class SampleActivity extends Activity {

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

    // Get the intent that started this Activity.
    Intent intent = this.getIntent();
    Uri uri = intent.getData();

    // Call setContext() here so that we can access EasyTracker
    // to update campaign information before activityStart() is called.
    EasyTracker.getInstance().setContext(this);

    if (uri != null) {
      if(uri.getQueryParmeter("utm_source") != null) {    // Use campaign parameters if avaialble.
        EasyTracker.getTracker().setCampaign(uri.getPath());
      } else if (uri.getQueryParameter("referrer") != null) {    // Otherwise, try to find a referrer parameter.
        EasyTracker.getTracker().setReferrer(uri.getQueryParameter("referrer"));
      }
    }
  }


  @Override
    public void onStart() {
    super.onStart();
    EasyTracker.getInstance().activityStart(this);
    ... // The rest of your onStart() code.
  }


  @Override
  public void onStop() {
    super.onStop();
    EasyTracker.getInstance().activityStop(this);
    ... // The rest of your onStop() code.
  }
}

Known Issues

  • The javadoc for CampaignTrackingReceiver uses an incorrect class path in its usage example. See Implementing Google Play Campaign Measurement for the correct usage.
  • Only one BroadcastReceiver class can be specified per app. Should you need to incorporate two or more BroadcastReceivers from different SDKs, you will need to create your own BroadcastReceiver class that will receive all broadcasts and call the appropriate BroadcastReceivers for each type of broadcast.
  • Google Play Campaign Measurement does not currently support web-to-device installs initiated from the web Play Store.

Campaign Parameters

Campaign parameters are used to pass information about the traffic sources and campaigns that are bringing users to your app.

  • In general campaign measurement, an unencoded campaign parameter string is passed as an argument to setCampaign() .
  • In Google Play Campaign Measurement, a referrer parameter with an encoded campaign parameter string as its value is appended to any URLs that point to your app's Play Store page.

The following is an example of a valid, unencoded campaign string that could be used for general campaign measurement:

"utm_campaign=my_campaign&utm_source=google&utm_medium=cpc&utm_term=my_keyword&utm_content=ad_variation1"

The table below shows the complete list of the available campaign parameters that can be used in Google Play or general campaign measurement.

Parameter Description Example(s)
utm_campaign Campaign name; used for keyword analysis to identify a specific product promotion or strategic campaign utm_campaign=spring_sale
utm_source Campaign source; used to identify a search engine, newsletter, or other source utm_source=google
utm_medium Campaign medium; used to identify a medium such as email or cost-per-click (cpc) utm_medium=cpc
utm_term Campaign term; used with paid search to supply the keywords for ads utm_term=running+shoes
utm_content Campaign content; used for A/B testing and content-targeted ads to differentiate ads or links that point to the same URL utm_content=logolink
utm_content=textlink
gclid Google Ads autotagging parameter; used to measure Google Ads. This value is generated dynamically and should never be modified.

Google Play URL Builder

Use the Google Play URL Builder to generate URLs for Google Play Campaign Measurement.