Skip to content
DL2App

Blog

Deferred deep linking on Android with the Play Install Referrer (Kotlin)

How to send someone who installs your Android app from a link to the screen that link pointed to: the referrer parameter on the Play Store link, reading it with the Install Referrer API in Kotlin, and the mistakes that lose it.

· DL2App · 5 min read

Someone taps a link to a product in your app. They don't have the app, so the link sends them to Google Play. They install it, open it, and land on the home screen: the product they wanted is gone. Deferred deep linking is what fixes that, and on Android it can be exact, with no guessing, because Google Play carries a value through the install for you.

This is how it works and how to build it in Kotlin.

The short answer

  • Add a referrer parameter to the Google Play link, URL-encoded: https://play.google.com/store/apps/details?id=com.example.app&referrer=tap_id%3Dabc123.
  • Read it on first launch with the Play Install Referrer API (com.android.installreferrer).
  • Look up what it points to and open that screen, once.
  • It only works for installs from Google Play, and only within 90 days of the install.

How it works

  1. Someone taps your link, for example https://go.example.com/products/42.
  2. Your link server sees the app isn't installed (the App Link didn't open it), records the tap with an ID, and redirects to Google Play with that ID in referrer.
  3. Google Play keeps the referrer through the install.
  4. On first launch, the app asks Google Play for the referrer, gets tap_id=abc123, and asks your server what that tap pointed to.
  5. The server answers /products/42, and the app opens it.

Keep the referrer short: put an ID in it, not the whole link. The ID lets your server count the install against the tap, and it keeps your link's data out of a store URL that anyone can copy and change.

1. The store link

https://play.google.com/store/apps/details?id=com.example.app&referrer=tap_id%3Dabc123

The value of referrer must be URL-encoded: = becomes %3D and & becomes %26. Unencoded, everything after the first & is read as a separate parameter of the Play link and lost.

2. Read it in the app

Add the library:

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

Then, on the first launch:

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 prefs = context.getSharedPreferences("deferred_link", Context.MODE_PRIVATE)
    if (prefs.getBoolean("checked", false)) return onResult(null)

    val client = InstallReferrerClient.newBuilder(context).build()
    client.startConnection(object : InstallReferrerStateListener {
        override fun onInstallReferrerSetupFinished(code: Int) {
            val referrer = if (code == InstallReferrerResponse.OK) {
                client.installReferrer.installReferrer
            } else null
            client.endConnection()
            prefs.edit().putBoolean("checked", true).apply()
            onResult(referrer)
        }

        override fun onInstallReferrerServiceDisconnected() {
            // Retry once on the next launch: don't mark it checked.
        }
    })
}

The callback doesn't arrive on the main thread, so switch back before you navigate.

3. Use it

readInstallReferrer(this) { referrer ->
    val tapId = referrer
        ?.let { Uri.parse("https://x/?$it").getQueryParameter("tap_id") }
        ?: return@readInstallReferrer
    // Ask your server what this tap pointed to, then navigate on the main thread.
    linkApi.resolveTap(tapId) { path ->
        runOnUiThread { router.open(path) }
    }
}

If there was no link, Google Play still returns a referrer, usually utm_source=google-play&utm_medium=organic. That's an install from a search on the Play Store, so there's nothing to open.

Mistakes that lose the link

  • Reading it on every launch. The referrer stays the same for 90 days. Without a "checked" flag, the app reopens the same product every time it starts.
  • Navigating before the app is ready. If the home screen loads first and then jumps, people notice. Show a short loading state on first launch, or open the screen once the answer is in.
  • Forgetting installs that don't come from Google Play. Sideloaded builds, debug builds and other stores (Samsung Galaxy Store, Huawei AppGallery) don't pass the referrer. FEATURE_NOT_SUPPORTED means the Play Store on the phone can't provide one.
  • Testing with a debug build. A build from Android Studio wasn't installed by Google Play, so there's no referrer. Test with an internal testing track: tap your link, install from Play, open.
  • Only handling the not-installed case. When the app is installed, the same link should open it directly through App Links. App Links checklist.

And on iPhone?

The App Store passes nothing through an install, so iOS has no equivalent. A link service matches the first launch to a recent tap, or uses a clipboard hand-off. It's useful, but it's an estimate, not an exact match. How deferred deep linking works on both platforms.

What it looks like in production

Bhoomee, an agriculture app whose users are mostly on Android, traced 468 installs to its download link in one month. 454 of them were matched exactly through the Google Play referrer, and only 14 needed an estimated match. Read the case study.

Doing it with DL2App

DL2App runs the server side for you: links on your own domain that open the app when it's installed, send people to Google Play with a referrer when it isn't, and answer the app's first-launch question with the link's path and data. Each install is labelled as matched exactly or estimated.

The React Native SDK (including Expo) is available now and reads the referrer for you; the native Android SDK is built and in final testing. Until then, a Kotlin app can send the referrer to the same first-launch endpoint the SDKs use, /v1/sdk/open, described in the API docs. To start, paste your Google Play link at portal.dl2.app: your first link is live in about a minute. See the Android docs and pricing.

Questions people ask

What is the Play Install Referrer API? A Google Play library that tells an app the referrer value from the Play Store link it was installed from. It's the official way to pass data through an install on Android.

How long is the install referrer available? For 90 days after the install. Read it on first launch and save that you've checked.

Why is my install referrer utm_source=google-play&utm_medium=organic? The app was installed without a referrer: from a Play Store search, or a link that didn't include one. Check that your link adds referrer and that its value is URL-encoded.

Does deferred deep linking need Firebase on Android? No. Firebase Dynamic Links used the same referrer, and it shut down in August 2025. The Install Referrer API works without Firebase.

Can I test the install referrer without publishing? Use an internal testing track on Google Play. Builds installed from Android Studio or a file don't have a referrer.

All posts

Start with one link

The free plan has no time limit and needs no card. Create a project, add your app, and send yourself the link.

Deferred deep linking on Android with the Play Install Referrer (Kotlin) · DL2App