@chiyou/minigame-framework 1.4.1 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chiyou/minigame-framework",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "基于 Cocos Creator 3.x 的小游戏开发框架，支持多平台发布",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/Framework/Adapter/PlatformAdapter/AbsPlatformAdapter.ts

@@ -1,15 +1,19 @@
 import { Component } from "cc";
 import { ScreenInfo } from "../../Definition/SystemDefinition";
 import { SystemMgr } from "../../Manager/SystemMgr";
+import { LaunchCategory, LaunchSceneInfo } from "../../Definition/AnalyticsDefinition";
 
 export abstract class AbsPlatformAdapter extends Component{
 
     protected coldStartOptions: any = null;
     protected warmStartOptions: any = null;
 
-    protected coldStartScene: string = "";
+    protected _coldStartScene: string = "";
     protected warmStartScene: string = "";
 
+    /** 启动场景分类表（子类在构造函数中初始化） */
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map();
+
     protected isShareActive: boolean = false;
 
     protected systemMgr: SystemMgr = null;
@@ -74,15 +78,22 @@ export abstract class AbsPlatformAdapter extends Component{
 
     abstract offHide(fn: Function): void;
 
+    /** 获取冷启动场景信息 */
+    public getColdStartSceneInfo(): LaunchSceneInfo {
+        for (const [category, sceneSet] of this.launchSceneCategoryMap) {
+            if (category === LaunchCategory.Other) continue;
+            if (sceneSet.has(this._coldStartScene)) {
+                return { scene: this._coldStartScene, category };
+            }
+        }
+        return { scene: this._coldStartScene, category: LaunchCategory.Other };
+    }
+
     abstract isNavigateToRecentUseAvailable(callback: Function): void;
 
     abstract navigateToRecentUse(): void;
 
-    abstract isLaunchFromRecentUse(): boolean;
-
-    abstract isLaunchFromDesktopShortcut(): boolean;
 
-    abstract isLaunchFromAdvertisement(): boolean;
 
     abstract checkSession(callback: (isValid: boolean) => void): void;
 

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterBilibili.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
@@ -7,6 +8,15 @@ import { ScreenInfo } from '../../Definition/SystemDefinition';
 export class PlatformAdapterBilibili extends AbsPlatformAdapter {
 
     static TAG: string = "PlatformAdapterBilibili";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set(["10001", "021036"])],
+        [LaunchCategory.Desktop, new Set(["10002"])],
+        [LaunchCategory.Search, new Set([])],
+        [LaunchCategory.Chat, new Set([])],
+        [LaunchCategory.Share, new Set([])],
+        [LaunchCategory.Ad, new Set([])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
 
     // Common
     public init(): void {
@@ -391,18 +401,18 @@ export class PlatformAdapterBilibili extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
 
         if (window["bl"] && window["bl"].getLaunchOptionsSync) {
             this.coldStartOptions = window["bl"].getLaunchOptionsSync();
             if (this.coldStartOptions !== null && this.coldStartOptions["scene"]) {
-                this.coldStartScene = this.coldStartOptions["scene"];
+                this._coldStartScene = this.coldStartOptions["scene"];
             }
         }
 
         LogUtils.Instance.info(PlatformAdapterBilibili.TAG, "冷启动场景更新", {
             operation: "updateColdStartScene",
-            scene: this.coldStartScene
+            scene: this._coldStartScene
         });
     }
 
@@ -508,38 +518,8 @@ export class PlatformAdapterBilibili extends AbsPlatformAdapter {
         });
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        let recentUseSceneSet: Set<string> = new Set<string>([
-            "10001",
-            "021036",
-        ]);
 
-        let isLaunchFromRecentUse: boolean = recentUseSceneSet.has(this.coldStartScene) || recentUseSceneSet.has(this.warmStartScene);
-        LogUtils.Instance.info(PlatformAdapterBilibili.TAG, "判断是否最近使用启动", {
-            operation: "isLaunchFromRecentUse",
-            result: isLaunchFromRecentUse
-        });
-
-        return isLaunchFromRecentUse;
-    }
 
-    public isLaunchFromDesktopShortcut(): boolean {
-        let desktopShortcutSceneSet: Set<string> = new Set<string>([
-            "10002",
-        ]);
-
-        let isLaunchFromDesktopShortcut: boolean = desktopShortcutSceneSet.has(this.coldStartScene) || desktopShortcutSceneSet.has(this.warmStartScene);
-        LogUtils.Instance.info(PlatformAdapterBilibili.TAG, "判断是否桌面快捷方式启动", {
-            operation: "isLaunchFromDesktopShortcut",
-            result: isLaunchFromDesktopShortcut
-        });
-
-        return isLaunchFromDesktopShortcut;
-    }
-
-    public isLaunchFromAdvertisement(): boolean {
-        return false;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         if (window["bl"] && window["bl"].checkSession) {

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterDesktopBrowser.ts

@@ -1,4 +1,5 @@
 import { game } from 'cc';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
@@ -9,6 +10,16 @@ export class PlatformAdapterDesktopBrowser extends AbsPlatformAdapter {
 
     static TAG: string = "PlatformAdapterDesktopBrowser";
 
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set()],
+        [LaunchCategory.Desktop, new Set()],
+        [LaunchCategory.Search, new Set()],
+        [LaunchCategory.Chat, new Set()],
+        [LaunchCategory.Share, new Set()],
+        [LaunchCategory.Ad, new Set()],
+        [LaunchCategory.Other, new Set()],
+    ]);
+
     // Common
     public init(): void {
 
@@ -156,11 +167,11 @@ export class PlatformAdapterDesktopBrowser extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
 
         LogUtils.Instance.info(PlatformAdapterDesktopBrowser.TAG, "冷启动场景更新", {
             operation: "updateColdStartScene",
-            scene: this.coldStartScene
+            scene: this._coldStartScene
         });
     }
 
@@ -210,17 +221,8 @@ export class PlatformAdapterDesktopBrowser extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        return false;
-    }
 
-    public isLaunchFromDesktopShortcut(): boolean {
-        return false;
-    }
 
-    public isLaunchFromAdvertisement(): boolean {
-        return false;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         // Browser不支持这个方法，直接返回true

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterDouYin.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
@@ -11,6 +12,15 @@ class DouYinPlatformBusiness {
 export class PlatformAdapterDouYin extends AbsPlatformAdapter {
 
     static TAG: string = "PlatformAdapterDouYin";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set(["021036", "021012", "101036", "011004", "181003", "061004"])],
+        [LaunchCategory.Desktop, new Set(["021020", "101020", "181020", "141020", "991020"])],
+        [LaunchCategory.Search, new Set([])],
+        [LaunchCategory.Chat, new Set([])],
+        [LaunchCategory.Share, new Set([])],
+        [LaunchCategory.Ad, new Set(["025001", "235001", "016001", "016002", "016003", "105001"])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
 
     private portalGame: any = null;
 
@@ -408,18 +418,18 @@ export class PlatformAdapterDouYin extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
 
         if (window["tt"] && window["tt"].getLaunchOptionsSync) {
             this.coldStartOptions = window["tt"].getLaunchOptionsSync();
             if (this.coldStartOptions !== null && this.coldStartOptions["scene"]) {
-                this.coldStartScene = this.coldStartOptions["scene"];
+                this._coldStartScene = this.coldStartOptions["scene"];
             }
         }
 
         LogUtils.Instance.info(PlatformAdapterDouYin.TAG, "冷启动场景更新", {
             operation: "updateColdStartScene",
-            scene: this.coldStartScene
+            scene: this._coldStartScene
         });
     }
 
@@ -524,54 +534,8 @@ export class PlatformAdapterDouYin extends AbsPlatformAdapter {
         });
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        let recentUseSceneSet: Set<string> = new Set<string>([
-            "021036",
-            "021012",
-            "101036",
-            "011004",
-            "181003",
-            "061004",
-        ]);
-
-        let isLaunchFromRecentUse: boolean = recentUseSceneSet.has(this.coldStartScene) || recentUseSceneSet.has(this.warmStartScene);
-        LogUtils.Instance.info(PlatformAdapterDouYin.TAG, "判断是否最近使用启动", {
-            operation: "isLaunchFromRecentUse",
-            result: isLaunchFromRecentUse
-        });
-        return isLaunchFromRecentUse;
-    }
-
-    public isLaunchFromDesktopShortcut(): boolean {
-        let desktopShortcutSceneSet: Set<string> = new Set<string>([
-            "021020",
-            "101020",
-            "181020",
-            "141020",
-            "991020",
-        ]);
-
-        let isLaunchFromDesktopShortcut: boolean = desktopShortcutSceneSet.has(this.coldStartScene) || desktopShortcutSceneSet.has(this.warmStartScene);
-        LogUtils.Instance.info(PlatformAdapterDouYin.TAG, "判断是否桌面快捷方式启动", {
-            operation: "isLaunchFromDesktopShortcut",
-            result: isLaunchFromDesktopShortcut
-        });
-        return isLaunchFromDesktopShortcut;
-    }
 
-    public isLaunchFromAdvertisement(): boolean {
-        let advertisementSceneSet: Set<string> = new Set<string>([
-            "025001", "235001", "016001",
-            "016002", "016003", "105001",
-        ]);
 
-        let isLaunchFromAdvertisement: boolean = advertisementSceneSet.has(this.coldStartScene);
-        LogUtils.Instance.info(PlatformAdapterDouYin.TAG, "判断是否广告启动", {
-            operation: "isLaunchFromAdvertisement",
-            result: isLaunchFromAdvertisement
-        });
-        return isLaunchFromAdvertisement;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         if (window["tt"] && window["tt"].checkSession) {

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterHonor.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
@@ -6,6 +7,15 @@ import { ScreenInfo } from '../../Definition/SystemDefinition';
 
 export class PlatformAdapterHonor extends AbsPlatformAdapter {
     static TAG: string = "PlatformAdapterHonor";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set([])],
+        [LaunchCategory.Desktop, new Set([])],
+        [LaunchCategory.Search, new Set([])],
+        [LaunchCategory.Chat, new Set([])],
+        [LaunchCategory.Share, new Set([])],
+        [LaunchCategory.Ad, new Set([])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
 
     // Common
     public init(): void {
@@ -289,7 +299,7 @@ export class PlatformAdapterHonor extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
     }
 
     public onGameShowCallback(warmStartOptions: any): void {
@@ -341,17 +351,8 @@ export class PlatformAdapterHonor extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        return false;
-    }
 
-    public isLaunchFromDesktopShortcut(): boolean {
-        return false;
-    }
 
-    public isLaunchFromAdvertisement(): boolean {
-        return false;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         // Honor不支持这个方法，直接返回true

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterHuaWei.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
 import { PlatformID, ScreenInfo } from '../../Definition/SystemDefinition';
@@ -6,6 +7,15 @@ import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 
 export class PlatformAdapterHuaWei extends AbsPlatformAdapter {
     static TAG: string = "PlatformAdapterHuaWei";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set([])],
+        [LaunchCategory.Desktop, new Set([])],
+        [LaunchCategory.Search, new Set([])],
+        [LaunchCategory.Chat, new Set([])],
+        [LaunchCategory.Share, new Set([])],
+        [LaunchCategory.Ad, new Set([])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
 
     // Common
     public init(): void {
@@ -287,7 +297,7 @@ export class PlatformAdapterHuaWei extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
     }
 
     public onGameShowCallback(warmStartOptions: any): void {
@@ -339,17 +349,8 @@ export class PlatformAdapterHuaWei extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        return false;
-    }
 
-    public isLaunchFromDesktopShortcut(): boolean {
-        return false;
-    }
 
-    public isLaunchFromAdvertisement(): boolean {
-        return false;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         // HuaWei不支持这个方法，直接返回true

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterKuaiShou.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
@@ -8,6 +9,16 @@ export class PlatformAdapterKuaiShou extends AbsPlatformAdapter {
 
     static TAG: string = "PlatformAdapterKuaiShou";
 
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set(["sidebar_new", "sidebar_miniprogram", "profile"])],
+        [LaunchCategory.Desktop, new Set()],
+        [LaunchCategory.Search, new Set()],
+        [LaunchCategory.Chat, new Set()],
+        [LaunchCategory.Share, new Set()],
+        [LaunchCategory.Ad, new Set(["dsp"])],
+        [LaunchCategory.Other, new Set()],
+    ]);
+
     // Common
     public init(): void {
 
@@ -292,18 +303,18 @@ export class PlatformAdapterKuaiShou extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
 
         if (window["ks"] && window["ks"].getLaunchOptionsSync) {
             this.coldStartOptions = window["ks"].getLaunchOptionsSync();
             if (this.coldStartOptions !== null && this.coldStartOptions["from"]) {
-                this.coldStartScene = this.coldStartOptions["from"];
+                this._coldStartScene = this.coldStartOptions["from"];
             }
         }
 
         LogUtils.Instance.info(PlatformAdapterKuaiShou.TAG, "冷启动场景更新", {
             operation: "updateColdStartScene",
-            scene: this.coldStartScene
+            scene: this._coldStartScene
         });
     }
 
@@ -361,44 +372,28 @@ export class PlatformAdapterKuaiShou extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        let recentUseSceneSet: Set<string> = new Set<string>([
-            "sidebar_new",
-            "sidebar_miniprogram",
-            "profile",
-        ]);
-        let isLaunchFromRecentUse: boolean = recentUseSceneSet.has(this.coldStartScene) || recentUseSceneSet.has(this.warmStartScene);
-        LogUtils.Instance.info(PlatformAdapterKuaiShou.TAG, "判断是否最近使用启动", {
-            operation: "isLaunchFromRecentUse",
-            result: isLaunchFromRecentUse
-        });
-        return isLaunchFromRecentUse;
-    }
-
-    public isLaunchFromDesktopShortcut(): boolean {
-        let isLaunchFromDesktopShortcut: boolean = false;
+    /** 重写：快手桌面判断需调用 API */
+    public getColdStartSceneInfo(): { scene: string; category: LaunchCategory } {
+        // 先用 API 检查是否从桌面启动
         if (window["ks"] && window["ks"].isLaunchFromShortcut) {
-            isLaunchFromDesktopShortcut = window["ks"].isLaunchFromShortcut();
+            if (window["ks"].isLaunchFromShortcut()) {
+                return { scene: this._coldStartScene, category: LaunchCategory.Desktop };
+            }
         }
-        LogUtils.Instance.info(PlatformAdapterKuaiShou.TAG, "判断是否桌面快捷方式启动", {
-            operation: "isLaunchFromDesktopShortcut",
-            result: isLaunchFromDesktopShortcut
-        });
-        return isLaunchFromDesktopShortcut;
-    }
 
-    public isLaunchFromAdvertisement(): boolean {
-        let advertisementSceneSet: Set<string> = new Set<string>([
-            "dsp",
-        ]);
-        let isLaunchFromAdvertisement: boolean = advertisementSceneSet.has(this.coldStartScene);
-        LogUtils.Instance.info(PlatformAdapterKuaiShou.TAG, "判断是否广告启动", {
-            operation: "isLaunchFromAdvertisement",
-            result: isLaunchFromAdvertisement
-        });
-        return isLaunchFromAdvertisement;
+        // 否则走通用逻辑（Map 查找）
+        for (const [category, sceneSet] of this.launchSceneCategoryMap) {
+            if (category === LaunchCategory.Other) continue;
+            if (sceneSet.has(this._coldStartScene)) {
+                return { scene: this._coldStartScene, category };
+            }
+        }
+        return { scene: this._coldStartScene, category: LaunchCategory.Other };
     }
 
+
+
+
     public checkSession(callback: (isValid: boolean) => void): void {
         if (window["ks"] && window["ks"].checkSession) {
             window["ks"].checkSession({

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterOppo.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
@@ -6,6 +7,15 @@ import { ScreenInfo } from '../../Definition/SystemDefinition';
 
 export class PlatformAdapterOppo extends AbsPlatformAdapter {
     static TAG: string = "PlatformAdapterOppo";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set([])],
+        [LaunchCategory.Desktop, new Set([])],
+        [LaunchCategory.Search, new Set([])],
+        [LaunchCategory.Chat, new Set([])],
+        [LaunchCategory.Share, new Set([])],
+        [LaunchCategory.Ad, new Set([])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
     
     // Common
     public init(): void {
@@ -278,7 +288,7 @@ export class PlatformAdapterOppo extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
 
         if (window["qg"] && window["qg"].getLaunchOptionsSync) {
             this.coldStartOptions = window["qg"].getLaunchOptionsSync();
@@ -326,17 +336,8 @@ export class PlatformAdapterOppo extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        return false;
-    }
 
-    public isLaunchFromDesktopShortcut(): boolean {
-        return false;
-    }
 
-    public isLaunchFromAdvertisement(): boolean {
-        return false;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         // Oppo不支持这个方法，直接返回true

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterTapTap.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
@@ -7,6 +8,15 @@ import { ScreenInfo } from '../../Definition/SystemDefinition';
 export class PlatformAdapterTapTap extends AbsPlatformAdapter {
 
     static TAG: string = "PlatformAdapterTapTap";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set([])],
+        [LaunchCategory.Desktop, new Set([])],
+        [LaunchCategory.Search, new Set([])],
+        [LaunchCategory.Chat, new Set([])],
+        [LaunchCategory.Share, new Set([])],
+        [LaunchCategory.Ad, new Set([])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
 
     // Common
     public init(): void {
@@ -316,18 +326,18 @@ export class PlatformAdapterTapTap extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
 
         if (window["tap"] && window["tap"].getLaunchOptionsSync) {
             this.coldStartOptions = window["tap"].getLaunchOptionsSync();
             if (this.coldStartOptions !== null && this.coldStartOptions["scene"]) {
-                this.coldStartScene = this.coldStartOptions["scene"].toString();
+                this._coldStartScene = this.coldStartOptions["scene"].toString();
             }
         }
 
         LogUtils.Instance.info(PlatformAdapterTapTap.TAG, "冷启动场景更新", {
             operation: "updateColdStartScene",
-            scene: this.coldStartScene
+            scene: this._coldStartScene
         });
     }
 
@@ -389,17 +399,8 @@ export class PlatformAdapterTapTap extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        return false;
-    }
 
-    public isLaunchFromDesktopShortcut(): boolean {
-        return false;
-    }
 
-    public isLaunchFromAdvertisement(): boolean {
-        return false;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         if (window["tap"] && window["tap"].checkSession) {

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterVivo.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
 import { ScreenInfo } from '../../Definition/SystemDefinition';
@@ -6,6 +7,15 @@ import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 
 export class PlatformAdapterVivo extends AbsPlatformAdapter {
     static TAG: string = "PlatformAdapterVivo";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set([])],
+        [LaunchCategory.Desktop, new Set([])],
+        [LaunchCategory.Search, new Set([])],
+        [LaunchCategory.Chat, new Set([])],
+        [LaunchCategory.Share, new Set([])],
+        [LaunchCategory.Ad, new Set([])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
 
     // Common
     public init(): void {
@@ -279,7 +289,7 @@ export class PlatformAdapterVivo extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
     }
 
     public onGameShowCallback(warmStartOptions: any): void {
@@ -331,17 +341,8 @@ export class PlatformAdapterVivo extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        return false;
-    }
 
-    public isLaunchFromDesktopShortcut(): boolean {
-        return false;
-    }
 
-    public isLaunchFromAdvertisement(): boolean {
-        return false;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         // Vivo不支持这个方法，直接返回true

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterWeiXin.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
@@ -87,6 +88,15 @@ class WeiXinPlatformBusiness {
 export class PlatformAdapterWeiXin extends AbsPlatformAdapter {
 
     static TAG: string = "PlatformAdapterWeiXin";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set(["1001", "1089", "1090", "1256", "1271"])],
+        [LaunchCategory.Desktop, new Set(["1023", "1113", "1114", "1223"])],
+        [LaunchCategory.Search, new Set(["1005", "1006", "1027", "1053", "1106", "1183"])],
+        [LaunchCategory.Chat, new Set(["1007", "1008", "1036", "1096"])],
+        [LaunchCategory.Share, new Set(["1044", "1073", "1074"])],
+        [LaunchCategory.Ad, new Set(["1045", "1046", "1067", "1084", "1095", "1200", "1201", "1228", "1232", "1238", "1274", "1295", "1387"])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
 
     private portalGame: PortalGame = new PortalGame();
     private gameClub: GameClub = new GameClub();
@@ -503,18 +513,18 @@ export class PlatformAdapterWeiXin extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
 
         if (window["wx"] && window["wx"].getLaunchOptionsSync) {
             this.coldStartOptions = window["wx"].getLaunchOptionsSync();
             if (this.coldStartOptions !== null && this.coldStartOptions["scene"]) {
-                this.coldStartScene = this.coldStartOptions["scene"].toString();
+                this._coldStartScene = this.coldStartOptions["scene"].toString();
             }
         }
 
         LogUtils.Instance.info(PlatformAdapterWeiXin.TAG, "冷启动场景更新", {
             operation: "updateColdStartScene",
-            scene: this.coldStartScene
+            scene: this._coldStartScene
         });
     }
 
@@ -576,52 +586,8 @@ export class PlatformAdapterWeiXin extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        let recentUseSceneSet: Set<string> = new Set<string>([
-            "1001",
-            "1089",
-            "1256",
-            "1103",
-            "1104",
-            "1257",
-        ]);
-
-        let isLaunchFromRecentUse: boolean = recentUseSceneSet.has(this.coldStartScene) || recentUseSceneSet.has(this.warmStartScene);
-        LogUtils.Instance.info(PlatformAdapterWeiXin.TAG, "判断是否最近使用启动", {
-            operation: "isLaunchFromRecentUse",
-            result: isLaunchFromRecentUse
-        });
-        return isLaunchFromRecentUse;
-    }
 
-    public isLaunchFromDesktopShortcut(): boolean {
-        let desktopShortcutSceneSet: Set<string> = new Set<string>([
-            "1023",
-            "1223",
-        ]);
 
-        let isLaunchFromDesktopShortcut: boolean = desktopShortcutSceneSet.has(this.coldStartScene) || desktopShortcutSceneSet.has(this.warmStartScene);
-        LogUtils.Instance.info(PlatformAdapterWeiXin.TAG, "判断是否桌面快捷方式启动", {
-            operation: "isLaunchFromDesktopShortcut",
-            result: isLaunchFromDesktopShortcut
-        });
-        return isLaunchFromDesktopShortcut;
-    }
-
-    public isLaunchFromAdvertisement(): boolean {
-        let advertisementSceneSet: Set<string> = new Set<string>([
-            "1045", "1046", "1067", "1068", "1084", "1095",
-            "1189", "1200", "1201", "1215", "1228", "1230",
-            "1232", "1238", "1274", "1295",
-        ]);
-
-        let isLaunchFromAdvertisement: boolean = advertisementSceneSet.has(this.coldStartScene);
-        LogUtils.Instance.info(PlatformAdapterWeiXin.TAG, "判断是否广告启动", {
-            operation: "isLaunchFromAdvertisement",
-            result: isLaunchFromAdvertisement
-        });
-        return isLaunchFromAdvertisement;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         if (window["wx"] && window["wx"].checkSession) {

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterXiaoMi.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
@@ -7,6 +8,15 @@ import { ScreenInfo } from '../../Definition/SystemDefinition';
 export class PlatformAdapterXiaoMi extends AbsPlatformAdapter {
 
     static TAG: string = "PlatformAdapterXiaoMi";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set([])],
+        [LaunchCategory.Desktop, new Set([])],
+        [LaunchCategory.Search, new Set([])],
+        [LaunchCategory.Chat, new Set([])],
+        [LaunchCategory.Share, new Set([])],
+        [LaunchCategory.Ad, new Set([])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
     
     // Common
     public init(): void {
@@ -284,11 +294,11 @@ export class PlatformAdapterXiaoMi extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
 
         LogUtils.Instance.info(PlatformAdapterXiaoMi.TAG, "冷启动场景更新", {
             operation: "updateColdStartScene",
-            scene: this.coldStartScene
+            scene: this._coldStartScene
         });
     }
 
@@ -346,17 +356,8 @@ export class PlatformAdapterXiaoMi extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        return false;
-    }
 
-    public isLaunchFromDesktopShortcut(): boolean {
-        return false;
-    }
 
-    public isLaunchFromAdvertisement(): boolean {
-        return false;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         // XiaoMi不支持这个方法，直接返回true

package/src/Framework/Adapter/PlatformAdapter/PlatformAdapterZhiFuBao.ts

@@ -1,4 +1,5 @@
 import { AbsPlatformAdapter } from './AbsPlatformAdapter';
+import { LaunchCategory } from "../../Definition/AnalyticsDefinition";
 import { LogUtils } from '../../Utils/LogUtils';
 import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
@@ -7,6 +8,15 @@ import { ScreenInfo } from '../../Definition/SystemDefinition';
 export class PlatformAdapterZhiFuBao extends AbsPlatformAdapter {
 
     static TAG: string = "PlatformAdapterZhiFuBao";
+    protected launchSceneCategoryMap: Map<LaunchCategory, Set<string>> = new Map([
+        [LaunchCategory.RecentUse, new Set(["1000", "1001", "1002", "1003"])],
+        [LaunchCategory.Desktop, new Set(["1023"])],
+        [LaunchCategory.Search, new Set([])],
+        [LaunchCategory.Chat, new Set([])],
+        [LaunchCategory.Share, new Set([])],
+        [LaunchCategory.Ad, new Set(["1400"])],
+        [LaunchCategory.Other, new Set([])],
+    ]);
 
     // Common
     public init(): void {
@@ -314,18 +324,18 @@ export class PlatformAdapterZhiFuBao extends AbsPlatformAdapter {
 
     public onGameColdStart(): void {
         this.coldStartOptions = null;
-        this.coldStartScene = "";
+        this._coldStartScene = "";
 
         if (window["my"] && window["my"].getLaunchOptionsSync) {
             this.coldStartOptions = window["my"].getLaunchOptionsSync();
             if (this.coldStartOptions !== null && this.coldStartOptions["scene"]) {
-                this.coldStartScene = this.coldStartOptions["scene"];
+                this._coldStartScene = this.coldStartOptions["scene"];
             }
         }
 
         LogUtils.Instance.info(PlatformAdapterZhiFuBao.TAG, "冷启动场景更新", {
             operation: "updateColdStartScene",
-            scene: this.coldStartScene
+            scene: this._coldStartScene
         });
     }
 
@@ -387,47 +397,8 @@ export class PlatformAdapterZhiFuBao extends AbsPlatformAdapter {
 
     }
 
-    public isLaunchFromRecentUse(): boolean {
-        let recentUseSceneSet: Set<string> = new Set<string>([
-            "1000",
-            "1001",
-            "1002",
-            "1003",
-        ]);
 
-        let isLaunchFromRecentUse: boolean = recentUseSceneSet.has(this.coldStartScene) || recentUseSceneSet.has(this.warmStartScene);
-        LogUtils.Instance.info(PlatformAdapterZhiFuBao.TAG, "判断是否最近使用启动", {
-            operation: "isLaunchFromRecentUse",
-            result: isLaunchFromRecentUse
-        });
-        return isLaunchFromRecentUse;
-    }
-
-    public isLaunchFromDesktopShortcut(): boolean {
-        let desktopShortcutSceneSet: Set<string> = new Set<string>([
-            "1023",
-        ]);
 
-        let isLaunchFromDesktopShortcut: boolean = desktopShortcutSceneSet.has(this.coldStartScene) || desktopShortcutSceneSet.has(this.warmStartScene);
-        LogUtils.Instance.info(PlatformAdapterZhiFuBao.TAG, "判断是否桌面快捷方式启动", {
-            operation: "isLaunchFromDesktopShortcut",
-            result: isLaunchFromDesktopShortcut
-        });
-        return isLaunchFromDesktopShortcut;
-    }
-
-    public isLaunchFromAdvertisement(): boolean {
-        let advertisementSceneSet: Set<string> = new Set<string>([
-            "1400",
-        ]);
-
-        let isLaunchFromAdvertisement: boolean = advertisementSceneSet.has(this.coldStartScene);
-        LogUtils.Instance.info(PlatformAdapterZhiFuBao.TAG, "判断是否广告启动", {
-            operation: "isLaunchFromAdvertisement",
-            result: isLaunchFromAdvertisement
-        });
-        return isLaunchFromAdvertisement;
-    }
 
     public checkSession(callback: (isValid: boolean) => void): void {
         // ZhiFuBao不支持这个方法，直接返回true

package/src/Framework/Definition/AnalyticsDefinition.ts

@@ -66,35 +66,111 @@ export interface UmaSDK {
     shareAppMessage(options: object): void;
 }
 
-// ==================== 预定义事件 ID ====================
+// ==================== 事件 ID 与参数 ====================
 
-/** 预定义事件 ID */
+/** 事件 ID（按业务分类） */
 export enum AnalyticsEventId {
+    // ==================== 留存 ====================
+    /** 游戏启动（DAU / 留存基数） */
+    GameLaunch = "game_launch",
+
+    // ==================== 关卡 ====================
+    /** 关卡开始 */
+    StageStart = "stage_start",
+    /** 关卡结束（成功 / 失败 / 放弃） */
+    StageEnd = "stage_end",
+    /** 复活成功 */
+    StageRevive = "stage_revive",
+
+    // ==================== 广告 ====================
+    /** 广告加载成功 */
+    AdLoadSuccess = "ad_load_success",
+    /** 广告加载失败 */
+    AdLoadError = "ad_load_error",
+    /** 广告展示 */
     AdShow = "ad_show",
-    AdClick = "ad_click",
-    AdComplete = "ad_complete",
-    AdSkip = "ad_skip",
-    AdError = "ad_error",
-    Purchase = "purchase",
+    /** 广告观看完成（isEnded=true） */
+    AdShowComplete = "ad_show_complete",
+    /** 广告跳过（isEnded=false） */
+    AdShowSkip = "ad_show_skip",
+}
+
+/** 关卡结束结果 */
+export enum StageResult {
+    Success = "success",
+    Fail = "fail",
+    Abandon = "abandon",
+}
+
+/** 复活方式 */
+export enum ReviveMethod {
+    /** 广告复活 */
+    Ad = "ad",
+    /** 道具复活 */
+    Item = "item",
+}
+
+/** 启动场景分类 */
+export enum LaunchCategory {
+    /** 最近使用/我的小程序 */
+    RecentUse = "recent",
+    /** 桌面图标/快捷方式 */
+    Desktop = "desktop",
+    /** 搜索 */
+    Search = "search",
+    /** 聊天消息卡片 */
+    Chat = "chat",
+    /** 分享卡片 */
     Share = "share",
-    Login = "login",
-    GameLaunch = "game_launch",
-    GameError = "game_error",
+    /** 广告 */
+    Ad = "ad",
+    /** 其他/未知 */
+    Other = "other",
+}
+
+/** 冷启动场景信息 */
+export interface LaunchSceneInfo {
+    /** 原始场景值 */
+    scene: string;
+    /** 归并后的场景分类 */
+    category: LaunchCategory;
 }
 
-/** 事件参数键名 */
+/** 事件参数键名（按业务分类） */
 export enum AnalyticsParamKey {
-    Score = "score",
+    // ==================== 通用 ====================
+    /** 时长（毫秒），关卡耗时等通用场景 */
     Duration = "duration",
-    Reason = "reason",
-    AdType = "ad_type",
-    AdId = "ad_id",
-    ItemId = "item_id",
-    ItemName = "item_name",
-    Price = "price",
-    Currency = "currency",
-    ShareType = "share_type",
-    ShareContent = "share_content",
-    ErrorCode = "error_code",
-    ErrorMsg = "error_msg",
+
+    // ==================== 留存 ====================
+    /** 原始启动场景值 */
+    LaunchScene = "launch_scene",
+    /** 归并后的场景分类 */
+    LaunchCategory = "launch_category",
+    /** 启动小时（0-23） */
+    LaunchHour = "launch_hour",
+
+    // ==================== 关卡 ====================
+    /** 关卡ID */
+    StageId = "stage_id",
+    /** 关卡名称 */
+    StageName = "stage_name",
+    /** 是否首次进入（1=首次, 0=重玩） */
+    IsFirst = "is_first",
+    /** 关卡结束结果（success / fail / abandon） */
+    Result = "result",
+    /** 关卡进度（0-1） */
+    Progress = "progress",
+    /** 是否复活后通关（1=是, 0=否） */
+    IsRevived = "is_revived",
+    /** 复活方式（ad / item） */
+    Method = "method",
+
+    // ==================== 广告 ====================
+    /** 广告场景（业务自定义，如 revive / daily_bonus） */
+    AdScene = "ad_scene",
+    /** 广告错误码 */
+    ErrCode = "err_code",
+    /** 广告错误信息 */
+    ErrMsg = "err_msg",
 }

package/src/Framework/Manager/AnalyticsMgr.ts

@@ -3,7 +3,7 @@ import { LogUtils } from "../Utils/LogUtils";
 import { ServiceLocator } from "../Utils/ServiceLocator";
 import { FwkErrorCode } from "../Definition/FwkErrorDefinition";
 import { PlatformID } from "../Definition/SystemDefinition";
-import { UmengConfig, EventParams, AnalyticsEventId, AnalyticsParamKey, UmaSDK, CommonParams } from "../Definition/AnalyticsDefinition";
+import { UmengConfig, EventParams, AnalyticsEventId, AnalyticsParamKey, StageResult, ReviveMethod, LaunchCategory, UmaSDK, CommonParams } from "../Definition/AnalyticsDefinition";
 import { EventMgr } from "./EventMgr";
 import { FrameworkBase } from "../Definition/FrameworkBase";
 import type { SystemMgr } from "./SystemMgr";
@@ -23,6 +23,12 @@ export class AnalyticsMgr extends BaseMgr {
     /** 通用属性（trackEvent 自动合并） */
     private _commonParams: CommonParams = null;
 
+    /** 当前会话已进入过的关卡（用于 is_first 判重） */
+    private _sessionEnteredStages: Set<string> = new Set();
+
+    /** 各关卡的开始时间戳（用于自动计算 duration） */
+    private _stageStartTimestamps: Map<string, number> = new Map();
+
     onLoad(): void {
         super.onLoad();
 
@@ -295,24 +301,156 @@ export class AnalyticsMgr extends BaseMgr {
 
     // ==================== 游戏特定事件 ====================
 
-    /** 广告展示 */
-    public trackAdShow(adType: string, adId: string, extraParams?: EventParams): void {
-        const params: Record<string, any> = {
-            [AnalyticsParamKey.AdType]: adType,
-            [AnalyticsParamKey.AdId]: adId,
-            ...this._flattenParams(extraParams),
-        };
-        this.trackEvent(AnalyticsEventId.AdShow, params);
+    /**
+     * 关卡开始上报
+     * 自动判重，is_first=1 仅在该用户当前会话内首次进入该关卡时上报。
+     * 同时记录开始时间戳，供 stageTrackEnd 自动计算 duration。
+     * @param stageId 关卡ID（必传）
+     * @param stageName 关卡名称（必传）
+     */
+    public stageTrackStart(stageId: string, stageName: string): void {
+        if (!this._isEnabled) return;
+
+        const isFirst = this._sessionEnteredStages.has(stageId) ? 0 : 1;
+        if (isFirst === 1) {
+            this._sessionEnteredStages.add(stageId);
+        }
+
+        // 记录开始时间戳（毫秒）
+        this._stageStartTimestamps.set(stageId, Date.now());
+
+        this.trackEvent(AnalyticsEventId.StageStart, {
+            [AnalyticsParamKey.StageId]: stageId,
+            [AnalyticsParamKey.StageName]: stageName,
+            [AnalyticsParamKey.IsFirst]: isFirst,
+        });
     }
 
-    /** 广告点击 */
-    public trackAdClick(adType: string, adId: string, extraParams?: EventParams): void {
-        const params: Record<string, any> = {
-            [AnalyticsParamKey.AdType]: adType,
-            [AnalyticsParamKey.AdId]: adId,
-            ...this._flattenParams(extraParams),
-        };
-        this.trackEvent(AnalyticsEventId.AdClick, params);
+    /**
+     * 关卡结束上报
+     * 规则：只有“最终结局”才上报。复活成功后的关卡仍在进行中，不报 stage_end。
+     * duration 由框架自动计算（当前时间戳 - stageTrackStart 记录的时间戳）。
+     * @param stageId 关卡ID
+     * @param result 结果：success / fail / abandon
+     * @param progress 关卡进度（0-1），成功时=1
+     * @param isRevived 是否为复活后通关（0=原始，1=复活后），默认 0
+     */
+    public stageTrackEnd(
+        stageId: string,
+        result: StageResult,
+        progress: number,
+        isRevived: number = 0,
+    ): void {
+        if (!this._isEnabled) return;
+
+        // 自动计算 duration（毫秒）
+        const startTs = this._stageStartTimestamps.get(stageId);
+        const duration = startTs ? Date.now() - startTs : 0;
+        // 上报后清除，避免内存泄漏
+        this._stageStartTimestamps.delete(stageId);
+
+        this.trackEvent(AnalyticsEventId.StageEnd, {
+            [AnalyticsParamKey.StageId]: stageId,
+            [AnalyticsParamKey.Result]: result,
+            [AnalyticsParamKey.Duration]: duration,
+            [AnalyticsParamKey.Progress]: progress,
+            [AnalyticsParamKey.IsRevived]: isRevived,
+        });
+    }
+
+    /**
+     * 复活成功上报
+     * 触发时机：玩家选择复活（看广告或使用道具）并成功复活后上报一次。
+     * 复活前的失败不报 stage_end（还未到最终结局）。
+     * @param stageId 关卡ID
+     * @param method 复活方式
+     */
+    public stageTrackRevive(stageId: string, method: ReviveMethod): void {
+        if (!this._isEnabled) return;
+
+        this.trackEvent(AnalyticsEventId.StageRevive, {
+            [AnalyticsParamKey.StageId]: stageId,
+            [AnalyticsParamKey.Method]: method,
+        });
+    }
+
+    // ==================== 留存事件 ====================
+
+    /**
+     * 游戏启动上报（DAU / 留存基数）
+     * 由 LifeCycleMgr.onGameColdStart() 自动调用，业务层无需手动上报。
+     * @param launchScene 原始启动场景值
+     * @param launchCategory 归并后的场景分类
+     * @param launchHour 启动小时（0-23）
+     */
+    public trackGameLaunch(launchScene: string, launchCategory: LaunchCategory, launchHour: number): void {
+        if (!this._isEnabled) return;
+        this.trackEvent(AnalyticsEventId.GameLaunch, {
+            [AnalyticsParamKey.LaunchScene]: launchScene,
+            [AnalyticsParamKey.LaunchCategory]: launchCategory,
+            [AnalyticsParamKey.LaunchHour]: launchHour,
+        });
+    }
+
+    // ==================== 广告事件 ====================
+
+    /**
+     * 广告加载成功
+     * @param adScene 广告场景（业务自定义，如 revive / daily_bonus）
+     */
+    public trackAdLoadSuccess(adScene: string): void {
+        if (!this._isEnabled) return;
+        this.trackEvent(AnalyticsEventId.AdLoadSuccess, {
+            [AnalyticsParamKey.AdScene]: adScene,
+        });
+    }
+
+    /**
+     * 广告加载失败
+     * @param adScene 广告场景
+     * @param errCode 错误码
+     * @param errMsg 错误信息
+     */
+    public trackAdLoadError(adScene: string, errCode: number, errMsg: string): void {
+        if (!this._isEnabled) return;
+        this.trackEvent(AnalyticsEventId.AdLoadError, {
+            [AnalyticsParamKey.AdScene]: adScene,
+            [AnalyticsParamKey.ErrCode]: errCode,
+            [AnalyticsParamKey.ErrMsg]: errMsg,
+        });
+    }
+
+    /**
+     * 广告展示成功
+     * @param adScene 广告场景
+     */
+    public trackAdShow(adScene: string): void {
+        if (!this._isEnabled) return;
+        this.trackEvent(AnalyticsEventId.AdShow, {
+            [AnalyticsParamKey.AdScene]: adScene,
+        });
+    }
+
+    /**
+     * 广告观看完成（isEnded=true）
+     * @param adScene 广告场景
+     */
+    public trackAdShowComplete(adScene: string): void {
+        if (!this._isEnabled) return;
+        this.trackEvent(AnalyticsEventId.AdShowComplete, {
+            [AnalyticsParamKey.AdScene]: adScene,
+        });
+    }
+
+    /**
+     * 广告跳过（isEnded=false）
+     * @param adScene 广告场景
+     */
+    public trackAdShowSkip(adScene: string): void {
+        if (!this._isEnabled) return;
+        this.trackEvent(AnalyticsEventId.AdShowSkip, {
+            [AnalyticsParamKey.AdScene]: adScene,
+        });
     }
 
     // ==================== 状态查询 ====================

package/src/Framework/Manager/LifeCycleMgr.ts

@@ -3,6 +3,7 @@ import { LogUtils } from "../Utils/LogUtils";
 import { ServiceLocator } from "../Utils/ServiceLocator";
 import { BaseMgr } from "./BaseMgr";
 import { EventMgr } from "./EventMgr";
+import { AnalyticsMgr } from "./AnalyticsMgr";
 
 /** 生命周期管理器 */
 export class LifeCycleMgr extends BaseMgr {
@@ -121,6 +122,11 @@ export class LifeCycleMgr extends BaseMgr {
         }
 
         this.getPlatformAdapter().onGameColdStart();
+
+        // 上报 GameLaunch 事件
+        const info = this.getPlatformAdapter().getColdStartSceneInfo();
+        const launchHour = new Date().getHours();
+        AnalyticsMgr.Instance.trackGameLaunch(info.scene, info.category, launchHour);
     }
 
     /**
@@ -147,30 +153,6 @@ export class LifeCycleMgr extends BaseMgr {
         EventMgr.Instance.emit(FrameworkBase.Message.LifeCycle_onGameHide);
     }
 
-    /**
-     * 是否从最近使用启动
-     * @return 是否从最近使用启动
-     */
-    public isLaunchFromRecentUse(): boolean {
-        if (this.getPlatformAdapter() === null) {
-            return false;
-        }
-
-        return this.getPlatformAdapter().isLaunchFromRecentUse();
-    }
-
-    /**
-     * 是否从桌面快捷方式启动
-     * @return 是否从桌面快捷方式启动
-     */
-    public isLaunchFromDesktopShortcut(): boolean {
-        if (this.getPlatformAdapter() === null) {
-            return false;
-        }
-
-        return this.getPlatformAdapter().isLaunchFromDesktopShortcut();
-    }
-
     /**
      * 是否支持跳转至最近使用
      * @param callback 回调函数
@@ -195,15 +177,12 @@ export class LifeCycleMgr extends BaseMgr {
         this.getPlatformAdapter().navigateToRecentUse();
     }
 
-    /**
-     * 是否从广告启动
-     * @return 是否从广告启动
-     */
-    public isLaunchFromAdvertisement(): boolean {
+    /** 获取冷启动场景信息 */
+    public getColdStartSceneInfo(): { scene: string; category: string } | null {
         if (this.getPlatformAdapter() === null) {
-            return false;
+            return null;
         }
 
-        return this.getPlatformAdapter().isLaunchFromAdvertisement();
+        return this.getPlatformAdapter().getColdStartSceneInfo();
     }
 }