iOS 安装里最关键的一步，蘑菇视频官网 - 跳转逻辑这件事｜我反复确认了两遍？十个里九个都错在这
导语 很多人把“跳转到 App Store”当作 iOS 安装转化链路的终点，但真正决定体验和归因准确性的，是在用户还没安装和安装后首次打开之间，参数如何被传递和还原。蘑菇视频官网的落地页、活动链接、渠道参数，如果处理不当，十个里九个都会在这里出错——安装到位，但用户和推广来源信息丢失，后续转化和归因全靠猜。
一、先把两种场景分清楚（关键）
- 已安装用户：点击官网链接，应直接打开 App，并把参数（视频 id、活动码、渠道）透传到 App。这靠 Universal Links / URL Scheme 实现。
- 未安装用户：点击官网链接会跳到 App Store 安装，安装完成后首次打开 App 如何拿到原始参数（deferred deep link）？这是最难也最容易出错的一步。
二、已安装用户的正确做法（直接透传） 要点：
- 在网站端使用 Universal Links（https 链接）；不要依赖老旧的自定义 scheme 作为唯一方式，因为 Safari 在某些场景会阻塞或提示。
- app 需配置 Associated Domains（applinks:your.domain.com），并在你的域名根目录或 /.well-known/ 下放置 apple-app-site-association（AASA）文件（无扩展名，Content-Type 为 application/json 或 application/pkcs7-mime）。
AASA 示例（精简）： { "applinks": { "apps": [], "details": [ { "appID": "TEAMID.com.yourcompany.mushroom", "paths": [ "/open/", "/promo/" ] } ] } }
iOS 端处理（基于 SceneDelegate / AppDelegate）：
- 在 continueUserActivity 中解析 NSUserActivity.webpageURL
- 根据路径和 query 将用户导到对应页面或播放指定视频
常见错误：
- AASA 文件放错位置（必须是 https://your.domain/apple-app-site-association 或 https://your.domain/.well-known/apple-app-site-association）
- appID（TEAMID + bundle id）写错或漏 Team ID
- 没在 Xcode 的 Associated Domains 中添加 applinks: 域名
- 页面跳转链路里使用了 302/重定向导致 Universal Link 被浏览器当作外链处理（会失效）
三、未安装用户（deferred deep link）——这一步十个里九个都错 iOS 没有像 Android 的 install referrer 那样的官方、通用参数透传机制。很多人误以为在跳转到 apps.apple.com 后加 query 就能回到 App 带参数，这是不成立的。App Store 不会把这些自定义 query 透传给 app。
可行方案（按稳定性与合规性排序）： 1) 使用成熟的 deferred deep linking 服务（推荐）
- Branch、Firebase Dynamic Links、Adjust、AppsFlyer 等，这些厂商用一套服务器端映射 + 指纹或 SDK 上报来实现高成功率的 deferred deeplink。
- 优点：稳定、有 SDK 支持、归因可视化、兼容多渠道。
- 缺点：依赖第三方，需付费或接入复杂度。
2) Server-side click mapping +首开匹配（自研） 流程：
- 点击短链（或落地页）时生成唯一 clickid 并写入服务端映射，同时把 clickid 存 cookie 或作为短链一部分。
- 跳转到 App Store 安装。
- App 首次打开时，向你的服务器发起注册请求（带 IDFV、安装时间、IP、UA 等），服务端通过指纹或时间窗口匹配最近的 click_id，返回对应参数给 App。
- 优点：不依赖第三方，自主可控。
- 缺点：指纹匹配有误差，iOS 隐私限制越来越严格，命中率低于专业服务；实现需考虑防作弊和隐私合规。
3) Smart App Banner + app-argument（条件适用）
- 在落地页加入 Smart App Banner meta:
- 当用户在 Safari 中看到并点击“打开”按钮，若已安装会打开 app 并传 app-argument。
- 对于未安装用户，Smart App Banner 的“View”会去 App Store，但 app-argument 并不会在安装后自动传回 app。
- 适用场景：提升已安装用户体验，但不能解决 deferred linking。
4) 非推荐/高风险做法（谨慎）
- 使用剪贴板、cookie + webview hack 等临时方案可能在短期有效，但有被 App Store 审核拒绝或后续 iOS 限制的风险。不要把这当长期方案。
四、落地页跳转实现要点（蘑菇视频官网适用） 推荐落地页跳转逻辑（伪流程）：
- 用户点击推广链接 https://mushroom.example/p/abc?ch=wechat&campaign=xxx
- 服务端记录 click（click_id、ip、ua、时间、参数），返回短链或页面。
- 页面优先尝试 Universal Link 打开 app（window.location = "https://mushroom.example/open?vid=xxx&click=click_id"）
- 若 app 已安装，则由 app 处理并拿到 click_id 或 vid。
- 若 app 未安装，跳转到 App Store（apps.apple.com/…）
- 安装后首次打开 app，app 向服务器上报设备信息，请求和 click_id 的匹配数据并拿回 vid、渠道信息，完成 deferred deep link。
五、测试清单（必须跑完）
- 已安装场景：点击落地页能否直接打开 App 并接收参数（Safari、Chrome、微信内置浏览器差异）
- 未安装场景：卸载 app 后完成安装，首次打开 app 能否拿到期望的参数（多台设备、多渠道、多时间窗口）
- AASA 文件是否可被访问，HTTP code 200，Content-Type 无扩展名
- Associated Domains 在不同构建环境（开发、生产）是否一致
- URL 重定向链是否包含中间 302 导致 Universal Links 失效
- 在真机上测试，不依赖模拟器（模拟器关于 App Store 跳转行为不同）
六、隐私与合规提醒（写给运维/产品）
- 尽量减少指纹化采集，明确在隐私政策中告知用途。
- Apple 对滥用剪贴板或隐蔽收集识别信息敏感度高，避免使用灰色手段。
- 如果使用第三方 SDK 做归因，确认其隐私合规与 iOS 14+ ATT 影响。
结语 那一步“参数从网站到 App 的最终回传”并非小细节，而是决定推广数据准确性与用户首体验的核心环节。蘑菇视频官网要做得稳：已安装走 Universal Links，未安装走成熟的 deferred linking 策略（优选第三方或谨慎自研），再配合严格的测试与隐私合规。反复确认两遍不是多余，正是把这一步做到位的区别。
最后给你一个简短的校验清单（复制使用）
- AASA 在 2 个路径可访问：/apple-app-site-association 和 /.well-known/apple-app-site-association
- Xcode Associated Domains 添加 applinks:your.domain.com
- Universal Links 在真机测试通过（Safari 点击）
- 点击链路记录 click_id 并能在首次打开中被匹配
- 测试已安装/未安装、不同浏览器、网络环境
需要的话，我可以把上面的落地页跳转伪代码、服务端匹配逻辑和 iOS 端的 continueUserActivity 实现示例整理成可直接交给开发的技术文档。想要哪一部分先看？