@chiyou/minigame-framework 1.3.9 → 1.4.1

package/package.json

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

package/src/Framework/Definition/AnalyticsDefinition.ts

@@ -10,6 +10,18 @@ import { PlatformID } from "./SystemDefinition";
 /** 事件参数类型 */
 export type EventParams = Record<string, string | number | boolean> | string;
 
+/** 通用属性（trackEvent 自动合并） */
+export interface CommonParams {
+    /** 游戏编号：6 */
+    app_index: number;
+    /** 游戏名称：点点方块三连消 */
+    app_name: string;
+    /** 平台标识：2（PlatformID数值） */
+    platform_id: number;
+    /** 游戏版本：3.5.1 */
+    app_version: string;
+}
+
 // ==================== 配置接口 ====================
 
 /** 友盟统计配置 */
@@ -20,88 +32,14 @@ export interface UmengConfig {
 
 // ==================== SDK 类型声明 ====================
 
-/** 关卡结束事件类型 */
-export enum StageEventType {
-    /** 关卡完成 */
-    Complete = "complete",
-    /** 关卡失败 */
-    Fail = "fail",
-}
-
-/** 关卡中行为事件类型 */
-export enum StageRunningEventType {
-    /** 使用道具 */
-    Tools = "tools",
-    /** 获得奖励 */
-    Award = "award",
-}
-
-/** 关卡开始参数 */
-export interface StageStartParams {
-    /** 关卡ID（必传，string类型） */
-    stageId: string;
-    /** 关卡名称（必传） */
-    stageName: string;
-}
-
-/** 关卡结束参数 */
-export interface StageEndParams {
-    /** 关卡ID（必传，string类型） */
-    stageId: string;
-    /** 关卡名称（必传） */
-    stageName: string;
-    /** 关卡结束结果（必传，complete/fail） */
-    event: StageEventType;
-    /** 关卡耗时（毫秒，可选） */
-    _um_sdu?: number;
-}
-
-/** 关卡中行为事件参数 */
-export interface StageRunningParams {
-    /** 关卡ID（必传，string类型） */
-    stageId: string;
-    /** 关卡名称（必传） */
-    stageName: string;
-    /** 事件类型（必传，tools/award） */
-    event: StageRunningEventType;
-    /** 事件参数 */
-    params?: StageRunningItemParams;
-}
-
-/** 关卡中行为物品参数 */
-export interface StageRunningItemParams {
-    /** 商品/道具名称（必传） */
-    itemName: string;
-    /** 商品/道具ID（可选） */
-    itemId?: string;
-    /** 商品/道具数量（可选） */
-    itemCount?: number;
-    /** 商品/道具单价（可选） */
-    itemMoney?: number;
-    /** 描述（可选） */
-    desc?: string;
-}
-
-/** 友盟关卡 SDK 接口 */
-export interface UmaStageSDK {
-    /** 关卡开始 */
-    onStart(params: StageStartParams): void;
-    /** 关卡结束 */
-    onEnd(params: StageEndParams): void;
-    /** 关卡中行为 */
-    onRunning(params: StageRunningParams): void;
-}
-
 /**
  * 友盟 SDK 接口定义
  * 
- * 仅包含实际可用的方法（共12个）
+ * 仅包含实际可用的方法（共11个）
  * 已移除：removeUserid, setUserInfo, setAnonymousid, setAppVersion, setSuperProperty（不可用）
  * 已移除：revenue, stage, level, rc（插件方法）
  * 
  * 使用方式：SDK 在 game.js 中初始化后，通过 wx.uma 全局实例访问
- * 
- * 关卡行为上报通过 wx.uma.stage 对象访问
  */
 export interface UmaSDK {
     /** 恢复会话（onShow 时调用） */
@@ -126,8 +64,6 @@ export interface UmaSDK {
     onShareAppMessage(callback: () => object): void;
     /** 调用分享 */
     shareAppMessage(options: object): void;
-    /** 关卡行为上报（stage 对象） */
-    stage: UmaStageSDK;
 }
 
 // ==================== 预定义事件 ID ====================

package/src/Framework/Manager/AnalyticsMgr.ts

@@ -3,9 +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, UmaStageSDK, StageEventType, StageRunningEventType, StageEndParams, StageRunningParams } from "../Definition/AnalyticsDefinition";
+import { UmengConfig, EventParams, AnalyticsEventId, AnalyticsParamKey, UmaSDK, CommonParams } from "../Definition/AnalyticsDefinition";
 import { EventMgr } from "./EventMgr";
 import { FrameworkBase } from "../Definition/FrameworkBase";
+import type { SystemMgr } from "./SystemMgr";
 
 export class AnalyticsMgr extends BaseMgr {
     /** 单例实例 */
@@ -19,8 +20,8 @@ export class AnalyticsMgr extends BaseMgr {
     private _isEnabled: boolean = false;
     /** 当前平台对应的 SDK 实例（通过 wx.uma 全局访问） */
     private _sdk: UmaSDK = null;
-    /** 关卡 SDK 实例 */
-    private _stageSdk: UmaStageSDK = null;
+    /** 通用属性（trackEvent 自动合并） */
+    private _commonParams: CommonParams = null;
 
     onLoad(): void {
         super.onLoad();
@@ -71,12 +72,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._stageSdk = this._sdk?.stage || null;
             this._isEnabled = !!this._sdk;
         } else {
             this._isEnabled = false;
@@ -85,7 +94,11 @@ export class AnalyticsMgr extends BaseMgr {
             });
         }
 
+        // 自动初始化通用属性（从 SystemMgr 获取 appIndex/appName/platformID/appVersion）
+        this._initCommonParams();
+
         this._isInited = true;
+
         LogUtils.Instance.info(AnalyticsMgr.TAG, "初始化完成", {
             enabled: this._isEnabled,
             platformID: PlatformID[platformID],
@@ -123,17 +136,57 @@ export class AnalyticsMgr extends BaseMgr {
     // ==================== 生命周期 ====================
     // 注意：SDK 在 game.js 中已自动注册 wx.onShow/wx.onHide 的 resume/pause 调用
 
+    // ==================== 通用属性 ====================
+
+    /**
+     * 初始化通用属性（由 init() 内部调用）
+     * 
+     * 自动从 SystemMgr 获取 appIndex/appName/platformID/appVersion，
+     * 后续所有 trackEvent 调用自动合并这些属性。
+     * 合并规则：通用属性与自定义属性同级平铺，自定义属性可覆盖同名通用属性。
+     * 
+     * 友盟 SDK 的 setSuperProperty 在小游戏环境不可用，需在框架封装层实现。
+     */
+    private _initCommonParams(): void {
+        const systemMgr = ServiceLocator.Instance.get("SystemMgr") as SystemMgr;
+        if (!systemMgr) {
+            LogUtils.Instance.warn(AnalyticsMgr.TAG, "SystemMgr未注册，跳过通用属性初始化");
+            return;
+        }
+
+        const appItem = systemMgr.getAppItem();
+        if (!appItem) {
+            LogUtils.Instance.warn(AnalyticsMgr.TAG, "AppItem未设置，跳过通用属性初始化");
+            return;
+        }
+
+        const platformID: PlatformID = BaseMgr.Instance.getCurrentPlatformID();
+        this._commonParams = {
+            app_index: appItem.appIndex,
+            app_name: appItem.appName,
+            platform_id: platformID,
+            app_version: systemMgr.getAppVersion(),
+        };
+
+        LogUtils.Instance.info(AnalyticsMgr.TAG, "通用属性初始化", {
+            operation: "_initCommonParams",
+            ...this._commonParams,
+        });
+    }
+
     // ==================== 事件上报 ====================
 
     /**
      * 上报自定义事件
+     * 自动合并通用属性（通用属性在前，自定义属性在后，自定义属性可覆盖同名通用属性）
      * @param eventId 事件 ID
      * @param params 事件参数
      */
     public trackEvent(eventId: string | AnalyticsEventId, params?: EventParams): void {
         if (!this._isEnabled) return;
         try {
-            this._sdk.trackEvent(eventId, params);
+            const mergedParams = this._mergeCommonParams(params);
+            this._sdk.trackEvent(eventId, mergedParams);
             LogUtils.Instance.info(AnalyticsMgr.TAG, "事件上报", {
                 eventId: eventId,
             });
@@ -262,157 +315,6 @@ export class AnalyticsMgr extends BaseMgr {
         this.trackEvent(AnalyticsEventId.AdClick, params);
     }
 
-    // ==================== 关卡行为上报（友盟 stage 接口） ====================
-
-    /**
-     * 关卡开始
-     * @param stageId 关卡ID（string类型）
-     * @param stageName 关卡名称
-     */
-    public stageOnStart(stageId: string, stageName: string): void {
-        if (!this._isEnabled || !this._stageSdk) return;
-        try {
-            this._stageSdk.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,
-            });
-        }
-    }
-
-    /**
-     * 关卡结束
-     * @param stageId 关卡ID（string类型）
-     * @param stageName 关卡名称
-     * @param event 结束结果（"complete" | "fail")
-     * @param duration 关卡耗时（毫秒，可选）
-     */
-    public stageOnEnd(stageId: string, stageName: string, event: StageEventType, duration?: number): void {
-        if (!this._isEnabled || !this._stageSdk) return;
-        try {
-            const params: StageEndParams = { stageId, stageName, event };
-            if (duration !== undefined) {
-                params._um_sdu = duration;
-            }
-            this._stageSdk.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,
-            });
-        }
-    }
-
-    /**
-     * 关卡中行为 - 使用道具
-     * @param stageId 关卡ID（string类型）
-     * @param stageName 关卡名称
-     * @param itemName 道具名称
-     * @param itemId 道具ID（可选）
-     * @param itemCount 道具数量（可选）
-     * @param itemMoney 道具单价（可选）
-     */
-    public stageOnRunningTools(
-        stageId: string,
-        stageName: string,
-        itemName: string,
-        itemId?: string,
-        itemCount?: number,
-        itemMoney?: number
-    ): void {
-        if (!this._isEnabled || !this._stageSdk) return;
-        try {
-            const params: StageRunningParams = {
-                stageId,
-                stageName,
-                event: StageRunningEventType.Tools,
-                params: { itemName, itemId, itemCount, itemMoney },
-            };
-            this._stageSdk.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,
-            });
-        }
-    }
-
-    /**
-     * 关卡中行为 - 获得奖励
-     * @param stageId 关卡ID（string类型）
-     * @param stageName 关卡名称
-     * @param itemName 奖励名称
-     * @param itemId 奖励ID（可选）
-     * @param itemCount 奖励数量（可选）
-     * @param itemMoney 奖励单价（可选）
-     */
-    public stageOnRunningAward(
-        stageId: string,
-        stageName: string,
-        itemName: string,
-        itemId?: string,
-        itemCount?: number,
-        itemMoney?: number
-    ): void {
-        if (!this._isEnabled || !this._stageSdk) return;
-        try {
-            const params: StageRunningParams = {
-                stageId,
-                stageName,
-                event: StageRunningEventType.Award,
-                params: { itemName, itemId, itemCount, itemMoney },
-            };
-            this._stageSdk.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,
-            });
-        }
-    }
-
     // ==================== 状态查询 ====================
 
     /** 是否已初始化 */
@@ -433,4 +335,20 @@ export class AnalyticsMgr extends BaseMgr {
         if (typeof params === "string") return { value: params };
         return params as Record<string, any>;
     }
+
+    /** 合并通用属性与自定义属性（通用属性在前，自定义属性在后，自定义属性可覆盖） */
+    private _mergeCommonParams(customParams?: EventParams): Record<string, any> | undefined {
+        const customObj = this._flattenParams(customParams);
+        
+        // 无通用属性时直接返回自定义属性
+        if (!this._commonParams) {
+            return customObj;
+        }
+        
+        // 合并：通用属性在前，自定义属性在后（自定义属性可覆盖同名通用属性）
+        return {
+            ...this._commonParams,
+            ...customObj,
+        };
+    }
 }

package/src/Framework/Manager/SystemMgr.ts

@@ -25,11 +25,13 @@ export class SystemMgr extends BaseMgr {
     static TAG: string = "SystemMgr";
 
     /** 应用配置 */
-    private appItem: AppItem = null;
+    private _appItem: AppItem = null;
     /** 版权信息 */
-    private copyrightInfo: CopyrightInfo = null;
+    private _copyrightInfo: CopyrightInfo = null;
     /** 是否本地游戏 */
-    private localGame: boolean = true;
+    private _localGame: boolean = true;
+    /** 游戏版本号 */
+    private _appVersion: string = "";
 
     onLoad(): void {
         super.onLoad();
@@ -48,8 +50,9 @@ export class SystemMgr extends BaseMgr {
      * 初始化系统管理器
      * @param appItem 应用配置
      * @param copyrightInfo 版权信息
+     * @param appVersion 游戏版本号（如 '3.5.1'）
      */
-    public init(appItem: AppItem, copyrightInfo: CopyrightInfo): void {
+    public init(appItem: AppItem, copyrightInfo: CopyrightInfo, appVersion: string): void {
         if (!appItem) {
             LogUtils.Instance.error(SystemMgr.TAG, FwkErrorCode.System.ConfigError, {
                 operation: "init",
@@ -66,19 +69,20 @@ export class SystemMgr extends BaseMgr {
             });
         }
 
-        this.appItem = appItem;
-        this.copyrightInfo = copyrightInfo;
+        this._appItem = appItem;
+        this._copyrightInfo = copyrightInfo;
+        this._appVersion = appVersion;
 
         let currPlatformID: PlatformID = BaseMgr.Instance.getCurrentPlatformID();
 
-        if (this.copyrightInfo && this.copyrightInfo.icpMap &&
-            this.copyrightInfo.icpMap.has(currPlatformID)) {
-            let icpItem: ICPItem = this.copyrightInfo.icpMap.get(currPlatformID);
+        if (this._copyrightInfo && this._copyrightInfo.icpMap &&
+            this._copyrightInfo.icpMap.has(currPlatformID)) {
+            let icpItem: ICPItem = this._copyrightInfo.icpMap.get(currPlatformID);
             if (icpItem !== null) {
-                this.localGame = icpItem.isLocalGame;
+                this._localGame = icpItem.isLocalGame;
             }
         } else if (currPlatformID === PlatformID.ID_H5_DesktopBrowser) {
-            this.localGame = false;
+            this._localGame = false;
         }
 
         let platformAdapterImpl: AbsPlatformAdapter = null;
@@ -131,13 +135,14 @@ export class SystemMgr extends BaseMgr {
         }
 
         LogUtils.Instance.info(SystemMgr.TAG, "初始化完成", {
-            appName: this.appItem?.appName || "未设置",
-            appIndex: this.appItem?.appIndex || "未设置",
-            platformCount: this.appItem?.appIDMap?.size || 0,
+            appName: this._appItem?.appName || "未设置",
+            appIndex: this._appItem?.appIndex || "未设置",
+            platformCount: this._appItem?.appIDMap?.size || 0,
             platformID: currPlatformID,
             platformName: PlatformID[currPlatformID],
-            appID: this.appItem?.appIDMap?.get(currPlatformID) || "未配置",
-            isLocalGame: this.localGame
+            appID: this._appItem?.appIDMap?.get(currPlatformID) || "未配置",
+            isLocalGame: this._localGame,
+            appVersion: this._appVersion,
         });
     }
 
@@ -146,7 +151,7 @@ export class SystemMgr extends BaseMgr {
      * @return 应用配置
      */
     public getAppItem(): AppItem {
-        return this.appItem;
+        return this._appItem;
     }
 
     /**
@@ -154,7 +159,15 @@ export class SystemMgr extends BaseMgr {
      * @return 是否本地游戏
      */
     public isLocalGame(): boolean {
-        return this.localGame;
+        return this._localGame;
+    }
+
+    /**
+     * 获取游戏版本号
+     * @return 游戏版本号
+     */
+    public getAppVersion(): string {
+        return this._appVersion;
     }
 
     /**