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

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.
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.
- 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.
Install @capacitor/app (npm install @capacitor/app && npx cap sync).
Register the JS handler once, at app bootstrap (before the router renders), using both appUrlOpen and getLaunchUrl(). See below.
Configure platforms: custom scheme (Info.plist CFBundleURLTypes, Android <intent-filter>), then verified links per platform:
- iOS Universal Links: references/ios-universal-links.md
- Android App Links: references/android-app-links.md
Route in the framework router: references/routing-patterns.md (React, Vue, Angular, OAuth callbacks, deferred links).
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)

import { App, type URLOpenListenerEvent } from '@capacitor/app';

let lastHandled: string | undefined;

function route(rawUrl: string) {
  if (rawUrl === lastHandled) return; // cold start can deliver the same URL to both paths
  lastHandled = rawUrl;
  const url = new URL(rawUrl);
  // myapp://product/123 -> host "product", pathname "/123"
  // https://example.com/product/123 -> pathname "/product/123"
  const path = url.protocol.startsWith('http')
    ? url.pathname
    : `/${url.host}${url.pathname}`;
  router.navigate(path + url.search); // your router
}

export async function initDeepLinks() {
  await App.addListener('appUrlOpen', (event: URLOpenListenerEvent) => route(event.url));
  const launch = await App.getLaunchUrl(); // resolves undefined or { url }
  if (launch?.url) route(launch.url);
}

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:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.example.app</string>
    <key>CFBundleURLSchemes</key>
    <array><string>myapp</string></array>
  </dict>
</array>

Android AndroidManifest.xml, inside the existing MainActivity (keep the template's android:launchMode="singleTask" so warm opens reuse the activity):

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="myapp" />
</intent-filter>

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:

grep -n "open url: URL\|continue userActivity" ios/App/App/AppDelegate.swift
grep -n "SceneDelegateProxy" ios/App/App/SceneDelegate.swift

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