@virjay/playscope-cocos 0.0.0-stage → 0.2.0

package/doc//344/275/277/347/224/250/346/214/207/345/215/227/README.md

@@ -0,0 +1,585 @@
+# PlayScope SDK 接入与使用指南
+
+> 本文档面向**游戏客户端开发者**与**负责对接 SDK 的 AI Agent**。
+> 语言精简、逻辑清晰，提供从零接入 PlayScope SDK（`@virjay/playscope-cocos`）的完整流程、接口定义、打点规范与最佳实践。
+
+本指南对应 **@virjay/playscope-cocos 0.2.0**。旧 @playscope/cocos 0.1.1 tarball 不包含新增能力；升级时更换导入路径并保留旧存储键。
+精确接口见 [全部公开类型](参考资料/public-api.d.ts) 和 [导出索引](参考资料/exports.json)，事件细节见 [80 项产品字典](参考资料/服务端/product-events.json)、[产品索引](参考资料/服务端/产品事件索引.md) 与 [通用事件信封](参考资料/服务端/game-event.json)。
+配置、广告和对局的可复制实现见 [示例目录](示例/README.md)。现有项目须核对自身冻结契约，不能仅凭本地类型通过推定服务端接收。
+
+---
+
+## 目录
+
+1. [SDK 简介与核心特性](#1-sdk-简介与核心特性)
+2. [5分钟快速上手 (Cocos Creator)](#2-5分钟快速上手-cocos-creator)
+3. [AI 对接标准流程 (SOP)](#3-ai-对接标准流程-sop)
+4. [核心 API 与接口参考](#4-核心-api-与接口参考)
+5. [游戏事件与对局归因 (Run 机制)](#5-游戏事件与对局归因-run-机制)
+6. [广告全链路打点与 LevelPlay 桥接](#6-广告全链路打点与-levelplay-桥接)
+7. [远程配置与实验分流](#7-远程配置与实验分流)
+8. [服务端接口协议 (底层参考)](#8-服务端接口协议-底层参考)
+9. [排错指南与验收清单](#9-排错指南与验收清单)
+10. [附录：老项目迁移与 BlockDrop 约定](#10-附录老项目迁移与-blockdrop-约定)
+
+---
+
+## 1. SDK 简介与核心特性
+
+PlayScope SDK 是专为 Cocos Creator 及 HTML5/TypeScript 游戏设计的高性能、离线优先的数据分析与远程配置 SDK。
+
+### 核心机制
+- **离线优先 (Local-First Outbox)**：事件调用 `track()` 后首先写入本地存储（如 `sys.localStorage`），通过落盘检查的事实可在离线／重启后重放；存储故障时仅在内存的事实仍可能丢失，使用 trackWithResult 检查 durability。
+- **自动会话与身份维护**：持久化安装唯一 ID（`installId`）与全局自增事件序号（`sequence`），运行时生成会话 ID（`sessionId`），并在首次启动时自动上报 `user_first_open`。
+- **分批上传与服务端确认 (ACK)**：SDK 自动分批上报，仅当服务端持久化成功并返回 ACK 后才从本地队列移除；网络失败或限流时自动指数退避重试。
+- **动态 Token 鉴权**：SDK 自动通过客户端凭证换取短期 Access Token 并自动静默刷新，宿主无需维护 Token 状态。
+- **单例保护**：同一存储 Key 下仅允许一个活跃实例，防止多实例并发读写导致数据损坏。
+
+---
+
+## 2. 5分钟快速上手 (Cocos Creator)
+
+### 2.1 安装依赖
+
+从 npm 安装并固定正式版本：
+
+```bash
+npm install @virjay/playscope-cocos@0.2.0 --save-exact
+```
+
+提交 package.json 和 package-lock.json。也可使用同版本 tarball，不覆盖旧包。
+
+### 2.2 创建常驻单例组件
+
+在 Cocos Creator 项目中新建脚本 `GameAnalytics.ts`，挂载在**全局常驻节点**（跨场景不销毁）：
+
+```typescript
+import { _decorator, Component, sys, game, Game } from 'cc';
+import { init, type CocosPlayScope, type TrackContext } from '@virjay/playscope-cocos';
+
+const { ccclass } = _decorator;
+
+@ccclass('GameAnalytics')
+export class GameAnalytics extends Component {
+  public static instance: GameAnalytics | null = null;
+  private telemetry: CocosPlayScope | null = null;
+
+  onLoad(): void {
+    if (GameAnalytics.instance) {
+      this.node.destroy();
+      return;
+    }
+    GameAnalytics.instance = this;
+    game.addPersistRootNode(this.node); // 跨场景常驻
+
+    this.setCollectionAllowed(false); // 接宿主真实授权结果，默认不采集。
+  }
+
+  public setCollectionAllowed(allowed: boolean): void {
+    const previous = this.telemetry;
+    this.telemetry = null;
+    previous?.dispose();
+    this.telemetry = init({
+      baseUrl: 'https://analytics.example.com', // PlayScope 服务端根地址 (末尾不带斜杠，不拼 /v1)
+      projectId: 'YOUR_PROJECT_UUID',           // 后台项目 UUID
+      projectKey: 'YOUR_CLIENT_KEY',            // 客户端专用的 Project Key (严禁使用管理员 Token)
+      collectionEnabled: allowed,               // 来自宿主真实许可
+      client: {
+        appVersion: '1.0.0',
+        buildNumber: '100',
+        platform: sys.isNative ? (sys.os === sys.OS.ANDROID ? 'android' : 'ios') : 'web',
+        locale: sys.language || 'zh-CN',
+        timezoneOffsetMinutes: -new Date().getTimezoneOffset(),
+      },
+    }, {
+      storage: sys.localStorage,
+      lifecycle: {
+        onHide: (callback) => {
+          game.on(Game.EVENT_HIDE, callback);
+          return () => game.off(Game.EVENT_HIDE, callback);
+        },
+        onShow: (callback) => {
+          game.on(Game.EVENT_SHOW, callback);
+          return () => game.off(Game.EVENT_SHOW, callback);
+        },
+      },
+    });
+
+    // app_launch／session_start 在真实业务入口调用，不随每次授权切换重复发送。
+  }
+
+  update(dt: number): void {
+    // 驱动 SDK 内部定时冲刷（约每 5 秒自动上报一次离线队列）
+    this.telemetry?.update(dt);
+  }
+
+  onDestroy(): void {
+    this.telemetry?.dispose();
+    this.telemetry = null;
+    if (GameAnalytics.instance === this) {
+      GameAnalytics.instance = null;
+    }
+  }
+
+  /**
+   * 通用打点接口
+   * @param name 事件名称 (如 game_start, level_win)
+   * @param properties 事件自定义属性
+   * @param context 可选的上下文 (如携带对局 run 信息)
+   */
+  public track(name: string, properties: Record<string, unknown> = {}, context?: TrackContext): boolean {
+    return this.telemetry?.track(name, properties, context) ?? false;
+  }
+
+  /** 获取底层 SDK 实例 (用于广告转发等进阶功能) */
+  public getClient(): CocosPlayScope | null {
+    return this.telemetry;
+  }
+}
+```
+
+### 2.3 业务打点调用
+
+在任意业务脚本中直接调用：
+
+```typescript
+// 普通页面事件不需要 run；关卡终局必须带完整 run，见第 5 节。
+GameAnalytics.instance?.track('screen_view', { screen: 'level_selection' });
+```
+
+---
+
+## 3. AI 对接标准流程 (SOP)
+
+如果你是负责接入 PlayScope 的 AI 编程助手，请严格按照以下 7 个步骤推进对接：
+
+```mermaid
+flowchart TD
+    S1["1. 确认项目配置与凭据 (baseUrl, projectId, projectKey)"] --> S2["2. 安装依赖并创建全局单例 Owner"]
+    S2 --> S3["3. 接入隐私授权 (collectionEnabled) 与生命周期"]
+    S3 --> S4["4. 接入基础生命周期打点 (launch, session)"]
+    S4 --> S5["5. 接入对局归因 (run 对象与冻结规则)"]
+    S5 --> S6["6. 接入广告打点 (展示 impression, 点击, 收入)"]
+    S6 --> S7["7. 运行自测与验收 (落盘检查, 断网恢复, 抓包核对)"]
+```
+
+### 步骤清单与要点
+
+| 步骤 | 任务内容 | 核心要求与禁止项 |
+| :--- | :--- | :--- |
+| **Step 1** | **凭据与环境准备** | 从服务端或配置中获取 `baseUrl`、`projectId`、`projectKey`。**绝对禁止**将管理员 Token（Admin Token）写入客户端代码。 |
+| **Step 2** | **建立唯一单例** | 在游戏现有框架（如 `GameRoot` 或常驻节点）中创建唯一实例。**禁止**在多个场景分别创建 `CocosPlayScope`。 |
+| **Step 3** | **隐私与授权管理** | 用户未同意隐私协议前，`collectionEnabled` 必须为 `false`（不写存储、不发请求）。同意后重建实例为 `true`。 |
+| **Step 4** | **基础事件打点** | 自动生成的首次事件由 SDK 处理；游戏内仅需在真实时机触发 `app_launch` 和 `session_start`。切勿在 `update` 帧循环中重复触发。 |
+| **Step 5** | **对局与归因绑定** | 开局时生成 `runId`（UUID），构建 `run` 对象（含关卡、配置版本）。局内所有事件（含局内广告）必须携带该 `run`。**局内配置必须冻结**，中途下发的新配置仅对下一局生效。 |
+| **Step 6** | **广告链路打点** | 区分 `ad_show` 与 `ad_impression`（后台统计展示数以 `ad_impression` 为准）。收入使用 `forwardLevelPlayRevenue` 自动转发。Banner 刷新每次必须生成新 `exposureId`。 |
+| **Step 7** | **验证与交付** | 检查控制台无初始化报错；断网产生事件并恢复网络后观察事件是否补发；确认服务端事件去重与入库正常。 |
+
+---
+
+## 4. 核心 API 与接口参考
+
+### 4.1 初始化入口：`init(options, runtime)`
+
+```typescript
+import { init } from '@virjay/playscope-cocos';
+
+const sdk = init(options, runtime);
+```
+
+#### `options: CocosOptions` 参数表
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :--- | :--- |
+| `baseUrl` | `string` | **是** | - | 服务端根地址，如 `https://analytics.example.com`（末尾不加斜杠，不拼 `/v1/...`） |
+| `projectId` | `string` | **是** | - | PlayScope 项目 UUID |
+| `projectKey` | `string` | **是** | - | 客户端专用鉴权 Key |
+| `collectionEnabled` | `boolean`| **是** | - | 隐私数据采集开关。`false` 时不读写存储、不发请求 |
+| `client` | `ClientContext` | **是** | - | 客户端环境元信息（版本号、平台、语言、时区等） |
+| `storageKey` | `string` | 否 | `playscope:<projectId>` | 本地持久化 Key（老项目升级时需保持历史 Key 一致） |
+| `queuePolicy` | `QueuePolicy` | 否 | 见下文 | 本地队列容量限制（默认最大 2000 条，4 MiB） |
+| `restoreCache` | `(saved: unknown) => unknown` | 否 | - | 读取本地远程配置缓存时的校验回调 |
+| `resolveConfiguration` | `(ctx: ConfigurationContext) => Promise<number>` | 否 | - | 远程配置拉取与应用回调，返回下次刷新秒数 |
+
+#### `runtime: CocosRuntime` 参数表
+
+| 字段 | 类型 | 必填 | 说明 |
+| :--- | :--- | :---: | :--- |
+| `storage` | `LocalStorageLike` | **是** | 传入 `sys.localStorage` 或具备 `getItem`/`setItem`/`removeItem` 的存储对象 |
+| `lifecycle` | `CocosLifecycle` | 否 | 前后台监听器，包含 `onHide` 与 `onShow` 方法 |
+| `transport` | `JsonTransport` | 否 | HTTP 请求传输器，默认内部使用 XHR（超时 10 秒） |
+| `now` | `() => number` | 否 | 时间戳生成器，默认使用 `Date.now` |
+
+---
+
+### 4.2 `CocosPlayScope` 常用实例方法
+
+```typescript
+class CocosPlayScope {
+  /** 当前设备的唯一安装 ID（只读，采集关闭时为 null） */
+  readonly installId: string | null;
+
+  /** 上报事件。入队成功返回 true（不代表已送达服务器） */
+  track(name: string, properties?: Record<string, unknown>, context?: TrackContext): boolean;
+
+  /** 上报结构化广告收入（底层会自动校验、去重并转化为标准事件） */
+  trackAdRevenue(fact: AdRevenueFact, context?: TrackContext): boolean;
+
+  /** 开启新会话（生成新的 sessionId，后续事件将使用新会话 ID） */
+  newSession(): void;
+
+  /** 驱动定时器（请在 Cocos 的 update(dt) 中调用，dt 单位为秒） */
+  update(dt: number): void;
+
+  /** 异步执行一轮交付（最多10批），不保证一次清空或配置已应用 */
+  flush(): Promise<void>;
+
+  /** 手动触发远程配置拉取（遵守到期时间与失败退避） */
+  refreshConfiguration(): Promise<ConfigurationResult>;
+
+  /** 释放实例并解绑生命周期监听（本地已落盘队列依然安全保留） */
+  dispose(): void;
+}
+```
+
+---
+
+### 4.3 核心数据结构
+
+#### 客户端环境信息 `ClientContext`
+```typescript
+interface ClientContext {
+  appVersion: string;             // 如 "1.0.0"
+  buildNumber: string;            // 如 "101"
+  platform: 'android' | 'ios' | 'web' | 'wechat';
+  locale: string;                 // 如 "zh-CN"
+  timezoneOffsetMinutes: number;  // 本地时区相对于 UTC 偏移分钟数，如 480 表示东八区
+  environment?: 'production' | 'test'; // scope默认production，服务端仍用独立项目隔离
+  device?: { type: 'android_id'; id: string }; // 仅Android合法可用值，SDK不主动采集
+}
+```
+
+#### 事件打点上下文 `TrackContext`
+```typescript
+interface TrackContext {
+  run?: unknown;             // 绑定的对局 run 对象（详见下文归因机制）
+  occurredAt?: string;       // 事件真实发生时间（ISO 8601 UTC 字符串，默认当前时间）
+  deduplicationKey?: string; // 持久去重最近2000个键；SDK重放保持原eventId
+  transform?: (event: EventFact) => EventFact; // 仅新事实入队调用，旧队列不重编码
+}
+```
+
+---
+
+## 5. 游戏事件与对局归因 (Run 机制)
+
+### 5.1 什么是 `run` 对象？
+
+在游戏分析中，单纯记录“玩家看了广告”或“玩家死了一次”价值有限；必须知道这个行为**发生在哪个关卡、哪次对局中，以及当期生效的是哪个配置版本**。
+
+`run` 对象是 PlayScope 用于归因对局数据的标准结构：
+
+```typescript
+interface GameRun {
+  runId: string;   // 每次开局生成一个全新的 UUID（可通过 telemetryUuid() 获取）
+  mode: string;    // 玩法模式，如 "endless"、"level_challenge"
+  level?: string | number | null; // 仅hasLevels项目可用，其他项目省略或null
+  config: {
+    configRevision: string; // 当前使用的配置版本号，如 "rev_20261112"
+    source: 'bundled' | 'cache' | 'remote'; // 配置来源：包体内置、本地缓存、远端下发
+    assignmentId: string | null;            // remote/cache必须有服务端分配ID；bundled为null
+    experimentId: string | null;            // 实验 ID
+    variantId: string | null;               // 实验变体 ID
+  };
+}
+```
+
+### 5.2 局内冻结原则 (Crucial!)
+
+> **黄金法则**：开局（`game_start`）时创建的 `run` 对象在整个对局过程中**绝对不可更改**。
+> 局内发生的所有操作（暂停、恢复、吃金币、看复活视频、终局 `run_ended`）均必须传递此 `run` 引用。
+> 如果游戏在局中拉取到了新的远程配置，**新配置必须暂存，只对下一局生效**，严禁篡改当前局的归因！
+
+#### 对局打点示例
+
+```typescript
+import { telemetryUuid } from '@virjay/playscope-cocos';
+
+class GamePlayManager {
+  private currentRun: GameRun | null = null;
+
+  // 开始新对局
+  public startNewGame(mode: string, level: string) {
+    this.currentRun = {
+      runId: telemetryUuid(), // 生成局唯一 UUID
+      mode,
+      level,
+      config: ConfigManager.getActiveAttribution(), // 获取当前冻结的配置归因
+    };
+
+    GameAnalytics.instance?.track('game_start', {}, { run: this.currentRun });
+  }
+
+  // 局内复活
+  public onPlayerRevive() {
+    GameAnalytics.instance?.track('revive_success', { failureIndex: 1 }, { run: this.currentRun });
+  }
+
+  // 终局结算
+  public onGameOver(finalScore: number) {
+    GameAnalytics.instance?.track('run_ended', {
+      outcome: 'lost', summary: { score: finalScore },
+    }, { run: this.currentRun });
+
+    // 终局后销毁当前局归因
+    this.currentRun = null;
+  }
+}
+```
+
+---
+
+## 6. 广告全链路打点与 LevelPlay 桥接
+
+PlayScope 提供了针对聚合广告（以 LevelPlay 为代表）的无缝集成能力。
+
+### 6.1 广告完整生命周期链条
+
+完整的广告行为包含以下事件：
+
+```mermaid
+sequenceDiagram
+    participant Game as 游戏业务层
+    participant AdSDK as 广告聚合SDK (如 LevelPlay)
+    participant PS as PlayScope
+
+    Game->>AdSDK: 1. 请求广告 (loadAd)
+    Game->>PS: track('ad_request', { placement, ad_format, ad_request_id })
+
+    alt 加载成功
+        AdSDK-->>Game: onAdLoaded 回调
+        Game->>PS: track('ad_load_success', { cache_hit })
+    else 加载失败
+        AdSDK-->>Game: onAdLoadFailed 回调
+        Game->>PS: track('ad_load_fail', { error_code })
+    end
+
+    Game->>AdSDK: 2. 展示广告 (showAd)
+    AdSDK-->>Game: onAdDisplayed 回调 (曝光)
+    Game->>PS: track('ad_show', { ... })
+    Game->>PS: track('ad_impression', { ... })  << 计费展示核心事件！
+
+    opt 用户点击
+        AdSDK-->>Game: onAdClicked 回调
+        Game->>PS: track('ad_click', { ... })
+    end
+
+    opt 激励视频奖励
+        AdSDK-->>Game: onAdRewarded 回调
+        Game->>Game: 根据游戏实际发奖和保存结果确定 outcome / persistence
+        Game->>PS: track('ad_rewarded_grant', { sdk_reward_received, reward_outcome, reward_persistence })
+    end
+
+    AdSDK-->>Game: 3. 收入回调 (ImpressionData)
+    Game->>PS: forwardLevelPlayRevenue(...)  << 自动上报 ad_revenue
+```
+
+---
+
+### 6.2 常见大坑与避坑指南
+
+> [!WARNING] 常见陷阱 1：只上报收入，漏报 `ad_impression`
+> **现象**：后台有收益金额，但展示次数为 0，导致 eCPM 计算异常。
+> **原因**：`forwardLevelPlayRevenue` 仅负责上报 `ad_revenue`（收入）。后台计算广告展示次数、人均展示与 eCPM 依赖独立的 `ad_impression` 事件！必须在广告曝光展示成功时同时触发 `ad_impression`。
+
+> [!WARNING] 常见陷阱 2：Banner 刷新时复用同一个 ID
+> **现象**：Banner 自动轮播多次，后台统计只计为 1 次曝光或收入去重失效。
+> **原因**：Banner 每次自动刷新展示，都是一次**独立的曝光**。必须为每次刷新生成一个**全新且独立**的 `exposureId`！
+
+> [!WARNING] 常见陷阱 3：迟到收入改绑新局
+> **现象**：玩家看完广告后已经结局或进入下一局，此时广告平台才回调收入，导致收入被错误统计到下一局。
+> **原因**：必须在广告展示时将 `exposureId`、`shownAt` 以及**当时那一局的 `run` 引用**暂存起来。当收入回调触发时，使用原始暂存的 `run` 进行上报，不可改用当前最新局。
+
+---
+
+### 6.3 推荐接入代码：LevelPlay 广告适配器
+
+PlayScope 提供了官方适配函数 `forwardLevelPlayRevenue`，直接对接 LevelPlay 回调：
+
+完整的 [LevelPlayTelemetry.ts](示例/LevelPlayTelemetry.ts) 提供请求、加载、展示、点击、关闭、奖励、收入和诊断的全部方法。
+原生层负责初始化、唯一auction／曝光绑定及早到收入缓冲；该类只接已绑定的规范化事实。
+每次banner刷新生成新exposureId，重复回调必须沿用同一个曝光对象；原局、展示时间、测试标记与配置归因均冻结。
+不要使用固定的假展示延迟或从当前局补造曝光归因。forwardLevelPlayRevenue只生成收入，recordDisplay另发ad_show和ad_impression。
+SDK奖励不等于游戏已发奖／落盘；没有明确25%／50%／75%或完播通知时，不从reward／关闭推导相应事件。
+当前完播率卡为rewarded ad_complete / ad_first_quartile，缺分母留空。测试／模拟／演示事实不计正式展示与收入。
+
+
+---
+
+## 7. 远程配置与实验分流
+
+如果你的项目需要使用 PlayScope 的云端参数配置（如关卡难度、功能开关、A/B 测试实验），可通过 `resolveConfiguration` 和 `restoreCache` 实现。
+
+### 7.1 核心工作流程
+
+1. **随包默认配置 (Bundled)**：包体内准备一份静态兜底配置，离线或首次启动直接可用。
+2. **本地缓存恢复 (`restoreCache`)**：SDK 初始化时读取持久化的上一份配置，校验有效后应用。
+3. **云端拉取更新 (`resolveConfiguration`)**：SDK 自动向服务端 `/config/resolve` 请求最新配置：
+   - 若返回 `delivery: "full"`：得到最新配置并保存缓存，等待下一局对局时应用生效。
+   - 若返回 `delivery: "not_modified"`：说明配置未变更，维持本地缓存配置。
+
+### 7.2 实现示例
+
+完整实现见 [QuestGarden.ts](示例/QuestGarden.ts) 的 readCache、restoreCache、resolveConfig、apply、beginQuest，项目契约见 [fixture](示例/project-fixture.json)。
+请求必须包含 apiVersion:1、installId、client、supportedSchemas:[1]、current（null或{revision,assignmentId}）。
+full响应须校验完整配置、configRevision与assignment；not_modified必须保留有效旧配置，并校验响应归因。
+先context.saveCache成功，再应用规则；错误抛回SDK以便独立退避，不能捕获所有失败后当成功返回。
+remote/cache归因必须有assignmentId，experimentId与variantId同空或同有效；bundled三者全null。
+刷新结果与事件交付独立，需要配置结果时await refreshConfiguration；它遵守到期时间，并非强制刷新。
+QuestGarden使用自定义quest_ad_income，不自动进入标准收入报表；需要标准看板的项目使用默认game-v1收入编码。
+
+
+---
+
+## 8. 服务端接口协议 (底层参考)
+
+> [!NOTE]
+> SDK 会全自动管理以下请求与鉴权，通常无需手动发起 HTTP 请求。本节供原理理解与抓包排查参考。
+
+所有接口前缀均为：`{baseUrl}/v1/projects/{projectId}`，请求与响应均为 `Content-Type: application/json`。
+
+### 8.1 客户端初始化与换票：`POST /client/bootstrap`
+- **用途**：客户端启动时使用项目客户端 Key 换取临时的安装 Token。
+- **请求头**：`X-Project-Key: {projectKey}`
+- **请求体**：
+  ```json
+  {
+    "apiVersion": 1,
+    "installId": "10000000-0000-4000-8000-000000000001",
+    "firstOpenedAt": "2026-11-12T00:00:00.000Z",
+    "client": {
+      "appVersion": "1.0.0",
+      "buildNumber": "100",
+      "platform": "android",
+      "locale": "zh-CN",
+      "timezoneOffsetMinutes": 480
+    }
+  }
+  ```
+- **成功响应**：返回 `accessToken`（Bearer Token，有效期通常为 24 小时）及 `serverTime`。
+
+### 8.2 批量事件上报：`POST /analytics/events`
+- **用途**：SDK 自动分批上报本地队列中积攒的事件。
+- **请求头**：`Authorization: Bearer {accessToken}`
+- **请求体**：
+  ```json
+  {
+    "apiVersion": 1,
+    "installId": "10000000-0000-4000-8000-000000000001",
+    "batchId": "30000000-0000-4000-8000-000000000001",
+    "sentAt": "2026-11-12T00:00:05.000Z",
+    "events": [
+      {
+        "eventVersion": 1,
+        "eventId": "40000000-0000-4000-8000-000000000001",
+        "name": "game_start",
+        "occurredAt": "2026-11-12T00:00:01.000Z",
+        "sessionId": "50000000-0000-4000-8000-000000000001",
+        "sequence": 1,
+        "client": {
+          "appVersion": "1",
+          "buildNumber": "1",
+          "platform": "android",
+          "locale": "zh-CN",
+          "timezoneOffsetMinutes": 480
+        },
+        "samplingProbability": 1,
+        "run": {
+          "runId": "20000000-0000-4000-8000-000000000001",
+          "mode": "classic",
+          "config": {
+            "configRevision": "bundled-v1",
+            "source": "bundled",
+            "assignmentId": null,
+            "experimentId": null,
+            "variantId": null
+          }
+        },
+        "properties": {}
+      }
+    ]
+  }
+  ```
+- **成功响应**：返回 `acceptedEventIds: ["40000..."]`。SDK只移除本批明确接受或permanent=true拒收项，其余原文重放。批次最多100条，服务端256KiB，SDK内部250KiB保守预算。
+
+### 8.3 远程配置获取：`POST /config/resolve`
+- **用途**：获取或更新远程游戏配置。
+- **请求头**：`Authorization: Bearer {accessToken}`
+- **请求体**：包含 `supportedSchemas` 与当前的 `current: { revision, assignmentId }`。
+- **响应**：若未修改返回 `delivery: "not_modified"`；若有更新返回 `delivery: "full"` 和最新配置对象。
+
+---
+
+## 9. 排错指南与验收清单
+
+### 9.1 常见状态码与处理方式
+
+| 状态 / 错误码 | 含义 | 排查与解决办法 |
+| :--- | :--- | :--- |
+| `duplicate_client` | 试图对同一个存储 Key 重复创建实例 | 检查是否在多个节点创建了组件。先调用旧实例的 `dispose()`，再创建新实例。 |
+| `collection_disabled` | 采集开关关闭 | 检查用户是否已同意隐私协议，未同意时 SDK 处于静默保护状态，属正常现象。 |
+| `queue_full` | 本地待发送队列已满 | 检查网络连接是否长期中断，或服务端是否返回 4xx/5xx 导致事件无法出队。 |
+| `duplicate` | 事件去重键已存在 | 同一 `deduplicationKey`（如同一笔广告收入）被重复触发，SDK 自动丢弃重复项，属正常防御。 |
+| `HTTP 401` | Token 过期或无效 | SDK 会自动重新触发 `/client/bootstrap` 获取新 Token，无需手动干预。 |
+| `HTTP 429 / 5xx` | 服务端限流或异常 | SDK 会自动进入退避状态（Backoff），并按指数退避算法择机重试。 |
+
+---
+
+### 9.2 对接验收核对清单 (Checklist)
+
+在完成接入后，请按照以下清单逐一核对验收：
+
+- [ ] **单例唯一性**：全局仅有一个 `CocosPlayScope` 实例，切场景不会销毁或重建第二份实例。
+- [ ] **凭据安全**：仅使用 `projectKey`，没有把管理员 Token 写入客户端。
+- [ ] **合规控制**：未同意隐私协议前 `collectionEnabled=false`，不产生任何本地写入与网络请求；取得实际授权后重建实例采集，已有身份与队列保留。
+- [ ] **生命周期事件**：首次启动有 `user_first_open`，冷启动有 `app_launch`，会话边界由宿主按实际前台／广告规则触发，不每次回调盲发。
+- [ ] **对局归因完整**：开局生成唯一 `runId`；中途事件均携带相同 `run`；对局内配置严格冻结。
+- [ ] **广告展示与收入配对**：
+  - 广告展示时有 `ad_impression`；
+  - 广告收入使用 `forwardLevelPlayRevenue` 成功上报 `ad_revenue`；
+  - Banner 自动刷新每次均生成新的 `exposureId`；
+  - 迟到收入正确关联原曝光时的 `run` 与 `exposureId`。
+- [ ] **离线可靠性**：开启飞行模式打点，杀进程重启，恢复网络后事件能完整补发至服务端，已落盘事实原ID／原文重放且服务端不重复计数；仅memory事件不承诺杀进程保留。
+
+---
+
+## 10. 附录：老项目迁移与 BlockDrop 约定
+
+### 10.1 存储 Key 与数据继承
+- SDK 默认存储 Key 为 `playscope:<projectId>`。
+- **老项目迁移**：若既有项目历史使用了自定义 Key（如 BlockDrop 的 `blockdrop:playscope:<projectId>`），必须在 `options.storageKey` 中显式指定，以完整保留老用户的 `installId`、事件序号和未发送队列。
+- **Scope 声明 (`legacyScope`)**：若老数据未包含服务环境元数据，可在 `options.legacyScope` 中声明历史的 `baseUrl`、`projectId` 和 `environment`，必须先核实真实历史来源且与当前目标匹配；缺声明会拒绝初始化。已绑定来源不能改绑，不重置身份。
+
+### 10.2 BlockDrop 既有工程注意事项
+- **全局唯一 Owner**：BlockDrop 的生命周期已由 `GameRoot` 与 `GameTelemetry` 统一调度，底层通过 `PlayScopeClient` 门面交互，**切勿**再次创建 `CocosPlayScope` 组件。
+- **广告链路**：BlockDrop 的 `GameTelemetry` 已经处理了 `ad_show`、`ad_impression` 与 `ad_revenue`，**切勿**在已有链路上重复调用 `forwardLevelPlayRevenue`，避免双重记账。
+- **历史 MAX 事件**：历史存量旧事件按原文重放，无需重新转换。
+
+
+
+## 11. 精确接口、存储与错误补充
+
+- [公开类型全集](参考资料/public-api.d.ts)覆盖全部46项公开导出，按[入口索引](参考资料/exports.json)选择路径；旧0.1.1声明保留在参考资料/0.1.1-types中。
+- CocosOptions还支持bootstrapClient、onIdentityReady、persistence、legacyScope、adRevenueEncoder；类型和必填项以声明为准。
+- CocosPlayScope还包括start、trackWithResult、flushWithResult、retryUploads、status、getDiagnostics、getQuarantinedEvents；核心PlayScopeClient另有cache、saveCache和diagnostics，无collectionEnabled／update／实例trackAdRevenue。
+- 配置和XHR超时／交付等待语义见类型及示例；核心不自动注册生命周期，已有调度的项目不叠加Cocos包装。
+- trackWithResult区分accepted(persisted/memory)、duplicate、queue_full、queue_bytes_full、event_too_large、invalid_event、collection_disabled、disposed。accepted不是ACK，memory时暂停上传等待存储修复。
+- flushWithResult返回status、accepted、rejected、quarantined、pending、durable、retryAt、error；completed是本轮结束，pending可能仍非零。
+- 读取故障／损坏／未知版本拒绝初始化并保留原键；scope绑定baseUrl、projectId、environment，仅去baseUrl末尾斜线。缺失环境默认production，不替代独立项目隔离。
+- 默认快照，4MiB预算计待传和完整隔离事实，不含配置／索引／迁移副本。eventLimits按整个队列长度预留；不驱逐旧事实。
+- segmented需要严格removeItem、单键完整替换与读回。v2根和不可变段按清理日志→新段→根提交→清理保存，迁移需额外空间。已有v2不会因省略选项降级；旧包不能直接回退，需完整校验所有段及隔离记录。
+- getQuarantinedEvents保留历史超大或单事件413原文，不等于成功；无公开自动重传／删除接口。永久拒收仅保留最近50项简要诊断，不同于完整隔离区。
+- PlayScopeInitializationError.code为storage_unavailable、state_corrupt、state_version_unsupported、cache_restore_failed、storage_capability_missing、scope_mismatch、scope_migration_required；仅storage_unavailable标retryable。duplicate_client另由PlayScopeOwnershipError抛出。
+- Diagnostics完整字段、ConfigurationResult／Status、FlushResult和ClientStatus的全部联合状态在公开类型中。日志不输出Key、Token或完整私密事件。
+- 单运行时writer检测不提供跨进程／标签页锁。Node测试和SIGKILL不等于真实JSB、断电或设备广告验收。
+- 完整广告字典及通用game placement覆盖见参考资料/服务端/game-ad-properties.json；项目实际冻结契约优先。事件字典存在不代表厂商有对应回调或后台已为每个事件提供卡片。

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/0.1.1-types/adapters/levelplay/index.d.ts

@@ -0,0 +1,15 @@
+import type { AdRevenueFact, TrackContext } from '../../core';
+/** Values forwarded by the host's existing LevelPlay impression listener. */
+export interface LevelPlayImpression {
+    revenue?: number | null;
+    precision?: string | null;
+    adNetwork?: string | null;
+    mediationAdUnitId?: string | null;
+    country?: string | null;
+}
+export type LevelPlayExposure = Omit<AdRevenueFact, 'amount' | 'currency' | 'precision' | 'provider' | 'network' | 'adUnitId' | 'country' | 'countrySource'>;
+export interface RevenueSink {
+    trackAdRevenue(fact: AdRevenueFact, context?: TrackContext): boolean;
+}
+/** Does not initialize ads or replace the game's native listener. Host supplies the original exposure context. */
+export declare function forwardLevelPlayRevenue(sink: RevenueSink, impression: LevelPlayImpression, exposure: LevelPlayExposure, context?: TrackContext): boolean;

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/0.1.1-types/cocos/Storage.d.ts

@@ -0,0 +1,13 @@
+import type { StoragePort } from '../core';
+export interface LocalStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/** Inject sys.localStorage; failures reach the outbox and prevent unsafe uploads. */
+export declare class CocosStorage implements StoragePort {
+    private readonly storage;
+    constructor(storage: LocalStorageLike);
+    getString(key: string): string | null;
+    setString(key: string, value: string): void;
+    flush(): void;
+}

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/0.1.1-types/cocos/XhrJsonTransport.d.ts

@@ -0,0 +1,8 @@
+import type { HttpResponse, JsonTransport } from '../core';
+/** XMLHttpRequest is supported by browsers and Cocos JSB Android/iOS. */
+export declare class XhrJsonTransport implements JsonTransport {
+    private readonly pending;
+    private disposed;
+    post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponse>;
+    dispose(): void;
+}

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//345/217/202/350/200/203/350/265/204/346/226/231/0.1.1-types/cocos/index.d.ts

@@ -0,0 +1,38 @@
+import type { PlayScopeOptions, TrackContext, AdRevenueFact, JsonTransport } from '../core';
+import type { LocalStorageLike } from './Storage';
+export * from '../core';
+export * from './Storage';
+export * from './XhrJsonTransport';
+export interface CocosLifecycle {
+    onHide(callback: () => void): () => void;
+    onShow(callback: () => void): () => void;
+}
+export interface CocosRuntime {
+    storage: LocalStorageLike;
+    lifecycle?: CocosLifecycle;
+    transport?: JsonTransport;
+    now?: () => number;
+}
+export interface CocosOptions extends PlayScopeOptions {
+    /** Host decides consent/collection policy before calling init. */
+    collectionEnabled: boolean;
+}
+/** Host owns event semantics; this wrapper only schedules flush and releases its subscriptions. */
+export declare class CocosPlayScope {
+    private readonly client;
+    private readonly off;
+    private elapsed;
+    private disposed;
+    constructor(options: CocosOptions, runtime: CocosRuntime);
+    start(): void;
+    get installId(): string | null;
+    getDiagnostics(): import("../core").Diagnostics;
+    track(name: string, properties?: Record<string, unknown>, context?: TrackContext): boolean;
+    trackAdRevenue(fact: AdRevenueFact, context?: TrackContext): boolean;
+    newSession(): void;
+    /** Call from a persistent Cocos component's update(dt), in seconds. */
+    update(dt: number): void;
+    flush(): Promise<void>;
+    dispose(): void;
+}
+export declare function init(options: CocosOptions, runtime: CocosRuntime): CocosPlayScope;