Skip to content

Troubleshooting / iOS association

iOS Universal Link Opens Safari Instead of Your App

Check the AASA file, Associated Domains entitlement, path rules, and the context in which Safari opens the URL.

For: iOS, Flutter, React Native, and Unity teams whose HTTPS links do not reach their installed app.

WilderLinks developer guide

The problem

A link opens Safari, or the app opens for some hosts but not others. That does not by itself tell you whether the saved WilderLinks route is wrong.

Apple associates an app with an HTTPS host using an apple-app-site-association (AASA) response and the app’s Associated Domains entitlement. The host, app identifier, and path must agree. Apple’s CDN can cache the association, and Safari may intentionally keep same-domain navigation in the browser.

Before you start

  • An installed iOS build with its Apple Team ID and bundle ID known.
  • The exact HTTPS link hostname configured in a WilderLinks domain and app profile.
  • A physical device for final Universal Link behavior testing.

Diagnose in order

  1. 01WilderLinks

    Inspect the AASA file for the clicked host

    Use the exact subdomain in the URL. Apple requires a publicly reachable HTTPS AASA file without a redirect. Compare the listed app identifier and path rules with the link and app profile you configured.

    • The extensionless .well-known URL returns the AASA response directly.
    • The file contains the matching Team ID and bundle ID.
    • The clicked path is included rather than excluded.
    Inspect Apple associationshell
    curl -i https://links.example.com/.well-known/apple-app-site-association

  2. 02Your app

    Match the app entitlement exactly

    In Xcode Signing & Capabilities, enable Associated Domains and add applinks:links.example.com for the target that receives the link. A root domain entry does not automatically stand in for every specific subdomain.

    • The entitlement uses the exact fully qualified host with no path or port.
    • The signed build on the device includes the entitlement.
    • The Team ID and bundle ID match the hosted AASA entry.
  3. 03Operating system

    Test the right opening context

    Try a link from a message or another app, not only a same-domain tap within Safari. Apple documents that Safari can keep same-domain navigation on the web. After association changes, device and Apple CDN caching can delay the result; reinstalling the app may be needed to retest.

    • Test a fresh install or reinstall after association changes.
    • Compare same-domain Safari navigation with a link opened from another app.
    • Confirm the app receives the URL before expecting SDK resolution.
  4. 04WilderLinks

    Then inspect the configured route

    Use the safe tester for the iOS platform to inspect the saved strategy, destination type, and deferred-payload presence. It cannot verify Apple’s association, launch Safari, or prove the app handled a URL.

    • The configured WilderLinks domain matches the URL host.
    • The SDK receives and resolves the delivered URL.
    • Your app navigates using the returned destination or payload.

Expected result

  • A supported tap can hand the matching HTTPS URL to the installed app.
  • The app passes that URL to its WilderLinks handler.
  • Your app chooses the final screen from the resolved result.

What this check cannot prove

  • The SDK does not install an Associated Domains entitlement or force Apple to open the app.
  • A browser-only route inspection cannot validate AASA caching or installed-app behavior.
  • No automatic App Store token recovery is provided for users who install the app after the click.

Next action

Handle the URL after iOS delivers it to your app.

Open the iOS SDK Guide
All developer field guides