How Universal Links Route Safari Traffic to Native Apps

Universal Links allow iOS and macOS devices to seamlessly redirect users from standard HTTPS web links clicked in Safari directly into a corresponding native application. This article explains the underlying architecture of Universal Links, detailing how secure domain association files, app entitlements, and operating system-level interception work together to verify and route web traffic to native apps without loading the webpage first.

The Core Mechanism: Two-Way Trust

Unlike traditional custom URL schemes (such as myapp://), which any app can claim and hijack, Universal Links use standard https:// links. To prevent unauthorized apps from intercepting a website's traffic, Apple requires a verifiable two-way trust between the website and the native application.

This trust is established BEFORE a user ever clicks a link, relying on two components:

  1. The App's Declaration: The app must explicitly list the web domains it wants to handle.
  2. The Website's Verification: The web server must explicitly publish a list of apps allowed to open its links.

Step 1: Configuring App Entitlements

Developers configure the native app in Xcode by enabling the Associated Domains capability. Here, the developer adds an entitlement entry prefixed with applinks:, such as applinks:example.com. This tells iOS or macOS that the app intends to handle Universal Links for that specific domain.

Step 2: Hosting the AASA File

The website owner must host a specific JSON file called the Apple App Site Association (AASA) file. This file must be placed at https://example.com/.well-known/apple-app-site-association and served over HTTPS with no redirects.

The AASA file contains two critical pieces of data:

  • App IDs: A combination of the Apple Developer Team ID and the App's Bundle Identifier.
  • Paths: Specific URL paths on the website (e.g., /products/* or /profile) that should trigger the native app, as well as paths that should be excluded and kept in Safari.

Step 3: Registration at App Installation

The interception process is fast because verification does not happen when a user clicks a link. Instead, it happens when the app is installed or updated:

  1. A user downloads the app from the App Store.
  2. The operating system reads the app's applinks: entitlement.
  3. A background system daemon (swcd - Shared Web Credentials daemon) reaches out to Apple's Content Delivery Network (CDN), which scrapes and caches the AASA file from the specified web domain.
  4. Once the OS verifies that the AASA file authorizes the app's Bundle ID, it registers the association in a local, system-level routing table on the device.

Step 4: Intercepting the Click in Safari

When a user taps an HTTPS link in Safari, the interception occurs at the operating system level before Safari makes a network request to load the webpage:

  1. Lookup: The user taps a link. Safari hands the URL off to the operating system to determine how to handle the navigation.
  2. Matching: The OS checks its local routing table to see if the domain and specific URL path match any registered Universal Links for currently installed apps.
  3. Interception: If a match is found, the OS cancels the Safari web request entirely.
  4. Handoff: The OS wakes up or launches the corresponding native app and passes the tapped URL into the app wrapped inside an NSUserActivity object.
  5. Deep Linking: The app's code (via the AppDelegate or SceneDelegate) reads the incoming URL from the NSUserActivity object, parses the path, and navigates the user directly to the specific view inside the app.

If the app is not installed, the local routing table finds no match, and Safari simply proceeds to load the standard HTTPS webpage as normal.

The Safari Navigation Exception

Safari enforces one major rule regarding user intent: Universal Links will only trigger in Safari if the user clicks a link that navigates to a different domain than the webpage they are currently viewing.

If a user is browsing example.com in Safari and taps a link pointing to example.com/product/123, iOS and macOS assume the user prefers to stay in the web browser, and the Universal Link will not trigger. However, if the user taps a link to example.com/product/123 from a Google search result, an email, or any other external website within Safari, the OS intercepts the link and opens the native app immediately. To help users who are stuck on the same domain, Safari displays a smart app banner at the top of the webpage, allowing the user to manually jump into the native app if they choose.