The Apple App Site Association file is the foundation of Universal Links on iOS. Without it, tapping a link to your domain opens Safari instead of your app. Get it right once, and iOS will route your links directly into the app experience you intended. Get it wrong, and you spend hours debugging a silent failure.<\/p>\n\n\n\n
This guide covers the complete setup: file format, JSON structure, path matching rules, serving requirements, and how to verify everything is working. If you are new to Universal Links in general, start with our complete guide to Universal Links<\/a> for the broader picture before diving into AASA specifics.<\/p>\n\n\n\n When a user installs your app, iOS fetches the AASA file from your domain and caches it. Later, when the user taps a link to your domain, iOS checks that cached file to determine whether your app should handle the URL. If the path matches a rule in the file, iOS opens the app. If it does not match, or if the file was never fetched successfully, the link opens in Safari.<\/p>\n\n\n\n This lookup happens at install time (and periodically thereafter via Apple's CDN), not at tap time. That distinction matters for troubleshooting: if you update your AASA file, users with the app already installed will not see the change immediately. Apple's servers re-crawl the file on their own schedule.<\/p>\n\n\n\n The file must live at one of two locations on your domain:<\/p>\n\n\n\n Apple always checks the The AASA file is a JSON document with no file extension. Here is the minimal structure for Universal Links:<\/p>\n\n\n\n A few things to note about this structure:<\/p>\n\n\n\n The The The The App ID format trips up a lot of developers. It is always You can verify your Team ID with a quick check:<\/p>\n\n\n\n The The Exclusions let you carve out paths that should open in Safari even when they fall under a broader match. List exclusions before the broader rule they override:<\/p>\n\n\n\n Order matters here. iOS evaluates You can require specific query parameters as part of a match:<\/p>\n\n\n\n The To route all paths on a domain to your app, use a single wildcard:<\/p>\n\n\n\n Be cautious with this. It means every link to your domain, including password reset emails and marketing unsubscribe pages, will try to open the app. A more targeted approach is usually better.<\/p>\n\n\n\n If you have multiple apps that should handle links from the same domain, list them all in the The last entry in this example covers both a beta and staging build with a single rule by listing both app IDs in the Apple's crawler has strict requirements for how the AASA file must be served. Any deviation causes a silent failure.<\/p>\n\n\n\n HTTPS only.<\/strong> The file must be served over HTTPS with a valid certificate. Self-signed certificates are not accepted. This applies to your production domain and any subdomain listed in your app's Associated Domains entitlement.<\/p>\n\n\n\n No redirects.<\/strong> Apple's crawler does not follow redirects. If your server redirects Correct content type.<\/strong> Serve the file with For Nginx:<\/p>\n\n\n\n For Apache:<\/p>\n\n\n\n File size limit.<\/strong> The AASA file must be 128 KB or smaller. In practice, even large files with hundreds of path rules stay well under this limit.<\/p>\n\n\n\n No authentication.<\/strong> The file must be publicly accessible. No HTTP basic auth, no IP restrictions.<\/p>\n\n\n\n The AASA file alone is not enough. Your app must also declare the associated domain in its entitlements. In Xcode, go to your target's Signing and Capabilities tab, click the "+" to add a capability, and select Associated Domains. Add an entry in the format:<\/p>\n\n\n\n If you want to handle links on a subdomain, add that subdomain separately:<\/p>\n\n\n\n The entitlement and the AASA file must agree. If your entitlement points to For more on wiring up the Swift side of Universal Links, including the There are several ways to verify your setup before shipping to users.<\/p>\n\n\n\n Apple provides an AASA validator<\/a> at… actually, use the official tool at developer.apple.com or check via The fastest way to verify your file is reachable and correctly configured:<\/p>\n\n\n\n Look for From iOS 14 onward, Apple routes AASA requests through its own CDN rather than having each device fetch your file directly. This means your file may be cached at Apple's edge and could lag behind your latest changes by hours. We cover this caching behavior in detail in our article on Apple CDN validation and Universal Links<\/a>. To force a re-fetch during development, you can delete and reinstall the app, or use the Note: After installing a debug build via Xcode, open the Console app on your Mac and filter for the process Wrong App ID format.<\/strong> The single most common error. Double-check that you are using your Team ID, not your App ID prefix.<\/p>\n\n\n\n Redirect on the AASA URL.<\/strong> Even a harmless-looking redirect like HTTP to HTTPS, or a trailing slash added by the server, will cause the crawl to fail. Test with curl and watch for any redirect.<\/p>\n\n\n\n File served with wrong content type.<\/strong> Servers often default to Entitlement and file domain mismatch.<\/strong> If the app entitlement says Old Assuming changes propagate immediately.<\/strong> Apple caches the AASA file. Test with developer mode enabled to see your latest changes without waiting for the cache to expire. For a systematic approach to tracking down these and other issues, see our AASA debugging guide<\/a>.<\/p>\n\n\n\n Missing the webcredentials or activitycontinuation sections.<\/strong> If you also need Shared Web Credentials or Handoff, those are separate top-level keys in the same AASA file. Omitting them when you need them is easy to overlook.<\/p>\n\n\n\n Here is a complete, production-ready AASA file for a typical e-commerce app:<\/p>\n\n\n\n Once the file is in place, your server is configured to serve it correctly, and the entitlement is added in Xcode, Universal Links will work for every new install. For existing installs, the update propagates as Apple's CDN re-crawls your domain.<\/p>\n\n\n\n For a broader look at how Universal Links fit into a deep linking strategy, including deferred links and analytics, see Tolinku's Universal Links documentation<\/a>. If you want to see how path matching and route configuration work in a managed setup, the deep linking features overview<\/a> covers how Tolinku handles AASA generation and hosting automatically.<\/p>\n","protected":false},"excerpt":{"rendered":" Configure your AASA file correctly for Universal Links. Learn the JSON format, path matching, and how to validate your configuration.<\/p>\n","protected":false},"author":2,"featured_media":444,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"Apple App Site Association File: Complete Setup Guide","rank_math_description":"Configure your AASA file correctly for Universal Links. Learn the JSON format, path matching, and how to validate your configuration.","rank_math_focus_keyword":"AASA file setup","rank_math_canonical_url":"","rank_math_facebook_title":"","rank_math_facebook_description":"","rank_math_facebook_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-aasa-file-setup.png","rank_math_facebook_image_id":"","rank_math_twitter_title":"","rank_math_twitter_description":"","rank_math_twitter_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-aasa-file-setup.png","footnotes":""},"categories":[12],"tags":[32,20,24,69,31,22],"class_list":["post-445","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ios","tag-apple-app-site-association","tag-deep-linking","tag-ios","tag-mobile-development","tag-swift","tag-universal-links"],"_links":{"self":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/445","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/comments?post=445"}],"version-history":[{"count":2,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/445\/revisions"}],"predecessor-version":[{"id":2771,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/445\/revisions\/2771"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media\/444"}],"wp:attachment":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media?parent=445"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/categories?post=445"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/tags?post=445"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}What the AASA File Does<\/h2>\n\n\n\n
https:\/\/yourdomain.com\/.well-known\/apple-app-site-association\nhttps:\/\/yourdomain.com\/apple-app-site-association\n<\/code><\/pre>\n\n\n\n.well-known\/<\/code> path first. The root path is the fallback for older iOS versions. You only need one, but serving both causes no harm. Either way, the file must be at the root of the domain (or subdomain) you register in your app's entitlements. You cannot nest it under a subdirectory.<\/p>\n\n\n\nJSON Structure<\/h2>\n\n\n\n
{\n "applinks": {\n "details": [\n {\n "appIDs": ["TEAMID.com.example.myapp"],\n "components": [\n {\n "\/": "\/shop\/*",\n "comment": "Match all shop URLs"\n }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\nappIDs<\/code> field<\/strong> takes an array of strings in the format TEAMID.bundleID<\/code>. Your Team ID is the 10-character alphanumeric string found in the Apple Developer portal<\/a> under Membership Details. Your Bundle ID is the identifier you set in Xcode (for example, com.example.myapp<\/code>). The combined value looks like A1B2C3D4E5.com.example.myapp<\/code>.<\/p>\n\n\n\ndetails<\/code> array<\/strong> can contain multiple objects, each targeting different app IDs with different path rules. This is how you support multiple apps or multiple build targets (production, staging, beta) from a single AASA file.<\/p>\n\n\n\ncomponents<\/code> array<\/strong> is the modern syntax introduced in iOS 13. Apple still supports the older paths<\/code> syntax but recommends components<\/code> for new implementations. The two are not interchangeable within a single entry.<\/p>\n\n\n\nApp ID Format<\/h2>\n\n\n\n
TEAMID.bundleID<\/code>, never just the bundle ID. Two common mistakes:<\/p>\n\n\n\n\n
# From your provisioning profile\nsecurity cms -D -i ~\/Library\/MobileDevice\/Provisioning\\ Profiles\/your-profile.mobileprovision | grep -A1 TeamIdentifier\n<\/code><\/pre>\n\n\n\nPath Matching with Components<\/h2>\n\n\n\n
components<\/code> syntax gives you fine-grained control over which URLs trigger your app. Each object in the components<\/code> array can have these keys:<\/p>\n\n\n\n\n
\/<\/code> : the path pattern to match<\/li>\n?<\/code> : a query string pattern to match<\/li>\n#<\/code> : a fragment pattern to match<\/li>\nexclude<\/code> : set to true<\/code> to exclude matching URLs (exclusions are evaluated in order)<\/li>\ncomment<\/code> : a human-readable label (ignored by iOS)<\/li>\n<\/ul>\n\n\n\nWildcards<\/h3>\n\n\n\n
*<\/code> character matches any sequence of characters. The ?<\/code> character (when used inside a path pattern, not as the query key) matches any single character. For a deeper look at wildcard behavior, edge cases, and advanced pattern strategies, see our guide to AASA wildcards and path matching<\/a>.<\/p>\n\n\n\n{\n "components": [\n {\n "\/": "\/products\/*",\n "comment": "All product detail pages"\n },\n {\n "\/": "\/u\/*\/settings",\n "comment": "User settings pages"\n }\n ]\n}\n<\/code><\/pre>\n\n\n\nExclusions<\/h3>\n\n\n\n
{\n "components": [\n {\n "\/": "\/products\/archived\/*",\n "exclude": true,\n "comment": "Archived products open in browser"\n },\n {\n "\/": "\/products\/*",\n "comment": "All other product pages open in app"\n }\n ]\n}\n<\/code><\/pre>\n\n\n\ncomponents<\/code> entries from top to bottom and stops at the first match. If you put the wildcard \/products\/*<\/code> before the exclusion, the exclusion will never be reached.<\/p>\n\n\n\nQuery String Matching<\/h3>\n\n\n\n
{\n "components": [\n {\n "\/": "\/share",\n "?": { "ref": "?" },\n "comment": "Share URLs with any ref parameter"\n }\n ]\n}\n<\/code><\/pre>\n\n\n\n?<\/code> value in the query object means "any single character or more." You can also match exact values or use *<\/code> for longer strings.<\/p>\n\n\n\nMatching Everything<\/h3>\n\n\n\n
{\n "components": [\n {\n "\/": "*"\n }\n ]\n}\n<\/code><\/pre>\n\n\n\nMultiple Apps in One File<\/h2>\n\n\n\n
details<\/code> array:<\/p>\n\n\n\n{\n "applinks": {\n "details": [\n {\n "appIDs": ["A1B2C3D4E5.com.example.consumer"],\n "components": [\n { "\/": "\/shop\/*" },\n { "\/": "\/account\/*" }\n ]\n },\n {\n "appIDs": ["A1B2C3D4E5.com.example.driver"],\n "components": [\n { "\/": "\/driver\/*" }\n ]\n },\n {\n "appIDs": [\n "A1B2C3D4E5.com.example.consumer.beta",\n "A1B2C3D4E5.com.example.consumer.staging"\n ],\n "components": [\n { "\/": "*" }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\nappIDs<\/code> array.<\/p>\n\n\n\nServing Requirements<\/h2>\n\n\n\n
\/.well-known\/apple-app-site-association<\/code> to another URL (even just adding a trailing slash), the crawl fails. Check your web server configuration, CDN rules, and any middleware that might issue automatic redirects.<\/p>\n\n\n\nContent-Type: application\/json<\/code>. Some servers default to application\/octet-stream<\/code> for files with no extension. You will need to explicitly set the content type.<\/p>\n\n\n\nlocation = \/.well-known\/apple-app-site-association {\n default_type application\/json;\n}\n<\/code><\/pre>\n\n\n\n<Files "apple-app-site-association">\n ForceType application\/json\n<\/Files>\n<\/code><\/pre>\n\n\n\nXcode Entitlements<\/h2>\n\n\n\n
applinks:yourdomain.com\n<\/code><\/pre>\n\n\n\napplinks:app.yourdomain.com\n<\/code><\/pre>\n\n\n\napp.yourdomain.com<\/code>, Apple will look for the AASA file at https:\/\/app.yourdomain.com\/.well-known\/apple-app-site-association<\/code>, not at your root domain. For a full walkthrough of the entitlement setup process, including provisioning profiles and development mode, see our Associated Domains entitlement guide<\/a>.<\/p>\n\n\n\napplication(_:continue:restorationHandler:)<\/code> delegate method and SwiftUI equivalents, see the Tolinku iOS setup guide<\/a>.<\/p>\n\n\n\nValidation<\/h2>\n\n\n\n
Apple's Validator<\/h3>\n\n\n\n
aasa-validator<\/code> CLI tools. The most reliable official check is the App Search API validation tool in the Search tab of App Store Connect for indexed content, but for basic AASA validation, a direct curl check is often faster.<\/p>\n\n\n\ncurl Check<\/h3>\n\n\n\n
# Check the file is reachable with the right content type\ncurl -sI https:\/\/yourdomain.com\/.well-known\/apple-app-site-association\n\n# Fetch and pretty-print the file contents\ncurl -s https:\/\/yourdomain.com\/.well-known\/apple-app-site-association | python3 -m json.tool\n\n# Check for redirects (should show no Location header)\ncurl -sIL https:\/\/yourdomain.com\/.well-known\/apple-app-site-association | grep -E "HTTP\/|Location:"\n<\/code><\/pre>\n\n\n\nHTTP\/2 200<\/code> (or HTTP\/1.1 200<\/code>) and content-type: application\/json<\/code> in the response headers. Any Location:<\/code> header indicates a redirect that will break Apple's crawler.<\/p>\n\n\n\nApple's CDN<\/h3>\n\n\n\n
applinks:yourdomain.com?mode=developer<\/code> entitlement value in debug builds. This developer mode bypasses Apple's CDN and fetches directly from your server.<\/p>\n\n\n\napplinks:yourdomain.com?mode=developer\n<\/code><\/pre>\n\n\n\n?mode=developer<\/code> only works for apps installed via Xcode or TestFlight on devices registered to your team.<\/p>\n\n\n\nOn-Device Verification<\/h3>\n\n\n\n
swcd<\/code> (the service responsible for associated domains). You will see log entries showing whether Apple successfully fetched and parsed your AASA file, along with any errors.<\/p>\n\n\n\nCommon Mistakes<\/h2>\n\n\n\n
application\/octet-stream<\/code> for files without extensions. Explicitly set application\/json<\/code>.<\/p>\n\n\n\napplinks:app.yourdomain.com<\/code> but the AASA file is only at yourdomain.com<\/code>, the link will not work.<\/p>\n\n\n\npaths<\/code> syntax mixed with components<\/code>.<\/strong> Apple's documentation deprecated the older paths<\/code> array in favor of components<\/code>. Do not mix them in the same entry.<\/p>\n\n\n\nPutting It Together<\/h2>\n\n\n\n
{\n "applinks": {\n "details": [\n {\n "appIDs": ["A1B2C3D4E5.com.example.shop"],\n "components": [\n {\n "\/": "\/checkout\/*",\n "exclude": true,\n "comment": "Checkout handled in browser for payment security"\n },\n {\n "\/": "\/products\/*",\n "comment": "Product detail pages"\n },\n {\n "\/": "\/collections\/*",\n "comment": "Category and collection pages"\n },\n {\n "\/": "\/account\/*",\n "comment": "Account and order history"\n },\n {\n "\/": "\/share\/*",\n "comment": "Shared content"\n }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\n