# Troubleshoot iOS Universal Links & Redirects iOS 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.
* **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 redirects. * 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
## 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 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. {% tabs %} {% tab title="XML" %} ```xml com.apple.developer.associated-domains applinks:brand.com applinks:*.brand.com applinks:brand.mmp.com ``` {% endtab %} {% endtabs %} #### 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 AASA file of the domain 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. {% tabs %} {% tab title="JSON" %} ```json { "applinks": { "apps": [], "details": [ { "appID": "TEAMID12345.com.brand.app", "paths": [ "/products/*", "/promo/special-offer", "NOT /customer-service/help/*" ] } ] } } ``` {% endtab %} {% endtabs %} ## 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.
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 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.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://integrations.impact.com/integration-guides/for-brands/tracking-integrations/troubleshoot-ios-universal-links-and-redirects.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.