|
|
@@ -0,0 +1,103 @@
|
|
|
+# 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. 归因架构（两端共用）
|
|
|
+
|
|
|
+采用"首启上报、服务端待归因、注册自动绑定"三段式，**不依赖客户端在注册时提交推荐码**：
|
|
|
+
|
|
|
+```text
|
|
|
+推广人生成分享链接（服务端签发不透明令牌，非裸 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 模式识别、首启上报。
|
|
|
+- 平台端（可选）：推广关系与归因记录查询页面。
|
qmj