# iOS Universal Links: How They Work and How to Set Them Up (2026) > iOS Universal Links explained: how AASA files work, entitlement setup, Swift handling, testing on device, common failures, and a no-code shortcut for teams without a developer. URL: https://u2l.ai/blog/universal-links-ios-guide Published: 2026-07-04T15:17:29+05:30 Updated: 2026-07-04T15:17:29+05:30 Author: Team U2L Category: developer Tags: universal-links, ios, deep-links, developer --- iOS Universal Links are standard HTTPS URLs that open your iOS app directly when it is installed and fall back to your website in Safari when it is not. They rely on a two-sided handshake: an `apple-app-site-association` (AASA) file hosted on your domain, and an Associated Domains entitlement in your Xcode project. When both agree, iOS routes the tap into the app with no chooser dialog and no error state. If you have ever tried to set up **iOS Universal Links** and watched them silently fail with no error message, you are in good company. Universal Links are one of Apple's cleanest ideas and one of its most frustrating implementations. Get one character wrong in the AASA file, forget a wildcard, miss a checkbox in the entitlements pane, and iOS just quietly opens the link in Safari as if the app never existed. There is no red banner. No log line in the console. Just a mysteriously ignored link. This guide walks through the whole picture: what Universal Links are, how the AASA handshake actually works, how to configure the entitlement, how to handle the incoming URL in Swift or SwiftUI, how to test on a real device (yes, it has to be a real device), the debugging tools Apple ships but nobody talks about, and the exact failure patterns that eat 80% of a developer's afternoon. If you are a marketer or a founder who does not have a developer on staff, we will also show a no-code path that skips the whole setup dance. ## Table of Contents - [What Are iOS Universal Links?](#what-are-ios-universal-links) - [Universal Links vs URI Schemes vs App Clips](#universal-links-vs-uri-schemes-vs-app-clips) - [How the AASA Handshake Works](#how-the-aasa-handshake-works) - [Step-by-Step: Setting Up Universal Links](#step-by-step-setting-up-universal-links) - [Handling the Incoming URL in Your App](#handling-the-incoming-url-in-your-app) - [Testing Universal Links on a Real Device](#testing-universal-links-on-a-real-device) - [Common Failures and How to Debug Them](#common-failures-and-how-to-debug-them) - [When to Skip Universal Links Entirely](#when-to-skip-universal-links-entirely) - [Frequently Asked Questions](#frequently-asked-questions) ## What Are iOS Universal Links? An **iOS Universal Link** is a standard HTTPS URL that iOS routes to a specific installed app instead of opening it in Safari. Introduced in iOS 9, Universal Links replace the older custom URI scheme model (`myapp://something`) with a domain-verified, hijack-proof handoff. When the app is not installed, the same URL loads as a normal web page. Same link, two graceful behaviours. The killer detail is the URL format. A Universal Link looks like `https://example.com/products/sneakers`. Nothing about it screams "app link." That is on purpose. The same URL can be shared over email, dropped in an Instagram bio, printed on a poster, or texted to a friend, and it always does the right thing based on what is installed on the receiving device. Apple's [Universal Links documentation](https://developer.apple.com/ios/universal-links/) covers the underlying model. Under the hood, Universal Links use a tiny piece of trust infrastructure. Your app declares in its entitlements that it can handle links for `example.com`. Your domain publishes a JSON file at `https://example.com/.well-known/apple-app-site-association` that names your app's bundle ID and lists which URL paths are eligible. iOS checks both sides on install (and periodically after) and caches the result. When a user taps a matching URL, iOS opens the app without ever loading the web page, unless the app is missing, in which case Safari takes over. No dialog, no chooser, no branded landing screen in between. The word "universal" is not marketing fluff, by the way. It is descriptive. One HTTPS URL universally routes to the right destination across iPhone, iPad, macOS Catalyst apps, and even AppClips. It just happens that iOS is where most teams first hit them, and where most of the debugging pain lives. ## Universal Links vs URI Schemes vs App Clips Three ideas get tangled up in "iOS deep linking" and it is worth pulling them apart before you start typing JSON. **URI schemes** are the old model: `myapp://path`. Any app can register any scheme, iOS has no way to verify who really "owns" it, and the link does nothing useful if the app is missing. Schemes are still fine for internal navigation and push notification routing, but Apple has been quietly reducing their reach for years. If you are shipping a customer-facing link in 2026, do not use a raw URI scheme. **Universal Links** are the current recommended model for opening app content from outside the app. HTTPS URL, verified by AASA, graceful web fallback, no way for another app to hijack. This is the workhorse. **App Clips** are a related feature that lets a small slice of your app launch on the fly without a full install (an ordering flow, a checkout, a rental unlock). App Clip codes and App Clip experiences also use HTTPS URLs and an AASA file, but with an `appclips` block instead of `applinks`. If you have a full app, App Clips are additive rather than a replacement. Most teams do not need them until they hit a specific in-store or in-restaurant use case. For the broader terminology map (Universal Link vs App Link vs deep link vs smart link), our [deep link vs universal link explainer](/blog/deep-link-vs-universal-link) lines up all the vocabulary side by side, and the [deep linking pillar guide](/blog/mobile-deep-linking-guide) sets the context for how Universal Links fit into a mobile marketing stack. ## How the AASA Handshake Works Every question that comes up in a Universal Links debugging session eventually reduces to "what does iOS actually check, and when?" The short answer is: two things, twice. The two things are your app's entitlement and your domain's AASA file. The two times are when the app is installed and, periodically, in the background as the OS refreshes its cache. Here is the handshake step by step: 1. When your app is installed, iOS reads the `com.apple.developer.associated-domains` entitlement, which is a list like `["applinks:example.com", "applinks:www.example.com"]`. 2. For each declared domain, iOS fetches `https://example.com/.well-known/apple-app-site-association` over HTTPS. Apple's Content Delivery Network (CDN) proxies this on modern iOS, so the request usually goes through `app-site-association.cdn-apple.com` rather than directly to your server. 3. iOS parses the JSON, finds an entry that matches your app's `appID` (which is `TEAMID.BUNDLEID`), and reads the `paths` (or `components` on newer iOS versions) that the domain is willing to hand off. 4. The verified matches get cached on device. When the user taps a URL, iOS consults the cache first, and only refetches the AASA periodically or on app update. The gotcha most teams hit is that this handshake is silent. If the JSON is malformed, if the Content-Type header is wrong, if there is a redirect on the well-known path, if the entitlement mode is set to unsigned in a way that does not match the environment, iOS just decides "this is not a Universal Link" and hands the URL to Safari. There is no error toast. There is no console log. There is, on new iOS versions, a `sysdiagnose` trace, but you have to know to look for it. This is why most Universal Links debugging is a game of elimination. ## Step-by-Step: Setting Up Universal Links ### Step 1: Build a valid AASA file Create a file named exactly `apple-app-site-association` (no extension). Its content is a JSON document describing which app owns which paths: ```json { "applinks": { "apps": [], "details": [ { "appID": "ABCD1234EF.com.example.myapp", "paths": ["/products/*", "/orders/*", "NOT /admin/*"] } ] } } ``` The `appID` is your Team ID (from your Apple Developer account) followed by the app's bundle identifier, joined with a dot. The `paths` array uses shell-style wildcards, and a path prefixed with `NOT ` is excluded, which is how you keep admin routes and legal pages inside Safari. On iOS 13 and newer, Apple recommends the `components` array instead of `paths`. It supports fragment matching, query-parameter matching, and localization, and it is the direction Apple is nudging everyone toward. If you only need to ship today and support older iOS, `paths` still works. If you are starting fresh, use `components`. Apple's [Allowing apps and websites to link to your content](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) documents the full AASA `components` format. ### Step 2: Host the AASA file correctly The file must live at `https://yourdomain.com/.well-known/apple-app-site-association`. A few rules that trip people up: - No `.json` extension on the filename, even though the body is JSON. - Serve it over HTTPS. Plain HTTP is not accepted. - Return `Content-Type: application/json`, not `text/plain` or anything else. - No redirects. The URL must return 200 on the first request. A 301 or 302 to the same path breaks the handshake. - Under 128 KB uncompressed. Big JSON files get rejected silently. - Available for both the apex domain and any subdomains you declare in the entitlement. `example.com` and `www.example.com` count as different hosts. ### Step 3: Add the Associated Domains entitlement in Xcode Open your app target, go to Signing & Capabilities, click "+ Capability" and add Associated Domains. Add an entry for each host, using the format `applinks:example.com`. If you want to test against a preview AASA that is not yet live, add `?mode=developer` to the entry during development. Make sure Associated Domains is enabled on your App ID inside the Apple Developer portal too, or the entitlement will be signed with the capability disabled and iOS will ignore the whole thing. Apple's [Supporting associated domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains) guide is the authoritative reference for the entitlement format and the newer `webcredentials`/`applinks` service syntax. ### Step 4: Handle the incoming URL in your app code Universal Links reach your app through the same continuation-of-user-activity API that Handoff uses. In SwiftUI, that means an `.onOpenURL` or `.onContinueUserActivity` modifier on your root view. In UIKit, it is the `application(_:continue:restorationHandler:)` method on your AppDelegate or the equivalent SceneDelegate hook. We show the exact Swift code in the next section. ### Step 5: Test on a real device before you ship Universal Links do not work in the iOS Simulator. You must test on hardware. The simplest test: email yourself the URL from a different account, open the Mail app on the device, long-press the link, and confirm the context menu shows an "Open in [Your App]" option. If it does, the handshake is working. If it does not, jump to the debugging section below. ## Handling the Incoming URL in Your App Setting up the file and entitlement is only half the job. Your app still needs to read the incoming URL and route the user to the right screen. Skip this and taps will open your app to whatever the last state was, which is a lousy experience. In SwiftUI: ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { RootView() .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in guard let url = activity.webpageURL else { return } handleIncomingURL(url) } } } func handleIncomingURL(_ url: URL) { // Route based on url.path and url.queryItems } } ``` In UIKit with a SceneDelegate: ```swift func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { guard userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url = userActivity.webpageURL else { return } router.route(to: url) } ``` The routing itself is your app's concern, not Apple's. A common pattern is to map URL paths to a small enum of destinations (`.product(id)`, `.order(id)`, `.profile(handle)`), then have the same routing layer handle both Universal Links and internal navigation. That way a push notification that opens `myapp://product/42` and a Universal Link that opens `https://example.com/products/42` land in the same code path. Which is exactly what you want. A subtle point: iOS delivers Universal Links via the `NSUserActivity` API only when the app is opened from outside itself. If you paste the same URL into the Safari address bar and hit go, iOS intentionally opens Safari, not the app. This is a documented anti-loop measure. If you want the address bar case to open the app too, users have to long-press and choose "Open in [App]" from the context menu. Do not spend a Saturday debugging this behaviour, we did once. ## Testing Universal Links on a Real Device Testing Universal Links is where the frustration usually peaks, because the Simulator does not support them and every real-device test involves some form of fresh install or cache reset. A few workflows that work. **The Mail test.** Email yourself the URL from a different email account, open the message on your test device, and tap the link. This is Apple's recommended smoke test and it correctly routes through the Universal Links path. **The Notes app test.** Type or paste the URL into a Notes document on your device, then tap it. Notes uses the same handoff as Mail. Do not test from Safari's address bar. That path is deliberately excluded. **Fresh install after AASA changes.** iOS aggressively caches AASA files. If you push a new AASA and reinstall the app on top, sometimes the cache carries over. The reliable reset is: delete the app, restart the device, then install fresh. That forces iOS to refetch. On iOS 14 and later you can also toggle the developer mode entry in Associated Domains to force a refresh. **Apple's own validator.** Apple hosts a validator at `https://app-site-association.cdn-apple.com/a/v1/example.com`. Swap in your domain and hit that URL. If Apple's CDN can parse your AASA, iOS can too. This is the fastest way to catch Content-Type errors, redirects, and encoding issues without any of the on-device dance. **swcutil on macOS.** On macOS, the `swcutil` command-line tool dumps the shared web credentials daemon's cache, including which domains are verified for which apps. `swcutil dl -d example.com` shows the current status. It is niche but priceless when the app "sometimes" opens. **Xcode Console.** Filter the device console for `swcd` (the shared web credentials daemon). When AASA verification fails, `swcd` logs why. It is verbose and sometimes cryptic, but it will tell you if the file was rejected as invalid JSON or fetched with the wrong content type. ## Common Failures and How to Debug Them We keep a running list of the failures we see teams hit most. About 90% of "my Universal Link opens Safari instead of the app" tickets come from one of these. **The AASA file has a `.json` extension.** The filename must be exactly `apple-app-site-association`, no extension. Serving it as `apple-app-site-association.json` breaks the fetch. Set a custom route in your web framework if you have to. **Wrong Content-Type header.** It must be `application/json`. `text/plain` will fail. Some CDNs default to `application/octet-stream` for unknown extensions; override the header explicitly. **A redirect on the well-known path.** If your web framework rewrites `/.well-known/apple-app-site-association` to a canonical URL or adds a trailing slash, iOS considers the response invalid. The path must return 200 directly with no hops. **Team ID mismatch.** The `appID` field is Team ID plus bundle ID. Copy the Team ID from your Apple Developer account, not from an outdated build setting. This one bites indie developers who switched teams for a specific project. **Associated Domains entitlement not signed.** Adding the capability in Xcode is not the same as enabling it on the App ID inside the developer portal. If the signing certificate does not include the entitlement, iOS silently drops it. Re-check on your provisioning profile. **Testing from Safari's address bar.** Universal Links are intentionally ignored when a user types the URL into Safari. This is not a bug. Use the Mail or Notes test instead. **Testing in the Simulator.** The Simulator does not support Universal Links. Testing there always fails. Use a real device. **Aggressive AASA caching.** iOS caches the AASA for a long time. After changing the file, do a full delete-and-reinstall on the test device. Optionally add `?mode=developer` to the entitlement during dev to loosen the caching. **Wildcards in `paths` behave differently from what you expect.** `*` matches any path, `?` matches a single character, and `NOT ` prefixes an exclusion. Order matters, first match wins. Test each pattern with the Apple validator before shipping. **iOS 17+ requires `components` to opt into query-parameter filtering.** If you upgraded to iOS 17 or later and query-parameter matching stopped working, migrate from `paths` to `components`. If you have gone through this list and things are still not working, our [broader deep linking guide](/blog/mobile-deep-linking-guide) covers the same territory from an "any deep link, any platform" perspective, which sometimes helps triangulate a subtle issue. ## When to Skip Universal Links Entirely Here is the underrated angle. Raw Universal Links are excellent when you own the app, control both the domain and the codebase, and have a developer who can babysit the AASA file across app updates and domain migrations. That is a lot of "ands." For everyone else - marketers, creators, ecommerce teams, affiliates, agencies running campaigns for clients whose apps they do not have code access to - Universal Links are the wrong level of abstraction. You do not want to debug JSON on someone else's CDN. You want a link that opens the app. That is what U2L AI's deep link tool is built for. You paste a destination URL (a YouTube video, an Instagram post, a Spotify track, an Amazon product), and U2L AI hands you back a single short link that behaves like a verified Universal Link on iOS, an App Link or intent URL on Android, and a normal web URL everywhere else. No AASA file to host. No entitlement to sign. No `NSUserActivity` handler to write. The [supported deep links](https://u2l.ai/supported-deep-links) page lists the apps we route into natively. Two other things we bake in because they show up in real campaigns: - **In-app browser detection.** Links opened from Instagram, TikTok, or Facebook get pushed out of the webview into the real app before the Universal Link fires, which is where most deep links quietly die. Our post on [why links open in an in-app browser](/blog/why-links-open-in-app-browser) explains the conversion cost. - **Full click analytics.** Every tap logs geo, device, OS, and browser. Raw Universal Links give you nothing to measure until you plumb your own analytics; the [features page](https://u2l.ai/features) has the full list of what is tracked out of the box. If you have an in-house app team and both platforms already have verified links, keep them. Layer a short-link platform on top for campaign tracking and OG customization. If you do not have that team, or you want to stop maintaining two verification files, skipping the setup entirely is a perfectly good answer in 2026. For a broader picture, our roundup of the [best deep linking tools](/blog/best-deep-linking-tools) compares no-code and SDK options side by side, and the [Firebase Dynamic Links replacement guide](/blog/firebase-dynamic-links-alternative) covers the migration angle for teams coming off Google's shutdown. ## Frequently Asked Questions ### What is the difference between Universal Links and URI schemes on iOS? Universal Links use a standard HTTPS URL verified by an AASA file on your domain, and they fall back to Safari when the app is not installed. URI schemes use a custom prefix like `myapp://` and simply fail if the app is missing. Universal Links are also hijack-proof; URI schemes are not. ### Do Universal Links work on Android? No. Universal Links are iOS only. Android's equivalent is called Android App Links, which uses an `assetlinks.json` file hosted on your domain instead of an AASA file. The [deep link vs universal link comparison](/blog/deep-link-vs-universal-link) walks through how App Links line up against Universal Links side by side. ### Can I test Universal Links in the iOS Simulator? No. The Simulator does not support Universal Links. You must test on a real device. The most reliable path is to email the URL to yourself and tap it from the Mail app. ### Why do my Universal Links open in Safari instead of the app? Nine times out of ten it is one of: wrong Content-Type on the AASA file, a redirect on the well-known path, a wrong Team ID in the `appID`, the Associated Domains entitlement not signed with the capability enabled on the App ID, or an aggressively cached old AASA on the device. Delete and reinstall the app, and re-check each of those. ### Does the AASA file need to be signed? No. Signed AASA files were required in iOS 8 and earlier. Since iOS 9 the file is served as plain JSON over HTTPS. Any legacy references to `apple-app-site-association.p7s` you may have seen are outdated. ### How long does it take iOS to pick up an AASA change? There is no fixed refresh interval. iOS re-fetches the AASA on app install and on some app updates, plus periodically in the background. For test devices, the reliable way to force a refresh is to delete the app, restart the device, and install fresh. In development, adding `?mode=developer` to the `applinks` entitlement makes iOS refetch more aggressively. ### Can I use Universal Links with a custom domain shortener? Yes, and it is common. If your app claims `links.brand.com`, your short link platform serves the AASA on that host, and every short link acts as a Universal Link. Just make sure the domain is included in your app's Associated Domains entitlement. ### Do Universal Links work in Chrome or Firefox on iOS? Yes, mostly. Third-party browsers on iOS use WebKit under the hood and respect Universal Links in most contexts, though behaviour inside in-app webviews on Instagram, Facebook, and other apps is inconsistent. Our [in-app browser explainer](/blog/why-links-open-in-app-browser) has the details. ## The Takeaway Universal Links are the modern, secure, fallback-aware way to open an iOS app from a link, and they are worth setting up if you own both the app and the domain. The hardest part is not the concept; it is the silent failure modes when the AASA file, the entitlement, or the routing code disagree by even a character. Bookmark the debugging list above the next time you hit a Saturday of "the link just opens Safari." If you do not have a developer, or you would rather skip the AASA and entitlement work, [sign up for U2L AI](/app/signup) to generate deep links that behave like Universal Links on iOS and App Links on Android with a single paste - no code, no verification files, no waiting for a cache refresh. If you already ship an app, use both: verified links in your own app for owned campaigns, and a short-link layer on top for measurement and OG customization.