This article will help you:
  • Attribute your app installs to marketing campaigns
  • Set up marketing source attribution for your Android and iOS app installs
  • Target mobile experiments with custom tags

Marketing source attribution is used to identify the sources, like search or an ad campaign, that bring traffic to a website or app. In this article, we'll show you how to track the marketing source for each of your app installs, so you know which campaigns are most effective at driving installations.

On the web, marketers most commonly track attribution information through tagging the campaign’s URL with a query string parameter, like a UTM, and then analyze the information gleaned from UTM parameters using an analytics tool. Optimizely enables testers to target based on UTM parameters via Audiences.

While URL query string parameters are common on the web, mobile source attribution is slightly varied. In this article, we will cover how a marketer working on an Android or iOS app can use and collect source information to understand which of their campaigns are best at getting visitors to install their app and then converting down the funnel.

Marketing source attribution for Android (Google Play)


In the Android world, the process looks pretty much the same as it does on the web. Here’s how it works:

  1. Campaign URLs have a special query parameter called referrer (for example, referrer=value). The value of the referrer parameter is a URL-encoded string of information about the campaign the user clicked on. These URLs will typically redirect a user to the Google Play store to download the app, or if the app is already installed, launch the app (optionally deep-linking to a particular view).

    Here’s what the referrer parameter looks like in a URL (referrer parameter is bolded)

    (see here for more information on possible referrer params).

  2. When a user clicks the ad, they are redirected to the app page on Google Play. Google Play records the referrer parameter and associates it with a unique identifier for the mobile device.
  3. The user downloads and installs the app. The first time the app launches, the install referrer receiver sends a unique device identifier to a Google Play API. Google Play responds with the referrer recorded in step 2.
  4. The app can now use the install referrer information to do a variety of things, including handing that information off to an analytics tool or using the information for targeting in Optimizely.

Essentially, the Google Play store acts as an intermediary between the ad campaign and the newly installed mobile app to make marketing source attribution possible.

Marketing source attribution for iOS (Apple App Store)

When it comes to passing marketing source information between ad campaigns clicked and newly installed apps in the Apple Store, there is no concept of install referrer. Instead, there are mobile source attribution vendors that have made many options available for marketers who want to do marketing source attribution for their iOS app installs.

There are different mobile source attribution vendors, many of them share similar features, like:

  • Maintaining relationships with major ad networks (like Google, Facebook, Twitter, etc.). Each vendor has a different set of relationships, so make sure that the networks you use are connected to the vendor you choose.
  • Tracking and recording any clicks on your campaigns. Additionally, the vendor will collect a set of heuristics which uniquely identify the user’s device - this process is known as “fingerprinting”. Each vendor does this a bit differently, see here for an explanation of how AppsFlyer and MobileAppTracking handle fingerprinting.
    • The attribution vendor can use the fingerprint heuristics to reconcile with clicks on your ads and figure out which ad click resulted in an app install (thus completing the install source attribution cycle).  
  • Additionally, every major ad network makes a tracking package available, so using the ad network’s tracking package may be suitable for apps advertising on a small number of networks.

To get started, the app developer will need to install the vendor’s SDK in their app.

When the app launches for the first time, the vendor’s SDK will make a call to the vendor’s API, transmitting a similar set of fingerprint heuristics for the user’s device.

All vendors will give you some level of reporting on install attribution in their web interface. Some of them will give you the ability to trigger a “postback” (essentially an API call to an endpoint you specify) which can inform your analytics platform that an install occurred as a result of a particular campaign. However, what you really want to do is get access to that campaign attribution on the device itself. This is done through a process called deferred deep-linking. As of this writing, the only two attribution vendors which have this capability are AppsFlyer and Tapstream.

Sample AppsFlyer / Optimizely iOS integration

Let’s take a look at how we would integrate AppsFlyer and Optimizely. The goal is to get access to install source attribution information and use it for targeting our experiments. We’ll use a Custom Tag as the carrier for this information. Let’s get started! 

Prerequisites Getting attribution information from the AppsFlyer SDK

When an app is installed, AppsFlyer uses the onConversionDataReceived method for an app install event. Essentially, this method will receive install attribution data from the AppsFlyer API and make it available via the installData object. See here for a full description of the implementation process.

The installData object is a dictionary of key:value pairs which describe the installation source. Here’s an example of the information you might get access to:


"af_status": "Non-organic",

"is_fb": true,

"media_source": "Facebook Ads",

"agency": "nanigans",

"campaign_name": "nanigans_US_18-25",

"campaign_id": "6012743935279",

"adgroup_name": "Adgroup-1",

"adgroup_id": "6012743942279",

"adset_name": "adset-1",

"adset_id": "6012743935479",

"ad_id": "6012743943079",

"af_sub1": null,

"af_sub2": null,

"af_sub3": null,

"af_sub4": null,

"af_sub5": null,

"install_time": "2014-05-22 14:12:37.208",

"click_time": "2014-05-22 14:08:08"



Registering Custom Tags using AppsFlyer attribution data

Now that we have access to the information contained in AppsFlyer’s installData object, we can hand that data off to Optimizely in the form of a Custom Tag. For example, let’s say we want to run a test which only targets our users coming from Facebook ads. Looking at the installData object, we can see that we have access to a “media_source” key whose value is the ad network where the user came from. Let’s create a custom tag called “marketing_source”. We can call the setValue:forCustomTag: method as follows:

[Optimizely setValue:[installData objectForKey:@"media_source"] forCustomTag:@"marketing_source"];

This will create a custom tag named “marketing_source” whose value is “Facebook Ads” (“Facebook Ads” is the value of the key named “media_source” in the installData object).

We can now initialize the the Optimizely experiments in our app by calling startOptimizely.

Targeting Optimizely mobile experiments using Custom Tags

Now that we’ve created our “marketing_source” tag in our app, we can target our mobile experiments to only those users who come from a particular ad network:

  1. Edit the mobile experiment you want to target using your new custom tag.
  2. Click on the Options menu in the top right corner and select Targeting.
  3. Add a Custom Tag targeting attribute for marketing_source = Facebook Ads

Now your users who clicked on Facebook ads will be included in the experiment, and all others will be excluded.

The applications for install source attribution information are exciting, and hopefully you’ve got a few of your own ideas after reading through this document.

We’re at a thrilling time in the evolution of digital marketing in a mobile world, and accurate install source attribution unlocks a whole new level of personalization and ad optimization for data-driven marketers.