Skip to content
Tolinku Docs

Troubleshooting iOS Deep Links

Section titled “Universal Links not opening the app”

Check the AASA file

Section titled “Check the AASA file”

Visit https://your-domain/.well-known/apple-app-site-association in a browser. Verify:

  • The file loads without redirects (redirects break AASA validation).
  • The appID field matches <TeamID>.<BundleID> exactly.
  • The paths array includes the route prefix you are testing.
  • Content-Type is application/json.

Use Apple’s AASA Validator to check for issues.

Check the Associated Domains entitlement

Section titled “Check the Associated Domains entitlement”

In Xcode, go to your target’s Signing & Capabilities and verify:

  • The Associated Domains capability is added.
  • The entry reads applinks:your-domain.com (no https://, no trailing slash).
  • If using both a Tolinku subdomain and a custom domain, both are listed.

Check Appspace Settings

Section titled “Check Appspace Settings”

In the Tolinku dashboard under Appspace Settings > iOS:

  • Bundle ID must match your Xcode project exactly.
  • Team ID must match your Apple Developer account (found in Membership details).
  • The route must have Universal Link enabled.

AASA caching

Section titled “AASA caching”

iOS caches the AASA file aggressively:

  • On iOS 14+, Apple fetches AASA files through its CDN. Changes may take up to 24 hours to propagate.
  • Deleting and reinstalling the app forces a fresh AASA fetch.
  • During development, you can use the ?mode=developer flag on the associated domain entry: applinks:your-domain.com?mode=developer. This bypasses the Apple CDN and fetches directly from your server.
Section titled “Links open in Safari after user override”

If a user long-presses a Universal Link and chooses “Open in Safari”, iOS remembers this preference. All subsequent taps on that domain will open in Safari.

Fix: Long-press the link again and choose “Open in [App Name]” to restore the default behavior.

This is an iOS behavior that cannot be overridden programmatically.

Section titled “Links work from Messages but not from Safari”

This is expected behavior. Universal Links triggered from within Safari on the same domain open in Safari, not the app. This is Apple’s same-domain restriction.

Workaround: Use a different domain for your website and your deep links. For example, use links.myapp.com for deep links and www.myapp.com for your website.

Deferred deep linking not working

Section titled “Deferred deep linking not working”

Signal-based matching fails

Section titled “Signal-based matching fails”
  • The matching window is short. If the user installs hours after clicking, the fingerprint may not match.
  • Ensure the SDK calls claimBySignals on the very first app open (before any navigation).
  • Check that the appspaceId passed to claimBySignals matches your Appspace.
  • VPNs, shared WiFi, or cellular IP changes between click and install can cause mismatches.
Section titled “handleUniversalLink returns nil”
  • Verify the URL’s host matches a domain in your Associated Domains entitlement.
  • Check that the URL path matches a route with Universal Links enabled.
  • handleUniversalLink only parses the URL; it does not make API calls. If it returns nil, the URL format is unexpected.

Testing checklist

Section titled “Testing checklist”
  1. AASA file accessible at /.well-known/apple-app-site-association (no redirects).
  2. Bundle ID and Team ID set in Appspace Settings.
  3. Route has Universal Links enabled.
  4. Associated Domains entitlement added in Xcode with correct domain.
  5. App installed on a physical device (Universal Links do not work in Simulator).
  6. Link opened from a different domain (not same-domain).
  7. SDK initialized with Tolinku.configure(apiKey:) before handling links.