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:
- Google Play Campaign Measurement - See which campaigns, websites, and apps referred a user to your app's Google Play Store page to download your app.
- Measuring General Campaigns - See which campaigns or traffic sources launched your app it was installed.
- Measuring Referrals - See which referring traffic source, such as websites or other apps, launched your app after it was installed.
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:
- 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.
- 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. - 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 moreBroadcastReceivers
from different SDKs, you will need to create your ownBroadcastReceiver
class that will receive all broadcasts and call the appropriateBroadcastReceivers
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.