Deep Linking in Mobile Apps: Universal Links and App Links

Deep linking in mobile apps sounds like a small feature: tap a link, land on the right screen. In practice it touches your web domain, your backend, both app stores’ signing setups, marketing attribution and sign-in. When one piece is wrong, the link opens a browser, a home screen or a 404, and nobody notices until a campaign underperforms.

The setup lives partly on your servers, which is why we treat it as part of mobile app backend development rather than a last-minute app task. This guide covers the three kinds of deep link, how Universal Links and Android App Links verify, what to do now that Firebase Dynamic Links is gone, how to route links inside the app, and a testing checklist for release day.

On Apple platforms, verification uses a JSON file named apple-app-site-association with no file extension, placed at https://yourdomain.com/.well-known/apple-app-site-association. The app declares the domain in its Associated Domains entitlement as applinks:yourdomain.com. Apple’s associated domains documentation is strict on hosting: the file must be served over https:// with a valid certificate and with no redirects.

Two details that cause most iOS failures

Every subdomain counts separately. www.example.com and example.com each need their own file and their own entitlement entry. Marketing links on go.example.com will not open the app just because the main domain works.

Apple’s CDN sits in the middle. Since iOS 14 and macOS 11, devices fetch the file from an Apple-managed CDN, not from your server. Apple says the CDN requests the file within a 24-hour window, and installed devices check for updates approximately once per week. A fix to your AASA file is therefore not instant, and testing on a phone that installed the app last week can show old behaviour. Test fixes on a fresh install, and get the file right before launch.

Common causes beyond those two: a CDN or firewall that redirects or blocks the .well-known path, a login wall in front of the domain, or path patterns in the file that do not match the URLs marketing actually sends.

On Android, an intent filter with android:autoVerify=“true” tells the system to verify each host by fetching https://yourdomain.com/.well-known/assetlinks.json. According to Android’s App Links documentation, the file must be served over HTTPS, even if the intent filter declares http, with content type application/json and without any redirects. It lists your app’s package name and the SHA-256 fingerprints of its signing certificates.

The fingerprint trap

With Play App Signing, Google signs the build users install. A fingerprint taken from your local keystore with keytool will usually not match. Copy the snippet from Play Console under Release, Setup, App signing. Add the debug or upload-key fingerprint too if testers install builds signed outside Play.

Why Android 12 raised the stakes

Starting in Android 12 (API level 31), a generic web link opens your app only if the app is approved for that specific domain. If verification fails, the link opens in the user’s default browser instead. Nothing tells the user why, so the failure shows up only in analytics as lower app opens.

Start by listing what Dynamic Links did for you. For many apps it was only two jobs: opening the app from a shared link, and sending users without the app to the right store. Verified links on your own domain cover the first job. A web page at that link URL covers the second: if the app is not installed, the browser loads the page, which shows the content or a store button.

Deferred deep linking is the harder part. Branch’s glossary describes it as a deep link that survives an install, so a new user goes through the app store and then lands on the specific content. If your growth depends on it, for invites, referrals or paid campaigns, Google lists Adjust, Airbridge, AppsFlyer, Bitly, Branch, Kochava and Singular as providers, while noting it has not vetted them. Compare them on attribution features, pricing and privacy terms during discovery.

Some products can avoid a vendor with account-based matching. An invite link carries a code. The new user installs, signs up, and enters or confirms the code, or the server matches the invite to the email address they register with. It is less automatic, but it uses no device fingerprinting and stays within your own systems. Paid acquisition at scale usually still needs an attribution provider; our mobile app marketing company page covers how that fits with campaign tracking.

Verification gets the user into the app. Routing decides whether they land somewhere useful. Many deep-link bugs live here rather than in the verification files.

• One central router. Every entry point (Universal Links, App Links, push notifications, widgets, in-app links) passes a URL to the same router. Two parsing paths mean two sets of bugs.
• Cold start and warm start. A link that opens a closed app arrives through a different callback from one that opens a running app. Test both on both platforms.
• Sign-in gates. If the destination needs an account, store the destination, run sign-in, then continue. Dropping users on the home screen after login loses many of them.
• Missing or forbidden content. Deleted items, expired offers and content for another account need a friendly screen, not a crash or a blank view.
• Versioned paths. Old app versions stay installed for months. Keep link paths stable and let the web fallback handle routes an old build does not know.
• Attribution parameters. Read UTM or campaign parameters into analytics, then strip them before routing.

Push notifications should carry a deep link URL rather than a custom payload format, so the same router handles them. Our push notifications for mobile apps page covers the delivery side.

A deep link is input from outside the app, and anyone can craft one. Treat it that way.

• Validate every parameter. IDs, amounts and redirect targets in a link are untrusted. Look them up on the server; never trust a price or role from a URL.
• No long-lived secrets in links. Password-reset and magic sign-in links should be single-use and short-lived, and should open through verified links, not custom schemes another app could register.
• Use verified links for OAuth redirects. RFC 8252 requires native apps to use the system browser for authorization and PKCE for public clients. Our authentication and SSO for mobile apps page covers the full flow.
• Confirm destructive actions. A link should never delete, pay or change settings without a confirmation screen.