Deep Link Doctor
Home / Developer notes

Links on your own website stay in Safari

Universal links on your own site stay in Safari because same-domain taps continue in the browser. How to send web visitors to the app with a link domain.

SymptomTapping a link on your own website stays in Safari even though the same link opens the app from Notes.
Likely causeNavigation within the same domain is treated as continuing in the browser, so iOS does not open the app.
FixLink to a different domain or subdomain that has its own entitlement entry and AASA file.

Short answer: When a user is already on example.com in Safari and taps a link to another page on example.com, iOS keeps them in the browser. Apple treats this as continuing on the website. To send web visitors into the app, link to a different domain or subdomain, such as go.example.com, that has its own entitlement entry and AASA file.

What is happening

Same-domain navigation: a tap on a link that points to the same domain as the page the user is viewing, which iOS keeps in the browser rather than opening as a universal link.

Apple's technote and its "Allowing apps and websites to link to your content" page describe this behaviour. The logic is that someone browsing your site has chosen the web, so links within it continue there.

  • The same URL opens the app when tapped from Notes, Messages or another site.
  • "Open in app" banners on your site that link to your own domain hit this problem.

Why does this happen?

Universal links are meant for crossing from one context to another, such as from a message or another site into your app. A tap within one domain does not cross that boundary, so iOS treats it as normal web navigation.

A related case: Apple says that if your app opens a universal link to your own website using UIApplication open methods, "the link won't open in your app". Route those links inside the app instead.

How to confirm it

  1. Tap the link from Notes. If the app opens, the file and entitlement are fine.
  2. Tap the same link from a page on your own domain. If it stays in Safari, this is same-domain navigation.
  3. Tap it from a page on a different domain. It should open the app.

How to fix it

  1. Pick a separate link domain or subdomain, for example go.example.com or a branded short link domain.
  2. Add it to the Associated Domains entitlement: applinks:go.example.com. A file on example.com does not cover a specific subdomain like go.example.com.
  3. Serve an AASA file at https://go.example.com/.well-known/apple-app-site-association with a 200 and no redirect.
  4. Point your "open in app" buttons and banners at the link domain, not your main site.
  5. Have the link domain fall back to the matching page on your main site for users without the app.
  6. Inside the app, handle your own URLs with in-app routing rather than calling open.
Entitlement
applinks:example.com
applinks:go.example.com

Web page on example.com
<a href="https://go.example.com/product/1">Open in the app</a>

Hosted options: deep linking providers such as Linkrunner, Branch, Airbridge and Adjust can host a branded link domain with its AASA file for you.

Publish the file on the new domain, check it with curl -I https://links.example.com/.well-known/apple-app-site-association and sudo swcutil dl -d links.example.com, and follow the universal links setup guide for the entitlement.

FAQ

Common questions

Why does the link open the app from Notes but not from my site?

From Notes, the tap crosses from another app into your domain. From your own site, the user is already on that domain, so iOS keeps the navigation in the browser.

Does a subdomain count as a different domain?

It needs its own entry in the entitlement and its own AASA file. Apple says each subdomain must serve its own file, and a file on the apex does not cover a specific subdomain such as `www`.

Can I use a wildcard entitlement for link subdomains?

Yes. Apple allows `applinks:*.example.com` for all subdomains, with the file served at the apex. Note that the wildcard form is not allowed for the `appclips` service.

Why does my app open its own links in Safari?

Apple says an app that opens a universal link to its own website using `open` methods will not open in the app. Handle those URLs with in-app navigation instead.

What are UTM parameters?

UTM parameters are tags added to the end of a link, such as utm_source and utm_campaign, that tell analytics tools where a visit came from. They let you see which campaign, channel and ad brought each visitor.

Which UTM parameters are required?

Use utm_source, utm_medium and utm_campaign on every campaign link. utm_term and utm_content are optional and help you compare keywords or ad variants.