BlogAndroid

Play Install Referrer deep links on Android: carry a link through Google Play (with code)

· 8 min read · By the Strait team

How to use the Google Play Install Referrer to carry a deep link through an install. The Play Store URL format, encoding the referrer, reading it in Kotlin, the once-per-install rules, and how to test it with an internal testing build.

Most deep linking problems on Android end at the same wall: the person doesn't have your app. They tap a link to a product, go to Google Play, install, open the app, and land on the home screen. The link is gone.

Android has an official way through that wall, and it is exact. The Play Install Referrer lets you put a string on a Play Store link and read the same string back inside the app after the install. Put a link id in it, and the first open can land on the link's screen. This post is the developer's version: the URL format, the encoding trap, the Kotlin to read it, the rules that make it reliable, and how to test it for real. For the concept with diagrams, start with deferred deep linking explained.

The idea in one paragraph

A Play Store listing URL takes a referrer query parameter. Google Play keeps that value with the install. When your app starts for the first time, it connects to the Play Store app through the Install Referrer library and asks for the referrer of its own install. If your link server put link=<id> in there, the app now knows which link sent this person, and can ask your server where that link points. No guessing and no device matching: the value travels with the install.

Step 1: build the Play Store URL

The listing URL looks like this:

Code
https://play.google.com/store/apps/details?id=com.yourco.app&referrer=<url-encoded value>

The value is your own string. Most people use query-string syntax inside it, because it is easy to parse later:

Code
link=lnk_8f2a&click=6f1c0b

Here is the trap: that inner string contains = and &. If you paste it into the outer URL unencoded, the &click=… part becomes a separate parameter of the Play Store URL, and the referrer your app reads stops at link=lnk_8f2a. The referrer must be URL-encoded as a whole:

TypeScript
// Node / browser: encode the whole referrer value once.
const referrer = `link=${linkId}&click=${tapId}`;
const playUrl =
  `https://play.google.com/store/apps/details?id=${encodeURIComponent(pkg)}` +
  `&referrer=${encodeURIComponent(referrer)}`;
// …&referrer=link%3Dlnk_8f2a%26click%3D6f1c0b

Strait's link engine builds exactly this shape. When someone without your app taps a link on Android, the Play Store URL it sends them to carries strait_link=<link id> and strait_click=<tap id>, encoded the same way (Deferred deep linking docs). The tap id matters later: it is what lets a purchase after the install be credited to the tap that brought the person.

Two more details about the URL:

  • Use the https://play.google.com form when a browser is involved. A link server usually reaches the Play Store from a browser page, often through an intent:// link whose fallback is the Play URL. Chrome documents that format, including S.browser_fallback_url (Chrome for Developers: Android Intents with Chrome). The intent link builder shows the full shape.
  • Keep the value short and boring. Ids, not destinations. A full destination URL inside the referrer means double encoding, and anything private in it ends up in the Play Store's hands.

Step 2: read the referrer in the app

Google's library does the reading. At the time of writing the dependency is version 2.2 (Android Developers: Play Install Referrer Library):

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

The client connects to the Play Store app, gets a ReferrerDetails object, and must be closed afterwards:

FirstOpen.kt
import com.android.installreferrer.api.InstallReferrerClient
import com.android.installreferrer.api.InstallReferrerClient.InstallReferrerResponse
import com.android.installreferrer.api.InstallReferrerStateListener

fun readInstallReferrer(context: Context, onResult: (String?) -> Unit) {
    val client = InstallReferrerClient.newBuilder(context).build()
    client.startConnection(object : InstallReferrerStateListener {
        override fun onInstallReferrerSetupFinished(code: Int) {
            val value = if (code == InstallReferrerResponse.OK) {
                runCatching { client.installReferrer.installReferrer }.getOrNull()
            } else null // FEATURE_NOT_SUPPORTED, SERVICE_UNAVAILABLE…
            client.endConnection()
            onResult(value)
        }
        override fun onInstallReferrerServiceDisconnected() {
            // Not an answer. Leave the check pending and try again on the next launch.
        }
    })
}

ReferrerDetails gives you four things: getInstallReferrer() (the string), getReferrerClickTimestampSeconds(), getInstallBeginTimestampSeconds() and getGooglePlayInstantParam() (library reference). The string comes back decoded once, so you get link=lnk_8f2a&click=6f1c0b and can parse it like any query string:

Kotlin
fun parseReferrer(raw: String?): Map<String, String> =
    raw.orEmpty().split('&').mapNotNull { part ->
        val i = part.indexOf('=')
        if (i <= 0) null
        else Uri.decode(part.substring(0, i)) to Uri.decode(part.substring(i + 1))
    }.toMap()

val linkId = parseReferrer(value)["link"] // null for organic installs

Expect other values too. An install from a store search usually carries Google's own organic referrer, and an install from an ad campaign carries utm_ tags. Treat anything without your key as "no link".

The referrer only says which link. The destination lives on your server, because links change: a sale ends, a product moves. So the app sends the link id to the server and gets the current destination back.

With Strait that call is POST /v1/referrer, made with the publishable key (safe to ship in an app):

Terminal
curl https://strait.link/v1/referrer \
  -H "Content-Type: application/json" \
  -d '{ "publishableKey": "st_pub_live_…", "linkId": "lnk_8f2a", "platform": "android" }'

The answer says whether the link matched, its destination, and the match method install_referrer (REST API reference). With an SDK you write less of this. You give the Strait Android, React Native or Flutter SDK a way to read the referrer (a small function on Android, a standard referrer package on React Native and Flutter), and it parses the value, calls the server once and hands your code a normal link event (Android SDK setup, Receive links on Android).

The rules that make it reliable

Reading the referrer is a few lines. Making it behave in production is where the work is. These are the rules we settled on, and the reasons:

  1. Check once per install, then remember. Google's own guidance is to call the API once, on the first run after install, and cache the result. The referrer stays available for 90 days and doesn't change unless the app is reinstalled (library page). Calling it on every launch would replay the same link forever.
  2. Mark it done only after your server answered. If the phone is offline on first launch, the library may answer but your server can't. Keep the check pending and run it again on the next launch, or that install's link is lost for good.
  3. Let a real link win. If the launch right after install was itself opened by a link (a verified App Link tapped right after installing, for example), handle that link and mark the deferred check done. Otherwise a stale referrer jump fires on top of the link the person just tapped.
  4. Don't block the first screen on it. Show your normal start screen or a short loading state, and route when the answer arrives. A slow Play Store connection should not look like a frozen app.
  5. Check in even when there's no link. If you count installs that matched against installs that didn't, you need the "no link" installs too. The Strait SDKs report them, so the match rate in Analytics has a real denominator.

The Strait SDKs follow all five: the check runs once, is skipped and marked done when the first launch came from a link, and runs again next launch if the phone was offline (Once per install).

Testing: the install must come from Google Play

This is the part that wastes the most time. A build installed with adb install, or run from Android Studio, has no referrer at all, because Google Play never saw the install. Your code is fine; the test is wrong.

What worked for us:

  1. Upload a build to an internal testing track in the Play Console and add your test account as a tester.
  2. Add the Play App Signing fingerprint to assetlinks.json. Play re-signs the build with its own key, so a Play-installed copy has a different SHA-256 from your debug build. Our post on SHA-256 mistakes that break App Links covers where to find it, and the assetlinks checker shows which fingerprints your file lists.
  3. Uninstall the app, tap your link in Chrome, and let it go to the Play listing.
  4. Install from Play and open it. The first screen should be the link's screen. Then reopen the app: it should go to the home screen, with no second jump.

What we saw on a real phone

We ran that test end to end in October 2026 with a build on a Google Play internal testing track. After uninstalling, a tap in Chrome went through the browser hand-off to the Play listing. The install's first open landed on the link's screen (a coupon), our server recorded the install with the method install_referrer, and reopening the app went to the home screen. The same flow worked when the tap started in Microsoft Edge. Once the Play signing fingerprint was in assetlinks.json, the Play-installed copy also verified its App Links on its own.

Two things we learned on the way. First, while the app isn't public, a phone outside the tester list sees "Item not found" on the Play listing, so Strait has a workspace setting to send not-installed Android taps to Google Play always, to your website, or to pick automatically (go-live checklist). Second, internal testing really does deliver the referrer; you don't need a public release to test this.

What the referrer can't do

  • It can't see installs that never open. Nothing runs until the app launches, so link-driven install counts will be lower than the Play Console's (Analytics: how we count).
  • It doesn't exist on iPhone. The App Store passes nothing from the tap to the app. Strait's iPhone install matching is a short-lived match instead, and it is opt-in (iPhone install matching).
  • It doesn't survive leaving Google Play. Installs from other stores, or from an APK on a website, carry no Play referrer.
  • It can't fix a tap that never reached the store. If an in-app browser shows your web page and the person never gets to Google Play, there is nothing to carry. That's an in-app browser problem; see why Instagram and WhatsApp links open the browser.

Before you test on a phone, you can check the decision side in your browser: the Will it open my app? simulator shows where an Android tap goes when the app isn't installed.

Sources and how we checked

  • Android Developers, Play Install Referrer Library: the 2.2 dependency, the ReferrerDetails methods, the response codes, the 90-day availability and the advice to call the API once after install. Play Install Referrer overview: what the API returns.
  • Chrome for Developers, Android Intents with Chrome: the intent:// format and S.browser_fallback_url.
  • The Play Store URL shape, the strait_link and strait_click values, POST /v1/referrer and the once-per-install rules are from Strait's link engine and SDK code and the deferred deep linking docs.
  • The real-phone results (Chrome and Edge taps, first open on the coupon screen, method install_referrer, App Links verifying on the Play-installed copy, "Item not found" for an unpublished listing) are from our recorded Android tests in October 2026.