调整极光
This commit is contained in:
joywayer
+34
-15
@@ -64,7 +64,7 @@ Contract Design Plan（本文档）
|
||||
| 后台 `/wechat/login` 中转接口 | secret 不入 IPA 的前提 | Phase 4 | 后台团队 |
|
||||
| 高德地图 `APIKey` + SDK Pod | 定位 | Phase 5 | 已有 key `b0d4a8e3fcbbcc0dd96283b7df6a4494`，但需新建 Bundle ID 注册 |
|
||||
| 七牛上传 token 颁发接口 | 录音上传 | Phase 3 | 后台团队 |
|
||||
| 极光 AppKey | 用户统计 | Phase 9 | 项目方 |
|
||||
| ~~极光 AppKey~~ | ~~用户统计~~ | **已决策暂不集成（ADR-005），未来启用时再协调** | — |
|
||||
| Sentry DSN | 崩溃监控 | Phase 9 | 项目方（需开通账号） |
|
||||
| Agora AppID（视频房间） | 子游戏视频 | Phase 8（默认 stub，可延后） | 项目方 |
|
||||
| 闲聊 SDK | 闲聊分享 | Phase 9（默认 stub） | 项目方 |
|
||||
@@ -161,7 +161,7 @@ Contract Design Plan（本文档）
|
||||
| **P6** | 子游戏容器 | `SubGameViewController` + `Coordinator` + `SwitchOverGameData` / `backgameData` | 契约 §10 中 `SwitchOverGameData` 项 | 中 |
|
||||
| **P7** | 弹层 | `OverlayViewController` + `window.settings` polyfill + 节流 | 契约 §10 中 `OpenurlTitleData` / `settings.*` 项 | 中 |
|
||||
| **P8** | 视频房间 stub | 3 个 stub handler + Native→H5 `getVideoinfo` / `phonestate` / `recordSuccess` callback | 契约 §10 D 节（NoopVideoRoom 路径） | 小 |
|
||||
| **P9** | SDK 真实化 + 监控 | Sentry / 极光 / 七牛 SPM 接入；闲聊 / Bugly 决策落地 | 契约 §10 全 26 项 | 中 |
|
||||
| **P9** | SDK 真实化 + 监控 | Sentry / 七牛 SPM 接入；极光 / 闲聊 / Bugly 决策落地为 Noop / 不集成 | 契约 §10 全 26 项 | 中 |
|
||||
| **P10** | 多渠道 + 灰度 | 渠道注入脚本 / CI 多渠道出包 / 真机回归 / 灰度切流 | 真机验收 + 灰度无回退 | 大 |
|
||||
|
||||
**相对成本说明**：
|
||||
@@ -591,7 +591,7 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
|
||||
### Phase 9: SDK 真实化 + 监控接入
|
||||
|
||||
#### 目标
|
||||
把所有 Noop / stub 替换成真实 SDK；接入 Sentry 崩溃监控 + 极光统计。
|
||||
首版 SDK 集成定型：接入 Sentry 崩溃监控；极光 / 闲聊 / Agora 维持 Noop 占位（编译开关 OFF）；Bugly 不集成。
|
||||
|
||||
#### 前置
|
||||
- Phase 1–8 完成
|
||||
@@ -602,7 +602,10 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
|
||||
- 编译开关 `SENTRY_ENABLED`（默认 ON）+ `NoopCrashReporter` fallback
|
||||
- DSN 通过 xcconfig 注入，不入 git
|
||||
- [ ] **9.2** `Source/Bridge/Handlers/H5ErrorRelay.swift`：注入 `window.onerror` / `unhandledrejection` polyfill + `reportH5Error` 桥 handler（Design §11.4，新增 handler 不破坏契约）
|
||||
- [ ] **9.3** 极光 SDK（Vendor）+ `Source/Analytics/JAnalytics.swift` 启动期注册
|
||||
- [ ] **9.3** 极光（JAnalytics）：保持 `NoopAnalytics` stub（**ADR-005 决策**）
|
||||
- `Source/Analytics/Tracker.swift` 协议 + `NoopAnalytics` 实现
|
||||
- `JAnalyticsTracker.swift` 留蓝图骨架（`#if JANALYTICS_ENABLED` 包裹，默认 OFF）
|
||||
- 上线后业务真要做用户激活 / 留存分析时再启用：放 Vendor、切换实现、加 AppKey、Bootstrapper 注册
|
||||
- [ ] **9.4** 闲聊：保持 NoopSharePlatform（业务方未启用闲聊分享，stub 已满足契约）
|
||||
- [ ] **9.5** Agora：保持 NoopVideoRoom + 编译开关 OFF
|
||||
- [ ] **9.6** Bugly：不集成（Sentry 已覆盖）
|
||||
@@ -611,12 +614,12 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
|
||||
|
||||
- 强制崩溃 → Sentry 后台收到 issue
|
||||
- H5 内 `throw new Error()` → Sentry 看到 H5 错误 + `container_role` 标签
|
||||
- 极光后台看到设备激活
|
||||
- `Tracker` 协议存在且默认绑到 `NoopAnalytics`，业务调用 `Tracker.event(...)` 不崩、不阻塞
|
||||
|
||||
#### 风险
|
||||
|
||||
- Sentry 账号必须 ≥ 2 人持有访问凭证（避免重蹈 Bugly 覆辙）
|
||||
- 极光 / Sentry / 自家后台埋点数据重叠：明确每个监控的"唯一职责"（Sentry=崩溃，极光=用户激活，自家=业务事件）
|
||||
- 首版无用户统计，业务侧若想看激活 / 留存只能等启用 JAnalytics 或自建埋点
|
||||
|
||||
---
|
||||
|
||||
@@ -679,7 +682,7 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
|
||||
|---------|-----|----------|
|
||||
| **SPM 优先** | ZIPFoundation / Sentry / 七牛 v8+ | Phase 1 / 9 / 3 |
|
||||
| **CocoaPods** | 高德 AMap | Phase 5 |
|
||||
| **Vendor `.framework`** | 微信 / QQ / 闲聊（暂不） / Agora（暂不） / JAnalytics | Phase 4 / 9 |
|
||||
| **Vendor `.framework`** | 微信 / QQ；闲聊 / Agora / **JAnalytics** 均暂不集成（Noop 占位） | Phase 4 |
|
||||
| **Vendor `.a`** | opencore-amr | Phase 3 |
|
||||
|
||||
每集成一个 SDK 立即提交一个独立 commit（CLAUDE.md "及时提交" 规则）。
|
||||
@@ -825,9 +828,9 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
|
||||
### Phase 9 SDK 真实化 + 监控
|
||||
- [ ] 9.1 Sentry SPM + CrashReporter
|
||||
- [ ] 9.2 H5ErrorRelay
|
||||
- [ ] 9.3 极光 SDK
|
||||
- [ ] 9.4 闲聊保持 Noop
|
||||
- [ ] 9.5 Agora 编译开关 OFF
|
||||
- [ ] 9.3 极光保持 NoopAnalytics（JANALYTICS_ENABLED OFF）
|
||||
- [ ] 9.4 闲聊保持 NoopSharePlatform
|
||||
- [ ] 9.5 Agora 保持 NoopVideoRoom（AGORA_ENABLED OFF）
|
||||
- [ ] 9.6 不集成 Bugly
|
||||
|
||||
### Phase 10 多渠道 + 回归 + 灰度
|
||||
@@ -863,6 +866,11 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
|
||||
- **风险**：联调期遇到的契约疑点可能来自旧版 H5 已废弃接口，需对照现网 msext + H5 团队双确认
|
||||
- **切换条件**：Phase 10 灰度前必须由 H5 团队提供最新版替换并复跑契约 §10 全部 26 项
|
||||
|
||||
### ADR-003：微信登录走后台中转 vs 客户端 fallback（2026-06-21）
|
||||
- **决策**：默认走后台 `/wechat/login` 中转；后台未就绪时临时客户端直拼，但代码标 `// FIXME` 且**禁止以 fallback 状态上线**
|
||||
- **理由**：客户端 secret 一旦进 IPA 永久泄露 + AppSecret 不可重置（Contract §0.4 / Design §17）；上线前必须闭环
|
||||
- **复盘节点**：Phase 4 完成时检查后台接口状态
|
||||
|
||||
### ADR-004：Resources/ 目录位于仓库根（非 Xcode 工程内）（2026-06-21）
|
||||
- **决策**：项目方提供的所有资源（`gamehall.zip` / 原生 Asset Catalog / 散落 png / mp3 / 后续渠道注入目录）统一放仓库根 `Resources/`，由打包脚本通过 Build Phase 引入；**不**直接放进 Xcode 工程的 `ylgamehall/` 源码目录
|
||||
- **理由**：
|
||||
@@ -871,12 +879,23 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
|
||||
- 符合 Design §2.2 的 SPM 包结构规划（`Resources/` 与 `Sources/` 并列）
|
||||
- **现状**：`Resources/` 已含 `gamehall.zip` / `Images.xcassets/` / `Res/`；11 个渠道注入目录预留位 `Resources/ChannelInjection/` 待 Phase 1 由 `Scripts/inject_channel.sh` 生成
|
||||
|
||||
### ADR-003：微信登录走后台中转 vs 客户端 fallback（2026-06-21）
|
||||
- **决策**：默认走后台 `/wechat/login` 中转；后台未就绪时临时客户端直拼，但代码标 `// FIXME` 且**禁止以 fallback 状态上线**
|
||||
- **理由**：客户端 secret 一旦进 IPA 永久泄露 + AppSecret 不可重置（Contract §0.4 / Design §17）；上线前必须闭环
|
||||
- **复盘节点**：Phase 4 完成时检查后台接口状态
|
||||
### ADR-005：JAnalytics（极光）首版降为 NoopAnalytics 占位（2026-06-21）
|
||||
- **背景**：Design §14.2 原标注极光"✅ 启用，启动注册"，但项目方在 2026-06-21 评审时确认**首版无用户激活 / 留存分析需求**
|
||||
- **决策**：与 Xianliao / Agora 同款渐进集成策略——首版不集成极光 SDK，`AnalyticsKit.tracker` 默认绑到 `NoopAnalytics`，业务调用 `Tracker.event(...)` 立即返回不做任何事；编译开关 `JANALYTICS_ENABLED` 默认 OFF，留蓝图 `JAnalyticsTracker.swift` 待启用
|
||||
- **理由**：
|
||||
- 减少首版外部依赖（首版 SDK 集成清单：微信 / QQ / 高德 / 七牛 / opencore-amr / Sentry / ZIPFoundation，共 7 个；不集成 4 个：极光 / 闲聊 / Agora / Bugly）
|
||||
- 现网 msext 的极光后端运维状态不可知，与 Bugly 同样有"账号断档监控失效"风险（CLAUDE.md / 父级 msext 已有先例），新外壳起步不重蹈
|
||||
- Sentry 的 breadcrumb / transaction 可兜一部分用户行为路径，初期定位够用
|
||||
- 接入成本（AppKey 申请 / Vendor 二进制 / Info.plist 隐私文案）推迟到真有业务需求时
|
||||
- **后续启用路径**（保持契约不变，业务无感）：
|
||||
1. 在 `Vendor/` 放入 `JAnalytics.framework`
|
||||
2. 把 `AnalyticsKit.tracker` 从 `NoopAnalytics()` 切换为 `JAnalyticsTracker()`
|
||||
3. xcconfig 注入 `JANALYTICS_ENABLED=1`
|
||||
4. Bootstrapper.registerSDKs 加 `JAnalytics.setup(appKey:)`
|
||||
5. Info.plist 加 AppKey + 隐私授权文案
|
||||
- **复盘节点**：上线 3 个月后业务方根据数据需求决定是否启用
|
||||
|
||||
---
|
||||
|
||||
文档完成日期：2026-06-21
|
||||
最后更新：2026-06-21（初版）
|
||||
最后更新：2026-06-21（ADR-005 极光降级 + Resources/ 目录记录）
|
||||
|
||||
@@ -132,15 +132,15 @@ Daoqi/
|
||||
│ ├── LocationKit/ # 高德定位
|
||||
│ ├── DeviceKit/ # 设备信息/电池/网络/振动
|
||||
│ ├── VideoRoomKit/ # Agora 封装
|
||||
│ ├── AnalyticsKit/ # 极光、Sentry
|
||||
│ ├── AnalyticsKit/ # Sentry(默认启用) / JAnalytics 极光(暂不集成,Noop 占位)
|
||||
│ ├── Logger/ # 统一日志
|
||||
│ └── Foundation+/ # 通用扩展
|
||||
├── Vendor/ # 闭源 SDK(.framework / .a)
|
||||
│ ├── WechatSDK.framework # 启用
|
||||
│ ├── AMapLocationKit.framework # 启用
|
||||
│ ├── JAnalytics.framework # 启用
|
||||
│ └── libopencore-amr*.a # 启用
|
||||
│ # 暂不集成(对应代码模块用 Noop 占位):
|
||||
│ # - JAnalytics.framework # 启用用户统计时再放入
|
||||
│ # - XianliaoSDK.framework # 启用闲聊分享时再放入
|
||||
│ # - AgoraRtcKit.framework # 启用视频房间时再放入(或改用 SPM)
|
||||
├── Resources/
|
||||
@@ -191,7 +191,7 @@ Daoqi/
|
||||
| `LocationKit` | `LocationService` | AMapKit Wrapper |
|
||||
| `DeviceKit` | `DeviceInfo`, `BatteryMonitor`, `NetworkMonitor`, `Vibrator`, `Pasteboard` | Foundation+ |
|
||||
| `VideoRoomKit` | `VideoRoom`(协议) → `NoopVideoRoom` 当前启用 / `AgoraVideoRoom` 留蓝图 | (Agora SDK 暂未引入) |
|
||||
| `AnalyticsKit` | `Analytics`(协议) → `SentryCrashReporter` / `JAnalytics` | SDK Wrappers |
|
||||
| `AnalyticsKit` | `CrashReporter`(协议) → `SentryCrashReporter` 启用 / `Tracker`(协议) → `NoopAnalytics` 当前启用 / `JAnalyticsTracker` 留蓝图 | SDK Wrappers |
|
||||
|
||||
---
|
||||
|
||||
@@ -548,10 +548,9 @@ SceneDelegate.scene(_:willConnectTo:options:) T=0
|
||||
│
|
||||
├─► (并行) SDK 注册 T=0
|
||||
│ • WeChat ~10 ms
|
||||
│ • JAnalytics ~10 ms
|
||||
│ • AMap (privacy + key) ~15 ms
|
||||
│ • crashReporter.start() ~20 ms(Sentry 默认启用)
|
||||
│ (Xianliao / Agora / Bugly 当前未集成,见 §14.2)
|
||||
│ (JAnalytics 极光 / Xianliao 闲聊 / Agora 声网 / Bugly 当前未集成,见 §14.2)
|
||||
│ 并发 Task,await 全部完成
|
||||
│
|
||||
├─► Window 创建 + LobbyViewController push T=50ms
|
||||
@@ -618,8 +617,8 @@ final class Bootstrapper {
|
||||
private func registerSDKs() async {
|
||||
await withTaskGroup(of: Void.self) { group in
|
||||
group.addTask { WeChatSDK.registerFull(appId: AppIDs.weChat) } // 含 contentFlag
|
||||
// XianliaoSDK 暂不集成(§14.2);Agora 同样,懒加载也无需启动注册
|
||||
group.addTask { AnalyticsKit.start() }
|
||||
// JAnalytics(极光) / XianliaoSDK(闲聊) / Agora(声网) 暂不集成(§14.2)
|
||||
// — 对应模块用 Noop 占位,首版不参与启动注册
|
||||
group.addTask { AMapWrapper.configure() }
|
||||
group.addTask { crashReporter.start() } // SentryCrashReporter by default; Noop if SENTRY_ENABLED=0
|
||||
}
|
||||
@@ -2085,7 +2084,7 @@ done
|
||||
|
||||
1. **首选 SPM** —— Apple 官方,Xcode 原生集成,无第三方工具依赖,无衍生工程文件污染,新人 clone 即用。适用于:Sentry、ZIPFoundation、Agora 4.x、七牛 v8+ 等**已发布官方 Swift Package** 的库
|
||||
2. **CocoaPods 兜底** —— 用于"有 podspec 但暂无 SPM 包"的 SDK,主要是高德定位、部分 Agora 旧版兼容场景。Podfile 仅写必须的 Pod,不引入大规模 transitive 依赖
|
||||
3. **Vendor 手动** —— `Vendor/` 目录直接放闭源 `.framework` / `.a`,xcconfig 配置 link flag。适用于:微信 OpenSDK、QQ OpenSDK、闲聊 SDK、JAnalytics、opencore-amr 等**官方不提供 SPM / Pod 的私有 framework**
|
||||
3. **Vendor 手动** —— `Vendor/` 目录直接放闭源 `.framework` / `.a`,xcconfig 配置 link flag。适用于:微信 OpenSDK、QQ OpenSDK、闲聊 SDK(暂不集成)、JAnalytics(暂不集成)、opencore-amr 等**官方不提供 SPM / Pod 的私有 framework**
|
||||
|
||||
#### 为什么不选纯 SPM
|
||||
微信 / QQ / 闲聊 / JAnalytics 等闭源 SDK 官方至今(2026)未提供 Swift Package,强行纯 SPM 化需要自己包一层私有 Package,维护成本反而上升。
|
||||
@@ -2109,7 +2108,7 @@ Sentry / ZIPFoundation 等纯 Swift 包走 Pods 需绕一道 podspec,失去 SPM
|
||||
| opencore-amr | 静态 `.a`(直接接入 — H5 端通过此库收发的 AMR 音频是契约边界) | 2014 版本 | ✅ 启用 |
|
||||
| ZIPFoundation | **SPM** | latest | ✅ 启用 |
|
||||
| Sentry-Cocoa | **SPM**(默认 ON,编译开关 `SENTRY_ENABLED` 提供逃生口) | latest | ✅ 启用,启动并发注册 |
|
||||
| JAnalytics | Vendor | 现网版本 | ✅ 启用,启动注册 |
|
||||
| **JAnalytics(极光)** | — | — | ⏸️ **暂不集成**(`AnalyticsKit.tracker = NoopAnalytics`)。新外壳首版不接用户统计 — 现网 msext 的极光后端运维状态不可知,且 Sentry 的 breadcrumb / transaction 可兜一部分行为指标。启用时:① Vendor `.framework` 放入 ② `NoopAnalytics` 换为 `JAnalyticsTracker` ③ Info.plist 加 AppKey ④ Bootstrapper 注册 |
|
||||
| **Bugly** | — | — | ⏸️ **不集成**。Sentry 已覆盖崩溃 / 性能监控,无需 Bugly。未来若有强需求(如旧外壳数据迁移),再单独评估 |
|
||||
|
||||
> **微信 OAuth 架构决策**:新项目走**后台中转** —— 客户端把 `code` 发给后台 `/wechat/login` 接口,由后台完成 `access_token` + `userinfo` 拉取,再回传 7 个字段给客户端,客户端最终 `callHandler:@"sharelogin"` 给 H5。
|
||||
|
||||
Reference in New Issue
Block a user