iOS Deep Linking
Overview
iOS Universal Links allow your dynamic links to open directly in your iOS app instead of the browser. When a user with your app installed taps a LinkSense dynamic link, iOS checks the Apple App Site Association (AASA) file and, if configured correctly, opens the link in your app.
LinkSense automatically hosts the AASA file for your project subdomain, so you only need to register your app and configure your Xcode project.
Prerequisites
Before setting up iOS deep linking, make sure you have:
- An Apple Developer account with an active membership
- Your app's Bundle Identifier (e.g.,
com.example.myapp) - Your Apple Team ID (found in the Apple Developer portal)
- A LinkSense project with a subdomain
Registering Your iOS App
In the LinkSense dashboard, open your project's Apps tab and add an iOS app. Provide the following information:
- App Name: a friendly name for the app
- Bundle ID: your app's Bundle Identifier
- Team ID: your Apple Developer Team ID
- App Store ID: your app's App Store ID, found in App Store Connect under App Information (for fallback redirects)
Your Team ID can be found in your Apple Developer Membership Details. It is a 10-character alphanumeric string (e.g., A1B2C3D4E5). For more on how Universal Links work, see Apple's guide on Supporting Universal Links in Your App.
Apple App Site Association (AASA)
LinkSense automatically generates and hosts the AASA file at the well-known path for your project subdomain. The file is served at:
The generated AASA file follows this structure:
{ "applinks": { "apps": [], "details": [ { "appIDs": ["TEAM_ID.com.example.myapp"], "paths": ["*"] } ] }}The AASA file is automatically updated when you add or remove iOS apps from your project. No manual file hosting is required.
Configuring Your Xcode Project
To enable Universal Links in your iOS app, you need to add the Associated Domains capability in Xcode:
- Open your project in Xcode
- Select your app target and go to Signing & Capabilities
- Click + Capability and add Associated Domains
- Add an entry with your LinkSense subdomain
Your entitlements file should include:
<key>com.apple.developer.associated-domains</key><array> <string>applinks:your-subdomain.linksense.net</string></array>Testing Universal Links
To test that Universal Links are working correctly:
- Install your app on a physical device (Universal Links do not work in the simulator)
- Open the Notes app or Messages and paste your dynamic link URL
- Tap the link: it should open directly in your app
- If the link opens in Safari instead, long-press it and check for an "Open in [App]" option
Universal Links do not fire when you type or paste the URL into Safari's address bar. iOS treats that as a direct web navigation, not as opening a link.
They also do not fire on a server-side redirect. iOS matches the URL that was tapped against the AASA files it has cached — not the URL a 302 later lands on. If the tapped URL is on a domain that is not in your app's Associated Domains, no app is associated and the browser opens.
A tap that the system handles — Notes, Messages, a native app — works. A tap inside an in-app browser or webview often does not, because the webview resolves the navigation itself instead of handing it to the system.
These are independent, and one link can hit both at once.
Webview mail clients. Gmail, Outlook and most mobile mail apps open links in an embedded browser. Universal Links do not fire there, even with a clean, untracked URL on your own subdomain.
ESP click tracking. SendGrid, Mailgun, Postmark, Customer.io and Resend rewrite the href to their own tracking domain before the message is sent. That domain appears in no AASA LinkSense serves, so iOS finds no associated app and opens a browser; the redirect that follows is a plain web navigation. A custom domain on your LinkSense project does not help — the rewrite happens before anyone taps.
Two fixes: turn off click tracking for the message or for the individual link (every major ESP supports this), or point your ESP at a tracking domain you control, host an AASA on it, and add it to your app's Associated Domains. Android App Links fail the same way, though some Android browsers are more forgiving about handing the URL back to the system.