Complete guide to implementing deep links and universal links in Capacitor apps. Covers iOS Universal Links, Android App Links, custom URL schemes, and navigation handling. Use this skill when users need to open their app from links.

Deep Linking in Capacitor Route custom scheme links, iOS Universal Links, and Android App Links into the web app. When to Use TRIGGER when: Adding myapp:// schemes, Universal Links, or App Links to a Capacitor app Links open the browser instead of the app, or open the app but land on the home page appUrlOpen fires on warm open but the URL is missing on cold launch (or the reverse) Deep links broke after updating to Capacitor 8.5+ / adopting SceneDelegate.swift OAuth / magic link / payment redirects must come back into the app adb shell pm get app links shows none or 1024 instead of verified Do not use: Full AppDelegate SceneDelegate migration of an app: capacitor uiscene migration Notification tap routing: capacitor push notifications Native log capture while debugging: ios android logs Sign in with Apple / Google plugin config: capacitor plugins Link Types Type Platform Format Needs hosted file Verified ownership Custom scheme both myapp://product/123 no no (any app can claim it) Universal Links iOS https://example.com/product/123 /.well known/apple app site association yes App Links Android 6+ https://example.com/product/123 /.well known/assetlinks.json yes Prefer verified https links for anything security sensitive (OAuth, magic links). Custom schemes can be hijacked by another app. Workflow 1. Inspect first. Read capacitor.config. , ios/App/App/Info.plist , ios/App/App/ .entitlements , ios/App/App/AppDelegate.swift , ios/App/App/SceneDelegate.swift (if present), android/app/src/main/AndroidManifest.xml , and the @capacitor/app version in package.json . 2. Decide the iOS lifecycle path. UIApplicationSceneManifest present in Info.plist (Capacitor 8.5+ template or migrated app) URL events arrive in SceneDelegate . Any custom code in AppDelegate application( :open:options:) or application( :continue:restorationHandler:) is dead code. See [references/ios scene delegate.md](references/ios scene delegate.md). No scene manifest AppDelegate path still works on 8.5 core, but Xcode 27 / Capacitor 9 require the scene lifecycle. Hand the migration to capacitor uiscene migration . 3. Install @capacitor/app ( npm install @capacitor/app && npx cap sync ). 4. Register the JS handler once, at app bootstrap (before the router renders), using both appUrlOpen and getLaunchUrl() . See below. 5. Configure platforms : custom scheme (Info.plist CFBundleURLTypes , Android <intent filter ), then verified links per platform: iOS Universal Links: [references/ios universal links.md](references/ios universal links.md) Android App Links: [references/android app links.md](references/android app links.md) 6. Route in the framework router: [references/routing patterns.md](references/routing patterns.md) (React, Vue, Angular, OAuth callbacks, deferred links). 7. Verify with the cold/warm matrix below on a real device. Only load a reference when its topic is in play. JS Handler (the part every app needs) Traps: Custom scheme URLs parse with the first segment as host , not pathname . Normalize both forms as above. Register the listener at bootstrap, not inside a lazily loaded page. A listener added after the event fired never sees it; getLaunchUrl() is the fallback for cold start. Wrap state updates from the listener in your framework's zone/run loop (Angular NgZone.run ) or navigation silently does nothing. Dedupe: on cold start the URL can be reachable via both getLaunchUrl() and appUrlOpen . Validate and allow list paths before navigating; a deep link is untrusted input. Custom Scheme Config iOS ios/App/App/Info.plist : Android AndroidManifest.xml , inside the existing MainActivity (keep the template's android:launchMode="singleTask" so warm opens reuse the activity): Verification Run every row on a physical device (Universal Links do not work reliably from the Simulator address bar; tap from Notes/Messages instead). Scenario iOS Android Custom scheme, warm xcrun simctl openurl booted "myapp://product/123" adb shell am start W a android.intent.action.VIEW d "myapp://product/123" com.example.app Custom scheme, cold kill app, then same command adb shell am force stop com.example.app , then same command Verified link, warm tap https://example.com/product/123 in Notes adb shell am start W a android.intent.action.VIEW c android.intent.category.BROWSABLE d "https://example.com/product/123" Verified link, cold swipe app away, tap link force stop, then same command Ownership check curl sI https://example.com/.well known/apple app site association (200, no redirect) adb shell pm get app links com.example.app shows verified Pass criteria: each case lands on the right route, appUrlOpen logs once, and on cold start getLaunchUrl() returns the URL. After a Capacitor 8.5 scene migration, re run the full matrix: cold launch takes a different native path ( scene( :willConnectTo:options:) ) than warm open ( scene( :openURLContexts:) / scene( :continue:) ). Grep for dead handlers after migration: Error Handling Symptom / message Cause Fix Link opens in Safari, app installed AASA not fetched, wrong appID , entitlement missing, or user long pressed and chose "Open in Safari" Check AASA via Apple CDN, TEAMID.bundleId , applinks: entitlement; long press link and choose "Open in App" to reset Custom AppDelegate URL code stopped running after 8.5 update Scene manifest exists; iOS calls SceneDelegate instead Move logic to SceneDelegate (reference: ios scene delegate) Warm opens work, cold launch lands on home Listener registered late, or custom SceneDelegate code ignores connectionOptions Call getLaunchUrl() at bootstrap; keep SceneDelegateProxy.shared.scene( :willConnectTo:options:) Safari cannot open the page because the address is invalid Custom scheme not registered in installed build Add CFBundleURLTypes , rebuild (not just cap sync ) Error: Activity not started, unable to resolve Intent No intent filter matches scheme/host Fix <data entries; reinstall app pm get app links shows 1024 or none assetlinks.json unreachable, wrong package, or wrong SHA 256 (often the Play App Signing key) Fix file, then adb shell pm verify app links re verify com.example.app Android shows app chooser for https link Domain not verified ( autoVerify missing or failed) Add android:autoVerify="true" , re verify OAuth redirect returns to browser tab, not app Redirect URI does not match registered scheme / verified domain Register exact redirect URI; prefer verified https link Resources Capacitor deep links guide: https://capacitorjs.com/docs/guides/deep links App plugin API: https://capacitorjs.com/docs/apis/app Updating to 8.5 (UIScene): https://capacitorjs.com/docs/updating/8 5 Apple Universal Links: https://developer.apple.com/documentation/xcode/supporting associated domains Android App Links: https://developer.android.com/training/app links/verify android applinks

capacitor-deep-linking