How to Track Play Store Campaign Codes

The new Android app that some of your colleagues are currently building has to be tracked. Fortunately, your organisation is mature, has therefore thought about this well in advance and as a result you are well under way with your analytics implementation.

(Note: if you are still wondering about how to implement in a mobile app, may I recommend my mini series on analysing mobile apps?)

But all of a sudden your friendly marketer tells you that they need to track “the full user journey”, and now you are a bit flummoxed. What does that even mean?

In all likelihood what she wants is a report like this one:

The report will tell her whether the emails she sent out to get people to download, install and eventually use the app are working or not. It will tell her that the “App v1.2 update available” email had a rate of “Emails” to “App installs” of 6%, significantly better than the others.

How does that work, technically?

Google Play Campaigns

Google’s Play Store is unique in the sense that it allows campaign tracking to pass through from the store all the way into the app.

Meaning: if your marketer sends visitors to the app’s page on the Play Store with tracking codes on the URL (the usual Google codes apply), Android (or rather Google Play Services) will pass those into the app when it installs it.

That in turn allows you to track them into Adobe Analytics (or any other analytics tool, of course).

The story goes like this:

1. Friendly marketer creates URL to app on Play Store, like so: 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
2. Friendly marketer sends email blast with that link
3. Visitor clicks link and lands on the app’s page on the Play Store
4. Visitor now install the app
5. Play Services on Android device receives APK and installs it
6. Play Services on device “broadcasts” an Intent to the app — a com.android.vending.INSTALL_REFERRER Intent, to be exact
7. Intent contains an “Extra” of type String named “referrer” that contains the above
8. A BroadcastReceiver in your app can use the Intent, extract the data and track it

Easy? Yup. Let’s make an example.

Code (simple)

Most of this comes straight from the manual pages (Adobe: Google Play Campaign Tracking (v3.1+), Google Play Campaign Tracking (v4.x+) & Google: Campaign Measurement – Android SDK, Testing Google Play Campaign Measurement), errors are entirely my fault.

I show you how to build a rudimentary app, as simple as possible, with just enough code in it to grab the campaign parameters and track them.

For that, we will need two things: an Activity so that we can launch the app and track the launch, and a BroadcastReceiver that picks up the Intent after installation.

So go ahead, create an Android project containing one Activity.

Next we need the Adobe Marketing Cloud library, which we can find on the Developer Connection. Extract adobeMobileLibrary.jar and ADBMobileConfig.json somewhere. Add adobeMobileLibrary.jar as an external library (also select it on the Order and Export tab!). Copy ADBMobileConfig.json into the assets folder in your project.

For the tracking to work, add android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE permissions to your AndroidManifest.xml file.

Customize your ADBMobileConfig.json file. For Analytics, all we really need is one or more report suite ID in the rsids field, and of course a tracking server in the server field.

Tip: you can find the value for server if you look at your web site, provided the site is being tracked. Load a page, look for an HTTP request containing /b/ss/ in the URL, then use the host part of that URL.

Your friendly marketer must enable mobile application reporting for the report suite. Note that you can test all of your work before he has done that.

Let’s add some code now.

The library wants to be configured when the app starts, therefore we add a call to Config.setContext(this.getApplicationContext()) to the onCreate method of the app. We also add Config.collectLifecycleData() to the onResume method and Config.pauseCollectingLifecycleData() to onPause.

Technically this is all we need for tracking. Meaningful analytics would definitely be more involved than this, but for our purposes the Activity is now ready. It should look like this:

package com.exner.test.jeapptrackingtest;

import android.app.Activity;
import android.os.Bundle;

import com.adobe.mobile.Config;

public class MainActivity extends Activity {

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.activity_main);

		// set context for Mobile Analytics
		Config.setContext(this.getApplicationContext());

		// for debugging
		Config.setDebugLogging(true);
	}

	@Override
	protected void onPause() {
		super.onPause();

		// pause collection of lifecycle metrics
		Config.pauseCollectingLifecycleData();
	}

	@Override
	protected void onResume() {
		super.onResume();

		// collect lifecycle metrics
		Config.collectLifecycleData();
	}

}

Next we create a class that extends BroadcastReceiver. The onReceive method in our class will be called when the app is installed on a device, and this is where we can pick up the campaign parameters that our friendly marketer has added to the URL to Google Play.

All we need is a call to Analytics.processReferrer(context, intent) in the onReceive method. This is what it’ll look like:

package com.exner.test.jeapptrackingtest;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

import com.adobe.mobile.Analytics;

public class InstallBroadcastReceiver extends BroadcastReceiver {

	@Override
	public void onReceive(Context context, Intent intent) {
		Analytics.processReferrer(context, intent);

		// DEBUG - show the referrer
		String referrer = intent.getStringExtra("referrer");
		Log.d("JE", "Referrer is: " + referrer);
	}

}

The call to processReferrer will grab the campaign parameters from the Intent and store them. No tracking happens at this time!

I added some debugging to the method. You can’t set a breakpoint in the onReceive method, because when this code is executed, your app won’t actually be debuggable!

The BroadcastReceiver needs to be exported in the manifest, of course, so let’s add it. The AndroidManifest.xml should now look like this:

Right. Our Activity is instrumented, we have a BroadcastReceiver that gets the campaign information, and the manifest is complete.

Now to the fun part.

Debugging

Here comes the fun complicated part. Debugging this is slightly tricky.

The main limitation is that in order for the campaign data to be sent, the following steps need to happen in order. No shortcuts!

1. Completely remove app from emulator or testing device
2. Push app to emulator or device but do not start it
3. Broadcast the Intent (either via ADB or however you like)
4. Now launch the app

Two crucial pieces of information: the referrer data from the Intent in the broadcast will only be sent on first launch! In order for data to be sent, utm_campaign, utm_medium & utm_source must be set in the URL!

I spent half a day testing and not seeing anything before I knew this, so chances are if you are reading this you will save a lot of time. You’re welcome.

Other than that, debugging is straight-forward: just look at Logcat output.

Let me walk you through the steps.

Firstly, you will need to load the APK for your app onto the device without running it.

I did not find a way of doing this using eclipse, so I basically used adb to install the APK manually every time I changed something.

(Can’t find an APK for your app? Go to preferences > Android > Build and untick the “Skip packaging and dexing …” option.)

Now launch your emulator or plug in your test device, then go to your platform-tools folder and install the APK.

adb install \dev\jeapptrackingtest\bin\JEAppTrackingTest.apk

Do NOT run it at this point!

For a normal user, the app would be installed via the Play Store. After installation, the Google Play Services on the phone would send the com.android.vending.INSTALL_REFERRER broadcast to the app, so this is what we need to do now.

Again we will use ADB here, although theoretically you should be able to write a small app that sends the broadcast.

adb shell am broadcast -a com.android.vending.INSTALL_REFERRER
    -n com.exner.test.jeapptrackingtest/.InstallBroadcastReceiver
    --es  "referrer" "utm_source=testSource&utm_medium=testMedium&utm_term=testTerm&utm_content=testContent&utm_campaign=testCampaign"

If you do this right (and I had to add “\” before the “&”s in the referrer), you should see the whole referrer in LogCat, like so:

Now you can launch your app and see whether the tracking picks up the campaign information and sends it in. Again, that should be visible in LogCat.

Note

One important thing: if you want to test this again, you have to remove the app completely from your emulator or device before you try again!