Google Play Install Referrer API: A Practical Guide for Android Apps

The Google Play Install Referrer API is a first-party Android mechanism for reading referral information associated with an install from Google Play. It is often the cleanest signal available for Google Ads campaign parameters, affiliate links, QR campaigns, and other URLs that send a person to a Play listing.

It does not tell you everything about advertising. It does not replace network-level incrementality testing, and it does not identify every organic install. It does give an app a durable, install-scoped answer to a narrower question: what referrer did Google Play associate with this package installation?

What the API returns

Google documents the current API and client library in its Install Referrer guide. The response can include:

• install_referrer: the URL-style referrer string attached to the install.
• Client and server timestamps for the referrer click and install start.
• The version that was first installed.
• Whether the user interacted with an Instant experience recently.

The referrer value remains available for 90 days and does not change until the app is reinstalled. Google recommends reading it once during first execution and closing the service connection afterward.

That has two practical implications. First, store only the campaign fields your product actually needs; do not keep re-querying the Play Store on every launch. Second, persist the result before the user has a chance to leave the onboarding flow. The first meaningful event may happen minutes or days after installation.

A reliable Android implementation

Add the official client library to the app module:

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

Then read the result on first run. This example keeps the connection lifecycle explicit and records the information your analytics layer needs.

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

client.startConnection(object : InstallReferrerStateListener {
    override fun onInstallReferrerSetupFinished(code: Int) {
        try {
            if (code != InstallReferrerClient.InstallReferrerResponse.OK) return

            val details = client.installReferrer
            saveInstallAttribution(
                referrer = details.installReferrer,
                clickTimeSeconds = details.referrerClickTimestampSeconds,
                installTimeSeconds = details.installBeginTimestampSeconds,
            )
        } finally {
            client.endConnection()
        }
    }

    override fun onInstallReferrerServiceDisconnected() {
        // Retry on a later app launch; do not block onboarding.
    }
})

Parse a campaign, not a free-form label

The install_referrer field is usually a query string. Parse only recognised keys and keep your mapping small enough to audit. For example:

val query = Uri.parse("https://example.invalid/?$referrer")
val source = query.getQueryParameter("utm_source")
val medium = query.getQueryParameter("utm_medium")
val campaign = query.getQueryParameter("utm_campaign")
val gclid = query.getQueryParameter("gclid")

Campaign URLs can contain values your dashboard does not understand, malformed escaping, or identifiers you should not expose broadly. Define an allowlist, normalize source names, and keep the raw referrer only if your privacy policy and retention rules justify it.

For Google Ads, preserve the click timestamp when a gclid is present. It is more useful than the first-open time: installs can lag clicks, especially when a person compares apps or changes devices. A correct click date lets you reconcile a conversion to the relevant campaign reporting period instead of guessing from the installation date.

Make the first attributed event intentional

There are two common ways teams lose this signal:

1. They attach campaign data to every event forever, which pollutes downstream analysis.
2. They wait until account creation, then lose it when a person abandons earlier in onboarding.

A better pattern is to attach normalized attribution to the first event that enters the onboarding funnel, then make it part of the anonymous journey. That creates a stable cohort for every later question: which source completed verification, reached first value, returned on Day 7, or started a trial?

Does an MMP prevent you from reading it?

No. Multiple SDKs can read the Play Install Referrer value. It is available for the installation rather than consumed by the first reader. The engineering question is consistency, not exclusivity.

If Adjust, AppsFlyer, Branch, or another mobile measurement partner is your company’s attribution source of truth, keep its resolved attribution alongside product analytics. That result may apply provider-specific rules, fraud handling, or cross-network logic that a direct referrer parser does not reproduce. A direct Play read can still be valuable for diagnostics and first-party onboarding analysis.

Where it fits in a complete measurement plan

Install referrer is strongest for Android traffic that passes through Google Play. It should sit beside, rather than replace:

• Deep-link attribution for campaigns that open the app directly.
• Apple Ads attribution for iOS Apple Ads traffic.
• Privacy-preserving network measurement such as SKAdNetwork and AdAttributionKit for broader iOS campaigns.
• An onboarding funnel that measures whether an acquired person reaches value.

The implementation is small. The decision it supports is much larger: stop buying installs as a proxy for growth, and compare the sources that produce activated customers.

To instrument the product side, read how to track onboarding drop-off or set up Android onboarding analytics.