Google Play Install Referrer: The Complete Developer's Guide (2026)

$ cat table-of-contents

1. What is Google Play Install Referrer?
2. How does Play Install Referrer work?
3. How do you set it up?
4. What data do you get back?
5. What are the limits?
6. When is Play Install Referrer enough on its own?
7. When do you need more than the referrer string?
8. Where LinkTrace fits
9. Frequently asked questions

What is Google Play Install Referrer?

Definition: Google Play Install Referrer is an API exposed by the Google Play Store app on Android devices that lets your app retrieve the referral content that led to its install. Concretely, it returns the referrer URL of the installed package, the timestamp of the referrer click, the timestamp of when the installation began, the app's version at first install, and whether the user interacted with your app's instant experience in the past 7 days.

Two requirements, both from Google's documentation:

• The API is exposed by the Play Store app itself. Devices with Google Play app version 8.3.73 or later have access, which in practice is effectively every active Play device.
• You need a Google Play Console account to use it.

The API is implemented as an Android Interface Definition Language (AIDL) interface. If your app is written in Kotlin or Java, Google provides a small client library that wraps the AIDL file. In any other language, you talk to the AIDL interface directly.

Some history worth knowing: Google launched the API in 2017 and deprecated the older install_referrer intent broadcast on 1 March 2020. If a tutorial tells you to register a broadcast receiver for com.android.vending.INSTALL_REFERRER, it is describing the dead mechanism, not the current one.

How does Play Install Referrer work?

The flow has five steps, and you own four of them:

1. You tag your Play Store link. Append a URL-encoded referrer parameter to your listing URL, for example https://play.google.com/store/apps/details?id=com.example.app&referrer=utm_source%3Dnewsletter%26utm_campaign%3Dlaunch. The value is arbitrary; most teams put UTM parameters in it.
2. The user taps and installs. Play records the referrer value alongside the click.
3. Your app asks, once, on first launch. It connects to the Play Store app and calls the API.
4. Play returns the exact string. Whatever you put in referrer comes back verbatim, plus click and install-begin timestamps.
5. You parse, store, and forward it. Decoding the string, sending it to your backend, and turning it into reports is your code.

The two timestamps are not decoration. Comparing the referrer click time against the install-begin time is the standard way to spot click injection, where a fraudulent source fires a fake click just before the install completes. Google introduced the API partly as a more spoof-resistant replacement for the broadcast.

How do you set it up?

1. Add the dependency

build.gradle (Kotlin DSL)

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

2. Connect to the Play Store app

Kotlin

private lateinit var referrerClient: InstallReferrerClient

referrerClient = InstallReferrerClient.newBuilder(this).build()
referrerClient.startConnection(object : InstallReferrerStateListener {

    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        when (responseCode) {
            InstallReferrerResponse.OK -> {
                // Connection established.
            }
            InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> {
                // API not available on the current Play Store app.
            }
            InstallReferrerResponse.SERVICE_UNAVAILABLE -> {
                // Connection couldn't be established.
            }
        }
    }

    override fun onInstallReferrerServiceDisconnected() {
        // Restart the connection with startConnection()
        // before making further requests.
    }
})

The connection is asynchronous and can drop (for example while the Play Store app updates itself), so production code needs the reconnect path in onInstallReferrerServiceDisconnected(), not just the happy path.

3. Read the referrer details

Kotlin

val response: ReferrerDetails = referrerClient.installReferrer
val referrerUrl: String = response.installReferrer
val referrerClickTime: Long = response.referrerClickTimestampSeconds
val appInstallTime: Long = response.installBeginTimestampSeconds
val instantExperienceLaunched: Boolean = response.googlePlayInstantParam

4. Close the connection

Call endConnection() when you are done. Google warns that leaving the connection open causes leaks and performance problems.

What data do you get back?

That is the whole payload. There are no named campaigns, no click counts, no per-link breakdowns: the API returns the one string that was on the link this particular user tapped.

What are the limits?

None of these are bugs. They are the boundary of what the API is for, and hitting them is usually the moment a team starts shopping for a link layer.

• Android only. There is no iOS equivalent from Google. If you ship on both platforms, the referrer covers half your users and the other half needs a different mechanism entirely.
• Play Store installs only. Sideloaded installs and most third-party stores produce nothing. (Samsung's Galaxy Store runs its own separate Install Referrer library, with its own integration.)
• It is a library in your app. A Gradle dependency, an asynchronous service connection, three response codes, and a reconnect path: this is an SDK in everything but name, and it only covers Android.
• You get a string, not a system. There is no link generator, no storage, no dashboard. Link naming conventions, parsing, deduplication, and reporting are yours to build and maintain.
• Organic installs are silent. An empty referrer means "untagged", which lumps together every visit you did not tag.
• No routing by itself. You can encode a screen name in the referrer value and route on first launch, but the encoding, parsing, and navigation are your code, and none of it exists on iOS.
• Timestamps are second-precision. Good enough for fraud heuristics, not a foundation for exact attribution science.

When is Play Install Referrer enough on its own?

Stay on the plain API when all of these are true:

• Your app is Android-only and distributed through Google Play.
• You need campaign-level answers ("which newsletter, creator, or community post drove installs"), not user-level journeys.
• You already have backend storage and analytics to send the string to, or you are happy building them.
• Nobody needs to click a pretty link: raw play.google.com URLs in your posts and emails are fine.

For a lot of indie Android apps this is genuinely the right answer. It is free, exact, and maintained by Google.

When do you need more than the referrer string?

The cracks appear the moment any of these show up:

• You ship iOS too and want one link and one measurement flow across both platforms instead of an Android-only special case.
• The link has to route somewhere. Invites and referrals expect the new user to land on a specific screen after a fresh install: the right household, the right group, the right profile. That is deferred deep linking, and on Android the referrer string is only the transport. You still build the payload format, the parsing, and the navigation, and none of it transfers to iOS.
• You want links that carry your brand. A long play.google.com URL in a bio or a QR code is not a brand asset.
• You want answers, not infrastructure. Per-link click counts and performance dashboards without building a reporting pipeline.
• You distribute beyond Play, or your journey starts on the web and ends in the app.

Where LinkTrace fits

If you want everything handled out of the box - links, deep linking, deferred deep linking, attribution, and reporting on both platforms - LinkTrace is the one-stop option: a single integration instead of a patchwork of referrer parsing, platform-specific deep link setup, and homegrown dashboards.

• One integration for both platforms. LinkTrace is SDK-less: your backend makes two HTTP calls, one to create a tagged link and one to ask, after signup, which link sent this user. The same flow covers Android and iOS, so deep linking and deferred deep linking work identically on both instead of being an Android-only special case.
• Deferred deep linking included, not DIY. You encode a screenName and up to two more key-value pairs in the link's customPayload. On first launch after signup, LinkTrace returns the payload and you navigate. The routing payload survives the store gap without you designing the encoding.
• Deep linking without the plumbing. When the app is already installed, verified links open it directly instead of detouring through the store. LinkTrace hosts the domain-side verification files (the apple-app-site-association and assetlinks.json) on your branded subdomain. The in-app side is a one-line Associated Domains entry on iOS and a few manifest lines on Android, not two separate platform integrations to design, host, and maintain.
• Branded links. Links are served on your own branded subdomain (Scale plan), which is also what enables Universal Links and Android App Links on your domain. Your links look like your product, not like a store URL.
• A dashboard instead of a pipeline. Link-wise click counts on every plan and a full analytics dashboard from the Growth plan, so you can see how different links perform without building reporting.

The free Starter plan (100 links, 1,000 attributed installs, no card required) is enough to run the full flow end to end and compare it against your referrer integration before deciding anything.

Frequently asked questions

Does Google Play Install Referrer work on iOS?

No. It is part of the Google Play Store app, so it exists only on Android devices with Google Play. iOS install attribution uses different mechanisms entirely, which is one reason cross-platform teams adopt a link layer that treats both platforms the same way.

Does it work for installs outside the Play Store?

No. Sideloaded installs produce no referrer data, and third-party stores are separate ecosystems. Samsung's Galaxy Store, for example, ships its own Install Referrer library that you would integrate separately.

Is the Install Referrer Library an SDK?

In practice, yes. It is a Gradle dependency with a service connection lifecycle, response codes, and a reconnect path that ships inside your app. It is small and first-party, but if "no SDK in the app" is a hard requirement for you, it does not meet it.

How long is referrer data available?

Ninety days, and it does not change unless the app is reinstalled. Google recommends calling the API once during the first execution after install and persisting the result, rather than polling it.

Can Play Install Referrer do deferred deep linking?

Partially, on Android only. You can encode a screen name or promo code in the referrer value, read it on first launch, and navigate there yourself. But the API gives you the transport, not the feature: the payload format, parsing, navigation, expiry, and the entire iOS equivalent are yours to build.

Is Play Install Referrer free?

Yes. It is part of Google Play, with no per-call or per-install charge. You pay in integration and maintenance time instead of money.

What happened to the install_referrer broadcast?

Google deprecated the install_referrer intent broadcast on 1 March 2020 in favor of the Play Install Referrer API, which is more reliable and more resistant to spoofing. Old tutorials describing a broadcast receiver are out of date.

If you remember three things

• Play Install Referrer is the exact, free way to know which tagged link drove a Play Store install on Android, and it stops at handing you the referrer string.
• Everything around the string is your build: link generation, routing, storage, dashboards, and the entire iOS half of your user base.
• If you want it all handled - links, deep and deferred deep linking, attribution, and dashboards on both platforms - a one-stop link layer like LinkTrace replaces the whole build with a single integration and minimal code changes.

Sources

API behavior and limits in this guide were checked against the following pages on 19 October 2026.

• Android Developers: Google Play Install Referrer (overview, requirements, returned data)
• Android Developers: Play Install Referrer Library (dependency, connection flow, 90-day availability)
• Android Developers Blog: Still Using InstallBroadcast? Switch to the Play Referrer API by March 1, 2020
• Samsung Developers: Galaxy Store Install Referrer Library
• LinkTrace: API Reference, Deferred Deep Linking, Pricing

---

LinkTrace is a deferred deep linking and install attribution service for startups and indie developers. Two HTTPS calls, flat pricing, no SDK. Create a free account or see the plans.

Related guides: Deferred Deep Links vs Deep Links, Deferred Deep Links Are Harder Than They Look, How to Track App Installs Without Firebase or AppsFlyer, and Universal Links vs App Links