Universal Links Setup for iOS: From AASA to Navigation

App doesn't open from a link in an email? Users complain that the site opens in the browser instead of the app? Universal Links solve this directly: a link like https://yourapp.com/product/123 opens the app on the correct screen, bypassing the browser. No custom schemes (myapp://product/123) that don't work in Safari and are blocked by corporate MDM. We are a mobile development team with over 5 years of experience; we have configured deep linking via universal links for 15+ iOS projects with a total audience of over 2 million users. On one project with 500 thousand users, we discovered that users could not navigate from an email campaign to a specific product—conversion dropped by 20%. After implementing universal linking, it recovered and grew by 15%. This article covers a proven methodology and common pitfalls. For deep linking iOS setup, follow the steps below.

Why Universal Links Are Better Than Custom Schemes

Custom URL schemes (myapp://) have fundamental drawbacks:

• They don't work in Safari by default—the user sees an error "Cannot Open App".
• They are not supported in corporate MDM environments.
• They have no fallback to the web version.

Universal Links are free of these problems: they use standard HTTPS, support fallback to the site, and require no additional user action. Security is higher—the scheme cannot be intercepted by another app.

How Universal Links Work and Where They Break

AASA file. The file at https://yourapp.com/.well-known/apple-app-site-association on the server must be JSON without file extension, served with Content-Type: application/json, accessible via HTTPS without redirects. Apple parses this file when the app is installed and caches it on a CDN—updating can take up to 24 hours. The AASA file should be kept under 50KB for optimal performance.

Most common mistake: the server serves the file with a redirect from http to https, or a 301 to a www version of the domain. Apple does not follow redirects when downloading AASA. Check with curl -v https://yourapp.com/.well-known/apple-app-site-association—it should return 200 with correct Content-Type. Use the swcutil command on macOS to validate entitlements.

Format for iOS 13+ (applinks with details):

{ "applinks": { "details": [{ "appIDs": ["TEAMID.com.yourapp.bundle"], "components": [ { "/": "/product/*", "comment": "Product pages" }, { "/": "/order/*" } ] }] } } 

App Entitlements. In Entitlements.plist you need com.apple.developer.associated-domains with an entry applinks:yourapp.com. A forgotten entitlement means the app simply doesn't receive the universal link callback. Enable associated domains iOS through Xcode capabilities.

Handling in Code. In AppDelegate or SceneDelegate, implement application(_:continue:restorationHandler:) (UIKit) or onOpenURL (SwiftUI). You get NSUserActivity with type NSUserActivityTypeBrowsingWeb and webpageURL. Parse the path using URLComponents to determine the target screen and build the navigation stack. AppDelegate universal link handling involves implementing that method. For SwiftUI deep link handling, use the onOpenURL modifier.

URL parsing must be robust: webpageURL may come with query parameters, fragments, or uppercase letters. Use URLComponents instead of manual string parsing to avoid encoding issues. Implement URL routing iOS logic using URLComponents.

Testing. In the simulator, universal links work via xcrun simctl openurl booted 'https://yourapp.com/product/123'. On a real device, use Safari (long press on the link → "Open in App"). Xcode → Diagnostics won't show AASA issues—you need swcutil on Mac and Console.app for swcd logs (Apple's universal links daemon).

How to Verify the AASA File Is Correct

1. Run curl -v https://yourapp.com/.well-known/apple-app-site-association. Expect HTTP/1.1 200 OK and Content-Type: application/json.
2. Use Apple's AASA Validator (built into Apple Developer).
3. On Mac, open Console.app, filter by swcd—you'll see AASA download logs.
4. On iOS: enter the link in Safari, after opening the app check logs via the device.

Apple uses a CDN to cache the AASA file and verifies the domain via SSL certificate. This prevents unauthorized apps from claiming your domain.

Typical Issues During Setup

Often developers face that the link opens the website instead of the app. The reason is an inaccessible or incorrect AASA file: the server serves a redirect or wrong format. Solution: remove redirects and ensure format matches iOS 13+. Another issue: universal link not handled because the entitlement com.apple.developer.associated-domains is missing from the target. Third: the AASA file not updating due to Apple caching (up to 24 hours). Use developer mode to speed up.

Scenarios and Edge Cases

Multiple domains. An app can handle up to 5 domains—just add multiple entries in entitlements. An AASA file is needed on each domain separately.

Links from email clients. Gmail and Outlook in iOS apps wrap links through their redirect services. Universal links won't fire in this case—Apple sees the redirect URL, not the target. This is a platform limitation, not a bug.

Service Deliverables

• AASA file setup on the server with required path patterns
• Entitlements and Xcode configuration for all targets and schemes (Debug, Release, Staging)
• Handler implementation in SceneDelegate / AppDelegate with routing to target screens using URLComponents
• Testing on real devices and via simulator
• Verification through Apple's validator and swcd logs
• Project documentation including server access instructions and entitlement configuration
• 30-day post-deployment support for any issues
• Optional training session for your team (1 hour) to maintain the setup

Pricing starts at $499 for a single domain with up to 5 path patterns. For multiple domains or custom logic, cost is calculated individually. Based on our experience, average savings are 40% compared to in-house setup due to reduced trial and error. We offer iOS deep linking turnkey solutions starting at $499. The iOS deep linking cost depends on complexity; typical multi-domain setups range from $799 to $1,299.

Timelines

Basic implementation with several path patterns and integration into existing navigation: 1 to 2 days. With support for multiple domains and custom routing logic: 2 to 3 days. Timelines are estimated conservatively; over 95% of projects meet the deadline.

Get an engineer consultation—we'll help with your project.