Universal links let iOS users tap a standard HTTPS URL and land directly inside your app. No custom scheme. No browser redirect. No confirmation dialog asking "Open in App?" The link just works. If the app is installed, it opens. If not, the URL loads in Safari like any normal web page.<\/p>\n\n\n\n
Apple introduced universal links in iOS 9<\/a> to replace the fragile If you are building an iOS app that needs to open from links (emails, social media, QR codes, websites, or marketing campaigns), universal links are the standard you should be using. This guide walks through how they work, how to set them up, and how to fix them when they break.<\/p>\n\n\n\n The mechanism behind universal links is straightforward, but there are several moving parts.<\/p>\n\n\n\n Here is the full flow:<\/p>\n\n\n\n You host a file on your web server.<\/strong> This file is called Apple downloads and caches the AASA file.<\/strong> When a user installs your app (or updates it), Apple's CDN fetches your AASA file and caches the result. This happens on Apple's servers, not on the user's device. Starting in iOS 14, Apple moved this verification to their own CDN<\/a> instead of having each device fetch it directly.<\/p>\n\n\n\n A user taps a link.<\/strong> When someone taps a URL that matches a pattern in your AASA file, iOS checks its cached copy of the file. If there is a match and your app is installed, iOS opens the app and passes the URL to it.<\/p>\n\n\n\n Your app receives the URL.<\/strong> Your app gets the URL through the The key detail here: Apple's CDN fetches your AASA file, not the user's device. This means changes to the file are not instant. Apple re-crawls AASA files periodically (roughly every 24-48 hours, though Apple does not publish an exact schedule). During development, you can force a re-download using Apple's developer mode<\/a>, but in production, expect a delay.<\/p>\n\n\n\n For a conceptual overview, see Tolinku's Universal Links documentation<\/a>.<\/p>\n\n\n\n There are three things you need to configure: the AASA file on your server, the Associated Domains entitlement in Xcode, and the link-handling code in your app.<\/p>\n\n\n\n Create a file named Here is a minimal AASA file:<\/p>\n\n\n\n The Open your project in Xcode and select your target. Go to "Signing & Capabilities" and click "+ Capability" to add "Associated Domains." Add an entry in this format:<\/p>\n\n\n\n If you want to test with a specific mode during development, you can append Developer mode tells iOS to fetch the AASA file directly from your server instead of Apple's CDN. This is useful during development because you do not have to wait for Apple to re-crawl your file after every change. Remove the When iOS opens your app from a universal link, it delivers the URL through the We will cover the code for each approach in the next section.<\/p>\n\n\n\n The AASA file is the most critical piece of the universal links setup. Get it wrong and nothing works. For a dedicated walkthrough, see the AASA file setup guide<\/a>. Here is what you need to know.<\/p>\n\n\n\n The AASA file is JSON. Apple supports two formats: the legacy format (iOS 12 and earlier) and the modern format (iOS 13+). Use the modern format with Here is a more complete example:<\/p>\n\n\n\n The To match across multiple path segments, chain wildcards: Set Apple evaluates components in order<\/a>. Put your exclusion rules before your inclusion rules. The first matching rule wins.<\/p>\n\n\n\n The modern AASA format also lets you match on query parameters and URL fragments:<\/p>\n\n\n\n The You can list multiple apps in a single AASA file. Each entry in the The AASA file must:<\/p>\n\n\n\n If you are using a CDN like Cloudflare<\/a> or Fastly<\/a>, make sure the CDN does not block Apple's crawler or require a CAPTCHA challenge.<\/p>\n\n\n\n Once iOS opens your app from a universal link, you need code to receive the URL and route the user to the right screen. Here are the three common patterns.<\/p>\n\n\n\n If your app uses For older apps that do not use scenes, implement In SwiftUI, use the The Regardless of which delegate pattern you use, parse URLs defensively. Users (and attackers) can craft arbitrary URLs that match your AASA patterns. Validate every component:<\/p>\n\n\n\n Universal links have a reputation for being finicky. Most issues come down to one of a few root causes.<\/p>\n\n\n\n This is the most common issue. Check these causes in order:<\/p>\n\n\n\n Confirm the response is valid JSON, the status code is 200 (not 301 or 302), and the Team ID or Bundle ID mismatch.<\/strong> The Associated Domains entitlement missing.<\/strong> Open your Apple CDN has not updated.<\/strong> After changing your AASA file, Apple's CDN may take 24-48 hours to re-fetch it. During development, use User previously dismissed the link.<\/strong> If a user taps-and-holds a universal link and chooses "Open in Safari," iOS remembers that choice for your domain. The user has to long-press the link again and choose "Open in [Your App]" to restore the behavior.<\/p>\n\n\n\n For a full troubleshooting checklist, see Tolinku's iOS troubleshooting guide<\/a>.<\/p>\n\n\n\n Apple provides a validation tool<\/a> (though it is not always reliable). Common issues:<\/p>\n\n\n\n Some apps (particularly social media apps) use in-app browsers that do not support universal links. Links tapped inside Instagram's in-app browser, for example, may load in the embedded web view instead of handing off to your app. This is a known limitation.<\/p>\n\n\n\n The workaround: on your web page, include a smart banner or a button that explicitly opens the universal link. The If your Team ID or Bundle ID changes between app versions, or if you change your domain, universal links will break. Make sure the AASA file on your server always matches the entitlements in your currently shipped app binary.<\/p>\n\n\n\n Testing universal links takes some care because you cannot just tap a link in Safari's address bar. For a comprehensive testing guide, see testing Universal Links<\/a>. Here are reliable methods.<\/p>\n\n\n\n The most reliable test. Type your universal link into the Notes app, then tap it. If the app opens, universal links are working.<\/p>\n\n\n\n You can also use the terminal to open a link on a connected device:<\/p>\n\n\n\n This command works with the iOS Simulator. For a physical device, paste the link into Notes or Messages and tap it.<\/p>\n\n\n\n Check what Apple's CDN has cached for your domain:<\/p>\n\n\n\n This returns the AASA file as Apple's CDN sees it. If the response does not match your server's file, Apple has not re-crawled it yet.<\/p>\n\n\n\n Connect your iOS device to your Mac and open Console.app. Filter for You can validate your AASA file programmatically as part of your CI\/CD pipeline:<\/p>\n\n\n\n Both open your app from a URL, but they work differently and have different tradeoffs.<\/p>\n\n\n\nyourapp:\/\/<\/code> custom URI scheme pattern. Custom schemes had real problems: they showed ugly error dialogs when the app was not installed, they could be hijacked by other apps claiming the same scheme, and they required awkward JavaScript hacks to detect whether the app was present. Universal links solved all of that by tying your app to your domain through a cryptographic verification process.<\/p>\n\n\n\nHow Universal Links Work<\/h2>\n\n\n\n
\n
apple-app-site-association<\/code> (AASA). It lives at https:\/\/yourdomain.com\/.well-known\/apple-app-site-association<\/code>. It tells Apple which URL paths your app can handle.<\/p>\n\n\n\nNSUserActivity<\/code> API. You parse the URL, extract the path and parameters, and navigate to the correct screen.<\/p>\n\n\n\nSetting Up Universal Links Step by Step<\/h2>\n\n\n\n
Step 1: Create the AASA File<\/h3>\n\n\n\n
apple-app-site-association<\/code> (no file extension) and place it at \/.well-known\/apple-app-site-association<\/code> on your domain. The file must be served over HTTPS with a valid TLS certificate. No redirects. The content type should be application\/json<\/code>.<\/p>\n\n\n\n{\n "applinks": {\n "details": [\n {\n "appIDs": ["ABCDE12345.com.example.myapp"],\n "components": [\n {\n "\/": "\/product\/*",\n "comment": "Matches product pages"\n },\n {\n "\/": "\/user\/*",\n "comment": "Matches user profiles"\n }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\nappIDs<\/code> value combines your Apple Team ID<\/a> with your app's bundle identifier, separated by a period. You can find your Team ID in the Apple Developer portal under Membership.<\/p>\n\n\n\nStep 2: Configure Xcode<\/h3>\n\n\n\n
applinks:yourdomain.com\n<\/code><\/pre>\n\n\n\n?mode=developer<\/code>:<\/p>\n\n\n\napplinks:yourdomain.com?mode=developer\n<\/code><\/pre>\n\n\n\n?mode=developer<\/code> flag before shipping to the App Store.<\/p>\n\n\n\nStep 3: Handle Incoming Links in Your App<\/h3>\n\n\n\n
NSUserActivity<\/code> continuation mechanism. How you receive it depends on your app's architecture.<\/p>\n\n\n\nThe Apple App Site Association File in Detail<\/h2>\n\n\n\n
Format and Structure<\/h3>\n\n\n\n
components<\/code> unless you need to support very old iOS versions.<\/p>\n\n\n\n{\n "applinks": {\n "details": [\n {\n "appIDs": ["ABCDE12345.com.example.myapp"],\n "components": [\n {\n "\/": "\/product\/*",\n "comment": "All product pages"\n },\n {\n "\/": "\/invite\/*",\n "comment": "Invitation links"\n },\n {\n "\/": "\/share\/*",\n "?": { "ref": "?*" },\n "comment": "Share links with referral parameter"\n },\n {\n "\/": "\/admin\/*",\n "exclude": true,\n "comment": "Never open admin pages in the app"\n }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\nPath Matching<\/h3>\n\n\n\n
"\/"<\/code> key defines URL path patterns. You can use these wildcards:<\/p>\n\n\n\n\n
*<\/code> matches any substring within a single path segment. \/product\/*<\/code> matches \/product\/123<\/code> but not \/product\/123\/reviews<\/code>.<\/li>\n?<\/code> matches any single character. \/user\/a?c<\/code> matches \/user\/abc<\/code> but not \/user\/abbc<\/code>.<\/li>\n<\/ul>\n\n\n\n\/product\/*\/reviews<\/code> matches \/product\/shoes\/reviews<\/code>.<\/p>\n\n\n\nExcluding Paths<\/h3>\n\n\n\n
"exclude": true<\/code> on a component to prevent specific URL patterns from opening your app. This is useful for admin panels, login pages, or API endpoints that should always load in the browser.<\/p>\n\n\n\nQuery Parameters and Fragments<\/h3>\n\n\n\n
{\n "\/": "\/product\/*",\n "?": { "campaign": "?*" },\n "#": "details",\n "comment": "Product links with a campaign parameter and #details fragment"\n}\n<\/code><\/pre>\n\n\n\n"?"<\/code> key matches query string parameters. The "#"<\/code> key matches the URL fragment. Both support the same wildcard syntax as paths.<\/p>\n\n\n\nMultiple Apps<\/h3>\n\n\n\n
details<\/code> array can have a different appIDs<\/code> value:<\/p>\n\n\n\n{\n "applinks": {\n "details": [\n {\n "appIDs": ["ABCDE12345.com.example.mainapp"],\n "components": [{ "\/": "\/product\/*" }]\n },\n {\n "appIDs": ["ABCDE12345.com.example.liteapp"],\n "components": [{ "\/": "\/lite\/*" }]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\nFile Serving Requirements<\/h3>\n\n\n\n
\n
Content-Type: application\/json<\/code><\/li>\nHandling Universal Links in Your App<\/h2>\n\n\n\n
UIKit with SceneDelegate (iOS 13+)<\/h3>\n\n\n\n
UISceneDelegate<\/code> (the default for apps created since iOS 13), implement the scene(_:continue:)<\/code> method:<\/p>\n\n\n\nimport UIKit\n\nclass SceneDelegate: UIResponder, UIWindowSceneDelegate {\n func scene(_ scene: UIScene,\n continue userActivity: NSUserActivity) {\n guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,\n let url = userActivity.webpageURL else {\n return\n }\n handleUniversalLink(url)\n }\n\n private func handleUniversalLink(_ url: URL) {\n let path = url.path\n let components = path.split(separator: "\/")\n\n if components.first == "product",\n let productID = components.last {\n \/\/ Navigate to product screen\n navigateToProduct(String(productID))\n } else if components.first == "user",\n let userID = components.last {\n \/\/ Navigate to user profile\n navigateToProfile(String(userID))\n }\n }\n}\n<\/code><\/pre>\n\n\n\nUIKit with AppDelegate (Legacy)<\/h3>\n\n\n\n
application(_:continue:restorationHandler:)<\/code>:<\/p>\n\n\n\nimport UIKit\n\n@UIApplicationMain\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n func application(_ application: UIApplication,\n continue userActivity: NSUserActivity,\n restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {\n guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,\n let url = userActivity.webpageURL else {\n return false\n }\n handleUniversalLink(url)\n return true\n }\n}\n<\/code><\/pre>\n\n\n\nSwiftUI<\/h3>\n\n\n\n
.onOpenURL<\/code> modifier. For a full SwiftUI integration guide, see Universal Links with SwiftUI<\/a>.<\/p>\n\n\n\nimport SwiftUI\n\n@main\nstruct MyApp: App {\n var body: some Scene {\n WindowGroup {\n ContentView()\n .onOpenURL { url in\n handleUniversalLink(url)\n }\n }\n }\n}\n<\/code><\/pre>\n\n\n\n.onOpenURL<\/code> modifier handles both universal links and custom URL schemes. It is the simplest approach if you are building a new SwiftUI app. Apple documents this in the SwiftUI App structure reference<\/a>.<\/p>\n\n\n\nParsing URLs Safely<\/h3>\n\n\n\n
func handleUniversalLink(_ url: URL) {\n guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else {\n return\n }\n\n let pathSegments = components.path\n .split(separator: "\/")\n .map(String.init)\n\n switch pathSegments.first {\n case "product":\n guard pathSegments.count == 2,\n let id = Int(pathSegments[1]) else { return }\n router.navigate(to: .product(id: id))\n\n case "invite":\n guard pathSegments.count == 2 else { return }\n let token = pathSegments[1]\n router.navigate(to: .invite(token: token))\n\n default:\n \/\/ Unknown path, open home screen\n router.navigate(to: .home)\n }\n}\n<\/code><\/pre>\n\n\n\nCommon Universal Links Problems and Fixes<\/h2>\n\n\n\n
Problem: Links Open in Safari Instead of the App<\/h3>\n\n\n\n
\n
https:\/\/yourdomain.com\/.well-known\/apple-app-site-association<\/code>. Test it with curl:<\/li>\n<\/ol>\n\n\n\ncurl -v https:\/\/yourdomain.com\/.well-known\/apple-app-site-association\n<\/code><\/pre>\n\n\n\nContent-Type<\/code> header is application\/json<\/code>.<\/p>\n\n\n\n\n
appIDs<\/code> value must exactly match {TeamID}.{BundleID}<\/code>. Check both values in the Apple Developer portal<\/a>.<\/p>\n\n\n\n.entitlements<\/code> file and confirm applinks:yourdomain.com<\/code> is listed. Also check that the Associated Domains capability is enabled in the Apple Developer portal under "Certificates, Identifiers & Profiles."<\/p>\n\n\n\n?mode=developer<\/code> on your associated domain to bypass the CDN. For details on CDN behavior, see Apple CDN validation for Universal Links<\/a>.<\/p>\n\n\n\nProblem: AASA File Validation Errors<\/h3>\n\n\n\n
\n
python3 -m json.tool<\/code> or jsonlint.com<\/a> to validate.<\/li>\napplication\/octet-stream<\/code>. Configure your server to return application\/json<\/code> for this specific path.<\/li>\nProblem: Links Work in Some Apps but Not Others<\/h3>\n\n\n\n
meta<\/code> tag for Safari Smart App Banners<\/a> can help:<\/p>\n\n\n\n<meta name="apple-itunes-app" content="app-id=123456789, app-argument=https:\/\/yourdomain.com\/product\/123">\n<\/code><\/pre>\n\n\n\nProblem: Universal Links Break After App Update<\/h3>\n\n\n\n
Testing Universal Links<\/h2>\n\n\n\n
On a Real Device<\/h3>\n\n\n\n
xcrun simctl openurl booted "https:\/\/yourdomain.com\/product\/123"\n<\/code><\/pre>\n\n\n\nApple's CDN Diagnostic Tool<\/h3>\n\n\n\n
curl -v "https:\/\/app-site-association.cdn-apple.com\/a\/v1\/yourdomain.com"\n<\/code><\/pre>\n\n\n\nUsing Console.app<\/h3>\n\n\n\n
swcd<\/code> (the daemon responsible for associated domains). You will see log messages showing whether iOS successfully validated your AASA file and whether incoming URLs matched any patterns.<\/p>\n\n\n\nAutomated Validation<\/h3>\n\n\n\n
# Fetch and validate the AASA file\nAASA=$(curl -s https:\/\/yourdomain.com\/.well-known\/apple-app-site-association)\n\n# Check it's valid JSON\necho "$AASA" | python3 -m json.tool > \/dev\/null 2>&1\nif [ $? -ne 0 ]; then\n echo "ERROR: AASA file is not valid JSON"\n exit 1\nfi\n\n# Check for the applinks key\necho "$AASA" | python3 -c "import sys, json; d = json.load(sys.stdin); assert 'applinks' in d" 2>\/dev\/null\nif [ $? -ne 0 ]; then\n echo "ERROR: AASA file missing 'applinks' key"\n exit 1\nfi\n\necho "AASA file is valid"\n<\/code><\/pre>\n\n\n\nUniversal Links vs. Custom URL Schemes<\/h2>\n\n\n\n