# 55 · 遥测与分析系统（Analytics & Telemetry System）

> **命名空间** `BaseGames.Analytics`  
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)  
> **依赖** `BaseGames.Core.Events` · `BaseGames.World`（SaveManager）· `BaseGames.Player`  
> **外部 SDK** Unity Analytics（可选）/ 自建轻量后端（推荐，见 §3）  
> **关联** 46_PlatformIntegration · 56_CrashRecoverySystem · 29_DifficultyModesGuide

---

## 目录

1. [系统设计原则](#1-系统设计原则)
2. [隐私合规基础](#2-隐私合规基础)
3. [数据收集架构选型](#3-数据收集架构选型)
4. [事件目录（Event Catalog）](#4-事件目录event-catalog)
5. [AnalyticsManager](#5-analyticsmanager)
6. [热力图数据收集](#6-热力图数据收集)
7. [难度调整数据分析](#7-难度调整数据分析)
8. [留存分析关键节点](#8-留存分析关键节点)
9. [数据看板设计](#9-数据看板设计)
10. [本地 Session 日志（离线分析）](#10-本地-session-日志离线分析)
11. [编辑器友好设计](#11-编辑器友好设计)

---

## 1. 系统设计原则

| 原则 | 含义 |
|------|------|
| **最小化数据** | 只收集决策所需的数据，不收集任何个人身份信息 |
| **玩家知情同意** | 游戏首次启动弹出遥测许可弹窗，玩家可选择退出 |
| **本地优先** | 即使玩家拒绝联网数据上传，本地 Session 日志仍然工作（供开发者内部分析）|
| **不影响游戏逻辑** | 遥测调用异步，失败静默忽略，永不阻塞主线程 |
| **可关闭** | `IAnalyticsBackend.IsEnabled` 可运行时切换，不需要重启 |

---

## 2. 隐私合规基础

### 2.1 必须遵守的法规

| 法规 | 适用地区 | 关键要求 |
|------|---------|---------|
| **GDPR** | 欧盟/欧洲 | 明确同意、可撤回同意、数据删除权 |
| **CCPA** | 美国加州 | 不出售个人信息、知情权 |
| **COPPA** | 美国（13岁以下）| 不向儿童收集数据，游戏无年龄门控时必须完全匿名化 |
| **PIPA/PIPL** | 日本/中国 | 目的明确、最小化原则 |

### 2.2 数据匿名化规则

```csharp
namespace BaseGames.Analytics
{
    public static class AnonymizationUtil
    {
        // 生成永久匿名 ID（不与任何账号绑定，存储在本地 PlayerPrefs）
        public static string GetOrCreateAnonymousId()
        {
            const string key = "analytics_anon_id";
            if (!PlayerPrefs.HasKey(key))
                PlayerPrefs.SetString(key, Guid.NewGuid().ToString("N"));
            return PlayerPrefs.GetString(key);
        }

        // 数据上传时永远不包含以下字段：
        // - 玩家姓名、Steam ID、Switch 账户 ID
        // - IP 地址（由后端在接收层截断）
        // - 存档文件内容
        // - 购买记录
    }
}
```

### 2.3 首次启动同意弹窗

集成到 `27_FirstLaunchSequence`（见 10_UISystem.md §27）。弹窗文案：

```
帮助我们改善游戏体验

我们收集匿名游戏数据（如死亡位置、关卡完成时间），
帮助改善难度平衡和游戏体验。

数据不包含任何个人信息，不会被出售给第三方。
你可以随时在设置菜单中关闭数据分享。

[  同意分享数据  ]     [  不，谢谢  ]
```

玩家选择保存到 `PlayerPrefs["analytics_consent"]`，`AnalyticsManager.IsEnabled` 据此决定是否上传。

---

## 3. 数据收集架构选型

### 推荐方案：自建轻量后端 + 本地 JSON 日志双轨

```
游戏客户端
  │
  ├── AnalyticsManager ──→ 本地 Session Log（JSON，始终记录）
  │                             │
  │                             └──→ [游戏结束时] 压缩打包 .log.gz
  │
  └── (若玩家同意) ──→ EventQueue（异步批量上传）
                             │
                             └──→ 自建 HTTP 后端（或 Unity Analytics）
                                    │
                                    └──→ 数据库（ClickHouse / BigQuery）
                                           │
                                           └──→ Grafana 看板
```

**为什么不直接用 Unity Analytics**：
- Unity Analytics 需要账号绑定，GDPR 合规难度较高
- 自建后端数据归我们所有，查询灵活性更高
- 独立游戏规模下，Hetzner VPS + ClickHouse 月费约 $20，足够

**备选方案（快速接入）**：GameAnalytics（免费层）——若团队不想维护后端，这是最快的合规方案。

---

## 4. 事件目录（Event Catalog）

### 4.1 必须收集（P0）

| 事件名 | 触发时机 | 关键字段 |
|--------|---------|---------|
| `session_start` | 游戏进入主菜单 | `anonymousId`, `platform`, `gameVersion`, `locale` |
| `session_end` | 游戏退出 | `sessionDuration`, `sceneOnExit` |
| `player_death` | 玩家死亡 | `sceneAddress`, `position`, `causeOfDeath`, `deathCount`, `playerHP`, `sessionTime` |
| `boss_attempt_start` | 进入 Boss 房间 | `bossId`, `playerLevel`, `equippedCharms` |
| `boss_defeated` | Boss 击败 | `bossId`, `attemptCount`, `timeElapsed`, `playerHP` |
| `ability_unlocked` | 玩家获得能力 | `abilityId`, `sessionTime`, `regionId` |
| `scene_entered` | 玩家进入新房间 | `sceneAddress`, `firstVisit`, `sessionTime` |
| `game_completed` | 通关结局触发 | `endingType`, `completionPercent`, `totalPlayTime` |
| `softlock_detected` | SoftlockDetector 触发 | `sceneAddress`, `stuckDuration`, `playerAbilities` |

### 4.2 推荐收集（P1）

| 事件名 | 触发时机 | 关键字段 |
|--------|---------|---------|
| `lore_collected` | Lore 道具拾取 | `loreId`, `regionId` |
| `shop_purchase` | 商店购买 | `itemId`, `price`, `playerGeo`, `regionId` |
| `challenge_completed` | 挑战房间完成 | `challengeId`, `grade`, `attemptCount` |
| `sequence_break_suspected` | 玩家绕过 AbilityGate | `gateId`, `regionId`, `playerAbilities` |
| `settings_changed` | 设置项改变 | `settingKey`, `newValue`（不记录敏感设置）|
| `difficulty_changed` | 难度模式切换 | `from`, `to`, `sessionTime` |
| `npc_dialogue_viewed` | NPC 对话播放完成 | `npcId`, `dialogueVersionLabel` |

### 4.3 不收集的数据（显式排除）

```csharp
// 禁止出现在事件 payload 中的字段
public static readonly HashSet<string> ForbiddenFields = new()
{
    "steamId", "switchUserId", "playerName", "saveFilePath",
    "localIpAddress", "macAddress", "hardwareDeviceId"
};
```

---

## 5. AnalyticsManager

```csharp
namespace BaseGames.Analytics
{
    public class AnalyticsManager : MonoBehaviour
    {
        [SerializeField] AnalyticsConfigSO _config;

        public bool IsEnabled =>
            PlayerPrefs.GetInt("analytics_consent", 0) == 1 && _config.enableAnalytics;

        // 单例（Persistent Scene 中唯一实例）
        public static AnalyticsManager Instance { get; private set; }

        // 本地日志（不依赖网络，始终运行）
        private SessionLogger _localLogger;

        // 在线上传队列（仅 IsEnabled 时激活）
        private EventQueue   _uploadQueue;

        void Awake()
        {
            if (Instance != null) { Destroy(gameObject); return; }
            Instance = this;
            _localLogger = new SessionLogger();
            if (IsEnabled)
                _uploadQueue = new EventQueue(_config.endpointUrl);
        }

        /// <summary>
        /// 记录分析事件（线程安全，异步上传，不阻塞调用方）
        /// </summary>
        public void Track(string eventName, Dictionary<string, object> properties = null)
        {
            if (Application.isEditor && !_config.trackInEditor) return;

            var payload = BuildPayload(eventName, properties);
            _localLogger.Log(payload);          // 始终写本地
            if (IsEnabled)
                _uploadQueue.Enqueue(payload);  // 异步上传
        }

        private AnalyticsEvent BuildPayload(string name, Dictionary<string, object> props)
        {
            return new AnalyticsEvent
            {
                EventName    = name,
                AnonymousId  = AnonymizationUtil.GetOrCreateAnonymousId(),
                Timestamp    = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
                GameVersion  = Application.version,
                Platform     = Application.platform.ToString(),
                Properties   = props ?? new Dictionary<string, object>()
            };
        }
    }
}
```

### 调用示例（在各系统中集成）

```csharp
// 玩家死亡时（在 PlayerController 的死亡流程中）
AnalyticsManager.Instance?.Track("player_death", new Dictionary<string, object>
{
    ["sceneAddress"]  = SceneManager.GetActiveScene().name,
    ["position"]      = $"{_transform.position.x:F1},{_transform.position.y:F1}",
    ["causeOfDeath"]  = _lastDamageSource,
    ["deathCount"]    = _saveData.TotalDeaths,
    ["sessionTime"]   = Time.realtimeSinceStartup
});
```

---

## 6. 热力图数据收集

### 6.1 死亡热力图

`player_death` 事件的 `position` 字段在后端聚合，生成各房间的死亡密度图。

**使用流程**：
1. 后端按 `sceneAddress` 分组，统计 `position` 分布
2. 将坐标映射到房间尺寸，生成热力图 PNG
3. 叠加到关卡设计截图，QA 检视高死亡区域

### 6.2 路线追踪

`scene_entered` 事件的序列，可还原玩家路线：

```
session_A: Forest_Main → Forest_SecretCave → Forest_Main → Cave_Entrance → ...
```

用于发现：
- 玩家绕路频率（某房间被经过 N 次但不进入）
- 迷失区域（某条走廊被多次往返）

---

## 7. 难度调整数据分析

关键指标与决策阈值：

| 指标 | 计算方式 | 调整触发阈值 |
|------|---------|------------|
| Boss 平均尝试次数 | `boss_defeated.attemptCount` 均值 | > 15次 = 考虑降低 Boss 血量 |
| 区域卡关率 | 进入该区域后 > 3 天无进度的玩家% | > 30% = 关卡设计问题，检查 |
| 死亡集中度 | 某房间死亡数 / 该房间访问数 | > 60% = 该房间可能过难 |
| 首次10分钟流失 | `session_end`（sessionDuration < 600s）% | > 20% = 新手引导失效 |
| 完成度分布 | `game_completed.completionPercent` 直方图 | 理想：正态分布 60~80% |

---

## 8. 留存分析关键节点

| 关键节点 | 分析目标 |
|---------|---------|
| **第1分钟**（游戏是否好玩）| 玩家是否跳过开始动画后立即退出 |
| **第10分钟**（新手引导） | 玩家是否完成了基础操作教程 |
| **第1次死亡** | 玩家是否在第一次死亡后继续游戏（留存核心） |
| **Forest Boss 前**（约30分钟）| 流失率峰值区域 |
| **进入 Cave**（第一个大进程节点）| 流失率是否显著下降（完成 Forest = 投入度高）|
| **2小时标记** | Day 1 留存率核心指标 |
| **通关**（目标约20~30小时）| 硬核玩家比例 |

---

## 9. 数据看板设计

### 9.1 开发阶段看板（Grafana / Google Sheets）

| 面板 | 数据来源 |
|------|---------|
| 日活跃游玩时长 | `session_end.sessionDuration` 均值 |
| Boss 击败率（各 Boss）| `boss_defeated` / `boss_attempt_start` 比率 |
| 死亡热力图（房间级别）| `player_death.position` 聚合 |
| 前10分钟流失漏斗 | session 时间段的玩家数量漏斗 |
| 能力获取时间线 | `ability_unlocked.sessionTime` 分布 |
| 难度模式分布 | `difficulty_changed` 统计 |

### 9.2 发行阶段看板（Steam 补充）

Steam 提供：
- 游玩时长中位数（不通过我们的遥测，Steam 直接提供）
- 成就解锁率（通过 Steam API 公开获取）
- 玩家评价情感分布

---

## 10. 本地 Session 日志（离线分析）

即使玩家拒绝联网上传，本地 Session 日志仍帮助 PlayTest 分析：

```
路径：{Application.persistentDataPath}/Analytics/session_YYYY-MM-DD_HH-mm.jsonl
格式：每行一个 JSON 事件（JSONL 格式，便于流式处理）
保留：最近 10 次 Session（自动轮转删除旧文件）
```

开发者可在 PlayTest 结束后：
```bash
# 提取所有死亡事件，按房间统计
cat session_*.jsonl | jq 'select(.event == "player_death") | .sceneAddress' | sort | uniq -c | sort -rn
```

---

## 11. 编辑器友好设计

- **AnalyticsConfigSO** Inspector：`trackInEditor` 开关（PlayMode 中是否发送事件到本地日志）
- **Analytics Debug Overlay**：在 Debug 模式下，屏幕右上角显示本 Session 已记录的事件计数
- **Event Inspector 工具**：EditorWindow 读取最新 session JSONL 文件，以表格展示所有事件（用于 PlayTest 后快速检视）
- **隐私审计检查器**：CI 中运行静态分析，检查所有 `Track()` 调用的 payload，确保不包含 `ForbiddenFields` 中的字段

---

*本文档版本 1.0 · 2026-04 · 关联 46_PlatformIntegration / 56_CrashRecoverySystem / 29_DifficultyModesGuide*