Short answer: the Google Play Install Referrer tells your app, on first launch, which link sent the user to Google Play. It only exists for Play installs, only covers same-session click-through installs and should be read once, on first launch. Most Android attribution failures come from reading it late, losing it in a redirect or testing outside Play.
What the Install Referrer is
Google Play Install Referrer: referral content that Google Play keeps for each install and hands to the app through the Install Referrer library, so the app can tell which link or campaign led to the install.
Android's documentation lists the current library dependency as com.android.installreferrer:installreferrer version 2.2. The ReferrerDetails object exposes four values:
- getInstallReferrer: the referrer string with your campaign parameters.
- getReferrerClickTimestampSeconds: when the referring click happened.
- getInstallBeginTimestampSeconds: when the install began.
- getGooglePlayInstantParam: whether the user launched the instant experience.
How long is the referrer available?
Android's documentation says referrer information is available for 90 days and does not change unless the app is reinstalled. Even so, it advises calling the API only once, on the first execution after install, and storing the result.
What the referrer does and does not cover
| Install type | Covered by Play referrer |
|---|---|
| Same-session click, installed from Google Play | Yes |
| View-through install | No |
| Click in an earlier session | No |
| Install from another Android store | No |
| Sideloaded APK or adb debug build | No |
Meta's documentation draws this comparison directly: the Google Play Install Referrer covers only same-session click-through installs, while the Meta Install Referrer also covers view-through and multi-session clicks from Facebook, Instagram and Audience Network. Meta's referrer data is read from the Facebook, Instagram and Facebook Lite apps and should be queried on first launch.
On Meta campaigns, Meta places encrypted campaign data in the Play referrer's utm_content field, using AES-GCM with a key from the App Dashboard. Meta says other parameters such as utm_source should not be used as a sign of a Facebook install.
Response codes to handle
- OK: the referrer was returned.
- FEATURE_NOT_SUPPORTED: the API is not available on the current Play Store app on that device.
- SERVICE_UNAVAILABLE: the Play service could not be reached.
Android's documentation also warns that the connection can drop, for example while the Play Store updates, and that you must call startConnection again. A single attempt with no retry loses referrers on some devices.
Common failure patterns
These are general practice rather than documented rules:
- Reading the referrer late. If the SDK waits for login or a later session, a crash or drop-off loses the read.
- Testing with adb. Debug builds installed from a computer have no Play referrer, so every test looks organic.
- Redirects that strip parameters. Google's older troubleshooting page says referrer parameters must reach Google Play, or attribution fails.
- Multiple install referrer receivers. The same older page notes that, with the legacy broadcast method, Google Play only broadcast to the first receiver.
- Not decoding Meta's utm_content. Without the decryption key, Meta installs look unlabelled.
How it fits with other Android signals
The Play referrer is the main Android signal, but not the only one:
- Meta Install Referrer. Meta reads it from the Facebook (v428 and later), Instagram (v296 and later) and Facebook Lite (v411 and later) apps. Its fields include actual_timestamp, is_ct (1 for a click, 0 for a view) and an encrypted install_referrer.
- Network claims. Self-attributing networks such as Google and Meta claim installs themselves, so a missing referrer does not always mean a lost attribution.
- Third-party stores. Google Ads records installs from other Android stores on first open and recommends Firebase for them, since there is no Play referrer.
- Reinstalls. A reinstall resets the referrer, so the same user can bring new referrer data.
How to check your implementation
- Install a release build from a Play internal or closed testing track after tapping a test link.
- Log the response code, referrer string and click timestamp on first launch.
- Confirm the string contains your campaign parameters.
- Check that your MMP shows the install against the right campaign.
- Kill the Play Store mid-test on a spare device to confirm your retry logic.
Related pages
- The install referrer troubleshooter diagnoses empty or failing referrers.
- Non-Play Android installs not attributed covers installs outside Play.
- Deferred deep link opens the home screen often traces back to the referrer.
- Paid installs showing as organic covers the wider problem.