Mobile App Download Tracking with Adobe Analytics

[#1]

This article will guide you through how to configure Tealium on an Android and/or iOS mobile app so you can properly track app downloads via Adobe Analytics or another analytics software, like Google Analytics. 

In this article:

Table of Contents Placeholder

The Problem

Tracking mobile app downloads and attributing downloads to marketing/ad spend is a tricky business, and is made more complicated by the fact that the different mobile operating systems do not handle the information in the same way.

The Solution

On Android, Google provides a handy referrer string to the app on first launch (known as "Install Referrer"), which provides standard Google "utm" campaign parameters in URL format that can be retrieved by your app developer and passed to third party analytics tools. On iOS, however, Apple does not provide this information, so the only way to get it is by device "fingerprinting", which attempts to identify a device by generating a hash from elements in the HTTP header information passed to the server (in Adobe's solution, they use the IP address and browser User Agent string to identify a device, with a 10 minute expiry time). Because of this limitation on iOS, acquisition information on iOS will always be less accurate than on Android. It is conceivable that within the 10 minute attribution "window", 2 users with the same user agent and IP address could download the same app (if, for example, they were both connecting through an HTTP proxy server). In this case, only the first user to launch the app would receive the attribution data. This situation could not arise on Android, because every download is uniquely tied to an individual device.

Download Flow

iOS

Ad -> Adobe Acquisition V3 -> [Device Fingerprint stored by Adobe] -> iOS App Store -> App downloaded -|END|

App Launch -> App sends beacon to Adobe Acquisition server -> Adobe responds with campaign information relating to this download on the device -> Data passed to Adobe Analytics with a lifecycle hit as context data -|END| 

Android

Ad -> Adobe Acquisition V3 -> [Unique one-time code generated by Adobe] -> Google Play store with UTM parameters -> App downloaded -|END|

App Launch -> Broadcast Receiver receives INSTALL_REFERRER intent, containing utm parameters and one-time code -> App sends one time code to Adobe Acquisition V3 -> Adobe responds with campaign information -> Data passed to Adobe Analytics with a lifecycle hit as context data -|END|

Full Description of the Process on Android

For Android, the process is slightly different:

1. Adobe link goes through to the Play Store and passes a "utm_content" parameter containing a unique ID
2. App is launched. App receives INSTALL_REFERRER intent containing utm_content parameter with unique Adobe ID
3. App makes a call to:
   http://c00.adobe.com/v3/<app_id>/end?a_ugid=<Unique_ID from utm_content>
4. Adobe returns acquisition data to the app
5. Callback fires and passes data to Adobe Analytics

Tealium Configuration to Support Acquisition Tracking

Usually, Adobe's Enterprise Cloud SDK would handle the acquisition process automatically via the Adobe SDK, but since Tealium does not require the Adobe SDK, we have to add some special config in Tealium iQ Tag Management to make this work. On iOS, no additional code is required in your app, but on Android, you will need to implement a Broadcast Receiver for the INSTALL_REFERRER intent. Please note that you can only have a single Broadcast Receiver listening for the INSTALL_REFERRER Intent, so if you have a requirement to trigger multiple Broadcast Receivers, you will need to implement a generic one, which will in turn trigger each Broadcast Receiver available in the app. Please see here for more info: http://stackoverflow.com/questions/9694639/more-than-one-broadcastreceiver-for-the-same-intent-with-...

To assist with this, Tealium has provided an acquisition helper framework, which will set up the broadcast receiver for you. This can be found on the Tealium GitHub pages in the "support" directory.
https://github.com/Tealium/tealium-android/tree/master/Support/InstallReferrer 

Tag Configuration Requirements and Instructions

1. Log in to Tealium iQ and add a new tag: "Custom Remote Command"
2. Set the "Command ID" field in the tag's user interface to "_http".
   This tells the Custom Remote Command  system to make an HTTP request.
3. To tell the tag which URL we wish to call, we need to add a few variables to the profile, which we'll set using extensions.
   Refer to the list of required variables below.
4. Add a Load Rule to the Custom Remote Command tag:
    utag_main_adobe_attribution is not defined
   This will ensure the tag only gets called once or until the acquisition data was returned successfully from Adobe.

Required Variables

The following variables are required:

• Callback – recommended variable name "callback"
  The callback function that will send the data to the Adobe Analytics tag
• URL – recommended variable name "acq_url"
  The URL that will be called to retrieve the acquisition campaign info
• Method – recommended variable name "acq_method"
  The HTTP method we'll be calling to retrieve the data. In this case, it will be "GET".
• Headers – recommended variable name "acq_headers"
  The HTTP header information we want to pass along with the request. This mapping accepts a JavaScript Object (JSON). Adobe matches based on User-Agent, so we need to ensure the Remote Command system has the correct User-Agent header set on the request.
• Install Referrer – recommended variable name "install_referrer"
• [First Party Cookie] utag_main_adobe_attribution – used to store acquisition data in a cookie to ensure the data is only sent to Adobe once. 

Extension Requirements and Instructions

 iOS Instructions

Use the following steps for iOS:

1. Add a "Set Data Values" extension, and select the three (3) new variables we created above as the target.
   The variables should be set to the following values:
   

   acq_method = [Text Value] -> GET
   acq_headers = [JS Code] -> {'User-Agent' : navigator.userAgent};
   acq_url = [Text Value] -> https://c00.adobe.com/v3/<app_id>/end

2. Add the following condition to the extension:

   ' platform' contains (ignore case) 'ios'

   

Android Instructions

Use the following steps for Android: 

1. Add a Set Data Values Extension, and select the three (3) new variables we created above as the target.
   They should be set to the following values, and in the following order:
   

   install_referrer = [JS Code] -> b.install_referrer.split("utm_content=")[1].split("&")[0];
   acq_method = [Text Value] -> GET
   acq_headers = [JS Code] -> {'User-Agent' : navigator.userAgent};
   acq_url = [JS Code] -> "https://c00.adobe.com/v3/<app_id>/end?a_ugid=" + b.install_referrer

2. Add the following condition to the extension:
   

   ' platform' contains (ignore case) 'android' AND install_referrer is populated
   

   

   The contents of these URLs are static for all Adobe clients, with the exception of the Tracking ID (long alphanumeric string between /v3/ and /end). This string is available in the Adobe Mobile Services UI.
   To get it, you must have added your app to the Mobile Services UI, then navigate to the SDK Acquisition Options config box and click More Details.
   

Add Callback Extension

Add a JavaScript Code Extension, scoped to the Custom Remote Command tag. This will contain our callback function which allows us to send the acquisition data returned from the Adobe servers to any endpoint we like (e.g. Adobe Analytics served through Tealium iQ Tag Manager)

Add the following code to the JavaScript Extension. Feel free to customize the code to change what happens with the attribution data. Currently, the data is sent via a utag.link call to a specified tag ID, and also persisted in a first-party cookie for the duration of the session for future reference. 

b.callback = function (code, body) {
 // var tag_id = null; // this will not fire any tags when the callback runs
 var tag_id = ['3', '5']; // this will fire tag with UID 3 and 5 when the callback runs
 if (body && body.toString().indexOf('null') === -1) {
 var context_data = JSON.parse(body).contextData;
 if (context_data) {
 utag.loader.SC('utag_main', {'adobe_attribution' : JSON.stringify(body)}); // store attribution data in utag_main cookie for later use
 var adobe_referrer_campaignname = context_data['a.referrer.campaign.name'];
 var adobe_referrer_trackingcode = context_data['a.referrer.campaign.trackingcode'];
 if (tag_id === null) {
 // fire attribution hit to all tags
 utag.link({ 
 "adobe_attribution" : JSON.stringify(body),
 "adobe_referrer_campaignname" : adobe_referrer_campaignname,
 "adobe_referrer_trackingcode" : adobe_referrer_trackingcode,
 "link_name" : "acquisition"
 });
 } else {
 utag.link({
 "adobe_attribution" : JSON.stringify(body),
 "adobe_referrer_campaignname" : adobe_referrer_campaignname,
 "adobe_referrer_trackingcode" : adobe_referrer_trackingcode,
 "link_name" : "acquisition"
 }, null, tag_id);
 }
 }
 }
};

Tag Mappings

Custom Remote Command Tag

acq_url -> url
acq_method -> method
acq_headers -> headers

callback -> callback_function

Adobe Analytics Tag Mappings (tag version AppMeasurement for JS 1.6.3)

link_name -> link_name
adobe_referrer_trackingcode -> contextData.a.referrer.campaign.trackingcode
adobe_referrer_campaignname -> contextData.a.referrer.campaign.name

The variables can also be mapped to other tags, such as Google Analytics, and the same acquisition data can also be sent to these tags.

If the "ClearVars" option is not set in the Adobe config, the campaign data will be sent on every Adobe request until the app is restarted

Testing

iOS Testing

Use the following steps for iOS testing. No additional tools or software is required.

1. Open the following link in the Safari browser on your iDevice
   https://c00.adobe.com/v3/<app_id>/start?a_i_id=964656807&a_dd=i&ctxa.referrer.campaign.name=testcamp...
2. Substitute the following values for your own:
   • a_i_id
     The Apple application ID that uniquely identifies your app on the App Store
   • Tracking Code and Campaign Name|
     (Optional) The trackingcode and campaign name parameters can be substituted for your own values if you wish
   • The Adobe Tracking ID
     Long string between /v3/ and /start

     You must obtain this from the Adobe Analytics console.

     
     
3. Ensure you have correctly configured Tealium iQ, and then launch the app on your device. If you have configured TiQ correctly, you'll see a hit going out to Adobe Analytics with your campaign data attached, link name (pev2 param) "acquisition"
   See also: https://marketing.adobe.com/resources/help/en_US/mobile/ios/t_testing-version-3-acquisition.html

Android Testing

Use the following steps for Android testing. These steps require the Tealium InstallReferrer module and Android Studio.

1. Follow an Adobe acquisition link to the Google Play Store. Note the utm parameters that are passed to the Play Store URL.
   Example Adobe link:

   https://c00.adobe.com/v3/<app_id>/start?a_g_id=com.tealium.digitalvelocity&a_dd=g&ctxa.referrer.camp...
   

   This MUST be done on your Android device. Once your device has followed the link, copy the long string in the "utm_content" parameter that Adobe passed to the Play store, e.g:  https://play.google.com/store/apps/details?id=com.tealium.digitalvelocity&referrer=utm_campaign%3Dad... The parameters are URL-encoded, and %3D is an equals symbol. Be sure not to include this in the string you copy down.

2. Launch the app.
3. Paste the following into your terminal (uses ADB - Android Debug Bridge).
   

   am broadcast -a com.android.vending.INSTALL_REFERRER -n 
   "com.tealium.blankapp/com.tealium.installreferrer.InstallReferrerReceiver"
   --es "referrer"
   "utm_source=<source_from_adobe>&utm_medium=<medium_from_adobe>&utm_term=<term_from_adobe>&utm_content=46b25e284dc36d5a7ef8f0e6b393febe3fcc8327&utm_campaign=<name_from_adobe>"; 

Be sure to substitute "com.tealium.blankapp" for the fully-qualified package name of your app (e.g. com.yourcompany.appname). Also ensure that you substitute the value passed to utm_content for the actual value you saved earlier on.

Example Adobe Analytics hit (dummy campaign data "name" for campaign name and "trackingcode" for tracking code: