Universal Links
Also known as: ios universal links, apple app site association, ios universal links
Universal Links are standard https URLs that open an installed iOS/iPadOS app directly instead of Safari, after the system verifies domain ownership via an apple-app-site-association file. If the app isn't installed, the same link loads the web page.
- Backed by an apple-app-site-association file at /.well-known/ plus an Associated Domains entitlement (applinks:).
- The app receives the link through NSUserActivity with type NSUserActivityTypeBrowsingWeb.
- If the app isn't installed, the same https URL opens the website instead of failing.
How they work
A Universal Link is a normal https URL with no custom scheme. To claim it, you host an apple-app-site-association (AASA) file at https://yourdomain.com/.well-known/apple-app-site-association and add an Associated Domains entitlement to the app with an applinks:yourdomain.com entry.
The AASA JSON declares which paths map to your app using your App ID (Team ID + bundle ID). The system fetches and caches it, then routes matching links straight to your app, delivering the URL to the app via NSUserActivity with the NSUserActivityTypeBrowsingWeb activity type.
Universal Links vs custom URL schemes
Older custom URL schemes (like myapp://) are unverified: any app can register the same scheme, and tapping the link fails silently or shows nothing if the app isn't installed. Universal Links solve both problems because Apple verifies domain ownership and the same https URL gracefully falls back to the website when the app is absent.
Common gotchas: the AASA file must be served over HTTPS with the correct application/json content type and no redirects; entering the URL directly in Safari's address bar won't trigger the app (the link must be tapped from another context); and you can debug routing with the swcutil command-line tool or Xcode's diagnostics.