Implementing iOS Deep Links: A Technical Guide to Universal Links and Custom URL Schemes

iOS deep links are specialized URIs that direct users straight to specific content inside an iOS application rather than opening a website homepage or launching an app’s default landing screen. On iOS, deep linking is accomplished through legacy Custom URL Schemes or standard Apple Universal Links, which map regular web URLs to in-app routes using cryptographically verified domain associations.

Understanding iOS Deep Linking Architectures

Deep linking fundamentally changes how users transition between websites, emails, advertisements, and native mobile applications. Instead of forcing a user to manually navigate through an app hierarchy after launch, a deep link passes contextual metadata directly into the application process during launch or reactivation.

On iOS, developers rely on two primary methods to handle incoming links: Custom URL Schemes and Universal Links. Choosing the correct strategy depends on security requirements, domain ownership, and desired user experience when an application is not installed.

1. User Clicks Link
   • Custom URL Scheme (e.g., myapp://path)
     • Is app installed?
       • Yes: Launch App
       • No: Show Error / Do Nothing
   • Universal Link (e.g., https://site.com)
     • Is app installed?
       • Yes: Launch App Directly
       • No: Fallback to Web Browser

Custom URL Schemes

Introduced in early versions of iOS, Custom URL Schemes allow apps to register a proprietary protocol prefix (such as myapp:// or storefront://). When the operating system encounters a URL with that scheme, it routes the link payload directly to the registered application.

While simple to implement, Custom URL Schemes carry distinct architectural vulnerabilities:

• No Uniqueness Enforcement: Multiple applications installed on the same device can register the exact same scheme (e.g., pay://). The operating system cannot guarantee which app will open, creating security risks such as credential phishing or request hijacking.
• No Native Fallback: If the user does not have the app installed, clicking a custom scheme URL in Safari or another app produces an unhandled error modal ("Safari cannot open the page because the address is invalid") rather than redirecting to a website or the App Store.

Universal Links

Introduced in iOS 9 and refined continuously by Apple, Universal Links connect standard web HTTP/HTTPS URLs (such as https://www.example.com/products/123) directly to a native application.

Universal Links fix the flaws of Custom URL Schemes through two-way trust verification:

1. Domain Trust: The app explicitly lists the domains it supports within its entitlements.
2. App Trust: The domain hosts a signed or publicly available JSON configuration file—the Apple App Site Association (AASA) file—that grants the specific iOS App ID permission to handle its URLs.

If the app is installed, iOS intercepts the HTTPS request and routes it straight to the native application without opening Safari. If the app is not installed, the operating system defaults seamlessly to loading the web page in the browser, providing an uninterrupted user experience.

Technical Comparison: Custom Schemes vs. Universal Links

Configuring the Apple App Site Association (AASA) File

The foundation of Universal Links security is the apple-app-site-association file. This JSON file must be hosted on your domain over HTTPS and served without any file extension.

Hosting Requirements and Location

The iOS operating system queries your domain to retrieve the AASA file under two valid paths:

1. https://yourdomain.com/.well-known/apple-app-site-association
2. https://yourdomain.com/apple-app-site-association

Apple recommends placing the file in the /.well-known/ directory.

Hosting Prerequisites

• Protocol: The file must be served strictly over secure HTTPS using a valid, non-self-signed SSL certificate.
• Content-Type: The web server must return the HTTP header Content-Type: application/json.
• Redirect Restrictions: The file must be served directly with an HTTP status code 200 OK. iOS will not follow HTTP redirects (such as 301 or 302 responses) when fetching the AASA file.
• Size Limit: The AASA file must not exceed 128 KB.

Modern AASA JSON Structure

Beginning with iOS 13, Apple introduced an expanded schema supporting explicit component matching, pattern exclusions, and wildcards. Below is an example of a production-ready AASA configuration:

{ "applinks": { "details": [ { "appIDs": [ "ABC123XYZ.com.example.myapp" ], "components": [ { "/": "/products/*", "comment": "Matches any product page URL" }, { "/": "/user/profile/*", "?": { "referrer": "?*" }, "comment": "Matches user profiles that include a referrer query string" }, { "/": "/admin/*", "exclude": true, "comment": "Prevents administrative URLs from opening in the mobile app" } ] } ] } }

Key Elements of the AASA Schema

• appIDs: Array combining your 10-character Apple Team ID and the target Application Bundle Identifier separated by a period (.). You can verify your Team ID inside the Apple Developer Account Portal.
• components: Array of matching rules evaluated sequentially by iOS:
  • "/": Defines the URL path pattern using syntax like * (matches zero or more characters) or ? (matches a single character).
  • "*": Defines matching rules for query parameters.
  • "exclude": true: Excludes specific matching patterns, ensuring sensitive paths (like user checkout or admin dashboards) remain strictly in the web browser.

Apple Universal Links CDN Caching

When a user installs or updates your application, iOS does not always fetch the AASA file directly from your host server. Instead, requests are routed through Apple's Universal Links Content Delivery Network (CDN) to optimize device battery and network performance.

To verify what Apple's CDN server has indexed for your domain, request your domain status directly from Apple's edge infrastructure:

https://app-site-association.cdn-apple.com/a/v1/yourdomain.com

If you deploy updates to your live web server, allow up to 24 hours for Apple's CDN infrastructure to refresh its cached representation of your AASA file.

Application Configuration in Xcode

Enabling deep links within your iOS project requires registering capabilities inside Xcode and updating your project configuration files.

1. Registering Custom URL Schemes

If your application uses custom schemes alongside Universal Links:

1. Open your project in Xcode and select your primary Application Target.
2. Navigate to the Info tab.
3. Expand the URL Types section at the bottom.
4. Click the + button to add a new URL Type.
5. In the Identifier field, enter your bundle ID or reverse-domain string (e.g., com.example.myapp).
6. In the URL Schemes field, enter your custom protocol prefix (e.g., myapp).

CFBundleURLTypes CFBundleTypeRole Editor CFBundleURLName com.example.myapp CFBundleURLSchemes myapp

2. Registering Universal Links Entitlements

To associate your app with an HTTPS domain:

1. In Xcode, select your primary Application Target and click the Signing & Capabilities tab.
2. Click + Capability and select Associated Domains.
3. Under the newly added Associated Domains entitlement box, click + to add a domain entry using the format: applinks:yourdomain.com
4. If your app serves multiple subdomains, list each explicitly:
   • applinks:www.yourdomain.com
   • applinks:shop.yourdomain.com

During local testing, bypass Apple's CDN caching mechanism by appending ?mode=developer to the domain string inside your entitlements configuration:

applinks:yourdomain.com?mode=developer

Processing Deep Links in Swift

Once configured, the operating system delivers incoming links to your application through system lifecycle delegates. How you receive and route these payloads depends on whether your project uses SwiftUI or UIKit lifecycle architectures.

Handling Universal Links in SwiftUI

SwiftUI provides a declarative modifier called .onOpenURL, which intercept both Custom URL Schemes and Universal Links universally across views.

import SwiftUI @main struct MobileApp: App { @StateObject private var router = AppRouter() var body: some Scene { WindowGroup { ContentView() .environmentObject(router) .onOpenURL { incomingURL in router.handleDeepLink(incomingURL) } } } } final class AppRouter: ObservableObject { @Published var selectedTab: Int = 0 @Published var activeProductID: String? func handleDeepLink(_ url: URL) { guard let components = URLComponents(url: url, resolvingAgainstBaseURL: true) else { return } // Parse path segments: e.g., /products/456 let pathComponents = components.path.split(separator: "/").map(String.init) if pathComponents.first == "products", pathComponents.count > 1 { let productID = pathComponents[1] self.selectedTab = 1 // Navigate to Catalog tab self.activeProductID = productID } } }

Handling Deep Links in UIKit (SceneDelegate)

Applications using scene-based lifecycle management intercept Universal Links and custom schemes through UISceneDelegate callback protocols.

import UIKit class SceneDelegate: UIResponder, UIWindowSceneDelegate { var window: UIWindow? // 1. Triggered when app is launched from a cold start via Universal Link func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) { if let userActivity = connectionOptions.userActivities.first, userActivity.activityType == NSUserActivityTypeBrowsingWeb, let incomingURL = userActivity.webpageURL { routeDeepLink(incomingURL) } else if let customURL = connectionOptions.urlContexts.first?.url { routeDeepLink(customURL) } } // 2. Triggered when app is running in background and restored via Universal Link func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { guard userActivity.activityType == NSUserActivityTypeBrowsingWeb, let incomingURL = userActivity.webpageURL else { return } routeDeepLink(incomingURL) } // 3. Triggered when app is restored via Custom URL Scheme func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { guard let incomingURL = URLContexts.first?.url else { return } routeDeepLink(incomingURL) } private func routeDeepLink(_ url: URL) { // Pass parsed URL payload to application routing manager print("Received deep link payload: \(url.absoluteString)") } }

Deferred Deep Linking Strategies

Standard deep links operate under the assumption that the user already has the native app installed on their device. If a non-installed user clicks a custom scheme, the request fails; if they click a Universal Link, they end up on the fallback website.

Deferred Deep Linking preserves the target destination metadata across the app installation process:

1. User Clicks Link
2. Safari Web Fallback
3. App Store Installation
4. Launch Installed App
5. Fetch Attribution Metadata
6. First App Launch

How Deferred Deep Linking Works

1. Fingerprinting & Attribution: When an uninstalled user clicks a deferred deep link, an attribution service (or custom web landing page) records contextual parameters (IP address, user agent, referral tokens) and redirects the user to the App Store.
2. App Store Installation: The user downloads and opens the app for the first time.
3. Context Retrieval: On initial boot, the app queries an attribution SDK or native API (such as Apple's SKAdNetwork or server match endpoints) to retrieve original link metadata and routes the user to their intended destination screen.

Debugging and Troubleshooting Common Issues

Deep link configurations involve multiple distinct subsystems—DNS, SSL certificates, remote CDN caching, build entitlements, and application lifecycle callbacks. Standardized testing commands help isolate points of failure.

Testing Deep Links via Command Line

To verify link routing on the iOS Simulator without relying on mobile browser UI, execute the Apple Simulator Utility (simctl) inside the macOS Terminal:

Testing a Custom Scheme

xcrun simctl openurl booted "myapp://products/789"

Testing a Universal Link

xcrun simctl openurl booted "https://www.example.com/products/789"

Common Pitfalls and Troubleshooting Steps

1. AASA CDN Stale Caching

   • Symptom: Changes made to server-side JSON files do not resolve on physical test devices.
   • Solution: Check Apple's CDN cache via https://app-site-association.cdn-apple.com/a/v1/yourdomain.com. For immediate testing, use developer mode entitlements (applinks:yourdomain.com?mode=developer).

2. Unwanted HTTP Redirects

   • Symptom: iOS ignores Universal Links and loads Safari every time.
   • Solution: Verify that your host server returns a direct 200 OK code for the AASA file path without 301/302 redirects. Also verify that the domain does not redirect https://domain.com requests to https://www.domain.com before serving the file.

3. User Disabling Universal Link Routing

   • Symptom: Clicking a link opens Safari instead of opening the native application, despite proper configuration.
   • Solution: In iOS, if a user clicks the top-right domain indicator link (e.g., example.com >) inside your app header, iOS remembers that choice and defaults to opening that domain in Safari for future clicks. To re-enable automatic app launches, long-press a Universal Link inside Messages or Mail and select Open in "[App Name]".

4. Missing Associated Domains Entitlement

   • Symptom: Build compiles successfully, but Universal Links do not launch the app.
   • Solution: Review your provisioning profiles on the Apple Developer Portal to confirm the Associated Domains capability is checked for your App ID.

Frequently Asked Questions

What is the main difference between Universal Links and Custom URL Schemes on iOS?

Universal Links use standard HTTP/HTTPS web URLs and rely on verified domain associations to open an app securely, falling back to Safari if the app is uninstalled. Custom URL Schemes use proprietary prefix protocols (like myapp://), offer no verification mechanisms, can be claimed by multiple apps, and produce unhandled errors if the app is not installed.

Why is my apple-app-site-association file not being detected by iOS?

Common causes include failing to serve the file over HTTPS, serving the file with an unapproved MIME type instead of application/json, hosting behind an HTTP redirect, exceeding the 128 KB file size limit, or waiting on Apple's Universal Link CDN cache to refresh.

Do Universal Links work inside all browsers and social media apps?

While Universal Links are fully supported natively by iOS systems, certain third-party apps wrap web navigation inside embedded WebViews or custom in-app browsers (e.g., Instagram, TikTok) that may block or intercept default Universal Link handoffs.

How do I handle Universal Links when the app is launched from a cold start vs. running in the background?

In SwiftUI, the .onOpenURL modifier processes incoming URLs automatically regardless of execution state. In UIKit SceneDelegate projects, cold launches deliver link metadata inside scene(_:willConnectTo:options:) via connectionOptions.userActivities, whereas background resumptions deliver links via the scene(_:continue:) delegate callback.

Can Universal Links work without a live web server or domain?

No. Universal Links explicitly require ownership and control of an active HTTPS domain hosting a valid apple-app-site-association file. Applications operating without a web domain must rely on legacy Custom URL Schemes.

Next Steps and Action Plan

To establish a production-ready iOS deep linking infrastructure:

1. Audit Domain Infrastructure: Confirm your production domain uses valid HTTPS certificates and can host raw JSON files under the /.well-known/ directory.
2. Generate and Deploy AASA JSON: Construct your apple-app-site-association file using your 10-character Apple Team ID and app bundle identifier, defining exact route matching rules.
3. Configure Xcode Project Capabilities: Add the Associated Domains capability to your target settings and add applinks: entries for all target domains and subdomains.
4. Implement App Routing: Use SwiftUI's .onOpenURL or UIKit's UISceneDelegate protocols to extract URL payloads and navigate to the requested screen.
5. Validate using CLI Tools: Test deep link resolution in local simulators using xcrun simctl openurl commands to verify behavior before sending builds to TestFlight.