Deep Links: Opening Your App From a Web Link

What a deep link does

Links reach customers in emails, messages, social posts, QR codes and ads. Without deep links, a link to "your order" opens a web page, even for someone signed in to your app. With them, it opens the right screen.

Typical uses:

• a "track your order" or "view your booking" link in a confirmation email;
• a password reset or sign-in link;
• a notification that opens the matching screen, covered in our guide to push notifications.

Custom schemes and web links

Android's guide to creating deep links describes three types:

• Custom deep links use a made-up scheme "such as example://products/123". They suit links from sources you control, but they "are not standard web links" and can trigger a choice of apps "if another app registers the same custom scheme".
• Web links use ordinary http and https addresses. On Android 12 and higher, unverified web links "are likely to be handled by the user's web browser by default, rather than being routed to your app".
• App Links are "verified web links": you prove to Android that you own the website, and links to it open your app.

Apple gives the same advice. Its page on custom URL schemes calls them "an acceptable form of deep linking" but says "universal links are strongly recommended". If several apps register the same scheme, "the app the system targets is undefined".

So for links you send customers, use verified web links on your own domain.

Universal links on iPhone

Apple's overview of linking to your content explains the idea: universal links "are standard HTTP or HTTPS links", so "one URL works for both your website and your app". When someone taps one, the system opens your app "without routing through the person's default web browser or your website".

The link works only after a two-way association between the app and the website:

• In the app: the developer adds the Associated Domains capability and lists your domains, such as applinks:www.example.com.
• On the website: a file called apple-app-site-association lists your app and the paths it should open.

Apple's page on supporting associated domains adds:

• each subdomain, such as example.com and www.example.com, "requires its own entry" and "must serve its own apple-app-site-association file";
• Apple's network "requests the apple-app-site-association file for your domain within 24 hours", and "devices check for updates approximately once per week after app installation", so changes to the file are not instant.

One behaviour often surprises people. When someone is already browsing your website in Safari and taps a universal link "in the same domain, the system opens that link in Safari".

App Links on Android

Android's overview of App Links describes them as "a special deep linking capability in Android 6 and later that allows your verified website URLs to immediately open corresponding content in your Android app, without requiring the user to select your app" from a list. They need "devices with Google services installed".

The setup mirrors Apple's:

• In the app: the manifest lists the website addresses the app handles, marked with android:autoVerify="true".
• On the website: a Digital Asset Links file, assetlinks.json, names the app's package and "the SHA256 fingerprints of your app's signing certificate".

When the app is installed, Android fetches the file and checks that the fingerprint "matches your app's signing certificate". A common mistake is using the wrong fingerprint. Android's page on declaring website associations warns that with Play App Signing, a fingerprint made on the developer's computer "will usually not match the one on users' devices", and points to the Play Console page (Release > Setup > App signing) that shows the correct snippet.

From Android 15, "Dynamic App Links" let you change which paths open the app by editing the file "without needing to publish a new version of your app".

What your website must host

Both files live in the /.well-known/ folder of every domain the app links to, so whoever runs your website is part of the setup. The rules are strict:

• Apple: host the file "using https:// with a valid certificate and with no redirects", at /.well-known/apple-app-site-association, with no file extension.
• Android: serve /.well-known/assetlinks.json "with content-type application/json", over HTTPS, and "without any redirects (no 301 or 302 redirects)", on each domain the app handles.

Redirects catch people out, for example a rule that sends example.com to www.example.com, or a security setting that blocks unknown files. Check both addresses in a browser after every website change or hosting move. Our guide to moving a website to a new host has a wider list of things to check.

When the app is not installed

Because these links are ordinary web addresses, the fallback is built in. Apple says that if the person has not installed your app, "the system opens the URL in their default web browser, allowing your website to handle it". Android's overview says the same: "users who don't have the app installed go to your website instead".

That makes the website half of the work. Every deep link needs a real page at the same address that shows the same content, or at least explains it and offers the app.

On iPhone, you can also invite web visitors to the app with a Smart App Banner, a single meta tag in the page's head. Apple's Smart App Banner documentation says that if the app is installed, "tapping the banner simply opens the app"; if not, it goes to the App Store. If you are weighing an installable website instead of an app, see our guide to progressive web apps.

Treat every link as untrusted

Anyone can create a link to your domain, so the app must not trust what is in it. Apple's page on supporting universal links says they "offer a potential attack vector into your app", so "validate all URL parameters and discard any malformed URLs". It adds: "don't allow universal links to directly delete content or access sensitive information about the user."

A link should open a screen; paying, cancelling or changing account details still needs the person signed in and confirming. Our mobile app security guide covers the wider picture.

Testing deep links

Test on real devices, with and without the app, from an email app, a messaging app and a web page on another domain.

• Android: the verification guide shows commands that report each domain's state; only "verified" means it worked, and "none" may mean the check has not finished. Android Studio's App Links Assistant can guide you through setting up and verifying the links.
• Apple: Apple says your test cases should "include improperly formatted URLs".
• Both: try links signed in and out, and with an old app version.

Add deep links to your release checklist, since a website change can break them without any change to the app. Our guide to testing a mobile app covers the rest.

A checklist

• The links you send customers are listed, each with a matching page on the website.
• Links are https addresses on your own domain, not custom schemes.
• The iPhone app lists your domains; the website serves apple-app-site-association on each.
• The Android app requests verification; assetlinks.json uses the Play App Signing fingerprint.
• Both files load over HTTPS with no redirects, on every domain and subdomain.
• The app checks every link and never acts on one without the person signed in.
• Links are tested from email and messages, with and without the app installed.

Frequently asked questions

What is the difference between a deep link and a universal link?

A deep link is any link that opens a particular screen in an app. A universal link is Apple's kind of deep link that uses an ordinary https address on your website, verified with a file on that site, so the same link opens the app if it is installed and the website if not. Android's equivalent is App Links.

Do deep links work if someone does not have the app?

Universal links and App Links do: they are normal web addresses, so without the app they open your website. Make sure each one has a real page at that address. Custom scheme links, such as example://, have no website to fall back to.

Why does my link open the website instead of the app?

Common causes are a missing or redirected apple-app-site-association or assetlinks.json file, a wrong signing certificate fingerprint on Android, a domain or subdomain missing from the app's settings, or on iPhone, tapping a link to the same domain while already in Safari.

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

Partly. Apple's association file on your website lists the paths the app handles, though devices check for updates about once a week. On Android 15 and later, Dynamic App Links let you change paths and exclusions in assetlinks.json without a new app version.

Are deep links safe?

They are safe if the app treats them as untrusted. Apple advises validating every parameter, discarding malformed links and not letting a link delete content or reveal sensitive information. Actions such as payments should still need sign-in and confirmation.

Planning an app that should open from your emails and website? We build iPhone and Android apps together with the backend, API and admin dashboard behind them. See our mobile app development service and all our services, or email [email protected].