深度链接

模板同时支持自定义 soar:// scheme 和已验证的 HTTPS App Links。所有进入应用的链接都会经过同一个 resolver，然后外层导航打开 modal destination，或把 URI 转发进 tab shell。

提供什么

Surface	状态	实现
Custom scheme	Integrated	`AndroidManifest.xml` 接收 `soar://...`
Supabase callback	Integrated	`soar://auth-callback` 保留给 supabase-kt
HTTPS App Links	Integrated	`LINKING_DOMAIN` manifest placeholder + Android asset links
冷启动和热启动	Integrated	`MainActivity.onCreate()` 和 `onNewIntent()` 都调用 `DeepLinkHandler`
Refer share sheet	Example	`ReferScreen` 通过 `ACTION_SEND` 分享 Play Store URL

关键文件

入口渠道

manifest 声明了三类相关的 ACTION_VIEW filter：

Link	Owner	说明
`soar://auth-callback`	Supabase Auth	用于 OTP、recovery、OAuth callback；`DeepLinkHandler` 会忽略
`soar://home`、`soar://todos` 等	App router	应用内页面的 custom scheme link
`https://<LINKING_DOMAIN>/home`	App router	域名设置完成后的 verified App Links

在 local.properties 设置 HTTPS host：

LINKING_DOMAIN=example.com

Gradle 会把它注入 manifest 的 ${linkingDomain}。缺失时 placeholder 回退到 your.domain.example；自定义 soar:// 链接仍然可用。

Android App Links 验证

HTTPS App Links 需要在域名上托管 Asset Links 文件：

https://<LINKING_DOMAIN>/.well-known/assetlinks.json

它必须包含最终 application id 和已安装构建所用签名证书的 SHA-256 指纹：

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.soarstarter.kotlin",
      "sha256_cert_fingerprints": ["AA:BB:CC:..."]
    }
  }
]

生产链接使用 release upload 证书或 Play app-signing 证书。debug 指纹只会验证 debug 构建。

捕获流程

ACTION_VIEW Intent
  -> MainActivity.onCreate() / onNewIntent()
  -> DeepLinkHandler.pendingUri
  -> DeepLinkResolver.resolve(uri, BuildConfig.LINKING_DOMAIN)
  -> AppNavGraph outer destinations or MainShellScreen tab destinations

DeepLinkHandler 在 StateFlow 中保存一个 pending URI。AppNavGraph 读取后会调用 consume()，避免同一个链接被处理两次。

DeepLinkResolver 接受：

soar://home
soar:///home
soar://anything?route=home
https://<LINKING_DOMAIN>/home

route query parameter 会覆盖 path，和 Expo sibling 的 deep-link 行为保持一致。

可路由 destination

DeepLinkDestination 当前包含：

URI segment	Destination	处理方式
空或 `home`	`Home`	Home tab
`component`、`components`	`Component`	Component tab
`showcase`	`Showcase`	Showcase tab；可移除 leaf
`todos`	`Todos`	Home tab，然后 `AppRoutes.Todos`
`me`	`Me`	Me tab
`profile`	`PersonalInfo`	Me tab，然后 personal-info screen
`notifications`	`Notifications`	Me tab，然后 notifications screen
`permissions`	`Permissions`	Me tab，然后 permissions screen
`refer`	`Refer`	外层 nav destination
`paywall`	`Paywall`	外层 nav destination
`redeem-code`	`RedeemCode`	外层 nav destination

Refer、Paywall 和 RedeemCode 会先由 AppNavGraph 处理，不进入 shell。其余链接会作为 shellDeepLinkUri 转发，在 MainShellScreen 内处理。

测试链接

对已安装构建运行 adb：

adb shell am start \
  -a android.intent.action.VIEW \
  -d "soar://notifications" \
  com.soarstarter.kotlin

Asset Links 验证后测试 HTTPS 形式：

adb shell am start \
  -a android.intent.action.VIEW \
  -d "https://example.com/paywall" \
  com.soarstarter.kotlin

测试推送点击时，可发送：

{ "url": "soar://notifications" }

Refer screen 关联

ReferScreen 不生成自定义 referral code。它会根据 package name 构造 Play Store URL：

https://play.google.com/store/apps/details?id=<package-name>

然后通过 Intent.ACTION_SEND 打开 Android share sheet。把它当作 starter pattern：如果邀请是你的产品功能，可以把 getInviteLink() 替换为 referral、branch 或 campaign URL。

提供什么

关键文件

入口渠道

Android App Links 验证

捕获流程

可路由 destination

测试链接

Refer screen 关联

相关页面

配置

推送通知

App Gates

On this page