Universal Links & Deep Linking

Getting a tapped link to open your app on the right screen — universal links, the Associated Domains entitlement, the AASA file, custom URL schemes, and link handling across SwiftUI and UIKit lifecycles. The full API/format reference, hosting rules, lifecycle matrix, routing, testing, and failure-mode table live in references/guide.md. This file is the decision and discipline layer: read it first, open the guide for specifics.

Dials

Set these explicitly at the start; they change what "correct" means.

1. LINK_TYPE — universal-link (default; secure, verified https://, falls back to web) · custom-scheme (myapp://, spoofable, no web fallback — for OAuth callbacks / internal glue only) · both (universal links public, custom scheme as private/test fallback).
2. AASA_HOSTING — well-known (default; https://<domain>/.well-known/apple-app-site-association) · root (legacy https://<domain>/apple-app-site-association; serve identically if you keep both).
3. HANDLING — swiftui-onOpenURL (default; .onOpenURL + .onContinueUserActivity(NSUserActivityTypeBrowsingWeb)) · uikit-userActivity (scene willConnectTo / continue + AppDelegate continue:restorationHandler:).

When to use

Adding, reviewing, or debugging any flow where a link opens the app: shared content links, email/SMS deep links, marketing links, OAuth redirects, QR codes, Handoff. Also the classic "the link just opens Safari" debugging session. If you only need in-app navigation between screens with no external entry point, this isn't it — use plain SwiftUI navigation.

Core rules