How an app spreads through the links its own users share: what to link first, the two files a domain must serve, why links must not be routed through a splash screen, what really happens when the app is not installed, and a first run that asks for no account. With code.
By Bogdan Vladoiu, 2026-11-17
In Why applications lose users I wrote that an app should be shareable from its first release, and that deep links are the feature that does it. This article is the technical side: what to link, how to wire it on Android and iOS, what happens on a phone that does not have the app yet, and what the first minute in the app should look like for someone who arrived through a link.
The other half, keeping the users you have, is in Maximizing user retention. I pitch the two together because they are the same bet: the app that works without a connection and can be handed from one person to another in a chat message wins its niche against apps that cannot, and it does so without a marketing budget.
The examples use a food delivery app at food.example.com with the Android package com.example.food. A dish has a page, and a dish is the thing people send to each other.
Your users already have a distribution network
People spend their day in chat apps, SMS, email and social feeds. Every one of those can carry a URL, and every phone knows how to hand a URL to the app that owns it. That handoff is built into the platform, costs nothing per use, and is the only acquisition channel where the recommendation comes from a friend at the exact moment the friend is enthusiastic.
When a user shares a dish, they are not recommending the dish. They are recommending your app, to someone who trusts them, with a reason to open it right now.
I have a private theory that this is a large part of why Windows Phone failed. It had its own version of app links, and almost nobody used them. On the phones that won, you tap a link in a message and land on the right screen of the right app; you tap an address and the mail app opens with the fields filled in. On the phone that lost, you copied, switched apps and pasted. An ecosystem is the links between its apps, and a phone without them is a drawer of separate tools. Take it as an opinion; I have no study to offer.
What to link first
Link the data people want to show each other: a dish, a product, a listing, a playlist, a route, a result. Ask what a user of your app would paste into a group chat, and that is your first link.
What teams usually ship first is something else: the password reset link and the account activation link. Those are links to chores. They are worth having, but if your web app can already reset a password, they bring nobody new. Do the links to valuable data in release 0, and the account links when you get to them.
A useful test for a release plan: can a user of version 1.0 send another person to a specific thing inside the app? If not, the app can only grow through the store's search box and whatever you pay for.
One URL, three outcomes
The link is an ordinary HTTPS address on your own domain:
https://food.example.com/dish/4821
It has to work in three situations:
| Who taps it | What should happen |
|---|---|
| Has the app | The app opens on the dish |
| Does not have the app | A web page shows the dish, with a way to get the app |
| A search engine or a link preview | The same web page, with a title, a description and an image |
Do not use a custom scheme such as food://dish/4821 for sharing. It does nothing on a phone without the app, chat apps do not turn it into a tappable link, and any other app can claim the same scheme. A custom scheme is acceptable for links only your own code produces. Everything a user can share should be https.
The web page is not a consolation prize. It is what makes the link safe to send to anyone, it gives chat apps something to build a preview from, and it is a page search engines can index, one per item in your catalogue. A dish page needs little:
<title>Truffle tagliatelle at Luca's</title>
<meta name="description" content="Fresh tagliatelle, black truffle, 30 minutes to your door.">
<meta property="og:title" content="Truffle tagliatelle at Luca's">
<meta property="og:image" content="https://food.example.com/img/4821.jpg">
<meta name="apple-itunes-app" content="app-id=1234567890, app-argument=https://food.example.com/dish/4821">
The last line makes Safari show a banner that opens the app, or its store page, for this exact address.
Two files on your domain
A phone will not hand your domain's links to an app merely because the app asks. The domain has to say, in a file it serves, which apps may open its links. There is one file per platform, and they are not interchangeable.
Android: App Links
The app declares which addresses it handles:
<activity android:name=".MainActivity" android:exported="true">
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="https" android:host="food.example.com" android:pathPrefix="/dish/" />
</intent-filter>
</activity>
The domain confirms it at https://food.example.com/.well-known/assetlinks.json:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.food",
"sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
}
}]
iOS: Universal Links
The app carries the entitlement applinks:food.example.com, and the domain serves https://food.example.com/.well-known/apple-app-site-association, with no file extension:
{
"applinks": {
"details": [{
"appIDs": ["ABCDE12345.com.example.food"],
"components": [{ "/": "/dish/*" }]
}]
}
}
The traps
These files fail silently. Nothing crashes; the link simply opens the browser. Nearly every "our deep links do not work" report I have looked at was one of these:
- The wrong fingerprint. The file must list the certificate that signed the build on the user's phone. A debug build is signed with a different one, and if the store re-signs your app, the fingerprint is the store's signing key, not your upload key. List every one you need; the field is an array.
- A redirect. Both files must be answered directly, over HTTPS, with status 200. A redirect from the bare domain to
www, or the other way, breaks verification for the host that redirects. Declare and serve each host you use. - The wrong content type or an HTML error page. Serve both as
application/json. A single-page web app that answers every unknown path with its index page will happily serve HTML for the file's address. - Testing before the file is live. Android verifies when the app is installed or updated. If the file was missing then, fix it and reinstall.
- Caching you do not control. iOS fetches its file through Apple's servers, not from the phone, so a change can take a day to arrive. Newer Android versions re-check in the background on their own schedule.
- Since Android 12, an unverified link opens the browser. Older versions showed a chooser asking which app to use. Now there is no chooser: verified or browser.
On Android you can ask the phone what it concluded:
adb shell pm get-app-links com.example.food
adb shell am start -a android.intent.action.VIEW -d "https://food.example.com/dish/4821"
The first prints the verification state per host. The second sends the link the way a tap would. Run both against a release-signed build before every release, for every link you support. Put the addresses in a text file and loop over it.
Inside the app: a link is a stack of screens
Here is where most of the pain comes from, and it is architectural, not platform plumbing.
The common first attempt routes every link through the launch screen: the splash screen receives the link, runs the start-up logic, then decides where to go. It works for two links. By the tenth it is a giant function full of branches, some links can no longer be told apart from each other, and a pattern added for the newest link quietly swallows an older one. Past a handful of links it stops scaling, and one wrong branch is enough to stop the app opening from its launcher icon.
The root cause is that code was written in the splash screen as if the splash screen were the only door. Session checks, consent, configuration fetches, first-run setup: once any of that lives in a screen, every other way into the app has to pass through that screen or duplicate it. Links make every nested screen a door. Start-up logic has to live in one global place that any entry point runs, and no screen may own it.
With that out of the way, routing is a pure function: an address in, a stack of screens out.
fun route(url: String): List<Screen> {
val path = url.substringAfter("://").substringAfter('/', "").substringBefore('?').trim('/')
val parts = if (path.isEmpty()) emptyList() else path.split('/')
val target = when {
2 == parts.size && "dish" == parts[0] ->
parts[1].toLongOrNull()?.let { Screen("dish", it) }
2 == parts.size && "restaurant" == parts[0] ->
parts[1].toLongOrNull()?.let { Screen("restaurant", it) }
else -> null
}
return listOfNotNull(Screen("home"), target)
}
Four properties make this hold up as links are added:
- It matches exactly. Number of segments, name of the first, type of the second. No pattern can swallow another, because no pattern is loose.
- Home is always underneath. After any link, pressing back lands on the home screen of your app, not on the chat the user came from and not on nothing. The ideal is to rebuild the full path, dish over restaurant over list, but one rule that is always true beats a clever one per link.
- An address it does not know opens home. Never an error screen, never a crash. Old links to things that no longer exist will be tapped for years.
- It can be tested without a phone. A table of addresses and expected stacks, checked on every build. Each new link adds a row; no old row may change.
The entry point then has almost nothing to do:
override fun onCreate(state: Bundle?) {
super.onCreate(state)
if (null == state) open(route(intent?.dataString ?: ""))
}
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
open(route(intent.dataString ?: ""))
}
open replaces the navigation stack with the list. If your navigation is a plain stack of screens, that is one assignment. The launcher icon is the same call with an empty address, which is why it can never break when a link is added.
One more rule: a linked screen must be able to load itself from its id. If the dish screen assumes the list screen already fetched the dish, it works in every manual test and fails for every person who arrives by link.
When the app is not installed
In the 2023 article I wrote that the phone offers to install the app and then opens it straight on the shared item. That sentence was too generous, and I want to correct it properly.
What the platforms do on their own: the link opens your web page, and the web page can send the visitor to the store. After the install, the app opens on its home screen. The address the visitor tapped is not handed to the freshly installed app. Carrying it across the install is called deferred deep linking, and it is extra work.
For years the usual answer was Firebase Dynamic Links. Google shut that service down on 25 August 2025. What remains:
On Android, the store can carry a parameter for you. The web page's install button links to the store with a referrer value:
https://play.google.com/store/apps/details?id=com.example.food&referrer=dish%3D4821
On first launch the app asks the store what it was installed with:
val client = InstallReferrerClient.newBuilder(context).build()
client.startConnection(object : InstallReferrerStateListener {
override fun onInstallReferrerSetupFinished(code: Int) {
if (InstallReferrerClient.InstallReferrerResponse.OK == code) {
val dish = client.installReferrer.installReferrer
.substringAfter("dish=", "").substringBefore('&').toLongOrNull()
if (null != dish) open(listOf(Screen("home"), Screen("dish", dish)))
}
client.endConnection()
}
override fun onInstallReferrerServiceDisconnected() {}
})
Ask once, on the first launch only, and remember that you asked. It is free, it is first-party, and it works only for installs that went through that store link.
On iOS there is no first-party equivalent. The honest options are a paid link provider, which matches the install to the tap with varying reliability, or accepting the gap and making it small.
Making the gap small is worth more than closing it. The visitor has already seen the dish on your web page. After the install, the app opens on a home screen that works without an account, and the dish is one search away. If the web page and the first run are good, most of the value of the link has already been delivered. I would ship that first and add the referrer on Android second.
The first run decides whether the link was worth sending
Someone tapped a friend's link, installed the app and opened it. If the next thing they see is a registration form, the journey ends there, and the friend's recommendation is spent.
Open on the home screen. Always. If and only if some condition is not met, consent or a required update, show that one screen and return. Splash screens and onboarding carousels spend the visitor's attention at the moment you have the most of it and give nothing back.
Let them use the app before asking who they are. Browsing needs no account at all: serve the catalogue from endpoints that ask for no session. For things the visitor creates, allow a fixed number before an account is required, and say so plainly.
const val FREE_ITEMS = 10
fun mayCreate(db: Db, signedIn: Boolean): Boolean =
signedIn || db.long("SELECT COUNT(*) FROM orders WHERE account_id = 0")!! < FREE_ITEMS
"You can save 10 orders before an account is required." Sign-in is available from the first second for anyone who wants it, and it has a "Not now" button. It is offered, never a wall.
What they made before signing in becomes theirs when they do. Rows created without an account carry account_id = 0. Signing in claims them:
fun Db.claim(account: Long) = transaction {
exec("UPDATE orders SET account_id = ? WHERE account_id = 0", account)
}
Nothing is lost and nothing is asked twice. The person who hits the limit has by then used the app ten times, which is the best moment there is to ask for an account. How those rows then reach the server, and how they survive on the device until they do, is the subject of the retention article.
There is a cost, and it is on the server: public endpoints need rate limiting, because they have no account to hold responsible.
Making sharing one tap
The link has to be easy to produce. Put a share action on every screen that has an address, and hand the platform's share sheet a plain URL:
fun share(context: Context, dish: Dish) {
val send = Intent(Intent.ACTION_SEND)
.setType("text/plain")
.putExtra(Intent.EXTRA_TEXT, "https://food.example.com/dish/${dish.id}")
context.startActivity(Intent.createChooser(send, null))
}
Send the address alone. Chat apps build the preview from the web page's own title and image; a sentence of marketing glued in front of the link makes the message look like an advertisement written by the sender.
An item that only exists on the device cannot be shared yet, since the server has no page for it. Say so on the button, "available once synced", and move on.
Public catalogue items need nothing more. Links to private things, an order, a document, a photo album, are a different feature and need three properties from their first version: an unguessable token in the address in place of the item's id, an expiry, and a way for the owner to revoke the link. Adding those after links are already out in the world is not possible, because the old links are in other people's chat histories.
A checklist for release 0
- One HTTPS address per valuable item, on your own domain.
- A web page at that address with a title, a description and an image.
- Both association files served directly, as JSON, for every host you use.
- A routing function that maps an address to a stack with home underneath, and a table of addresses that is checked on every build.
- Start-up logic in one global place, with no screen owning it.
- Every linked screen loads itself from its id.
- The app opens on its home screen and can be used before signing in.
- A share action wherever there is an address.
None of this is expensive at the start. All of it is expensive later, when the navigation has grown around a single entry point and forty screens assume the one before them. Regardless of what your app does, be the food app: let people hand each other a dish from the first release.
ComputeShack builds apps that keep working offline, and fixes the ones that do not.