Play Install Referrer

Definition

The Play Install Referrer is a Google Play API that lets a newly installed Android app read the referrer string and click timestamps recorded when the user arrived at its Play Store listing.

It is the closest thing mobile has to a deterministic install signal, and it needs no advertising identifier and no user consent, because Google Play is passing the app data about its own install. That makes it the backbone of deferred deep linking on Android: the referrer string can carry your own link identifier, so the first launch after install knows which link the user came from.

Where the string comes from

Play preserves the referrer query parameter from the Play Store URL the user arrived on. Everything downstream depends on that parameter being set on the outbound link — if the link has no referrer, the API works perfectly and returns nothing useful.

# The outbound Play Store URL. The referrer value must be URL-encoded.
https://play.google.com/store/apps/details
  ?id=com.example.shop
  &referrer=utm_source%3Dnewsletter%26utm_campaign%3Dspring%26dl_id%3Dabc123

# What getInstallReferrer() returns on first launch:
utm_source=newsletter&utm_campaign=spring&dl_id=abc123

The string is opaque to Play — it is whatever you put there, up to a length limit, conventionally formatted as URL-encoded key-value pairs. dl_id above is a first-party click identifier: your server generated it when the link was clicked, so resolving it on first launch gives you the full deep link destination without matching on any device signal at all.

The implementation

dependencies {
    implementation("com.android.installreferrer:installreferrer:2.2")
}

val client = InstallReferrerClient.newBuilder(context).build()

client.startConnection(object : InstallReferrerStateListener {
    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        when (responseCode) {
            InstallReferrerClient.InstallReferrerResponse.OK -> {
                val details: ReferrerDetails = client.installReferrer
                val referrer = details.installReferrer          // the string
                val clickTs  = details.referrerClickTimestampSeconds
                val beginTs  = details.installBeginTimestampSeconds
                val instant  = details.googlePlayInstantParam   // Instant App?

                handleReferrer(referrer, clickTs, beginTs, instant)
            }
            // Play Store too old, or no Play Store at all.
            InstallReferrerClient.InstallReferrerResponse.FEATURE_NOT_SUPPORTED,
            // Transient: Play services unavailable right now.
            InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE ->
                scheduleRetry()
        }
        client.endConnection()   // one-shot connection; always close it
    }

    override fun onInstallReferrerServiceDisconnected() = scheduleRetry()
})

The failure modes worth knowing

1. Read the referrer on the very first launch, before anything can consume it, and persist the parsed result immediately.
2. Never block your UI on the API. It is asynchronous and can fail; render the default experience and route when the referrer resolves.
3. Call endConnection() after each attempt — the client is one-shot and leaks a service binding otherwise.
4. Send the raw string to your server unparsed as well, so a parsing change does not require the referrer again.
5. Treat the referrer as untrusted input. It arrives from a URL a stranger can construct; validate the click ID against your own records before honouring the destination.

Meta ads are the one common case where the referrer is present but not directly readable — see the Meta install referrer, which arrives encrypted inside the same string.