@chiyou/minigame-framework 1.4.1 → 1.4.3

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,
+        });
     }
 
     // ==================== 状态查询 ====================