Universal links ios are standard HTTPS URLs that open your native app directly when it is installed and fall back to a normal webpage in Safari when it is not, with no custom URL scheme and no app store interstitial in between. Apple introduced them in iOS 9 to replace custom schemes with a web-verified, tamper-resistant way to deep link into apps.
This guide covers how apple universal links actually work under the hood, the exact files and entitlements you need to configure them, a Swift handler you can drop into your AppDelegate, and the four problems that break universal links in ios more often than anything else.
What Are iOS Universal Links?
A universal link is a regular https:// URL that both your website and your iOS app agree to handle, verified through a file hosted on your domain. Unlike custom schemes such as myapp://, the link works everywhere, in a browser, an email client, or a text message, because it is a normal web address first.
When someone taps https://yourdomain.com/products/shoes, iOS checks whether an installed app has claimed that domain. If it has, the app opens straight to that product page. If not, Safari opens the same URL as a normal webpage. No error message, no "install our app" dead end, no redirect chain.
Opens directly in your iOS app if it is installed
Opens in Safari if the app is not installed
Works without any app store redirect prompt in between
Platforms like Smler's deep linking solution build on top of this behaviour to add analytics and branded short domains without breaking the link's ability to open the app.
How Do Apple Universal Links Work?
A universal link ios implementation rests on three pieces: an Apple App Site Association (AASA) file hosted on your server, an Associated Domains entitlement declared inside your app, and a handler method that receives the URL once iOS decides to open your app instead of Safari.
1. The Apple App Site Association file
The AASA file is a JSON file you copy into the Smler dashboard, not inside the app, at one of these two locations:
https://yourdomain.com/.well-known/apple-app-site-association
https://yourdomain.com/apple-app-site-associationIt tells iOS which app, and which paths on your domain, are allowed to open that app instead of the browser:
{
"applinks": {
"apps": [],
"details": [
{
"appIDs": ["TEAMID.com.yourcompany.yourapp"],
"paths": [
"/products/*",
"/blog/*"
]
}
]
}
}Requirements that trip people up:
Served over HTTPS, not HTTP
Content-Type header of
application/jsonNo redirects, the file must respond at the exact URL with a 200 status
File size under 128 KB
2. The Associated Domains entitlement
Inside Xcode, you add the Associated Domains capability to your app's target and list every domain that should trigger your app, prefixed with applinks::
applinks:yourdomain.com
applinks:www.yourdomain.comThis entitlement is what tells iOS, at install or update time, to go fetch and cache the AASA file from each listed domain. Without it, iOS never looks for the file at all and every link from that domain opens in Safari regardless of what the AASA file says. Apple's associated domains documentation covers the entitlement syntax in full.
3. Handling the link in your app
When iOS opens your app from a universal link, it does not call your scheme handler, it calls a dedicated method on your app delegate with the full URL:
func application(_ application: UIApplication,
continue userActivity: NSUserActivity,
restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let url = userActivity.webpageURL else {
return false
}
// Hit the Smler endpoint to resolve the short URL to a long URL,
// then route to the matching screen in your app
handleIncomingURL(url)
return true
}Your job inside handleIncomingURL is to hit the Smler endpoint to get the corresponding long URL for this short URL. Using that, you can open the specific screen in app. If the path does not match anything you recognise, fall back to your app's home screen rather than doing nothing.
What happens on a tap, end to end:
iOS checks whether any installed app has claimed the tapped domain via Associated Domains
It matches the URL's path against the patterns cached from that domain's AASA file
If there is a match and the app is installed, iOS opens the app and calls the delegate method above
If there is no match, or the app is not installed, Safari opens the URL as a normal webpage
Note that iOS only downloads and caches the AASA file when the app is installed or updated, not on every tap. That caching is also why changes to the file do not show up instantly, more on that in the troubleshooting section below.
Universal Links vs App Links vs Custom URL Schemes
Universal links are Apple's iOS-only implementation of verified HTTPS deep linking; Android App Links are the equivalent on Android, using a similar verified-domain model; custom URL schemes (myapp://) are an older, unverified approach available on both platforms but without domain ownership checks. If you are building for both platforms, you need both universal links and App Links configured separately, they do not share a single file format.
| Approach | Platform | Domain verified | Works as a web link |
|---|---|---|---|
| Universal Links | iOS | Yes (AASA file) | Yes |
| App Links | Android | Yes (assetlinks.json) | Yes |
| Custom URL Scheme | iOS and Android | No | No |
For a full side-by-side comparison, including setup differences, see the Universal Links vs App Links guide.
How to Set Up Universal Links in iOS: Step-by-Step Tutorial
Setting up a universal link ios implementation takes nine steps, from writing the AASA file to verifying it fires on a real device. Skipping the "test from an external app" step is the most common reason developers think it is broken when it is actually working.
Write your AASA file with your Team ID, bundle identifier, and the exact paths you want the app to claim
Host the file at
https://yourdomain.com/.well-known/apple-app-site-associationwith a valid SSL certificate, no redirectsAdd the Associated Domains capability in Xcode's Signing & Capabilities tab
List your domains in the format
applinks:yourdomain.comImplement the delegate method shown above to receive and route the incoming URL
Build and install a fresh copy of the app on a physical test device (universal links are unreliable on simulators)
Tap the link from an external source such as Notes, Messages, or Mail, never from inside Safari's own address bar or the same domain
Validate the file's format with a dedicated tool before assuming the code is at fault
Monitor real-world performance once you ship, to see how often links actually open the app versus the browser
Why Aren't My Universal Links Working in iOS?
Universal links in ios usually break for one of four reasons: the AASA file isn't reachable, the Associated Domains entitlement is missing or stale, the long-press menu doesn't show the app option, or iOS is still serving a cached version of an old AASA file. Each has a distinct, checkable fix.
1. The AASA file isn't being downloaded
This is the most common issue. Verify:
The file is accessible at the correct URL with no typos in the path
Your server returns it over HTTPS with a valid SSL certificate
No redirects are happening between the request and the file
The Content-Type header is set correctly
Check your file's format and headers with Smler's AASA validator before digging into app code.
2. Links open in Safari instead of the app
If universal links open Safari rather than your app, check:
The Associated Domains entitlement is correctly configured in Xcode
You have installed a fresh build after adding Associated Domains, old installs won't re-check it
The URL's path actually matches a pattern in your AASA file
You are testing from an external source, not from Safari's own address bar or the same domain
3. The long-press menu shows the wrong options
When users long-press a universal link, they should see an option to open it in your app. If that option is missing, iOS has not recognised the link as a universal link at all, which almost always traces back to the AASA file or the Associated Domains configuration rather than your in-app routing code.
4. Changes to the AASA file don't take effect
iOS caches the AASA file and does not re-check it on every tap. To force an update:
Uninstall and reinstall the app on test devices
For production users, ship an app update through the App Store, which forces a re-download
Allow up to 24 hours for Apple's CDN to propagate the change everywhere
For a systematic way to confirm a link is actually firing on device, walk through the guide to testing deep links on iOS.
What Happens When the App Isn't Installed?
Universal links only handle the case where your app is already on the device, they do nothing for a user who clicks the link, lands on your website, and installs the app later with no memory of what they originally wanted. That gap is covered by deferred deep linking, which remembers the intended destination through the App Store install and reopens the app to that exact content afterward.
For a complete mobile strategy you typically need both. Smler's deferred deep linking capabilities are built to work alongside universal links rather than replace them, and the iOS integration guide walks through wiring both into the same Swift codebase.
Universal Links and URL Shorteners
Universal links have to use your own domain, which creates friction when you need a short link for SMS, want per-link analytics, or are running the same campaign across several channels. An intelligent URL shortener solves this without breaking the link's ability to open your app.
Smler's platform is built specifically to sit in front of universal links, letting you:
Create short, branded URLs that preserve universal link behaviour
Use custom branded domains that keep user trust intact
Apply device-based routing for apps that ship on both iOS and Android
If you are moving off Firebase Dynamic Links, Smler also documents a Firebase Dynamic Links migration path now that Firebase has shut the service down.
Universal Links Best Practices
1. Support both www and non-www domains
Users may land on https://example.com or https://www.example.com. Add both as separate applinks: entries and host an AASA file at each.
2. Use specific path patterns
Claiming everything with "*" invites conflicts. Specify exact patterns like "/products/*" so you keep control over which links actually open the app.
3. Implement a sensible fallback
If a deep link's parameters are missing or malformed, route to a default screen. A crash on a bad link is worse than no deep link at all.
4. Test across iOS versions
Universal link behaviour has shifted across releases. Test on the current iOS version and on the oldest version your app still supports.
5. Monitor link performance
Track how often links are actually opening the app versus falling back to the browser. Smler's analytics dashboard surfaces this split per link.
A Brief History of Universal Links
Apple introduced universal links at WWDC 2015 as part of iOS 9, alongside Spotlight indexing and Safari View Controller, to fix the two big problems with custom URL schemes: any app could register any scheme, and there was no way to verify the app claiming a scheme actually owned the matching domain. Requiring domain ownership through the AASA file solved both at once, and the core mechanism has stayed the same since, with iOS 17 and 18 mainly improving caching speed and Xcode's debugging tools around it.
