Troubleshoot iOS Universal Links & Redirects

iOS’s Universal Links are designed to bridge the gap between web and mobile app environments using standard HTTP/HTTPS protocols. Unlike Uniform Resource Identifier (URI) schemes, which rely on custom browser protocols (e.g., myapp://), Universal Links leverage a secure handshake between a domain’s Apple App Site Association (AASA) file and the app’s Associated Domains Entitlements.

sequenceDiagram
    participant App as 📱 Mobile App<br/>(Client-Side)
    participant Server as 🌐 Domain<br/>(Server-Side)

    Note over App: Request Permission:<br/>Associated Domains (iOS)

    App->>Server: 1. Authorized to open domain
    App->>Server: 2. Fetches Verification File via HTTPS<br/>(AASA for iOS)

    Note over Server: JSON file confirms App ID

    Server-->>App: 3. Permission Confirmed
    Server-->>App: 4. HANDSHAKE SECURED

Client-Side (Mobile App): This is where the request lives. The app is built with a "Digital Access Key" (Entitlement) that tells the phone's operating system which domains it is interested in.
Server-Side (Domain): This is where the proof lives. The domain hosts the AASA file that confirms the app is authorized to handle its links.

This guide provides a technical framework for ensuring Universal Links successfully launch an app through a redirect chain, and offers a standardized checklist for troubleshooting broken link behavior.

Successful Universal Links via redirects

Ensure the following steps for Universal Links to successfully track when routing traffic through tracking domains:

The initial click is user-initiated.
Redirects are server-side HTTP 3xx (301/302), not client-side JavaScript scripts.
The final URL after the redirect belongs to the brand’s Universal Link domain or a Mobile Measurement Partner (MMP) configured for app linking (e.g., brand.example or brand.mmp.example).
The final URL matches an allowed path in the brand’s Apple App Site Association (AASA) file.
The click happens in a browser that supports Universal Links (e.g., Safari, Chrome—not restricted webviews or third-party browsers).
No intermediate interstitial page interrupts the redirect chain.

Successful execution flow

graph TD
    Step1["Step 1: User selects a link"] --> Step2["Step 2: The link hits a tracking URL<br/>(e.g., https://tracker.example.com/...)"]
    Step2 --> Step3["Step 3: The server issues an<br/>HTTP 301 or 302 Response"]
    Step3 --> Step4["Step 4: The destination URL opens, e.g.,<br/>https://brand.com/promo"]
    Step4 --> Step5["Step 5: iOS detects universal link, and<br/>mobile app opens"]

    style Step1 fill:#EBEBFF,stroke:#9370DB
    style Step2 fill:#EBEBFF,stroke:#9370DB
    style Step3 fill:#EBEBFF,stroke:#9370DB
    style Step4 fill:#EBEBFF,stroke:#9370DB
    style Step5 fill:#EBEBFF,stroke:#9370DB

Unsuccessful Universal Links via redirects

1. Intermediary partner pages using JavaScript redirects

Intermediary redirect pages hosted by partners or networks are a common failure point, e.g., You’re being redirected outside the app. These pages typically redirect using JavaScript, e.g., window.location.href = "https://brand.com/promo";

Why the redirect chain breaks

The following transitions do not preserve the user gesture needed for Universal Link invocation:

The redirect is not server-side (it’s in the browser context).
iOS sees it as a new navigation, not tied to the original user click.
As a result, https://brand.com/promo opens in Safari as a web page instead of launching the app.

2. Restricted WebViews

Some in-app browsers, like Facebook, Instagram, or custom in-app browsers, block Universal Links. Consequently, these links only open inside the web view and are blocked from launching the mobile app. To mitigate these restrictions, we recommend using enhanced deeplinking.

3. Missing app-side domain association (Entitlements)

Even if the domain’s AASA file and redirect are correct, the mobile app must explicitly opt in to Universal Link handling. Failure to do so will result in the link opening in Safari instead of the app.

Common issues include:

The app is not configured with Associated Domains in Xcode (Entitlements.plist).
The entitlement’s string is missing the proper domain, e.g., applinks:brand.com
The app is not installed (iOS fallback behavior is to open in browser).
The app was updated or reinstalled without revalidating the entitlement configuration, which serves as the client-side configuration that defines the mobile app's authorized relationship with the domain.

<plist version="1.0">
<dict>
<key>com.apple.developer.associated-domains</key>
<array>
	<string>applinks:brand.com</string>
	<string>applinks:*.brand.com</string>
	<string>applinks:brand.mmp.com</string>
</array>
</dict>
</plist>

4. Back navigation/history

Even if the app opens successfully, a user who navigates back to Safari and selects the link a second time may find that the OS treats it as a standard web navigation rather than retriggering the Universal Link logic.

5. Path mismatch

To prevent the link from defaulting to Safari, the final URL must match the paths defined in the tracking domain’s AASA file initiating the redirect—whether that is the brand’s website, an MMP, or an impact.com tracking domain.

6. AASA file issues

Even with correct redirects and app configuration, the universal link fails if:

The AASA file is missing or malformed.
It’s not served with the proper Content-Type: application/json.
It’s hosted at the wrong path (must be /.well-known/apple-app-site-association).
It doesn’t include the correct app ID and paths.

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID12345.com.brand.app",
        "paths": [
          "/products/*",
          "/promo/special-offer",
          "NOT /customer-service/help/*"
        ]
      }
    ]
  }
}

Troubleshooting checklist

🔁 Are all redirects server-side (HTTP 3xx) after the initial user tap? Avoid JavaScript-based or meta-refresh redirects, especially on intermediary pages.
📄 Does the final URL path match one of the allowed paths in the AASA file? Check for typos, trailing slashes, or missing path declarations in the apple-app-site-association file.
🔐 Is the app correctly configured with Associated Domains in entitlements? Verify that the app’s Associated Domains are correctly configured and deployed to the device, ensuring the applinks:brand.com entitlement is explicitly declared in the entitlements file during the app build.
👆 Was the link tap user-initiated (e.g., from an email, message, or button tap)? iOS suppresses Universal Link behavior if the redirect is triggered automatically or when the link is pasted directly in the address bar.
🌐 Is the link being opened in Safari or Chrome, not in a restricted webview (e.g., Facebook, Instagram)? Many in-app browsers block Universal Link handoff to the system.
⚠️ Is there an intermediate splash/interstitial page between the tap and the destination? These often use JavaScript redirects, breaking Universal Link resolution.
🔍 Is the AASA file accessible and properly formatted?
- Hosted at https://brand.com/.well-known/apple-app-site-association
- Served with Content-Type: application/json
- Contains correct app ID and paths array
📱 Is the app installed and up-to-date on the device? If not, the Universal Link will fall back to Safari (by design).
🔄 Has the user already tapped the link, opened the app, and then returned to Safari? Tapping the same link after back navigation may not reopen the app due to history caching.