Glossary Term

Install Referrer

glossary install referrer featured

The install referrer is the campaign data Google Play attaches to an app install and hands to the app on first launch. It carries the UTM parameters or click ID from the link the user tapped before installing, which lets the app credit that install to a specific campaign, source, or referral. Android exposes it through the Play Install Referrer API.

Why the Install Referrer Matters

It is the only deterministic install attribution signal on Android. The alternative, probabilistic matching, pairs a click with an install using IP address and device attributes inside a short window, and it fails whenever two devices share a network or the window is wrong. The install referrer removes that guess: the exact string from the click survives the trip through the Play Store and arrives intact inside the app.

Three things depend on it:

  • Paid campaign attribution. Knowing which ad, keyword, or creative produced an install rather than just a click.
  • Referral programs. Identifying which existing user invited a new one so the reward fires correctly.
  • Organic versus paid split. Installs from a Play Store search return utm_source=google-play&utm_medium=organic, which separates them from campaign-driven installs.

What the Install Referrer String Contains

The referrer string is whatever was placed in the referrer query parameter of the Play Store URL, URL-encoded. Google Play stores that value at install time and returns it unchanged.

https://play.google.com/store/apps/details?id=com.example.app&referrer=utm_source%3Dgoogle%26utm_medium%3Dcpc%26utm_campaign%3Dspring_sale

The app decodes that value back to a familiar query string:

utm_source=google&utm_medium=cpc&utm_campaign=spring_sale

Any key-value pairs work, but UTM parameters are the convention because GA4 for Firebase and most mobile measurement partners parse them automatically. Google Ads app campaigns append a gclid instead. Since these values become permanent campaign labels the moment someone installs, consistency matters more here than on the web, and UTM naming rules keep a team from shipping utm_source=Google on one creative and utm_source=google on the next.

Alongside the string itself, the API’s ReferrerDetails object returns:

  • getInstallReferrer(): the referrer string.
  • getReferrerClickTimestampSeconds(): when the user clicked the link.
  • getInstallBeginTimestampSeconds(): when the install started.
  • getGooglePlayInstantParam(): whether the user came through Google Play Instant.

Those two timestamps are the standard click injection check. A click recorded after the install already began means a fraudulent click was fired mid-install to steal credit.

How the Play Install Referrer API Works

The API replaced the old INSTALL_REFERRER broadcast intent. Google Play stopped broadcasting that intent on March 1, 2020, so any app still listening for it receives nothing. The current library requires Google Play Store version 8.3.73 or higher and needs no Android permissions.

  1. Add the dependency: implementation 'com.android.installreferrer:installreferrer:2.2.
  2. Build a client with InstallReferrerClient.newBuilder(context).build().
  3. Call startConnection() and wait for onInstallReferrerSetupFinished().
  4. On response code OK, read getInstallReferrer() from the returned ReferrerDetails.
  5. Call endConnection() and persist the value locally.

Read it once on first launch and store the result. The connection is a live binding to the Play Store app, and leaving it open wastes resources. Other response codes to handle are FEATURE_NOT_SUPPORTED (Play Store too old or absent), SERVICE_UNAVAILABLE (no connection), and DEVELOPER_ERROR.

Install Referrer vs Referrer Header

They are unrelated despite the shared word. The referrer header is an HTTP request header a browser sends to name the page a visitor came from, and it exists only for web requests. The install referrer is a string the Play Store stores against an install and returns through an Android API. No HTTP request carries it, and no browser sets it.

Common Install Referrer Issues

It only covers Google Play. Sideloaded APKs, Amazon Appstore, Samsung Galaxy Store, and Huawei AppGallery return nothing through this API. Each alternative store runs its own referrer mechanism or none at all.

The value never updates. Google Play sets it at install and keeps it available for 90 days. It changes only when the app is reinstalled, so it attributes the install and nothing after it. Routing that new user to the right in-app screen is a separate job handled by a deferred deep link.

Double decoding corrupts it. The referrer arrives URL-encoded once. Decoding twice destroys any campaign name that legitimately contains an encoded character.

iOS has no equivalent. Apple provides the AdServices framework and SKAdNetwork instead, which return an attribution token and aggregated postbacks rather than a free-form string.

Frequently Asked Questions

What is an install referrer?

An install referrer is the campaign string Google Play passes to an Android app when that app is installed. It normally holds UTM parameters or a click ID copied from the referrer parameter of the Play Store link the user tapped. The app reads it on first launch to record which campaign drove the install.

How does the Google Play Install Referrer API work?

The app connects to the Play Store service through InstallReferrerClient, waits for the setup callback, then reads a ReferrerDetails object containing the referrer string and two timestamps. It requires no permissions and works only on devices running Google Play Store 8.3.73 or higher. The API replaced the INSTALL_REFERRER broadcast intent, which Google Play stopped sending on March 1, 2020.

Can you put UTM parameters in an install referrer?

Yes, and it is the standard practice. URL-encode the full UTM query string and pass it as the referrer value on the Play Store URL, so utm_source=google&utm_medium=cpc becomes referrer=utm_source%3Dgoogle%26utm_medium%3Dcpc. GA4 for Firebase and most mobile measurement partners parse those parameters without extra configuration.

How long is install referrer data available?

Google Play keeps the referrer available for 90 days after install. The value does not change during that period unless the app is reinstalled. Read and store it on first launch rather than depending on the API to still return it weeks later.

Does install referrer tracking work on iOS?

No. The install referrer is specific to Google Play and Android. On iOS, Apple’s AdServices framework returns an attribution token that is exchanged for campaign data, and SKAdNetwork delivers aggregated, privacy-limited install postbacks.

To build the tagged campaign links that feed a Play Store referrer value, use the free UTM builder at linkutm.

Back to Glossary