foodie-server/docs/app-install-attribution.md

App 推广安装归因方案（讨论稿）

记录时间：2026-09-02 状态：方案讨论完成，待管理层拍板三个决策点后按 spec-kit 立项（规格 → 计划 → 任务 → 实现） 需求：推广人员分享推荐链接，他人通过链接去应用商店下载 App 后，系统能关联"这个用户是谁推荐的"

1. 现状基础

• info_user 已有 mycode（本人 8 位邀请码，注册时生成）和 thiscode（记录邀请人）字段；/setuser 已能接收 thiscode 入库。
• 缺失部分：推荐码从分享到安装的传递链路、归因记录与注册自动绑定、邀请奖励结算逻辑（当前 thiscode 只记录不结算）。

2. 核心难点

• Android：Google Play 官方提供 Install Referrer API，下载来源可 100% 自动传递。
• iOS：苹果隐私规则禁止 App 下载过程传递任何来源信息（平台级限制，所有 App 一致，无技术绕过方案）。iOS 归因必然需要"一次用户轻交互"或接受模糊匹配。
• 用户不点链接、直接去商店搜索下载的，技术上无法归因，只能靠手填邀请码兜底。

3. 分平台方案

3.1 Android：Play Install Referrer（100% 准确，无感）

分享链接：https://play.google.com/store/apps/details?id={包名}&referrer={推广令牌}
App 首启调 Play Install Referrer API 读出令牌 → 首启上报 → 注册自动绑定

3.2 iOS：按可靠度分层的通道组合

优先级	通道	原理	用户成本	准确率
1	手机号中转	落地页"输手机号领新客券"，服务端记录（手机号 → 推广令牌）；注册用同一手机号时精确匹配自动绑定	填一次手机号	≈100%
1'	快速预注册（中转页变体）	落地页直接手机号+验证码预建账号，下载后登录即归因；适合不给奖励的场景	完成注册	≈100%
2	复制邀请码	落地页"复制"按钮把 https://域名/r/{令牌} 写入系统剪贴板（设备级全局存储，装 App 不清空）；注册页输入框出现 iOS 系统粘贴建议条，点一下自动填	点两下	≈100%（依赖配合）
2'	剪贴板无弹窗自动读取	iOS 16+ UIPasteboard.detectPatterns 可无弹窗检测剪贴板内 URL 并取值；因此复制内容必须包成 URL 而非裸码。时机必须在注册页而非启动页	无感	高（iOS 16+）
3	指纹匹配	落地页记录 IP+UA（机型/系统）+屏幕+点击时间；App 首启上报同字段，服务端窗口期配对	无	60–80%
4	手填邀请码	推广人 LINE 里直接发码，注册页输入框手输	手输	100%

注意事项：

• 剪贴板是单槽位，复制码后用户若复制其他内容（下载窗口期内很常见）即被覆盖丢失，故剪贴板只做增强层，不做主力。
• 不要在 App 启动页读剪贴板（iOS 16 弹"允许粘贴"确认框，用户拒绝即失效且伤体验）。
• iOS 15 及以下直接读剪贴板仅显示顶部通知不拦截。
• Apple 官方 AdAttributionKit/SKAN 只服务广告网络，不适用于个人分享链接。
• Universal Link 仅对已安装用户有效，不适用新装机。

4. 归因架构（两端共用）

采用"首启上报、服务端待归因、注册自动绑定"三段式，不依赖客户端在注册时提交推荐码：

推广人生成分享链接（服务端签发不透明令牌，非裸 mycode，可验真/撤销/统计）
        ↓
落地页（记录指纹 + 手机号/复制码；Android 直跳 Play 带 referrer）
        ↓
App 首启 → POST /app/install/attribution（令牌 + 设备信息）
        ↓
服务端待归因记录：设备指纹/手机号 + 令牌 + 上报时间（状态=待绑定）
        ↓
用户注册 → 服务端自动查待归因记录 → 绑定 thiscode → 记录置为已消费

绑定优先级（需写死）：手填邀请码 > 手机号中转 > 剪贴板 > 指纹匹配（用户明确意图优先）。

5. 必须定死的规则

1. 归因窗口：安装后 7~30 天内注册有效（建议 7 天），过期作废。
2. 一机一记录：待归因记录消费后作废；同设备重装重复上报不重复发奖。
3. 多来源冲突：last-click wins（最后点击生效）；同 IP 窗口期内多条不同令牌的点击，保守处理（放弃归因或取最后一条）。
4. 指纹误判保守策略：匹配不上宁可算自然流量，不错归。
5. 防刷：服务端令牌签发、设备唯一性校验、奖励冷却期；裸推广码不可作为链接参数（防手编）。
6. iOS 剪贴板失效兜底链：手机号中转（不受剪贴板影响）→ 指纹（不受剪贴板影响）→ 手填。

6. 预期归因率

场景	归因率
Android（点了链接）	≈100%（Install Referrer）
iOS 走了手机号中转	≈100%
iOS 只点了复制码、剪贴板未被覆盖	≈100%
iOS 剪贴板被覆盖、无手机号	指纹兜住 60–80%
未点链接直接商店搜索	0%（手填码除外）

iOS 综合预期 85% 以上（取决于落地页"填手机号/复制码"的转化率）；其余算自然流量。

7. 落地节奏与工作量粗估

• 第一期（自建，无采购成本）：推广短链/令牌服务 + 落地页（含领券/复制交互，需适配 LINE 内建浏览器引导外部浏览器打开）+ 归因上报接口 + 待归因表 + 注册绑定逻辑 + App 双端改造（Android 读 referrer、iOS 粘贴建议条/首启上报）。
  • 后端 + 落地页约 1–2 周；App 双端约 1–2 周；含联调测试合计约 2–4 周。
• 第二期（规模化可选）：接入 AppsFlyer OneLink / Adjust，短链全平台自动归因 + 推广数据报表；有按量费用。
• 隐私合规：设备指纹与手机号用于营销归因，需写入 App 隐私政策（台湾个资法）；落地页附用途说明。

8. 待拍板决策点

1. iOS 方案：方案 A 落地页填手机号领新客券（≈100%，需券预算）还是方案 B 零成本复制码+手填（综合 70–80%）。
2. 新客优惠券：面额与预算（零成本也建议放"首单免配送费/95 折"类轻钩子，否则中转页填写率极低）。
3. 推荐奖励规则：推荐人得什么（只记录 / 注册即奖 / 首单奖励 / 持续分成）——决定要不要建邀请关系表与结算逻辑。

9. 立项后范围（spec-kit）

• specs/0xx-app-referral-attribution/spec.md：用户故事（推广人生成链接、被邀请人下载注册自动绑定、推荐数据查询）、验收场景、防刷规则。
• 后端：短链/令牌、落地页、归因上报、待归因表、注册绑定、（可选）邀请奖励结算。
• App 端需求单：Android Install Referrer 读取、iOS 粘贴建议条/URL 模式识别、首启上报。
• 平台端（可选）：推广关系与归因记录查询页面。