Apple App Site Association: Complete Developer Guide

What Is the Apple App Site Association File?

The apple app site association (AASA) file is a JSON configuration file that tells Apple’s servers which parts of your website should open inside your native iOS app rather than in a browser. It forms the backbone of Universal Links, Apple’s preferred deep-linking technology. Without it, tapping a link to your domain will always open Safari, even if the user has your app installed.

In short, the file creates a verified, cryptographically trusted relationship between your web domain and your iOS or iPadOS app. Apple fetches and caches this file through its own CDN so it can validate the association before a device ever opens a link.

• Key Takeaways
• The apple app site association file must be hosted at the root of your HTTPS domain with no file extension.
• It enables Universal Links, letting users open specific in-app screens directly from a URL.
• Apple fetches the file via its own CDN, not directly from your server, so public accessibility is required.
• The file must be valid JSON and served with the correct application/json MIME type.
• Both your server and your Xcode project must be configured together for Universal Links to work end-to-end.

Why the Apple App Site Association File Matters

Deep linking is one of the most powerful tools for improving user experience in a mobile app. When a customer taps a link in an email, a social post, or a web browser, sending them directly to the relevant in-app screen—rather than the app’s home screen or a mobile website—reduces friction and improves engagement.

The AASA file makes this possible in a secure way. Because Apple verifies the file server-side before the device acts on it, a malicious app cannot claim your domain without your cooperation. This verification step is what separates Universal Links from older, less secure URL scheme approaches.

Businesses that rely on seamless handoffs between web and app—such as e-commerce, banking, travel, and media platforms—depend on a correctly configured apple app site association file to deliver that experience.

The Structure of the AASA File

The file is plain JSON. There is no file extension—it is literally named apple-app-site-association. The two most important keys you will work with are applinks (for Universal Links) and, optionally, webcredentials (for Shared Web Credentials) and appclips (for App Clips).

A Minimal Example

Below is a stripped-down but functional structure for enabling Universal Links:

• applinks — the parent key that activates Universal Link handling.
• details — an array of objects, each pairing an app identifier with URL patterns.
• appIDs — a list of strings in the format TEAM_ID.BUNDLE_ID.
• components — defines which URL paths, query strings, or fragments trigger the app.

Path vs. Components Syntax

Older AASA files used a paths array with wildcard strings like /products/*. Apple now recommends the newer components syntax, which separates the path (/), query string (?), and fragment (#) into distinct keys. This gives you more precise control and is required for some advanced matching scenarios.

You can mix and match: keep legacy paths for broad compatibility while using components for nuanced rules. Always test with both older and newer iOS versions if your user base is diverse.

How to Create and Host the Apple App Site Association File

Creating the file is straightforward, but hosting it correctly is where developers most often go wrong. Follow these steps carefully to avoid common pitfalls.

1. Write the JSON — Use a text editor or your preferred IDE. Validate the JSON with a linter before uploading.
2. Name the file exactly apple-app-site-association — no extension, no variation in capitalisation.
3. Upload to your server root — Place it at https://yourdomain.com/apple-app-site-association. You may also use the /.well-known/ directory: https://yourdomain.com/.well-known/apple-app-site-association.
4. Set the correct Content-Type header — The server must return application/json. Some servers default to application/octet-stream for extensionless files, which will cause Apple’s CDN to reject it.
5. Ensure HTTPS — Apple will not fetch the file over plain HTTP. Your SSL certificate must be valid and not self-signed.
6. Make it publicly accessible — No authentication, no IP restrictions. Apple’s CDN servers must reach the file freely.

Configuring Your Xcode Project

The server-side file is only half of the equation. Your iOS app must also declare the associated domain in its Xcode project, or Universal Links will never trigger—even if the AASA file is perfect.

Adding the Associated Domains Entitlement

1. Open your project in Xcode and select the target.
2. Go to the Signing & Capabilities tab.
3. Click the + button and add the Associated Domains capability.
4. Add an entry in the format applinks:yourdomain.com. Include subdomains separately if needed (e.g., applinks:www.yourdomain.com).

Handling Universal Links in Your App Delegate

In your AppDelegate or SceneDelegate, implement the application(_:continue:restorationHandler:) method to receive incoming Universal Link URLs. Parse the URL, extract the relevant path or query parameters, and navigate the user to the correct screen in your app.

SwiftUI apps should use the .onOpenURL modifier on the root view, which provides a cleaner, declarative approach to handling deep links.

Validating and Debugging Your Setup

Apple provides an official validation tool through the App Search API at https://app-site-association.cdn-apple.com/a/v1/yourdomain.com. Hitting this URL in a browser shows you exactly what Apple’s CDN has cached for your domain—if it returns an error or old data, Apple has not successfully fetched your file.

Common Errors and Fixes

• File returns 404 — Check the file path and server routing rules. Some frameworks block extensionless files by default.
• Wrong Content-Type — Update your server configuration (.htaccess, nginx.conf, or server middleware) to serve the correct MIME type.
• Invalid JSON — Run the file through a JSON validator. A single trailing comma or missing bracket will silently break the entire setup.
• App Team ID or Bundle ID mismatch — Double-check the string in the JSON matches exactly what is in your Apple Developer account.
• CDN caching delay — Apple’s CDN can take time to refresh. After making changes, wait and then check the CDN endpoint again before concluding something is broken.

On-device debugging is also possible via Console.app on a Mac. Filter logs from your connected iPhone by searching for “swcd” (the daemon that manages associated domains). It will report whether it successfully downloaded and validated your apple app site association file.

Advanced Configurations and Edge Cases

Once your basic setup is working, you may need to handle more complex scenarios. Subdomains each require their own AASA entry in the associated domains entitlement—applinks:shop.yourdomain.com is treated as a completely separate domain from applinks:yourdomain.com.

App Clips

If your app includes an App Clip, you add an appclips key alongside applinks in the same JSON file. The structure mirrors the applinks section, using the App Clip’s bundle identifier (which conventionally ends in .Clip).

Excluding Paths

Use the exclude flag within a components object to prevent certain URLs from triggering the app. This is useful when you want most paths to open in-app but specific ones—like your terms-of-service or privacy policy pages—to stay in Safari.

Supporting Multiple Apps for One Domain

A single AASA file can list multiple app identifiers in the appIDs array, making it possible to associate a main app and a companion app (or even a completely separate app) with the same domain. Each app still needs the associated domains entitlement on its end.

Frequently Asked Questions

Where exactly should I host the apple app site association file?

Host it at the root of your HTTPS domain, accessible at https://yourdomain.com/apple-app-site-association, or inside the /.well-known/ directory. The file must have no file extension and return a valid application/json Content-Type header. Both locations are checked; Apple recommends the well-known directory for new projects.

Does the apple app site association file need to be signed?

No. Signing the AASA file with a certificate is no longer required as of iOS 13 and later. Apple now fetches and validates the file through its own CDN, which handles trust verification server-side. Unsigned plain JSON is the current standard and recommended approach.

How long does it take Apple to update the cached AASA file?

Apple's CDN caches the file and may not reflect changes immediately. Propagation can take anywhere from a few hours to over a day. You can check what Apple currently has cached by hitting the App Search API endpoint for your domain, and on-device updates typically occur when the app is installed or updated.

Why are my Universal Links opening in Safari instead of my app?

This usually means either the AASA file is misconfigured, not publicly accessible, or the associated domains entitlement in Xcode does not match your domain exactly. Also note that long-pressing a Universal Link and choosing "Open in Safari" will cause iOS to remember that preference for that link. Reinstalling the app resets this behaviour.

Can one apple app site association file support multiple apps?

Yes. The appIDs array inside the details object accepts multiple identifiers, so a single AASA file can associate several apps with the same domain. Each individual app must still declare the associated domains entitlement in its own Xcode project pointing to that domain.

Conclusion

The apple app site association file is a small JSON document with an outsized impact on your users’ experience. By correctly creating, hosting, and validating it—and pairing it with the right Xcode configuration—you give your app the ability to intercept relevant web URLs and deliver users instantly to the right in-app screen. Getting it right requires attention to detail: exact file naming, proper MIME types, valid JSON, and matching identifiers. Once everything is aligned, Universal Links work seamlessly and reliably, forming a robust bridge between your web presence and your native iOS app.

If you want to explore more about building seamless digital and in-person experiences, take a look at our guide to the best restaurants in Pittsburgh, PA as an example of location-aware content that benefits greatly from smooth app-to-web handoffs.