capacitor-deep-linking

Files (6)

• SKILL.md
• metadata.json
• android-app-links.md · references/
• ios-scene-delegate.md · references/
• ios-universal-links.md · references/
• routing-patterns.md · references/

SKILL.md (first lines)

# 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)

```typescript
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`:

```xml
<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):

```xml
<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:)`).

From Cap-go/capgo-skills, MIT.

More from Cap-go/capgo-skills