@chiyou/minigame-framework 1.3.8 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chiyou/minigame-framework",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "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;
+}
+
 // ==================== 配置接口 ====================
 
 /** 友盟统计配置 */
@@ -83,7 +95,7 @@ export interface StageRunningItemParams {
 }
 
 /** 友盟关卡 SDK 接口 */
-export interface UmaStageSDK {
+export interface UmaSDKStage {
     /** 关卡开始 */
     onStart(params: StageStartParams): void;
     /** 关卡结束 */
@@ -127,7 +139,7 @@ export interface UmaSDK {
     /** 调用分享 */
     shareAppMessage(options: object): void;
     /** 关卡行为上报（stage 对象） */
-    stage: UmaStageSDK;
+    stage: UmaSDKStage;
 }
 
 // ==================== 预定义事件 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, StageEventType, StageRunningEventType, StageEndParams, StageRunningParams, CommonParams, UmaSDKStage } from "../Definition/AnalyticsDefinition";
 import { EventMgr } from "./EventMgr";
 import { FrameworkBase } from "../Definition/FrameworkBase";
+import { SystemMgr } from "./SystemMgr";
 
 export class AnalyticsMgr extends BaseMgr {
     /** 单例实例 */
@@ -20,7 +21,9 @@ export class AnalyticsMgr extends BaseMgr {
     /** 当前平台对应的 SDK 实例（通过 wx.uma 全局访问） */
     private _sdk: UmaSDK = null;
     /** 关卡 SDK 实例 */
-    private _stageSdk: UmaStageSDK = null;
+    private _sdkStage: UmaSDKStage = null;
+    /** 通用属性（trackEvent 自动合并） */
+    private _commonParams: CommonParams = null;
 
     onLoad(): void {
         super.onLoad();
@@ -76,7 +79,7 @@ export class AnalyticsMgr extends BaseMgr {
         if (enabled) {
             // 从全局获取 SDK 实例（在 game.js 中初始化后挂载到 wx.uma）
             this._sdk = this._getGlobalSDK();
-            this._stageSdk = this._sdk?.stage || null;
+            this._sdkStage = this._sdk?.stage || null;
             this._isEnabled = !!this._sdk;
         } else {
             this._isEnabled = false;
@@ -85,7 +88,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 +130,58 @@ export class AnalyticsMgr extends BaseMgr {
     // ==================== 生命周期 ====================
     // 注意：SDK 在 game.js 中已自动注册 wx.onShow/wx.onHide 的 resume/pause 调用
 
+    // ==================== 通用属性 ====================
+
+    /**
+     * 初始化通用属性（由 init() 内部调用）
+     * 
+     * 自动从 SystemMgr 获取 appIndex/appName/platformID/appVersion，
+     * 后续所有 trackEvent 调用自动合并这些属性。
+     * 合并规则：通用属性与自定义属性同级平铺，自定义属性可覆盖同名通用属性。
+     * 
+     * 注意：仅适用于 trackEvent，不适用于 stage 系列接口。
+     * 友盟 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,
             });
@@ -270,9 +318,9 @@ export class AnalyticsMgr extends BaseMgr {
      * @param stageName 关卡名称
      */
     public stageOnStart(stageId: string, stageName: string): void {
-        if (!this._isEnabled || !this._stageSdk) return;
+        if (!this._isEnabled || !this._sdkStage) return;
         try {
-            this._stageSdk.onStart({ stageId, stageName });
+            this._sdkStage.onStart({ stageId, stageName });
             LogUtils.Instance.info(AnalyticsMgr.TAG, "关卡开始", {
                 operation: "stageOnStart",
                 stageId,
@@ -296,13 +344,13 @@ export class AnalyticsMgr extends BaseMgr {
      * @param duration 关卡耗时（毫秒，可选）
      */
     public stageOnEnd(stageId: string, stageName: string, event: StageEventType, duration?: number): void {
-        if (!this._isEnabled || !this._stageSdk) return;
+        if (!this._isEnabled || !this._sdkStage) return;
         try {
             const params: StageEndParams = { stageId, stageName, event };
             if (duration !== undefined) {
                 params._um_sdu = duration;
             }
-            this._stageSdk.onEnd(params);
+            this._sdkStage.onEnd(params);
             LogUtils.Instance.info(AnalyticsMgr.TAG, "关卡结束", {
                 operation: "stageOnEnd",
                 stageId,
@@ -338,7 +386,7 @@ export class AnalyticsMgr extends BaseMgr {
         itemCount?: number,
         itemMoney?: number
     ): void {
-        if (!this._isEnabled || !this._stageSdk) return;
+        if (!this._isEnabled || !this._sdkStage) return;
         try {
             const params: StageRunningParams = {
                 stageId,
@@ -346,7 +394,7 @@ export class AnalyticsMgr extends BaseMgr {
                 event: StageRunningEventType.Tools,
                 params: { itemName, itemId, itemCount, itemMoney },
             };
-            this._stageSdk.onRunning(params);
+            this._sdkStage.onRunning(params);
             LogUtils.Instance.info(AnalyticsMgr.TAG, "关卡使用道具", {
                 operation: "stageOnRunningTools",
                 stageId,
@@ -384,7 +432,7 @@ export class AnalyticsMgr extends BaseMgr {
         itemCount?: number,
         itemMoney?: number
     ): void {
-        if (!this._isEnabled || !this._stageSdk) return;
+        if (!this._isEnabled || !this._sdkStage) return;
         try {
             const params: StageRunningParams = {
                 stageId,
@@ -392,7 +440,7 @@ export class AnalyticsMgr extends BaseMgr {
                 event: StageRunningEventType.Award,
                 params: { itemName, itemId, itemCount, itemMoney },
             };
-            this._stageSdk.onRunning(params);
+            this._sdkStage.onRunning(params);
             LogUtils.Instance.info(AnalyticsMgr.TAG, "关卡获得奖励", {
                 operation: "stageOnRunningAward",
                 stageId,
@@ -433,4 +481,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;
     }
 
     /**

package/src/Framework/Manager/UIMgr.ts

@@ -474,9 +474,11 @@ export class UIMgr extends BaseMgr {
         labelComponent.string = content;
         labelComponent.updateRenderData(true);
         let textWidth: number = labelComponent.node.getComponent(UITransform).contentSize.width;
+        let textHeight: number = labelComponent.node.getComponent(UITransform).contentSize.height;
 
         this.node_toastRoot.active = true;
         this.node_toastRoot.getComponent(UITransform).width = textWidth + 80;
+        this.node_toastRoot.getComponent(UITransform).height = textHeight + 40;
 
         // 设置 Toast 位置
         if (position !== undefined) {