ionic-deep-links

深层链接（URL scheme + Universal Links + App Links）

你可能需要配合使用的三种深层链接：

类型	示例	验证方式	适用场景
自定义 scheme	myapp://reset-password?token=…	无	内部流程、OAuth 回调。配置简单，任何人都可以注册该 scheme。
iOS Universal Link	https://yourapp.com/reset-password?token=…	域名上的 apple-app-site-association 文件	品牌链接，可打开应用，也可回退到网页。
Android App Link	https://yourapp.com/reset-password?token=…	域名上的 assetlinks.json 文件	在 Android 上实现与 Universal Links 相同的目标。

要打造完善的应用，通常需要三种链接都支持：同一个 URL 可在 iOS 和 Android 上使用（Universal/App Link），并在无法验证链接时回退到自定义 scheme。

何时查阅

• 自定义 URL scheme + @capacitor/app 监听器：custom-scheme.md
• iOS Universal Links（entitlement + AASA 文件）：ios-universal-links.md
• Android App Links（intent filters + assetlinks.json）：android-app-links.md
• 将链接路由到页面：routing.md

规范 URL 格式

为每种用途选定一个路径前缀，并在自定义 scheme、Universal Links 和 App Links 中保持一致，这样同一套路由代码就能处理所有三种链接：

用途	自定义 scheme	Universal/App Link
身份验证（重置密码 / OAuth 回调 / magic link）	myapp://auth/<flow>?...	https://yourapp.com/auth/<flow>?...
邀请	myapp://invite/<code>	https://yourapp.com/invite/<code>
分享	myapp://share/<id>	https://yourapp.com/share/<id>

此脚手架中的身份验证路径适用于 ionic-firebase、ionic-supabase，以及密码重置 / OAuth 回调流程：

• Magic link：https://yourapp.com/auth/finish-signin?...
• 密码重置：myapp://auth/reset-password?token=...
• OAuth 回调（Supabase）：myapp://auth/callback#access_token=...

深层链接处理器中的路由逻辑会匹配 pathname.startsWith('/auth/')，并将请求交给相应流程处理。

硬性规则

• ✅ 使用 @capacitor/app 的 appUrlOpen 监听器——它会以统一方式处理所有三种链接。
• ✅ 在域名根目录托管 AASA / assetlinks.json 文件，并设置正确的 Content-Type（application/json，不带扩展名）。
• ✅ 使用 xcrun simctl openurl（iOS 模拟器）和 adb shell am start -a android.intent.action.VIEW -d "<url>"（Android 模拟器）进行测试。
• ❌ 密码重置 / OAuth 不要只依赖自定义 scheme——现代操作系统版本和电子邮件客户端越来越常会屏蔽这类链接。
• ❌ 冷启动时别忘了调用 App.getLaunchUrl()——冷启动打开时，appUrlOpen 可能不会可靠触发（许多 Capacitor 版本中会触发，但行为取决于平台和版本）。为确保万无一失：启动时始终检查一次 getLaunchUrl()。

库

npm install @capacitor/app
npx cap sync