Android Market (Google Play) Campaign Analytics

1) Introduction
2) Implementation
3) Testing
4) Viewing

Introduction

The Android OS supports URL parameters in download links to Google Play (formerly Android Market). These parameters can be captured with Localytics to automatically populate campaign information. This enables the source of the application install to be recorded and associated with future app sessions, retention analysis and custom events, which is critical for understanding the performance of current campaigns and optimization of future campaigns.

Implementing Google Play Campaign Tracking

There are three steps required to enable campaign tracking in an application already using Localytics.

1. Create a receiver to capture and store the installation intent containing the referral information
2. Fire an event with the stored data whenever the application is launched
3. Create a URL containing referral information

1) Create a receiver

Android will fire an intent called: com.android.vending.INSTALL_REFERRER during the application install process. This occurs before the application is launched for the first time. The code below demonstrates how to receive this intent and store the data in the application’s SharedPreferences. The details of how the values are persisted is abstracted out so they can be replaced with another mechanism if the application is already doing something different:

package your.pacakage.name.here

public class ReferralReceiver extends BroadcastReceiver
{
    @Override
    public void onReceive(Context context, Intent intent)
    {
        // Workaround for Android security issue: http://code.google.com/p/android/issues/detail?id=16006
        try
        {
            final Bundle extras = intent.getExtras();
            if (extras != null) {
                extras.containsKey(null);
            }
        }
        catch (final Exception e) {
            return;
        }

        Map<String, String> referralParams = new HashMap<String, String>();

        // Return if this is not the right intent.
        if (! intent.getAction().equals("com.android.vending.INSTALL_REFERRER")) { //$NON-NLS-1$
            return;
        }

        String referrer = intent.getStringExtra("referrer"); //$NON-NLS-1$
        if( referrer == null || referrer.length() == 0) {
            return;
        }

        try
        {    // Remove any url encoding
            referrer = URLDecoder.decode(referrer, "UTF-8"); //$NON-NLS-1$
        }
        catch (UnsupportedEncodingException e) { return; }

        // Parse the query string, extracting the relevant data
        String[] params = referrer.split("&"); // $NON-NLS-1$
        for (String param : params)
        {
            String[] pair = param.split("="); // $NON-NLS-1$
            referralParams.put(pair[0], pair[1]);
        }

        ReferralReceiver.storeReferralParams(context, referralParams);
    }

    private final static String[] EXPECTED_PARAMETERS = {
        "utm_source",
        "utm_medium",
        "utm_term",
        "utm_content",
        "utm_campaign"
    };
    private final static String PREFS_FILE_NAME = "ReferralParamsFile";

    /*
     * Stores the referral parameters in the app's sharedPreferences.
     * Rewrite this function and retrieveReferralParams() if a
     * different storage mechanism is preferred.
     */
    public static void storeReferralParams(Context context, Map<string, String> params)
    {
        SharedPreferences storage = context.getSharedPreferences(ReferralReceiver.PREFS_FILE_NAME, Context.MODE_PRIVATE);
        SharedPreferences.Editor editor = storage.edit();

        for(String key : ReferralReceiver.EXPECTED_PARAMETERS)
        {
            String value = params.get(key);
            if(value != null)
            {
                editor.putString(key, value);
            }
        }

        editor.commit();
    }

    /*
     * Returns a map with the Market Referral parameters pulled from the sharedPreferences.
     */
    public static Map<string, String> retrieveReferralParams(Context context)
    {
        HashMap<String, String> params = new HashMap<String, String>();
        SharedPreferences storage = context.getSharedPreferences(ReferralReceiver.PREFS_FILE_NAME, Context.MODE_PRIVATE);

        for(String key : ReferralReceiver.EXPECTED_PARAMETERS)
        {
            String value = storage.getString(key, null);
            if(value != null)
            {
                params.put(key, value);
            }
        }
        return params;
    }
}

In order for this intent to be captured, the manifest needs to be updated so the receiver is registered. Inside the block of AndroidManifest.xml add your receiver:

        <receiver android:name="your.package.name.here.ReferralReceiver" android:exported="true">
              <intent-filter>
                <action android:name="com.android.vending.INSTALL_REFERRER" />
              </intent-filter>
        </receiver>

2) Tag the application

In your application’s startup, tag an event with the referral information. Assuming your session object is called ‘session’ do the following:

session.tagEvent(“Application Launched”, ReferralReceiver.retrieveReferralParams(this.getApplicationContext()));

If possible, it would be good to fire a duplicate to this event the very first time the application is launched, called “First Launch.”

3) Construct a URL

To set up Localytics campaign tracking through Google Play, you must generate a referral link. Use the link to refer users to your application. Localytics will automatically parse and record the referral information and populate it in your reports.

To generate the referral link, use the package name (eg, com.example.applications) for your app and the referral link parameters in the following table.

Parameter	Required	Description	Example(es)
utm_source	Yes	Campaign source; used to identify a search engine, newsletter, or other source	utm_source=google
utm_medium	Yes	Campaign medium; used to identify a medium such as email or cost-per-click (cpc)	utm_medium=cpc
utm_term	No	Campaign term; used with paid search to supply the keywords for ads	utm_term=running+shoes
utm_content	No	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
utm_campaign	Yes	Campaign name; used for keyword analysis to identify a specific product promotion or strategic campaign	utm_campaign=spring_sale

This is a sample URL that will pass referring information to Localytics:

http://market.android.com/details?id=com.example.applications&referrer=utm_source%3Dsourcename %26utm_medium%3Dmediumname%26utm_term%3Dtermsused%26utm_campaign%3Dcampaignname

You may also use the following URL creation tool:

Package Name: *	(Java package, e.g. *com.example.application*)
Campaign Source: *	(original referrer, e.g. *google, citysearch, newsletter4*)
Campaign Medium: *	(marketing medium, e.g. *cpc, banner, email*)
Campaign Term:	(paid keywords, e.g. *running+shoes*)
Campaign Content:	(ad-specific content used to differentiate ads)
Campaign Name: *	(product, promotion code, or slogan)

Testing Referral Tracking

The definitive test is to submit the application to the market, construct a URL, and see the data on the Localytics Dashboard. This isn’t practical during development so the easiest way to do this is to use adb to send the installation intent. Once connected via adb shell the following command will send the intent:

am broadcast -a com.android.vending.INSTALL_REFERRER -n your.pacakage.name.here/.ReferralReceiver --es "referrer" "utm_source=test_source&utm_medium=test_medium&utm_term=test_term&utm_content=test_content&utm_campaign=test_name"

Viewing the data

The result of all this work will be a new event in your Localytics Dashboard called “Application Launched”. This event will have attributes for each of the parameters present in the referral URL. With this event it is possible to see what sources users of the application are coming from in any time period.