Short answer: the Google Play Install Referrer is a value the Play Store hands to your app after it is installed. It holds the referrer parameter from the store link the person tapped, plus timestamps for that click and for the install. Because it comes from the store itself, it is the most reliable way to know which link led to an Android install.
How does it work?
A tracked link sends Android users to your Play Store page with a referrer parameter added:
https://play.google.com/store/apps/details?id=com.example.app&referrer=measura_click_id%3Dabc123The Play Store keeps that value with the install. When the app first opens, it asks the Play Store for it through the Install Referrer API, gets measura_click_id=abc123 back, and the attribution service looks up that click.
What does it contain?
According to Google's reference, the response includes:
| Field | Meaning |
|---|---|
installReferrer | The referrer string from the store link |
referrerClickTimestampSeconds | When the click on the store link happened, by the device's clock |
installBeginTimestampSeconds | When the install began, by the device's clock |
referrerClickTimestampServerSeconds, installBeginTimestampServerSeconds | The same two moments, by Google's clock |
installVersion | The app version that was first installed |
googlePlayInstantParam | Whether the user used your instant app in the past 7 days |
How do I read it in Kotlin?
Add Google's library:
dependencies {
implementation("com.android.installreferrer:installreferrer:2.2")
}Then connect once, on the first launch after install:
val client = InstallReferrerClient.newBuilder(context).build()
client.startConnection(object : InstallReferrerStateListener {
override fun onInstallReferrerSetupFinished(responseCode: Int) {
if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
val details = client.installReferrer
val referrer = details.installReferrer // "measura_click_id=abc123"
val clickedAt = details.referrerClickTimestampSeconds
val installBeganAt = details.installBeginTimestampSeconds
// Store these, then send them with your install event.
}
client.endConnection()
}
override fun onInstallReferrerServiceDisconnected() {
// Try again on a later launch: the value is still there.
}
})An attribution SDK does this for you. The Measura SDK reads the referrer on first launch and sends it with the install event, so there is nothing to write.
What are its limits?
- Play Store installs only. Installs from other app stores, preinstalled apps and side-loaded APKs have no Play referrer.
- Kept for 90 days. Google keeps the value for 90 days after install, and it does not change unless the app is reinstalled. Read it once, on first launch, and keep it.
- Needs Play Store 8.3.73 or later, which almost every device in use has.
- Short and readable by anyone. Keep the referrer short, and never put personal data or anything secret in it: anyone who sees the link can read it. Send an opaque ID and look up the details on your server.
Why is it the strongest attribution signal?
Because nothing on the phone can change it afterwards. The value travels from the link, through the Play Store, into your app. Click injection, where malware fires a fake click just as an install starts, cannot alter what the Play Store recorded. That is why an attribution service should try the referrer before anything else, and why a referrer match deserves more confidence than a match on a device fingerprint.
At Measura, a referrer match starts at a base score of 98 out of 100, the highest of any method. The other methods and their scores are in the methodology, and our guide to click injection and click spamming shows how the referrer's timestamps help catch fraud.
What about Meta's install referrer?
Meta ads that send people to the Play Store also put campaign data in the referrer, encrypted inside utm_content. To read it you need the Install Referrer Decryption Key from your Meta App Dashboard: open your app, then Settings, then Basic, and find the key in the Android section.
In Measura, paste that key under Integrations in the dashboard. From then on, installs from Meta ads on Android are credited to the exact Meta ad, from the Play Store's own record.
Questions people ask
Does the install referrer need the advertising ID or a permission?
No. It works without the advertising ID and without any Android permission.
Why does my referrer say utm_source=google-play&utm_medium=organic?
That is what the Play Store returns when the install did not come from a link with a referrer, for example when someone found your app by searching the store.
Can the referrer carry a deep link?
It can carry a short ID that your app exchanges for one after install, which is how deferred deep links work. Our guide to deep links after Firebase Dynamic Links shows the whole flow.