Deep links in a mobile app: universal links, App Links and what breaks them

What is a deep link, and which kind should your app use?

A deep link opens a specific screen in your app, such as an order, a booking or a product, instead of the home screen. Use normal https links that your website verifies: universal links on iOS and App Links on Android. The same address then opens the app for people who have it and the matching web page for everyone else, from emails, ads, QR codes and messages.

Deep links touch the app and the website at the same time, which is why they often break quietly. Our mobile app development team plans them alongside the screens they open.

What kinds of deep links are there?

Apple describes custom schemes as an acceptable form of deep linking but strongly recommends universal links. On Android, App Links have been available since Android 6 and need the website to confirm that it trusts the app.

How do universal links and App Links verify your domain?

Both platforms check a file on your website when the app is installed, so only the owner of the domain can send its links to an app.

• iOS: a file called apple-app-site-association in the site's .well-known folder, plus the Associated Domains entitlement in the app. Apple requires the file over https with a valid certificate and no redirects, and each subdomain, such as www and support, must serve its own copy.
• Android: a file called assetlinks.json at /.well-known/assetlinks.json, served over https as application/json, without any 301 or 302 redirects, on every host the app handles. It lists the app's package name and the SHA256 fingerprint of its signing certificate.

On iOS, these files are fetched through an Apple-managed content delivery network, which requests your file within 24 hours, and devices check for updates about once a week after installing the app. A fix to the file is therefore not instant on phones that already have the app.

What usually stops deep links from opening the app?

• Redirects. Android does not verify App Links if the domain redirects, for example from http to https or from example.com to www.example.com. Serve the file directly on every host listed in the app.
• The wrong fingerprint. If Play App Signing signs your app, the fingerprint from your own keystore will usually not match the one on users' devices; Play Console shows the correct Digital Asset Links snippet. A debug build signed with a debug key also fails if only the release key is listed.
• A missing subdomain. Links on www, a shop subdomain or a campaign domain each need their own file.
• Files behind a login, firewall or VPN. Android's guidance is not to ship test URLs that are only reachable on a VPN, because verification needs the public file.
• Testing in the wrong place. When someone is browsing your site in Safari and taps a link to the same domain, iOS keeps them in Safari on purpose. Test from Mail, Notes or a messaging app instead.

What should happen when the app is not installed?

The link opens your website, so every path the app handles needs a real, useful page there, not a 404 or a bare store badge. Show the content the link promised, and offer the app as an option. This is where the web development side of deep links matters most.

If someone installs the app from that page, plan what the first open should show. On Android, the Play Install Referrer API lets the app read the referrer URL of the install, which can carry details of the link that brought the person in.

How should the app handle an incoming link safely?

Treat every link as untrusted input. Apple advises validating all URL parameters, discarding malformed URLs and never letting a link directly delete content or reveal sensitive information. In practice:

• Check that the record exists and that the signed-in person may see it.
• If the screen needs a login, send the person to sign in and then continue to the linked screen.
• Send unknown paths to a sensible screen instead of crashing or showing a blank page.

Deep links pair naturally with notifications; our guide to push notification permission covers earning the right to send them.

Can you change which links open the app without an app update?

Partly. Apple's association file can describe which URL components the app handles. On Android 15 and higher, Dynamic App Links let you define rules and exclusions in assetlinks.json without publishing a new version, although the server rules cannot expand the scope declared in the app's manifest. Keep the manifest broad enough for the paths you expect, and use the server file to exclude pages such as account settings that should stay on the web.

How do you test deep links before release?

• Android: after installing, wait at least 20 seconds, then use adb shell pm get-app-links to see whether each domain shows as verified; Android 12 and higher can also re-run verification manually.
• iOS: if your test server is not reachable from the internet, the Associated Domains alternate mode lets a development build bypass Apple's network.
• Both: tap links from email, chat, a QR code and an ad preview, with and without the app installed, signed in and signed out, and include malformed links.

Add deep link checks to the release list in our App Store and Google Play publishing checklist, so a website change never breaks them silently.

Frequently asked questions

Last updated November 12, 2026