@virjay/playscope-cocos 0.0.0-stage → 0.2.0

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//346/234/215/345/212/241/347/253/257/standard-contract.json

@@ -0,0 +1,183 @@
+{
+  "version": 1,
+  "id": "standard",
+  "description": "通用对局契约：game-event 信封、内置平台事件与产品字典。",
+  "envelope": {
+    "document": "game-event.json"
+  },
+  "summary": {
+    "type": "object",
+    "properties": {
+      "score": {
+        "type": "number",
+        "minimum": -1000000000000,
+        "maximum": 1000000000000
+      },
+      "durationMs": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 7776000000
+      },
+      "metrics": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "number"
+        }
+      }
+    },
+    "additionalProperties": false
+  },
+  "platformSchemas": "builtin",
+  "adPlacementOverrides": true,
+  "platform": [
+    "app_first_open",
+    "app_foreground",
+    "app_background",
+    "screen_view",
+    "activity_heartbeat",
+    "run_created",
+    "run_started",
+    "run_paused",
+    "run_resumed",
+    "run_checkpoint",
+    "run_failed",
+    "run_revived",
+    "run_ended",
+    "config_received"
+  ],
+  "activity": [
+    "app_foreground",
+    "activity_heartbeat",
+    "run_started"
+  ],
+  "lifecycle": {
+    "game_start": "run_started",
+    "game_pause": "run_paused",
+    "game_resume": "run_resumed",
+    "game_over": "run_failed",
+    "revive_success": "run_revived",
+    "level_win": "run_ended",
+    "level_lose": "run_ended"
+  },
+  "checks": [
+    "heartbeat"
+  ],
+  "capabilities": {
+    "standardGameCards": true
+  },
+  "run": {
+    "anyOf": [
+      {
+        "type": "null"
+      },
+      {
+        "type": "object",
+        "properties": {
+          "config": {
+            "$ref": "#/$defs/Attribution"
+          }
+        }
+      }
+    ],
+    "$defs": {
+      "Attribution": {
+        "type": "object",
+        "properties": {
+          "source": {
+            "enum": [
+              "bundled",
+              "cache",
+              "remote"
+            ]
+          },
+          "assignmentId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "experimentId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "variantId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "required": [
+                "experimentId"
+              ],
+              "properties": {
+                "experimentId": {
+                  "type": "string"
+                }
+              }
+            },
+            "then": {
+              "required": [
+                "variantId"
+              ],
+              "properties": {
+                "variantId": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          {
+            "if": {
+              "required": [
+                "variantId"
+              ],
+              "properties": {
+                "variantId": {
+                  "type": "string"
+                }
+              }
+            },
+            "then": {
+              "required": [
+                "experimentId"
+              ],
+              "properties": {
+                "experimentId": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          {
+            "if": {
+              "required": [
+                "source"
+              ],
+              "properties": {
+                "source": {
+                  "const": "bundled"
+                }
+              }
+            },
+            "then": {
+              "properties": {
+                "assignmentId": {
+                  "type": "null"
+                },
+                "experimentId": {
+                  "type": "null"
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  }
+}

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//346/234/215/345/212/241/347/253/257//344/272/247/345/223/201/344/272/213/344/273/266/347/264/242/345/274/225.md

@@ -0,0 +1,87 @@
+# 产品事件索引（80 项）
+
+从随附 product-events.json 摘录。required 仅列 properties 必填字段；run、项目覆盖和额外语义见事件契约章节。
+原始 source／notes 中的 MAX 字样是产品历史描述，不限制 LevelPlay 使用，也不代表该厂商一定提供对应回调。
+
+| 编号 | 事件 | 触发时机 | 必填 properties | 活跃 |
+| --- | --- | --- | --- | --- |
+| E001 | app_install | 首次安装启动 | 无 | False |
+| E002 | app_launch | 冷启动或热启动 | 无 | True |
+| E003 | session_start | 前后台切换进入前台 | 无 | True |
+| E004 | session_end | 进入后台 | 无 | False |
+| E005 | user_first_open | 新设备首次启动 | 无 | True |
+| E006 | user_return | 流失 ≥7 天后再次启动 | 无 | True |
+| E010 | user_login | 登录成功 | 无 | True |
+| E011 | user_register | 完成注册 | 无 | True |
+| E020 | game_start | 点击「开始」进入一局 | 无 | True |
+| E021 | game_pause | 局中点击暂停 | 无 | True |
+| E022 | game_resume | 从暂停恢复 | 无 | True |
+| E023 | game_over | 对局结束（死亡判定） | failureIndex | True |
+| E024 | board_cant_place | 无解探测（出现死局） | 无 | True |
+| E025 | new_high_score | 本局打破个人纪录 | 无 | True |
+| E026 | combo_milestone | 达到连击里程碑(2/3/4/5x) | 无 | True |
+| E027 | level_win | 关卡模式通关 | 无 | True |
+| E028 | level_lose | 关卡模式失败 | 无 | True |
+| E030 | revive_offer_show | 死亡时弹出复活视频选项 | 无 | False |
+| E031 | revive_video_start | 用户点击「看视频复活」 | 无 | True |
+| E032 | revive_video_complete | 激励视频完整播放 | 无 | False |
+| E033 | revive_video_fail | 视频加载失败/中途退出 | 无 | False |
+| E034 | revive_success | 玩家成功复活继续游戏 | failureIndex | True |
+| E035 | revive_block_issued | 复活块生成器下发 | 无 | False |
+| E040 | hint_video_start | 点击「提示/技能」 | 无 | True |
+| E041 | hint_video_complete | 完整播放 | 无 | False |
+| E050 | difficulty_entropy_trigger | 熵增刺客触发 | 无 | False |
+| E051 | difficulty_pity_trigger | 放水保底触发 | 无 | False |
+| E052 | quantile_fetch | 拉取云端分位数 | 无 | False |
+| E060 | ad_request | 业务层调用 loadAd | placement | False |
+| E061 | ad_load_success | 广告加载成功 | 无 | False |
+| E062 | ad_load_fail | 广告加载失败 | 无 | False |
+| E063 | ad_impression | 广告展示（计费点） | 无 | False |
+| E064 | ad_click | 用户点击广告 | 无 | True |
+| E065 | ad_rewarded_grant | 激励视频完整播放发奖 | 无 | False |
+| E066 | ad_skipped | 可跳过广告被跳过 | 无 | False |
+| E067 | ad_close | 广告被关闭 | 无 | False |
+| E120 | mediation_init_success | MAX 聚合 SDK 初始化成功 | sdk_version, country, init_latency_ms | False |
+| E121 | mediation_init_fail | MAX 聚合 SDK 初始化失败 | error_code, error_msg, retry_count | False |
+| E122 | adapter_init | 各广告源 adapter 初始化（AdMob/Meta/Unity 等） | network, network_version, init_status, error_code | False |
+| E123 | ad_request_bid | 本次请求哪些网络参与竞价 | placement, requested_networks, bid_responses, winner_network, bid_price | False |
+| E124 | ad_no_fill | 所有网络都没返回广告 | placement, requested_networks, fill_rate_at_request | False |
+| E125 | ad_request_timeout | 请求超时 | placement, network, timeout_ms, retry | False |
+| E126 | ad_show | 广告成功展示到屏幕（首次曝光） | placement, ad_unit_id, network, ad_format, show_latency_ms | False |
+| E127 | ad_first_quartile | 视频播放 25% | placement, network, ad_unit_id, quartile, played_sec | False |
+| E128 | ad_midpoint | 视频播放 50% | placement, network, ad_unit_id, quartile, played_sec | False |
+| E129 | ad_third_quartile | 视频播放 75% | placement, network, ad_unit_id, quartile, played_sec | False |
+| E130 | ad_complete | 视频播放 100%（完播） | placement, network, ad_unit_id, played_sec, reward_granted | False |
+| E131 | ad_landing_open | 点击后跳转落地页（应用商店/网页） | placement, ad_unit_id, landing_type | True |
+| E132 | ad_landing_return | 从落地页返回 | placement, return_within_sec, action_after_return | True |
+| E133 | ad_revenue | 广告主付费（毛收入） | placement, ad_unit_id, network, revenue, currency, exchange_rate_usd | False |
+| E134 | ad_payout | 平台分成后到手（净收入） | placement, network, gross_revenue, platform_share, net_revenue, currency | False |
+| E135 | ad_ecpm | 千次曝光收入 | placement, network, country, ecpm_usd, impressions, ad_count | False |
+| E136 | ad_freq_cap_hit | 频控命中（被拦截，未展示） | placement, user_id, cap_type, cap_value, hit_count | False |
+| E104 | mail_claim | 领取附件 | message_id, user_id, item, count, claim_latency_sec | True |
+| E105 | mail_expire | 附件过期未领 | message_id, user_id, item, lost_value, expire_at | False |
+| E106 | popup_show | 弹窗出现 | popup_id, ab_version, session_count, force_show | False |
+| E107 | popup_btn_click | 弹窗按钮点击 | popup_id, btn_text, btn_action, click_position | True |
+| E108 | red_dot_show | 红点出现 | entry, count, source | False |
+| E109 | red_dot_click | 红点点击 | entry, count_before, count_after, clear_method | True |
+| E110 | stamina_change | 体力增减 | user_id, change_type, delta, before, after, reason | False |
+| E111 | stamina_overflow | 体力溢出 | user_id, overflow_amount, recover_at, max_stamina | False |
+| E070 | config_fetch | 从 Remote Config 拉取配置 | user_id, config_version, fetch_latency_ms, ab_group, source | False |
+| E071 | config_apply | 配置生效（参数已应用到本地） | user_id, config_version, applied_params_count, diff_params | False |
+| E080 | client_error | 客户端业务异常 | error_type, error_msg, stack_trace, page, user_action | False |
+| E081 | sdk_error | 第三方 SDK 报错 | sdk_name, error_code, error_msg, retry_count, network | False |
+| E082 | crash | 客户端崩溃 | stack_trace, device, os, app_version, is_recoverable | False |
+| E083 | cheat_signal | 作弊/外挂信号 | cheat_type, signal_strength, device_id, action | False |
+| E090 | push_token_register | 设备首次注册推送 token | push_id, user_id, token, channel, registered_at | False |
+| E091 | push_token_refresh | token 刷新（换设备/重置/过期） | push_id, user_id, old_token, new_token, channel, refreshed_at | False |
+| E092 | push_send | 后台发起一次推送任务 | push_id, target_segment, target_size, channel, copy_id, ab_group, scheduled_at | False |
+| E093 | push_delivered | API 层面送达成功 | push_id, user_id, channel, delivered_at, latency_ms | False |
+| E094 | push_received | SDK 收到推送 | push_id, user_id, received_at, push_type | False |
+| E095 | push_open | 用户点击打开 | push_id, user_id, opened_at, deep_link | True |
+| E096 | push_dismiss | 收到但划掉未点击 | push_id, user_id, dismissed_at, displayed_duration_ms | False |
+| E097 | push_convert | 收到/点击后 24h 内回流 | push_id, user_id, converted_at, return_within_sec, action_after_return | True |
+| E098 | push_channel_fail | 通道失败 | push_id, user_id, channel, error_code, error_msg, retry_count | False |
+| E100 | marquee_show | 跑马灯曝光 | marquee_id, ab_version, country, position, exposure_duration_ms | False |
+| E101 | marquee_click | 跑马灯点击 | marquee_id, link_action, ab_version, click_latency_ms | True |
+| E102 | mail_new | 收到新站内信 | message_id, template_id, user_id, has_attachment | False |
+| E103 | mail_read | 打开站内信 | message_id, user_id, time_to_read_sec | True |

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//346/235/245/346/272/220/344/270/216/347/211/210/346/234/254.json

@@ -0,0 +1,35 @@
+{
+  "date": "2026-11-12",
+  "sdkPackageVersion": "0.2.0",
+  "sdkSourceStatus": "0.2.0 distribution source; npm name @virjay/playscope-cocos",
+  "serverSourceVersion": "0.1.21",
+  "note": "Source snapshots for this SDK distribution; server source version does not prove a rebuilt/released server. Project-specific contracts may differ.",
+  "sdkSourceSha256": {
+    "core/types.ts": "202e3a01ac32b589c15fd1a78cafcbae525769c7571ec2acf5b213d9ff039f3e",
+    "core/PlayScopeClient.ts": "45ec11717248a2a1ee125fab6b04002bc9abf7031dec81f8accdea65d8ce0171",
+    "core/ConfigurationSync.ts": "f68f98bb3e1852fb5e0948ad79b7e65433bd82cf56a13e0601f4492183a4b27d",
+    "core/revenue.ts": "f35c52f86c376c92147c776f67c350820d55421979bec44c69531352ac36fe42",
+    "core/PersistentState.ts": "0225aa806e48704f9eadfe83f221118a8dc7165c00ac12c384bf2983f153141d",
+    "core/ClientScope.ts": "218f52c139b019203acabe616cf309d01b7129c37e5c149fccb2876897365bc2",
+    "core/ClientOwnership.ts": "0090a14fb1f177233ac7fdefca0c2055135bef0f5919d55014cdc67d745e648a",
+    "core/HttpError.ts": "7280dd6445c1f4ad1837f558b18451e3d94c3924f51303e6d76fe1a81e0789f8",
+    "core/QueueAdmission.ts": "0f4b2664a6839f78289c35fa11076999acf07c1575a213dc9dbef67364a0a23e",
+    "core/uuid.ts": "9606b0561f5ee05b8d2865de38b0a3b198f3ba620f3241b53653f4fe4f3e065c",
+    "core/FactEncoding.ts": "1340b10d060eb8a9c853c1192c2798db71dbe20960fdb854d5b8875044f5f016",
+    "cocos/index.ts": "d0770451dedf74d88a666ab0b1444bc2146266f919e76f9b3d11c218dce7eb65",
+    "cocos/Storage.ts": "c3fa8d586a5cad49329e78c7d1f8ef8c9fe8d663715e31eb8753ea255b67bf21",
+    "cocos/XhrJsonTransport.ts": "a36a2516e0e1e02ca76c8a66beaf1b84c21e1fff768ce84d0e934e87b793811a",
+    "adapters/levelplay/index.ts": "4e392549557e67e82c6b0a85b50d4edcc43dc866691141ce2a1c75f0792de39d",
+    "protocols/game-v1/index.ts": "454c1f485b4004992075bc24ac3c7b86d0f935708d67d161b85800a7608dac8b",
+    "examples/quest-garden/QuestGarden.ts": "2e3850ec5b89e47829d51b94afebf5f6b485b19f0244ea4b42e1599a30d89906",
+    "examples/quest-garden/project-fixture.json": "84c0a8fe4cfda1c3fd5a6770002c9be7ab25cbf43273b26b45f3d06e25467ba7"
+  },
+  "serverSourceSha256": {
+    "internal/contract/game-event.json": "acf39884ef6ad1bff46d4b44b459f7b156051ef102f06605c9f7bb8cca70a0db",
+    "internal/contract/client-context.json": "066767bcc4b6a22d7713539f5cca1cfd91b0ad93e0fe1e73419427d1e623a7ac",
+    "internal/contract/product-events.json": "2f261d3ee191783f3660e69cc7c5d06cd714fc649285bdb466caf25894dbce96",
+    "internal/contract/seeds/standard.json": "69595310293eb23d043c1ed65c6d2ecdd22f6bd78b0e6c94fcee528038f8db86",
+    "internal/contract/game.go": "822a706fd15dc4060dd38b9a16fb3e98fc59591d460a7ddac0aa39f28b0418a8",
+    "internal/contract/product.go": "006292482da541621fddb2aff9e5266273f7caeb7716acb3e7680dfc51464f02"
+  }
+}

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//347/244/272/344/276/213/CoreIntegration.ts

@@ -0,0 +1,13 @@
+import { PlayScopeClient, type PlayScopeOptions, type StoragePort, type JsonTransport } from '@virjay/playscope-cocos';
+
+/** Existing host owns its tick/lifecycle. Do not also construct CocosPlayScope for this store/key. */
+export function createCore(options: PlayScopeOptions, storage: StoragePort, transport: JsonTransport,
+  collectionAllowed: boolean): PlayScopeClient | null {
+  if (!collectionAllowed) return null;
+  const client = new PlayScopeClient(options, storage, transport);
+  client.start();
+  void client.flush();
+  return client;
+}
+// Host must call client.flush() from its existing schedule and client.dispose() when releasing it.
+// Supply a dedicated transport instance; dispose can abort requests owned by that transport.

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//347/244/272/344/276/213/LevelPlayTelemetry.ts

@@ -0,0 +1,119 @@
+import { telemetryUuid, type CocosPlayScope, type AdRevenueFact } from '@virjay/playscope-cocos';
+import { forwardLevelPlayRevenue, type LevelPlayImpression } from '@virjay/playscope-cocos/adapters/levelplay';
+
+/** Documentation host adapter. Native SDK initialization/callback binding remains with the game. */
+export interface AdRequestSnapshot {
+  requestId: string;
+  placement: AdRevenueFact['placement'];
+  format: AdRevenueFact['format'];
+  isTest: boolean;
+  isMock?: boolean;
+  isDemo?: boolean;
+  adConfigRevision?: string;
+  run: unknown;
+}
+export interface AdExposureSnapshot extends AdRequestSnapshot {
+  exposureId: string;
+  shownAt: string;
+  network: string;
+  adUnitId: string;
+  country?: string;
+}
+export interface RewardOutcome {
+  outcome: 'granted' | 'not_granted' | 'failed' | 'unknown' | 'demo';
+  persistence: 'saved' | 'pending' | 'not_required' | 'unknown';
+  reason?: string;
+}
+const copy = <T>(value: T): T => JSON.parse(JSON.stringify(value));
+
+export class LevelPlayTelemetry {
+  constructor(private readonly telemetry: CocosPlayScope) {}
+
+  createRequest(input: Omit<AdRequestSnapshot, 'requestId'>): AdRequestSnapshot {
+    return copy({ ...input, requestId: telemetryUuid() });
+  }
+
+  /** Call once per native display/auction. Reuse the result for repeated/late callbacks. */
+  captureExposure(request: AdRequestSnapshot, display: {
+    exposureId: string; shownAt: string; network: string; adUnitId: string; country?: string;
+  }): AdExposureSnapshot {
+    return copy({ ...request, ...display });
+  }
+
+  recordRequest(request: AdRequestSnapshot): boolean {
+    return this.once('ad_request', this.properties(request), request.run, request.requestId);
+  }
+  recordLoaded(request: AdRequestSnapshot, cacheHit: boolean): boolean {
+    return this.once('ad_load_success', { ...this.properties(request), cache_hit: cacheHit }, request.run, request.requestId);
+  }
+  recordLoadFailure(request: AdRequestSnapshot, code: string): boolean {
+    return this.once('ad_load_fail', { ...this.properties(request), error_code: code }, request.run, request.requestId);
+  }
+  recordDisplay(exposure: AdExposureSnapshot, latencyMs: number): { shown: boolean; impression: boolean } {
+    if (!Number.isSafeInteger(latencyMs) || latencyMs < 0) throw Error('invalid_display_latency');
+    const properties = this.properties(exposure);
+    return {
+      shown: this.once('ad_show', { ...properties, show_latency_ms: latencyMs },
+        exposure.run, exposure.exposureId, exposure.shownAt),
+      impression: this.once('ad_impression', properties, exposure.run, exposure.exposureId, exposure.shownAt),
+    };
+  }
+  recordClick(exposure: AdExposureSnapshot): boolean { return this.exposureEvent('ad_click', exposure); }
+  recordClose(exposure: AdExposureSnapshot): boolean { return this.exposureEvent('ad_close', exposure); }
+  recordSkipped(exposure: AdExposureSnapshot): boolean { return this.exposureEvent('ad_skipped', exposure); }
+
+  recordRevenue(exposure: AdExposureSnapshot, impression: LevelPlayImpression): boolean {
+    // Do not independently track ad_revenue as well: this helper already generates it.
+    return forwardLevelPlayRevenue(this.telemetry, impression, {
+      exposureId: exposure.exposureId, placement: exposure.placement,
+      businessPlacement: exposure.placement, format: exposure.format, isTest: exposure.isTest,
+      isMock: exposure.isMock, isDemo: exposure.isDemo, shownAt: exposure.shownAt,
+      adConfigRevision: exposure.adConfigRevision,
+    }, { run: exposure.run });
+  }
+  /** Call after the game has determined the actual reward and persistence outcome. */
+  recordRewardOutcome(exposure: AdExposureSnapshot, reward: RewardOutcome): boolean {
+    if (exposure.format !== 'rewarded') return false;
+    return this.once('ad_rewarded_grant', { ...this.properties(exposure), sdk_reward_received: true,
+      reward_outcome: reward.outcome, reward_persistence: reward.persistence,
+      ...(reward.reason ? { reward_reason: reward.reason } : {}),
+    }, exposure.run, exposure.exposureId);
+  }
+  recordDisplayFailure(request: AdRequestSnapshot, code: string, retryCount: number, network: string): boolean {
+    return this.once('sdk_error', { ...this.properties(request), sdk_name: 'levelplay', error_code: code,
+      error_msg: 'LevelPlay display failed', retry_count: retryCount, network, phase: 'display',
+    }, request.run, request.requestId);
+  }
+  /** Use only if the target native SDK actually supplies the matching playback callback. */
+  recordVideoQuartile(exposure: AdExposureSnapshot, quartile: 25 | 50 | 75, playedSec: number): boolean {
+    if (exposure.format !== 'rewarded' || !Number.isFinite(playedSec) || playedSec < 0) return false;
+    const names = { 25: 'ad_first_quartile', 50: 'ad_midpoint', 75: 'ad_third_quartile' } as const;
+    return this.once(names[quartile], { ...this.properties(exposure), quartile, played_sec: playedSec },
+      exposure.run, exposure.exposureId);
+  }
+  /** Do not call this from reward/close callbacks unless there is independent completion evidence. */
+  recordVideoComplete(exposure: AdExposureSnapshot, playedSec: number, rewardGranted: boolean): boolean {
+    if (exposure.format !== 'rewarded' || !Number.isFinite(playedSec) || playedSec < 0) return false;
+    return this.once('ad_complete', { ...this.properties(exposure), played_sec: playedSec,
+      reward_granted: rewardGranted ? 'yes' : 'no' }, exposure.run, exposure.exposureId);
+  }
+  private exposureEvent(name: string, exposure: AdExposureSnapshot): boolean {
+    return this.once(name, this.properties(exposure), exposure.run, exposure.exposureId);
+  }
+  private properties(request: AdRequestSnapshot | AdExposureSnapshot): Record<string, unknown> {
+    const exposure = 'exposureId' in request ? request : null;
+    return { placement: request.placement, business_placement: request.placement,
+      ad_request_id: exposure?.exposureId ?? request.requestId, originating_request_id: request.requestId,
+      ad_format: request.format, provider: 'levelplay', is_test: request.isTest,
+      is_mock: request.isMock === true, is_demo: request.isDemo === true,
+      ...(request.adConfigRevision ? { ad_config_revision: request.adConfigRevision } : {}),
+      ...(exposure ? { network: exposure.network, ad_unit_id: exposure.adUnitId, ad_shown_at: exposure.shownAt,
+        ...(exposure.country ? { country: exposure.country, country_source: 'levelplay_sdk' } : {}) } : {}),
+    };
+  }
+  private once(name: string, properties: Record<string, unknown>, run: unknown, identity: string, occurredAt?: string): boolean {
+    return this.telemetry.track(name, properties, {
+      run, occurredAt, deduplicationKey: `levelplay:${name}:${identity}`,
+    });
+  }
+}

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//347/244/272/344/276/213/PlayScopeExample.ts

@@ -0,0 +1,46 @@
+import { _decorator, Component, sys, game, Game } from 'cc';
+import { init, type CocosPlayScope } from '@virjay/playscope-cocos';
+const { ccclass } = _decorator;
+
+/** Mount one instance on the game's persistent owner node. */
+@ccclass('PlayScopeExample')
+export class PlayScopeExample extends Component {
+  private client: CocosPlayScope | null = null;
+  private allowed = false;
+  get telemetry(): CocosPlayScope | null { return this.client; }
+
+  onLoad(): void {
+    if (!this.client) this.setCollectionAllowed(false);
+  }
+  /** Connect this method to the game's actual stored consent / consent change callback. */
+  setCollectionAllowed(allowed: boolean): void {
+    if (this.client && this.allowed === allowed) return;
+    const previous = this.client;
+    this.client = null;
+    previous?.dispose();
+    this.client = init({
+      baseUrl: 'https://analytics.example.com',
+      projectId: 'YOUR_TEST_PROJECT_UUID',
+      projectKey: 'YOUR_PROJECT_CLIENT_KEY',
+      collectionEnabled: allowed,
+      client: { appVersion: '1.0.0', buildNumber: '1',
+        platform: sys.isNative ? sys.platform === sys.Platform.ANDROID ? 'android' : 'ios' : 'web',
+        locale: sys.language, timezoneOffsetMinutes: -new Date().getTimezoneOffset(), environment: 'test' },
+    }, {
+      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); },
+      },
+    });
+    this.allowed = allowed;
+  }
+  /** Call from the real launch path once; not on every consent change. */
+  recordLaunch(): boolean { return this.client?.track('app_launch', { reason: 'launch' }) ?? false; }
+  update(dt: number): void { this.client?.update(dt); }
+  onDestroy(): void {
+    const previous = this.client;
+    this.client = null;
+    previous?.dispose();
+  }
+}

package/doc//344/275/277/347/224/250/346/214/207/345/215/227//347/244/272/344/276/213/QuestGarden.ts

@@ -0,0 +1,129 @@
+import { CocosPlayScope, telemetryUuid } from '@virjay/playscope-cocos';
+import type { CocosRuntime, ClientContext, AdRevenueFact, ConfigurationContext, FlushResult } from '@virjay/playscope-cocos';
+import { forwardLevelPlayRevenue } from '@virjay/playscope-cocos/adapters/levelplay';
+import type { LevelPlayExposure, LevelPlayImpression } from '@virjay/playscope-cocos/adapters/levelplay';
+
+export interface QuestConnection {
+  baseUrl: string;
+  projectId: string;
+  projectKey: string;
+  environment: 'production' | 'test';
+}
+interface Rules { schemaVersion: 1; revision: string; harvestTarget: number; season: string }
+interface Assignment { assignmentId: string; experimentId: string | null; variantId: string | null }
+interface Cache { config: Rules; assignment: Assignment }
+interface Attribution { configRevision: string; source: 'bundled' | 'cache' | 'remote';
+  assignmentId: string | null; experimentId: string | null; variantId: string | null }
+export interface QuestRun { runId: string; mode: 'garden-quest'; level: string; config: Attribution }
+export interface QuestExposure extends LevelPlayExposure { run: QuestRun | null }
+const BUNDLED: Rules = { schemaVersion: 1, revision: 'garden-bundled-1', harvestTarget: 3, season: 'spring' };
+function readCache(value: unknown): Cache | null {
+  const saved = value as Cache | null, rules = saved?.config, assignment = saved?.assignment;
+  if (!rules || rules.schemaVersion !== 1 || typeof rules.revision !== 'string' || !rules.revision ||
+    !Number.isSafeInteger(rules.harvestTarget) || rules.harvestTarget < 1 || rules.harvestTarget > 20 ||
+    typeof rules.season !== 'string' || !rules.season || !assignment || typeof assignment.assignmentId !== 'string' || !assignment.assignmentId ||
+    !(assignment.experimentId === null && assignment.variantId === null ||
+      typeof assignment.experimentId === 'string' && !!assignment.experimentId && typeof assignment.variantId === 'string' && !!assignment.variantId)) return null;
+  return { config: { schemaVersion: 1, revision: rules.revision, harvestTarget: rules.harvestTarget, season: rules.season },
+    assignment: { assignmentId: assignment.assignmentId, experimentId: assignment.experimentId, variantId: assignment.variantId } };
+}
+/** Example protocol owned by this game. Custom events must be registered in its own game project. */
+export function encodeQuestIncome(fact: Readonly<AdRevenueFact>) {
+  return { name: 'quest_ad_income', properties: { placement: fact.placement, exposure_id: fact.exposureId,
+    usd: fact.amount, provider: fact.provider, network: fact.network, ad_unit: fact.adUnitId, precision: fact.precision } };
+}
+
+/** Small independent host: gameplay and config application stay here; SDK only collects and delivers facts. */
+export class QuestGarden {
+  private readonly sdk: CocosPlayScope;
+  private readonly client: ClientContext;
+  private rules: Rules = { ...BUNDLED };
+  private attribution: Attribution = { configRevision: BUNDLED.revision, source: 'bundled',
+    assignmentId: null, experimentId: null, variantId: null };
+  private active: { run: QuestRun; rules: Rules; harvests: number; activeMs: number } | null = null;
+  private started = false;
+  private disposed = false;
+  private completed = 0;
+  constructor(connection: QuestConnection, runtime: CocosRuntime, collectionEnabled: boolean,
+    client: Omit<ClientContext, 'environment'>) {
+    const { environment, ...endpoint } = connection;
+    this.client = JSON.parse(JSON.stringify({ ...client, environment }));
+    this.sdk = new CocosPlayScope({ ...endpoint, client: this.client, collectionEnabled,
+      // Separate project IDs are also required for real test/production projects.
+      storageKey: `quest-garden:${environment}:${connection.projectId}`, persistence: 'segmented',
+      queuePolicy: { maxEvents: 64, maxBytes: 512 * 1024, eventLimits: { quest_harvested: 48 } },
+      adRevenueEncoder: encodeQuestIncome,
+      restoreCache: saved => {
+        const cache = readCache(saved);
+        if (cache) this.apply(cache, 'cache');
+        return cache;
+      },
+      resolveConfiguration: context => this.resolveConfig(context),
+    }, runtime);
+  }
+  start(): void {
+    if (this.disposed || this.started) return;
+    this.started = true; this.sdk.start(); this.sdk.track('app_launch', { reason: 'launch' });
+  }
+  beginQuest(questId: string): string | null {
+    if (this.disposed || this.active || !questId) return null;
+    const run: QuestRun = { runId: telemetryUuid(), mode: 'garden-quest', level: questId, config: { ...this.attribution } };
+    this.active = { run, rules: { ...this.rules }, harvests: 0, activeMs: 0 };
+    this.sdk.track('game_start', {}, { run });
+    this.sdk.track('quest_started', { quest_id: questId, season: this.rules.season }, { run });
+    return run.runId;
+  }
+  harvest(): boolean {
+    if (this.disposed || !this.active) return false;
+    const quest = this.active;
+    quest.harvests++;
+    this.sdk.track('quest_harvested', { quest_id: quest.run.level, index: quest.harvests }, { run: quest.run });
+    if (quest.harvests >= quest.rules.harvestTarget) {
+      this.completed++;
+      this.sdk.track('quest_completed', { quest_id: quest.run.level, harvests: quest.harvests }, { run: quest.run });
+      this.sdk.track('run_ended', { outcome: 'completed', summary: { score: quest.harvests, durationMs: quest.activeMs,
+        metrics: { harvests: quest.harvests } } }, { run: quest.run });
+      this.active = null;
+    }
+    return true;
+  }
+  captureExposure(exposureId: string, placement: string, format: 'banner' | 'rewarded', isTest: boolean): QuestExposure {
+    return { exposureId, placement, businessPlacement: placement, format, isTest,
+      run: this.active ? JSON.parse(JSON.stringify(this.active.run)) : null };
+  }
+  recordIncome(impression: LevelPlayImpression, exposure: QuestExposure): boolean {
+    if (this.disposed) return false;
+    const { run, ...fact } = exposure;
+    return forwardLevelPlayRevenue(this.sdk, impression, fact, { run });
+  }
+  update(dt: number, playing = true): void {
+    if (this.disposed) return;
+    if (playing && this.active && Number.isFinite(dt) && dt > 0 && dt <= 1) this.active.activeMs += dt * 1000;
+    this.sdk.update(dt);
+  }
+  get progress() { return { completed: this.completed, questId: this.active?.run.level ?? null,
+    harvests: this.active?.harvests ?? 0, target: this.active?.rules.harvestTarget ?? this.rules.harvestTarget }; }
+  get installId() { return this.sdk.installId; }
+  get status() { return this.sdk.status; }
+  get diagnostics() { return this.sdk.getDiagnostics(); }
+  flush(): Promise<FlushResult> { return this.sdk.flushWithResult(); }
+  refreshConfiguration() { return this.sdk.refreshConfiguration(); }
+  dispose(): void { if (!this.disposed) { this.disposed = true; this.sdk.dispose(); } }
+  private apply(cache: Cache, source: 'cache' | 'remote'): void {
+    this.rules = cache.config;
+    this.attribution = { configRevision: cache.config.revision, source, ...cache.assignment };
+  }
+  private async resolveConfig(context: ConfigurationContext): Promise<number> {
+    const previous = readCache(context.cache);
+    const response = await context.request('/config/resolve', { apiVersion: 1, installId: this.installId,
+      client: this.client, supportedSchemas: [1], current: previous ? { revision: previous.config.revision, assignmentId: previous.assignment.assignmentId } : null }) as {
+        apiVersion: number; delivery: string; config: unknown; configRevision: string; assignment: unknown; refreshAfterSeconds: number };
+    if (this.disposed) return 3600;
+    const cache = readCache({ config: response?.delivery === 'full' ? response.config :
+      response?.delivery === 'not_modified' ? previous?.config : null, assignment: response?.assignment });
+    if (response?.apiVersion !== 1 || !cache || cache.config.revision !== response.configRevision) throw new Error('invalid_quest_config');
+    context.saveCache(cache); this.apply(cache, 'remote');
+    this.sdk.track('config_received', { revision: cache.config.revision });
+    return response.refreshAfterSeconds;
+  }
+}

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

@@ -0,0 +1,23 @@
+# 接入示例代码索引
+
+本目录提供了若干个开箱即用的参考实现，涵盖 Cocos Creator 组件、纯 TypeScript 核心集成、广告上报封装及端到端游戏对局示例。
+
+---
+
+## 示例文件一览
+
+| 文件 | 适用场景 | 核心内容与职责 |
+| :--- | :--- | :--- |
+| **`PlayScopeExample.ts`** | **Cocos Creator 组件接入** | 可直接挂载在 Cocos 场景常驻节点的组件示例，包含单例管理、隐私授权切换、前后台监听、帧循环 `update` 及销毁处理。 |
+| **`LevelPlayTelemetry.ts`** | **LevelPlay 广告全链路上报** | 规范化广告展示、曝光、点击、奖励及收入上报的适配层，演示如何生成独立 `exposureId`、配对展示与收入。 |
+| **`CoreIntegration.ts`** | **纯 TypeScript / 已有框架项目** | 适用于已有独立调度管理器或非 Cocos 项目，演示如何直接创建和操作 `PlayScopeClient` 核心实例。 |
+| **`QuestGarden.ts`** | **完整对局与配置归因参考** | 完整的端到端游戏宿主示例，演示关卡对局 `run` 对象的创建、局内配置冻结、云端配置拉取与缓存恢复。 |
+| **`project-fixture.json`** | **后台项目配置参考** | 配套 `QuestGarden` 的项目创建材料、事件 Schema、云端配置及发布权重示例。 |
+
+---
+
+## 快速导航建议
+
+- **如果你是在 Cocos Creator 中接入通用游戏**：优先参考 [PlayScopeExample.ts](PlayScopeExample.ts) 与 [LevelPlayTelemetry.ts](LevelPlayTelemetry.ts)。
+- **如果你的工程已有现成的全局调度器**：参考 [CoreIntegration.ts](CoreIntegration.ts)，将 SDK 核心注入已有调度，避免重复创建包装层。
+- **如果你需要接入 A/B 测试或对局归因**：参考 [QuestGarden.ts](QuestGarden.ts) 中的 `run` 冻结与配置缓存应用逻辑。