Android Install Referrer: How Deterministic Install Attribution Works
On Android, an install from Google Play can be tied to the exact link tap that caused it, with no guessing from network addresses and no advertising ID. The mechanism is the install referrer: a short string that rides on the store URL, survives the install, and is handed to the app when it first runs.
This article explains how that works, what Google's API returns, and where it stops working. It also covers what happens on Android stores other than Google Play and on sideloaded installs, and how a link service puts a click id into the referrer and reads it back.
What the install referrer is
The install referrer is a value attached to the Play Store URL that sent a person to your listing. Google's Play Install Referrer API lets the installed app retrieve that referral content from Google Play.
Install attribution means working out which link tap, if any, led to an install. A probabilistic match, often called a fingerprint, compares coarse signals from the tap and from the first launch, such as the network address and the device model, and picks the likeliest tap. A deterministic match needs no comparison, because the app receives an identifier that names the tap. The install referrer is the deterministic path on Android: the string that was on the store URL is the string the app reads back.
The flow from tap to first launch
- Tap. A person taps a link. The link service records the click and gives it an id.
- Redirect to the store. The app is not installed, so the service redirects to the Play Store listing and adds a
referrerquery parameter that carries the click id. - Install. The person installs from the listing. Google Play holds on to the referrer string.
- First launch. The app connects to the Play Store app on the device, asks for the install referrer, and gets the string back.
- Match. The SDK in the app sends the string to the link service, which looks up the click id and credits that click.
A store URL with a referrer looks like this:
https://play.google.com/store/apps/details?id=com.example.app&referrer=utm_source%3Dnewsletter%26utm_campaign%3Dspring
The format comes from Google's user acquisition guide for Play Games on PC, which says those campaigns run in a similar way to the ones on Android phones. That guide notes that the referrer string must be URL-encoded, 512 characters or less, and placed in the referrer query parameter.
What the API returns
Google publishes the API in two forms. The Play Install Referrer Library (com.android.installreferrer:installreferrer:2.2) is a Java wrapper. Underneath it sits an AIDL service interface (AIDL stands for Android Interface Definition Language), which Google documents for apps written in other languages.
With the library you build an InstallReferrerClient, call startConnection(), wait for the onInstallReferrerSetupFinished() callback, call getInstallReferrer(), which returns a ReferrerDetails object, then close with endConnection(). At the AIDL level the response is a bundle, and Google's reference lists these keys:
| Key | Type | What Google says it holds |
|---|---|---|
install_referrer | String | The referrer URL of the installed package |
referrer_click_timestamp_seconds | long | Client-side time of the referrer click |
install_begin_timestamp_seconds | long | Client-side time the installation began |
referrer_click_timestamp_server_seconds | long | Server-side time of the referrer click |
install_begin_timestamp_server_seconds | long | Server-side time the installation began |
install_version | string | The app's version when it was first installed |
google_play_instant | boolean | Whether the app's instant experience was launched in the past 7 days |
Google sets two rules on the same pages. The referrer information is available for 90 days and does not change unless the app is reinstalled. Google also asks you to call the API only once, during the first run after install.
The connection callback carries a response code: OK, FEATURE_NOT_SUPPORTED (the installed Play Store app does not support the API), SERVICE_UNAVAILABLE (the connection could not be started), SERVICE_DISCONNECTED (which Google calls potentially transient and suggests retrying) and DEVELOPER_ERROR (incorrect usage).
How a link service uses the referrer
The referrer is a string you choose, so a link service can put its own click id in it. Take AdTo. A tap on https://acme.adto.app/welcome records a click with a 16-character id. If the app is not installed, AdTo redirects to the app's Play Store URL with this parameter, replacing any referrer already on the URL you saved:
referrer=adto_click%3D<click id>%26adto_l%3Dacme%2Fwelcome
Decoded, the value is adto_click=<click id>&adto_l=acme/welcome. The first part names the click. The second names the link, so the server can still attribute the install from the referrer alone when the click record never landed.
On first launch the Flutter SDK reads the referrer natively and sends it with the install registration. The server finds that exact click and answers with a verdict, which the app receives on a stream:
adto.onAppInstalled.listen((install) {
// Emits again if a late referrer upgrades the verdict.
if (install.matched) {
debugPrint('${install.matchSource} ${install.referrerSource} ${install.slug}');
// referrer google_play welcome
}
});
A referrer match has matchConfidence: 'guaranteed'. AdTo's deterministic attribution docs add these details:
- Waiting. The registration waits at most 5 seconds by default for the referrer (
installReferrerTimeout), and the Play reader retries transient responses. A referrer that arrives later is sent as a late claim, and the upgraded verdict is emitted again. - No time window. A store referrer matches regardless of IP changes or time elapsed. One older than 30 days still matches, with the fraud flag
stale_referrer. - One install per click. A click already credited to another device's install is not credited again.
- Server clocks. Both timestamp pairs are sent, and the timing checks in the fraud rules trust only the server pair. One rule flags a tap that came more than 5 seconds after Google Play began the download.
Where it stops working
The referrer exists only when a store recorded one. These cases end without it. Other stores have their own section below.
- No referrer on the way to the store. Someone who searches the store, or taps a plain store link, installs without a click id in the referrer. AdTo's SDK reports this read as
organic: the store answered but recorded no referrer. - Sideloaded and development installs. A sideloaded app is one installed from an APK file instead of from a store. Google's API retrieves referral content from Google Play over a connection to the Play Store app, so it is limited to what Play recorded. AdTo's docs say a build installed with
flutter runoradb installhas no campaign referrer, and the Play read endsorganicornot_available. AdTo also has a fraud rule for the reverse case, where a Play referrer names a tap but something other than Google Play installed the app. - No Play Store, or one without the API. AdTo reports
not_availablewhen the store is absent.FEATURE_NOT_SUPPORTEDis Google's code for a Play Store app that does not support the API. - The read does not finish. A connection that never comes up, or a timeout, is not a final answer. AdTo's SDK reads again on up to five later launches.
Without a deterministic signal, a link service either falls back to a probabilistic match or counts the install as organic. AdTo falls back to a scored fingerprint over recent mobile web clicks from the same hashed IP and device family, and credits an install only on a unique, high-confidence match. An app can turn that fallback off and use deterministic signals only. The full order is in How attribution works.
Other Android stores
In AdTo, each app can hold optional store URLs for four more Android stores. The device's brand is detected from the user agent and the Sec-CH-UA-Model client hint, a request header that carries the device model. If that brand has a store URL saved, the visitor goes there. Otherwise they go to Google Play. The same referrer value is added to those store URLs, and the SDK reads each store's referrer on first launch.
| Store | Devices sent there | What your app adds |
|---|---|---|
| Huawei AppGallery | Huawei and Honor | Nothing |
| Samsung Galaxy Store | Samsung | A Gradle dependency (below) |
| Xiaomi GetApps | Xiaomi, Redmi and POCO | A Gradle dependency (below) |
| vivo store | vivo | Nothing |
The two dependencies go in the app's own Gradle file:
dependencies {
implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'
implementation 'com.miui.referrer:homereferrer:1.0.0.7'
}
If more than one store returns a referrer, the one whose install began last wins, and Google Play wins ties. The verdict's referrerSource names the store.
One caution: the Google pages cited in this article cover Google Play only. AdTo tags the other four stores the same way and reads each one's referrer, but its docs say that whether each store passes the value through has not been confirmed with a real install. Verify it on a device from that store before you rely on it. Until then, treat installs through those stores as fingerprint-attributed. The details are in App stores and OEM routing.
How to test it before release
Install attribution only works for a build that was installed the way your users install it, so the test needs a physical device and the store build.
- On the dashboard's Apps page, save the real Play Store URL and the SHA-256 fingerprint of the certificate the installed build is signed with. For a store build that is the Play App Signing key.
- Create a link.
- Uninstall the app from the device.
adb shell pm clear <package>also resets the SDK's state without uninstalling. - Tap the link on that device. You land in Play with
referrer=adto_click=…&adto_l=…on the store URL. - Install from the store and open the app once.
onAppInstalledfires withmatched: true,matchConfidence: 'guaranteed',matchSource: 'referrer'andreferrerSource: 'google_play'. - Check the Overview, where the referrer-status chips show how the Android read ended.
Each test consumes its click, so tap the link again for every run. A verdict with installState: 'update' means the device already had the app before this build, so uninstall first. The full list is on the Testing page.
Doing this with AdTo
AdTo is a hosted service for short links, install attribution and deferred deep links, which are links whose destination is delivered after the install. Its links live at https://<username>.adto.app/<slug>. When a tap leads to a store, AdTo tags the store URL with the click id, and the Flutter SDK, flutter_adto, reads the Play Install Referrer on first launch. Google's referrer library is bundled with the package, so you initialize the SDK and listen to onAppInstalled.
The app receives the matched link and its metadata, so a new user can be sent to the content they tapped. Every verdict names the signal that decided it. AdTo is not a measurement partner (MMP). It sends no postbacks to ad networks and has no SKAdNetwork support.
Create an AdTo account to try it on a real device. For background, read What is Deferred Deep Linking? or the SDK's Install attribution page.