@chiyou/minigame-framework 1.4.0 → 1.4.2

package/src/Framework/Manager/AnalyticsMgr.ts

@@ -3,10 +3,10 @@ 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, StageEventType, StageRunningEventType, StageEndParams, StageRunningParams, CommonParams, UmaSDKStage } 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 { SystemMgr } from "./SystemMgr";
+import type { SystemMgr } from "./SystemMgr";
 
 export class AnalyticsMgr extends BaseMgr {
     /** 单例实例 */
@@ -20,11 +20,15 @@ export class AnalyticsMgr extends BaseMgr {
     private _isEnabled: boolean = false;
     /** 当前平台对应的 SDK 实例（通过 wx.uma 全局访问） */
     private _sdk: UmaSDK = null;
-    /** 关卡 SDK 实例 */
-    private _sdkStage: UmaSDKStage = null;
     /** 通用属性（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();
 
@@ -74,12 +78,20 @@ export class AnalyticsMgr extends BaseMgr {
 
         // 根据当前平台是否开启统计来决定是否启用
         const platformID: PlatformID = BaseMgr.Instance.getCurrentPlatformID();
-        const enabled = umengConfig.platformEnableMap.get(platformID);
+        let enabled = umengConfig.platformEnableMap.get(platformID);
+
+        if (enabled) {
+            // 额外检查：本地游戏无网络请求能力，不上报统计
+            const systemMgr = ServiceLocator.Instance.get<SystemMgr>("SystemMgr");
+            if (systemMgr && !systemMgr.supportRequest()) {
+                enabled = false;
+                LogUtils.Instance.info(AnalyticsMgr.TAG, "本地游戏不支持网络请求，统计禁用");
+            }
+        }
 
         if (enabled) {
             // 从全局获取 SDK 实例（在 game.js 中初始化后挂载到 wx.uma）
             this._sdk = this._getGlobalSDK();
-            this._sdkStage = this._sdk?.stage || null;
             this._isEnabled = !!this._sdk;
         } else {
             this._isEnabled = false;
@@ -139,7 +151,6 @@ export class AnalyticsMgr extends BaseMgr {
      * 后续所有 trackEvent 调用自动合并这些属性。
      * 合并规则：通用属性与自定义属性同级平铺，自定义属性可覆盖同名通用属性。
      * 
-     * 注意：仅适用于 trackEvent，不适用于 stage 系列接口。
      * 友盟 SDK 的 setSuperProperty 在小游戏环境不可用，需在框架封装层实现。
      */
     private _initCommonParams(): void {
@@ -290,175 +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 接口） ====================
+    /**
+     * 复活成功上报
+     * 触发时机：玩家选择复活（看广告或使用道具）并成功复活后上报一次。
+     * 复活前的失败不报 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,
+        });
+    }
+
+    // ==================== 留存事件 ====================
 
     /**
-     * 关卡开始
-     * @param stageId 关卡ID（string类型）
-     * @param stageName 关卡名称
+     * 游戏启动上报（DAU / 留存基数）
+     * 由 LifeCycleMgr.onGameColdStart() 自动调用，业务层无需手动上报。
+     * @param launchScene 原始启动场景值
+     * @param launchCategory 归并后的场景分类
+     * @param launchHour 启动小时（0-23）
      */
-    public stageOnStart(stageId: string, stageName: string): void {
-        if (!this._isEnabled || !this._sdkStage) return;
-        try {
-            this._sdkStage.onStart({ stageId, stageName });
-            LogUtils.Instance.info(AnalyticsMgr.TAG, "关卡开始", {
-                operation: "stageOnStart",
-                stageId,
-                stageName,
-            });
-        } catch (e) {
-            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
-                operation: "stageOnStart",
-                reason: String(e),
-                stageId,
-                stageName,
-            });
-        }
+    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 stageId 关卡ID（string类型）
-     * @param stageName 关卡名称
-     * @param event 结束结果（"complete" | "fail")
-     * @param duration 关卡耗时（毫秒，可选）
+     * 广告加载成功
+     * @param adScene 广告场景（业务自定义，如 revive / daily_bonus）
      */
-    public stageOnEnd(stageId: string, stageName: string, event: StageEventType, duration?: number): void {
-        if (!this._isEnabled || !this._sdkStage) return;
-        try {
-            const params: StageEndParams = { stageId, stageName, event };
-            if (duration !== undefined) {
-                params._um_sdu = duration;
-            }
-            this._sdkStage.onEnd(params);
-            LogUtils.Instance.info(AnalyticsMgr.TAG, "关卡结束", {
-                operation: "stageOnEnd",
-                stageId,
-                stageName,
-                event,
-                duration,
-            });
-        } catch (e) {
-            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
-                operation: "stageOnEnd",
-                reason: String(e),
-                stageId,
-                stageName,
-                event,
-            });
-        }
+    public trackAdLoadSuccess(adScene: string): void {
+        if (!this._isEnabled) return;
+        this.trackEvent(AnalyticsEventId.AdLoadSuccess, {
+            [AnalyticsParamKey.AdScene]: adScene,
+        });
     }
 
     /**
-     * 关卡中行为 - 使用道具
-     * @param stageId 关卡ID（string类型）
-     * @param stageName 关卡名称
-     * @param itemName 道具名称
-     * @param itemId 道具ID（可选）
-     * @param itemCount 道具数量（可选）
-     * @param itemMoney 道具单价（可选）
+     * 广告加载失败
+     * @param adScene 广告场景
+     * @param errCode 错误码
+     * @param errMsg 错误信息
      */
-    public stageOnRunningTools(
-        stageId: string,
-        stageName: string,
-        itemName: string,
-        itemId?: string,
-        itemCount?: number,
-        itemMoney?: number
-    ): void {
-        if (!this._isEnabled || !this._sdkStage) return;
-        try {
-            const params: StageRunningParams = {
-                stageId,
-                stageName,
-                event: StageRunningEventType.Tools,
-                params: { itemName, itemId, itemCount, itemMoney },
-            };
-            this._sdkStage.onRunning(params);
-            LogUtils.Instance.info(AnalyticsMgr.TAG, "关卡使用道具", {
-                operation: "stageOnRunningTools",
-                stageId,
-                stageName,
-                itemName,
-                itemId,
-                itemCount,
-                itemMoney,
-            });
-        } catch (e) {
-            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
-                operation: "stageOnRunningTools",
-                reason: String(e),
-                stageId,
-                stageName,
-                itemName,
-            });
-        }
+    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 stageId 关卡ID（string类型）
-     * @param stageName 关卡名称
-     * @param itemName 奖励名称
-     * @param itemId 奖励ID（可选）
-     * @param itemCount 奖励数量（可选）
-     * @param itemMoney 奖励单价（可选）
+     * 广告展示成功
+     * @param adScene 广告场景
      */
-    public stageOnRunningAward(
-        stageId: string,
-        stageName: string,
-        itemName: string,
-        itemId?: string,
-        itemCount?: number,
-        itemMoney?: number
-    ): void {
-        if (!this._isEnabled || !this._sdkStage) return;
-        try {
-            const params: StageRunningParams = {
-                stageId,
-                stageName,
-                event: StageRunningEventType.Award,
-                params: { itemName, itemId, itemCount, itemMoney },
-            };
-            this._sdkStage.onRunning(params);
-            LogUtils.Instance.info(AnalyticsMgr.TAG, "关卡获得奖励", {
-                operation: "stageOnRunningAward",
-                stageId,
-                stageName,
-                itemName,
-                itemId,
-                itemCount,
-                itemMoney,
-            });
-        } catch (e) {
-            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
-                operation: "stageOnRunningAward",
-                reason: String(e),
-                stageId,
-                stageName,
-                itemName,
-            });
-        }
+    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();
     }
 }