Testing Google Play Campaign Measurement

Andrew Wales, Google Analytics Mobile Developer Relations – June 2013

This document describes how to test a Google Play Campaign Measurement implementation in an Android application before publishing to the Google Play Store.

Introduction

Google Play Campaign Measurement is a feature of Google Mobile App Analytics that enables the attribution of native Android app installs to advertising campaigns and other marketing efforts in your Google Analytics app reports. Verifying that your Google Play Campaign Measurement implementation is working properly before the application is submitted to Google Play ensures that campaign measurement data is as accurate as possible at the time of launch.

This guide will illustrate one means of testing a Google Play Campaign Measurement implementation.

Before You Begin

Before using this guide to test a Google Play Campaign Measurement implementation, you will need the following:

Overview

The method of testing a Google Play Campaign Measurement implementation used in this guide involves the following steps:

  1. Preparing the Test Environment.
  2. Broadcasting an INSTALL_REFERRER intent to your application from the ADB Shell
  3. Verifying that the Google Analytics SDK has received the campaign data.

After following these steps, you'll be able to verify that your Google Analytics implementation is able to receive and report campaign information passed to Google Play.

Preparing the Test Environment

Before testing your Google Play Campaign Measurement implementation, take the following steps to prepare the testing environment:

  • Install the application on your test device or emulator.
  • Verify the application is not running.
  • Make sure you have a way to view logcat output from your test device.

Broadcasting an INSTALL_REFERRER Intent

The next step is to broadcast an INSTALL_REFERRER intent to your application that contains some Google Analytics campaign data. This is the same intent that the Google Play Store application broadcasts to your application after it is installed by a user.

To broadcast the INSTALL_REFERRER intent to your application:

  1. Verify that your application is not currently running.
  2. Open a terminal and run this command:
    $ cd <path_to_adb_tool>
    $ echo 'am broadcast \
        -a com.android.vending.INSTALL_REFERRER \
        -n "your.package.name/path.to.receiver" \
        --es "referrer" \
          "utm_source=test_source&utm_medium=test_medium&utm_term=test_term&utm_content=test_content&utm_campaign=test_name"; \
        exit' | ./adb shell
    

    Note that the ADB is generally located in your <sdk>/platform-tools/ directory. For example, if your application package was com.example.gatestapp and you were using the broadcast receiver provided by the Google Analytics SDK, you would use the following command:

    $ echo 'am broadcast \
        -a com.android.vending.INSTALL_REFERRER \
        -n "com.example.gatestapp/com.google.android.gms.analytics.CampaignTrackingReceiver" \
        --es "referrer" \
          "utm_source=test_source&utm_medium=test_medium&utm_term=test_term&utm_content=test_content&utm_campaign=test_name"; \
        exit' | ./adb shell
    

    If the intent was broadcast successfully, the command should return a message similar to this one:

    Broadcasting: Intent { act=com.android.vending.INSTALL_REFERRER cmp=com.example.analyticsecommtest/com.google.analytics.tracking.android.AnalyticsReceiver (has extras) }
    Broadcast completed: result=0
    

    If you do not see this message, the intent has not been broadcast and you will need to retry this step until you can successfully broadcast the intent.

Verifying the Campaign Data Was Received

The last step in testing is to open the application and verify in the Google Analytics SDK logs that the campaign information was successfully received. To verify that the campaign information was received:

  1. Run your application.
  2. If the campaign data was received properly, you can expect to see the SDK print a debug message using logcat similar to this one:
    GAv4    : Received installation campaign: source=testSource
    

If you see this success message in logs, congratulations! Your Google Play Campaign measurement implementation is working as expected. Note that you will still want to verify that your Google Play URLs are configured properly using the Google Play URL Builder.

On the other hand, if your Google Play Campaign Measurement implementation did not receive the campaign information, you'll see a message similar to this one:

Thread[GAThread,5,main]: No campaign data found.

This means that your Google Play Campaign Measurement implementation is not working correctly. Check out the Troubleshooting section to learn about next steps.

Troubleshooting

There are several common reasons for a Google Play Campaign Measurement test to fail. This section highlights those common points of error and provides next steps for resolving them.

Debug output is not enabled

If you don't see any messages from the Google Analytics SDK, you'll need to verify that you've implemented the SDK and that you've set the LogLevel to VERBOSE (v3.x) or enabled debug mode (v2.x).

The INSTALL_REFERRER intent was not broadcast

In order for the test to succeed, you must successfully broadcast an INSTALL_REFERRER intent to your application from the Android Debug Bridge. If you're not sure that the intent was broadcast successfully, return to the Broadcast section of this guide and rerun the test, verifying that you used the correct command and are seeing the broadcast success message returned.

The Google Analytics Receiver did not receive the intent

The Google Analytics SDK provides a receiver, CampaignTrackingReceiver, that must receive the INSTALL_REFERRER in order for any campaign data to be passed from Google Play to your Google Analytics reports. If the CampaignTrackingReceiver never receives the intent, the campaign data will not be recorded in Google Analytics. There are two main reasons the CampaignTrackingReceiver may not be receiving the intent:

  1. The CampaignTrackingReceiver is not implemented in the application. Learn how to implement the Google Analytics receiver.
  2. The CampaignTrackingReceiver is implemented, but another receiver is receiving the INSTALL_REFERRER instead. This happens when an application has more than one broadcast receiver registered to handle the INSTALL_REFERRER intent.

    If your application has two receivers registered for this intent, it is recommended that you create a custom receiver that can receive the INSTALL_REFERRER intent and dispatch it to other receivers, including the Google Analytics receiver, as necessary. Here's an example of a simple receiver to accomplish this:

    // This example uses Google Analytics SDK for Android v3.x implementation
    package com.example.gatestapp;
    
    import android.content.BroadcastReceiver;
    import android.content.Context;
    import android.content.Intent;
    
    import com.google.analytics.tracking.android.CampaignTrackingReceiver;
    
    /*
     *  A simple Broadcast Receiver to receive an INSTALL_REFERRER
     *  intent and pass it to other receivers, including
     *  the Google Analytics receiver.
     */
    public class CustomReceiver extends BroadcastReceiver {
    
      @Override
      public void onReceive(Context context, Intent intent) {
    
        // Pass the intent to other receivers.
    
        // When you're done, pass the intent to the Google Analytics receiver.
        new CampaignTrackingReceiver().onReceive(context, intent);
      }
    }