Deferred deep link not working

Definition

A deferred deep link fails when the signal meant to carry the pre-install destination across the app store — an install referrer, a stored token, or a server-side match — is absent, expired, or never read on first launch.

Unlike a standard deep link, which either works or does not, deferred deep linking depends on a signal surviving a journey through a store, an install, and a first launch. Each platform provides a different signal with different reliability, and the useful diagnostic question is not "is it broken" but "which signal was this install supposed to use, and did that signal exist". On Android the answer is usually knowable with certainty. On iOS it frequently is not, and that is a property of the platform rather than of your integration.

Which signal was this install relying on?

Start here, because it determines whether the failure is a bug you can fix or a limit you have to design around.

Android: the referrer did not arrive

The Play Install Referrer is a string you set on the store URL, which Google holds through the install and hands to the app on request. If it is missing, one of four things happened.

# The referrer value must be a SINGLE url-encoded parameter.
# Decoded, this one is:
#   utm_source=newsletter&utm_campaign=spring&dl=%2Fproducts%2F42

https://play.google.com/store/apps/details?id=com.example.shop&referrer=utm_source%3Dnewsletter%26utm_campaign%3Dspring%26dl%3D%252Fproducts%252F42

# A double-encoding mistake here is the most common silent failure: the
# inner value needs encoding too, or the & inside it terminates the
# referrer parameter and everything after it is dropped.

1. The install did not come from a Play URL carrying `referrer`. The user searched for the app in the Play app rather than following your link, or your fallback sent them to a bare store URL with the parameter stripped. The referrer is set by the URL that opened the store listing — nothing else can set it.
2. The referrer was double-encoded or truncated. An unencoded & inside the referrer value terminates the parameter, so everything after the first & is silently discarded. This produces a partial referrer, which is worse than none because it looks like it worked.
3. The app never asked for it. The referrer is pulled through the Play Install Referrer library, not pushed. The old INSTALL_REFERRER broadcast was removed in 2020, and integrations copied from pre-2020 guides listen for a broadcast that will never fire.
4. The install came from outside Play. Sideloaded APKs, Firebase App Distribution, App Center, pre-installed builds, and most alternative stores carry no Play referrer.

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

client.startConnection(object : InstallReferrerStateListener {
    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        when (responseCode) {
            InstallReferrerClient.InstallReferrerResponse.OK -> {
                val details = client.installReferrer
                // "utm_source=newsletter&utm_campaign=spring&dl=%2Fproducts%2F42"
                val referrer = details.installReferrer

                // These two timestamps are also the basis of click-injection
                // and click-spamming detection.
                val clickTime = details.referrerClickTimestampSeconds
                val installTime = details.installBeginTimestampSeconds

                router.handleDeferred(referrer)
                client.endConnection()
            }
            InstallReferrerClient.InstallReferrerResponse.FEATURE_NOT_SUPPORTED ->
                Log.w(TAG, "Play Store version does not support the referrer API")
            InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE ->
                Log.w(TAG, "Play Store unreachable — retry later, do not give up")
        }
    }

    override fun onInstallReferrerServiceDisconnected() {
        // Transient. Retry — do not treat as "no referrer".
    }
})

The causes that are not platform-specific

You are testing on a device that has installed the app before. Deferred deep linking fires on *first* launch after install. A reinstall on a device that has run the app is not a first launch in the sense that matters — Android may still return a cached referrer from the original install, and iOS will find leftover state. Test on a device that has genuinely never had the app, or reset it fully.

The app was already installed. If the user already has the app, there is no deferred flow at all — the link opens the app directly through the ordinary Universal Link or App Link path. A destination lost in this case is a routing bug, not a deferred one, and looking at the deferred integration will find nothing.

The SDK initialised after the first screen decided what to show. The deferred payload arrives asynchronously — a service connection on Android, a network call on iOS. If your app has already routed to the home screen by the time it resolves, the destination is technically received and functionally lost. The first screen has to be prepared to be told where to go after it has drawn.

The payload was consumed once and discarded. Deferred context is delivered once. An integration that reads it during a launch that then crashes, or reads it on a code path that runs before the router exists, loses it permanently. Persist it before acting on it.

The match window expired. Any deferred mechanism has a window between click and install after which it stops matching. A tester who clicks a link, gets distracted, and installs the next day falls outside it — and so does a real user, which is a good reason not to treat the window as a formality.

Testing it without a false pass

The reason so many deferred integrations ship broken is that the convenient tests are the misleading ones and the honest tests are slow. Budget for the slow one before release rather than discovering the difference from install data.