cap-go/capgo-skills/capacitor-deep-linking

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

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.
• 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.

1. Install @capacitor/app (npm install @capacitor/app && npx cap sync).
2. Register the JS handler once, at app bootstrap (before the router renders), using both appUrlOpen and getLaunchUrl(). See below.
3. 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

1. Route in the framework router: references/routing-patterns.md (React, Vue, Angular, OAuth callbacks, deferred links).
2. 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).

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

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