Mobile App Download Tracking with Adobe Analytics

Mobile App Download Tracking with Adobe Analytics

by on ‎04-25-2017 04:36 PM - edited on ‎04-26-2017 07:15 PM by Community Manager (1,331 Views)

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. 

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 Marketing 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: "TagBridge Custom Command"
  2. Set the "Command ID" field in the tag's user interface to "_http". This tells the TagBridge 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. Please refer to the list of required variables below.
  4. Add a Load Rule to the TagBridge Custom 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:


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 TagBridge 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.

 

aa_tag_config.pngTealium iQ - Tag Management 2017-03-24 09-10-08.png

Extension Requirements and Instructions

iOS

  1. Add a "Set Data Values" extension, and select the 3 new variables we created above as the target. They 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'

    aa_ios_extension.png

Android

 

  1. Add a Set Data Values Extension, and select the 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
    Tealium iQ - Tag Management 2017-03-24 08-53-33.png

 

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"

 

Adobe App Acquisition Tracking - Google Docs 2017-03-24 08-56-39.png

Add Callback Extension

Add a JavaScript Code Extension, scoped to the TagBridge Custom 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 bodyTxt = JSON.stringify(body);
     if (body.contextData) {
       // store attribution data in utag_main cookie for later use
       utag.loader.SC('utag_main', {'adobe_attribution': bodyTxt});
       var adobe_referrer_campaignname = body.contextData['a.referrer.campaign.name'];
       var adobe_referrer_trackingcode = body.contextData['a.referrer.campaign.trackingcode'];
       var obj = {
         "adobe_attribution": bodyTxt,
         "adobe_referrer_campaignname": adobe_referrer_campaignname,
         "adobe_referrer_trackingcode": adobe_referrer_trackingcode,
         "link_name": "acquisition",
         "timestamp": new Date().toISOString()
       };
       if (tag_id === null) {
         // fire attribution hit to all tags
         utag.link(obj);
       } else {
         utag.link(obj, null, tag_id);
      }
    }
  }
};

 

Tag Mappings

TagBridge Custom Command Tag

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

callback -> callback_function

 

Tealium iQ - Tag Management 2017-03-24 09-09-08.png

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

 

Tealium iQ - Tag Management 2017-03-24 09-12-11.png

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

Please note that 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 (no additional tools or software 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...

    Remember to substitute the following values for your own:

    a) a_i_id - The Apple application ID that uniquely identifies your app on the App Store
    b) (Optional) The trackingcode and campaign name parameters can be substituted for your own values if you wish
    c) The Adobe Tracking ID (long string between /v3/ and /start

    You must obtain this from the Adobe Analytics console.



    Adobe App Acquisition Tracking - Google Docs 2017-03-24 09-15-16.png

  2. 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"

 

Also see:
https://marketing.adobe.com/resources/help/en_US/mobile/ios/t_testing-version-3-acquisition.html

Android (Requires 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 itself. Once your device has followed the link, copy down 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:

 

Adobe App Acquisition Tracking - Google Docs 2017-03-24 09-22-43.png