How Universal Links Work
Universal Links are Apple's mechanism for creating a seamless bridge between web URLs and native iOS app content. Unlike custom URI schemes, Universal Links use standard HTTPS URLs that belong to your verified domain. When a user taps a Universal Link, iOS checks whether an installed app has registered to handle that domain and path pattern. If a match is found, the app opens directly to the relevant content. If no app is installed, the URL loads normally in Safari.
The verification process is what makes Universal Links secure and reliable. Apple requires you to host an Apple App Site Association (AASA) file at /.well-known/apple-app-site-association on your domain. This JSON file declares which app IDs are authorized to open links from your domain and which URL paths the app handles. iOS downloads and caches this file when the app is installed or updated, creating a verified link between your domain and your app.
This domain-based verification eliminates the security risks associated with URI schemes. No other app can claim your domain's URLs, and users are never prompted with an ambiguous "Open with..." dialog. The experience is instant and deterministic, tap a link, land in the app.
Setting Up the AASA File
The Apple App Site Association file is the foundation of your Universal Links implementation. It must be hosted at the root of your domain at the exact path /.well-known/apple-app-site-association and served over HTTPS without any redirects. The file must have a Content-Type of application/json and must not exceed 128 KB in size.
The modern AASA format introduced in iOS 13 uses an applinks key with a details array. Each entry specifies an appID (your team ID plus bundle identifier) and an array of path patterns the app should handle. You can use pattern matching with * for wildcards and ? for single characters. Exclude paths you want to keep as web-only using the exclude flag set to true.
A critical detail many teams miss is that Apple's CDN caches your AASA file. When you update the file, changes may not propagate immediately. Apple operates a dedicated CDN at app-site-association.cdn-apple.com that periodically fetches and caches AASA files. During development, you can use Apple's AASA validator tool or the swcutil command-line utility to verify your file is correctly formatted and accessible. Always validate after deployment, a single JSON syntax error will silently break all your Universal Links.
Universal Links vs Other Deep Link Types
Understanding where Universal Links fit in the deep linking landscape helps you make the right implementation choices. There are three primary deep link mechanisms on iOS: URI schemes, Universal Links, and deferred deep links. Each serves a different purpose and has distinct trade-offs.
URI schemes are the simplest to implement but the least reliable. They use custom protocols like myapp://product/123 and work only when the app is installed. They fail silently otherwise, offer no web fallback, and any app can register the same scheme, creating potential conflicts. URI schemes still have a role in app-to-app communication where you control both endpoints, but they are not suitable for user-facing campaigns.
Universal Links solve the reliability and security problems. They use your verified HTTPS domain, provide automatic web fallback, and cannot be hijacked. However, they only work when the app is already installed. For acquisition campaigns targeting new users, you need deferred deep links that preserve the link payload through the app store install flow and deliver the user to the correct content after first launch.
In practice, most growth teams use all three in combination. Universal Links handle the majority of re-engagement and organic sharing scenarios. Deferred deep links power acquisition campaigns. URI schemes handle internal app-to-app routing where needed.
Managing Universal Links for Growth Campaigns
Running Universal Links across multiple campaigns, channels, and content types introduces operational complexity that compounds quickly. Each campaign needs links that route correctly, carry attribution parameters, and degrade gracefully. Manually managing AASA path patterns, link generation, and fallback behavior across dozens of campaigns is error-prone and time-consuming.
Linkrunner streamlines this process by generating smart links that leverage Universal Links under the hood while handling the routing logic automatically. When a user taps a Linkrunner smart link on iOS, the system detects whether the app is installed and routes accordingly, opening the app via Universal Links when possible or directing through the appropriate fallback flow. Campaign parameters and attribution data persist through every path, giving your growth team clean data regardless of how the user reaches the app.
Beyond link generation, monitoring Universal Link performance is essential. Track the ratio of app-opens to web-fallbacks for each campaign. A high fallback rate on a re-engagement campaign targeting existing users might indicate an AASA misconfiguration or a path pattern that is not covered. Set up automated checks that verify your AASA file is accessible and correctly formatted after every deployment.
Common Pitfalls and Debugging
Universal Links have several well-documented quirks that trip up even experienced mobile teams. The most common issue is that Universal Links do not work when a user types or pastes a URL directly into Safari's address bar. This is by design, Apple treats direct URL entry as an explicit intent to visit the website. Links must be tapped from another app, a web page, or a system surface like Spotlight or Messages.
Another frequent problem involves the long-press menu. When a user long-presses a Universal Link, iOS shows a context menu with an option to "Open in Safari" or "Open in [App]." If a user selects "Open in Safari," iOS remembers this preference for your domain and will stop opening Universal Links in the app. The user must long-press again and explicitly choose to open in the app to reset this behavior. This is a common source of "it stopped working" bug reports.
Cross-domain redirects also break Universal Links. If your marketing links redirect through a tracking domain before reaching your Universal Link domain, iOS will not trigger the app open. The Universal Link domain must be the URL the user directly interacts with, not a redirect destination. Ensure your link infrastructure respects this constraint, and test your full redirect chain on a physical iOS device, the Simulator does not fully replicate Universal Link behavior.
