Deep Links (URL schemes + Universal Links + App Links)

Three flavors of deep linking that you'll likely need together:

You usually want all three for a polished app: one URL works on iOS and Android (Universal/App), with custom schemes as a fallback for cases where verified linking isn't possible.

When to consult

• Custom URL scheme + @capacitor/app listener: [custom-scheme.md](references/custom-scheme.md)
• iOS Universal Links (entitlement + AASA file): [ios-universal-links.md](references/ios-universal-links.md)
• Android App Links (intent filters + assetlinks.json): [android-app-links.md](references/android-app-links.md)
• Routing the link to a page: [routing.md](references/routing.md)

Canonical URL shape

Pick one path prefix per concern and use it consistently across custom schemes, Universal Links, and App Links so the same router code handles all three:

The auth path is shared across ionic-firebase, ionic-supabase, and password-reset / OAuth-callback flows in this scaffold:

• Magic link: https://yourapp.com/auth/finish-signin?...
• Password reset: myapp://auth/reset-password?token=...
• OAuth callback (Supabase): myapp://auth/callback#access_token=...

Routing logic in the deep-link handler matches on pathname.startsWith('/auth/') and delegates to the right flow.

Hard rules

• ✅ Use @capacitor/app's appUrlOpen listener — it fires for all three flavors uniformly.
• ✅ Host the AASA / assetlinks.json files at your domain root with the right Content-Type (application/json, no extension).
• ✅ Test with xcrun simctl openurl (iOS sim) and adb shell am start -a android.intent.action.VIEW -d "<url>" (Android emulator).
• ❌ Don't rely on custom schemes alone for password reset / OAuth — modern OS versions and email clients increasingly suppress them.
• ❌ Don't forget to call App.getLaunchUrl() on cold-start — appUrlOpen may not fire reliably for cold opens (it does in many Capacitor versions, but the behavior is platform- and version-dependent). Belt-and-suspenders: always check getLaunchUrl() once at boot.

Library

npm install @capacitor/app
npx cap sync