Mobile app deep linking works when two files are in the right place.

What Apple looks for, and where

On iOS the association file is named apple-app-site-association, and Apple states plainly that it has no extension. Not .json, no extension at all. It goes in your site's .well-known directory, so the URL reads https://yourdomain.com/.well-known/apple-app-site-association. Apple also requires that you host the file using https with a valid certificate and with no redirects.

Inside, the file holds an applinks object with a details array. Each entry lists appIDs in the form of your Team ID prefix followed by your bundle identifier, such as ABCDE12345.com.example.app, plus a components array saying which paths on the domain belong to the app. That Team ID prefix is the same identifier you handle when you automate releases through the app store connect api. On the app side you add the Associated Domains capability with an entry shaped like applinks:example.com, with no path, no query and no trailing slash. Each subdomain needs its own entry and serves its own file.

One detail changes how you debug all of this. Since macOS 11 and iOS 14, apps no longer request the file from your web server directly. The request goes to an Apple managed content delivery network instead. Apple documents that its CDN requests the file for your domain within 24 hours, and that devices check for updates roughly once a week after the app is installed. So fixing the file and seeing the fix are two different events. If your web server is not reachable from the public internet while you develop, Apple documents an alternate mode that you turn on by adding a query string to the entitlement, which bypasses the CDN.

Apple, Supporting associated domains

What Google checks on the Android side

The Android file is assetlinks.json, and Google gives the location as https://domain.name/.well-known/assetlinks.json. For each unique hostname found in your intent filters, Android queries that address. Three serving rules travel with it. The file is served with content type application/json. It has to be reachable over an HTTPS connection, whether or not your intent filters declare https as the data scheme. And it has to be reachable without any redirects, no 301 and no 302.

The contents are a relation and a target. The relation is delegate_permission/common.handle_all_urls. The target names the android_app namespace, your package_name, and sha256_cert_fingerprints. The fingerprint is where most failures live: if Google Play signs your app, the fingerprint that matters is the one Play signs with, not the upload key on your laptop. One file can list several apps, and if your links cover several host domains you publish the file on every one of them.

In the manifest, at least one intent filter needs android:autoVerify set to true, the android.intent.action.VIEW action, both the BROWSABLE and DEFAULT categories, and an http or https data scheme. The system then verifies the association. Get the fingerprint wrong and the app installs perfectly, runs perfectly, and simply never claims the link. Nothing in the build tells you.

Google, Verify Android App Links

Why the link still opens the browser

Most taps do not start in Safari or Chrome. They start inside Instagram, Gmail, Slack or a mail client, and many of those apps open links in an embedded web view of their own. An embedded web view renders a web page. It is not a handoff, so your association is never consulted. This is the most common reason a link that is configured correctly still opens the web, and no amount of fixing the file will change it.

Redirects are the second reason, twice over. Both platforms refuse a redirect on the association file itself, so a tidy rule on your web server that forces every path through a canonical host can break verification without touching a line of app code. And the link itself is matched against the URL the user actually opened. A shortened link belongs to the shortener, so the association on your domain is not in the conversation. Serve deep links on a host you control.

The rest are quieter. The user can opt out: iOS remembers when someone chooses to open your domain in the browser, and Android lets a user turn off verified links for an app in system settings. Hosts have to match exactly, so example.com and www.example.com are two hosts, two entries and two files. And a staging domain with basic auth in front of it returns a login page rather than JSON, which reads as a missing file. Open both URLs in a private window before you rewrite any code, and test on a device that has never opened the link, because your own phone is contaminated by every earlier attempt.

Deferred deep linking, and where it stops

The tap you care about most is the one from a person who does not have the app. They tap, land in the store, install, open, and see a generic home screen with no memory of why they came. Deferred deep linking is the name for carrying that original intent across the install, and the two platforms are not equal here.

Android has a first party answer. Google Play passes an install referrer string, and the Play Install Referrer library hands your app that string on first run along with the referrer click and install begin timestamps. Google documents the referrer as available for 90 days, unchanged unless the app is reinstalled, and advises calling the API once during the first run after install. That is enough to route a new user to the right screen with no third party in the path.

iOS has no equivalent that carries a link through the App Store. Third party attribution SDKs fill the gap with probabilistic matching on device signals or with clipboard reads, and both routes have narrowed: the system now shows the user an alert when an app reads the pasteboard, and matching a person across apps by device signals is the behaviour governed by app tracking transparency. If the feature has to exist, budget for an SDK and read the consent rules before you design the flow around it.

There is a duller pattern that works on both platforms. Ask the new user for the thing the link was about: a short code shown on the page they came from, or a sign in that restores their context from your own server. It is one extra screen, and it survives every privacy change either platform makes.