Deep Link Doctor
Home / Developer notes

New users land on the home screen after install

Users who install from a link land on the home screen because universal links and App Links do not survive install. How deferred deep linking restores it.

SymptomUsers who install the app from a link land on the home screen instead of the content the link pointed to.
Likely causeUniversal links and App Links only route to an installed app, so the link is lost on the way through the App Store or Play Store.
FixAdd deferred deep linking, such as the Play Install Referrer on Android or a provider SDK, to restore the destination on first open.

Short answer: Universal links and App Links only work when the app is already installed. A new user who taps a link goes to the website or store, installs, and opens the app with no link at all. Restoring that destination on first open is called deferred deep linking.

What is happening

Deferred deep linking: routing a user to specific in-app content on the first open after they install the app from a link. Neither Apple nor Google defines the term; this is the industry meaning.

Apple says: "If the person hasn't installed your app, the system opens the URL in their default web browser." The app only receives the URL when the link itself launches it. Android App Links behave the same way: an absent or unverified app falls back to the browser.

  • Your AASA and assetlinks files can be perfect and this still happens.
  • It hits paid and referral campaigns hardest, since most clicks come from people without the app.

Why does this happen?

The store sits between the link and the first open, and the first open is not launched by the link, so the app receives no URL. Apple documents no first-party way to carry a URL through an App Store install.

  • iOS: no install referrer equivalent in Apple's documentation.
  • Android: Google offers the Play Install Referrer API, which can return "the referrer URL of the installed package".

How to confirm it

  1. Uninstall the app from a test device.
  2. Tap a deep link to a specific screen.
  3. Install from the store and open the app.
  4. If you land on the home screen, there is no deferred handling.
  5. With the app installed, tap the same link to confirm normal routing works, for example from Notes on iOS or with adb shell am start -W -a android.intent.action.VIEW -d "https://example.com/product/1" com.example.app.

How to fix it

  1. Android: use the Play Install Referrer library (com.android.installreferrer:installreferrer:2.2). Google's API returns the referrer URL of the install; teams commonly put the destination in the referrer parameter of the Play Store link and read it back on first open.
  2. Google says referrer details are available for 90 days and asks you to "invoke the API only once during the first execution after install".
  3. iOS: Apple's documentation has no install referrer, so deferred deep linking relies on third-party matching methods. Ask any provider how their matching works.
  4. Route the first open to the restored destination, and fall back to the home screen if nothing is found.
// build.gradle (Android)
implementation("com.android.installreferrer:installreferrer:2.2")

Hosted options: providers that handle deferred deep linking on both platforms include Linkrunner, Branch, Airbridge and Adjust.

The deferred deep linking guide explains each approach. Make sure the installed-app path works first: follow the universal links setup guide and the Android App Links setup guide, and confirm both with swcutil and adb shell pm get-app-links.

FAQ

Common questions

Why don't universal links survive an app install?

The system only hands a universal link to an app that is installed at the moment of the tap. After an install from the App Store, the first open carries no link, and Apple documents no way to pass it through.

Does the Play Install Referrer work on every Android device?

It needs the Google Play Store app version 8.3.73 or later and applies to installs from Google Play. Installs from other stores need their own approach.

How long is the install referrer available?

Google says the information is available for 90 days and does not change unless the app is reinstalled. Read it once on the first launch after install.

Is deferred deep linking the same as a universal link?

No. A universal link opens an installed app directly. Deferred deep linking is the extra step that restores the destination for users who had to install first.

What are UTM parameters?

UTM parameters are tags added to the end of a link, such as utm_source and utm_campaign, that tell analytics tools where a visit came from. They let you see which campaign, channel and ad brought each visitor.

Which UTM parameters are required?

Use utm_source, utm_medium and utm_campaign on every campaign link. utm_term and utm_content are optional and help you compare keywords or ad variants.