新手从零接入 Detour 延迟深度链接 SDK 的完整流程

当开发者初次接触 Detour（Software Mansion 开源延迟深度链接 SDK），需要从账号注册到生产环境完成全平台接入时使用。

适用场景

解决思路

1. 先向用户确认两件事：目标平台（React Native（Expo 或 bare）、iOS 原生 Swift、Android 原生 Kotlin/Java、Flutter）以及是否已有 Detour 账号和已配置的 app；已有账号则跳到 Phase 2，否则从 Phase 1 开始。
2. Phase 1 仪表盘配置（所有平台通用）：在 app.godetour.dev 注册账号并确认邮件。
3. 创建 organization，选择一个唯一子域名，它将成为所有延迟链接的基础 URL：https://YOURORG.godetour.link。
4. 创建 app，记录仪表盘自动生成的 App ID（初始化 SDK 用）、Publishable API Key（认证 SDK 调用用）、App Hash（默认延迟链接 URL 的一部分）。
5. 在 Link Settings 标签页设置 Web Fallback Redirect URL（桌面/不支持浏览器落地页），参数转发先保持默认；短链接是可选的，除非明确需要否则跳过。
6. 在 App Configuration 标签页填写：iOS 的 Bundle ID、Apple Team ID、App Store ID；Android 的包名（必须与 app 中完全一致）和 SHA-256 签名证书指纹；这些用于 Detour 自动托管 apple-app-site-association 和 assetlinks.json；Android 的 intent-filter 片段必须从此标签页复制，绝不手写。
7. 在 API Configuration 标签页复制 Publishable API Key 和 App ID，存入环境变量，绝不硬编码。
8. Phase 2 配置 Universal Links（iOS）和 App Links（Android）：让已安装 app 时 Detour 链接直接打开 app 而不经过浏览器；Detour 会自动托管验证文件，唯一改动是在 app 内注册 Detour 域名；按平台加载对应参考文件（React Native → references/react-native.md 的 Universal/App Links 节；iOS → references/ios.md 的 Universal Links 节；Android → references/android.md 的 App Links 节；Flutter → references/flutter.md 的 Universal/App Links 节）。
9. Phase 3 SDK 集成：按平台加载参考文件（React Native → references/react-native.md；iOS → references/ios.md；Android → references/android.md；Flutter → references/flutter.md）。
10. 将生成的代码与已安装的 SDK 核对：参考文件可能滞后于已发布 SDK，以已安装包为准；核对所用符号（导出、方法签名、枚举值、配置字段）是否与用户项目中实际安装的一致（React Native 查 node_modules/@swmansion/react-native-detour 类型，Flutter 查插件的 lib/，iOS/Android 查 SDK 公开头文件/源码）；安装版本查 registry/README 而非假定固定版本号；若已安装 SDK 与参考文件冲突，以已安装 SDK 为准并告知用户差异。
11. 理解 linkProcessingMode：all（默认，deferred + Universal/App Links + 自定义 scheme 全支持）、web-only（deferred + Universal/App Links，不支持自定义 scheme）、deferred-only（仅 deferred）；除非有特定理由，否则从 all 开始。
12. 处理链接结果对象：所有平台都返回 route（可直接导航的完整路径和查询串，如 /articles/2?ref=campaign）、pathname（不含查询串的路径）、params（解析后的查询参数键值对）、url（原始完整 URL）、type（deferred、verified（Universal/App Link）或 scheme）；导航后必须调用 clearLink() 或消费 intent，防止 app 恢复时重复导航。
13. Phase 4 分析：Detour 自动追踪 Clicks、Installs via link、Fallbacks、Organic vs non-organic，无需代码；仪表盘视图有 Overview（趋势和留存）、Links（按 campaign 逐日）、Events（自定义 SDK 事件）。
14. 手动事件追踪使用 DetourAnalytics.logEvent，事件名只能取 DetourEventNames / DetourEventName 枚举值，不要自造字符串；正确示例：DetourAnalytics.logEvent(DetourEventNames.Purchase, { revenue: 29.99 })；错误示例：DetourAnalytics.logEvent("article_opened", {})。
15. 对没有枚举等价物的事件，使用 logRetention 加描述性字符串，如 DetourAnalytics.logRetention("article_opened")；留存追踪从首次 logRetention 调用起最多 30 天。
16. Phase 5 架构与匹配原理：确定性匹配（Android）——Play Store 传递带精确 click_id 的 install referrer 时直接查找，精确匹配非常可靠；概率匹配（iOS 及 Android 回退）——无 click_id 时按信号打分：IP 精确匹配 500 分、设备型号+OS 版本 450 分、user-agent 设备签名 350 分、iOS 粘贴板 token 350 分、时区 200 分、屏幕尺寸 200 分、语言 100 分；默认阈值 850 分（可配置 700-1200），时间窗口 15 分钟（可配置 5-180 分钟）。
17. 主动告知已知限制：iCloud Private Relay/VPN 会混淆 IP 削弱最强信号；iOS 粘贴板被拒会丢失 350 分；广告网络重定向链可能剥离 click_id 迫使 Android 走概率路径；Play Store referrer 缺失（侧载和预装无 referrer 数据）；共享设备上相似指纹有误判风险；不适合路由敏感数据或金融决策。
18. Phase 6 测试延迟链接流程：先卸载 app，再在真机浏览器点击默认 Detour 链接 https://YOUR_ORG.godetour.link/APP_HASH/your/path，然后从商店重定向安装 app，打开 app 后 SDK 数秒内调用 match API，验证 link 对象填充了预期 route。
19. 注意：每次延迟链接测试都必须先卸载 app，app 已安装时点击链接会按 Universal/App Link 解析而非延迟；每次延迟测试需要新链接，同一链接在同一设备上不会第二次触发延迟解析；初始测试不要用短链接，先用默认 https://ORG.godetour.link/APP_HASH/path 格式。
20. Universal/App Links 测试：app 已安装时点击链接，应直接打开而不经过浏览器；Android 12+ 见 references/android.md 测试节，debug APK 需手动 adb 启用。
21. 运行 app 前先查看项目 README 或 package.json scripts 确认正确运行命令，不要假定 npx react-native run-android，很多项目用 npm run android 或自定义脚本。
22. 通用规则：不要跳过任何阶段，按顺序完成所有阶段并在进入下一阶段前与用户确认；所有代码用占位符 YOUR_API_KEY、YOUR_APP_ID、YOUR_ORG，绝不索要真实凭据；Android App Links 的 intent-filter 片段始终从 Detour 仪表盘复制，绝不手写；分析中 logEvent 只用 DetourEventNames/DetourEventName 枚举值，绝不自造事件名字符串；短链接是可选的且与默认链接分离，不要作为标准配置的一部分建议创建；更深入参考见 detour.swmansion.com/docs。

适用边界 · 注意事项

• 用户尚未确定目标平台或没有 Detour 账号时，不要直接跳到平台 SDK 集成步骤。
• app 已安装时不要用延迟链接测试流程（会按 Universal/App Link 解析），且同一链接在同一设备上无法第二次触发延迟解析。
• 不要用短链接做初始测试，也不要把创建短链接当作标准配置的一部分。