@chiyou/minigame-framework 1.3.7 → 1.3.8

package/package.json

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

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

@@ -4,6 +4,8 @@ import { FwkErrorCode } from '../../Definition/FwkErrorDefinition';
 import { AuthorizeResult, GetSettingResult } from '../../Definition/PrivacyDefinition';
 import { ScreenInfo } from '../../Definition/SystemDefinition';
 import { AdMgr } from '../../Manager/AdMgr';
+import { ServiceLocator } from '../../Utils/ServiceLocator';
+import type { AnalyticsMgr } from '../../Manager/AnalyticsMgr';
 
 class PortalGame {
     pageManager: any;
@@ -93,6 +95,7 @@ export class PlatformAdapterWeiXin extends AbsPlatformAdapter {
 
     private business: WeiXinPlatformBusiness = new WeiXinPlatformBusiness();
 
+    private analyticsMgr: AnalyticsMgr = null;
     // Common
     public init(): void {
 
@@ -296,11 +299,21 @@ export class PlatformAdapterWeiXin extends AbsPlatformAdapter {
             window["wx"].onShareAppMessage(() => {
                 this.isShareActive = true;
 
-                return {
+                let shareParam = {
                     title: title,
                     imageUrl: imageUrl,
                     imageUrlId: templateId, 
                     query: query,
+                };
+
+                if (this.analyticsMgr === null) {
+                    this.analyticsMgr = ServiceLocator.Instance.get<AnalyticsMgr>("AnalyticsMgr");
+                }
+
+                if (this.analyticsMgr && this.analyticsMgr.isEnabled) {
+                    return this.analyticsMgr.trackShare(shareParam);
+                } else {
+                    return shareParam;
                 }
             });
         }
@@ -331,13 +344,24 @@ export class PlatformAdapterWeiXin extends AbsPlatformAdapter {
             });
 
             this.isShareActive = true;
-            // onShow回调
-            window["wx"].shareAppMessage({
+
+            let shareParam = {
                 title: title,
                 imageUrl: imageUrl,
                 imageUrlId: templateId,
                 query: query,
-            });
+            };
+
+            if (this.analyticsMgr === null) {
+                this.analyticsMgr = ServiceLocator.Instance.get<AnalyticsMgr>("AnalyticsMgr");
+            }
+            // onShow回调
+            if (this.analyticsMgr && this.analyticsMgr.isEnabled) {
+                let data = this.analyticsMgr.trackShare(shareParam);
+                window["wx"].shareAppMessage(data);
+            } else {
+                window["wx"].shareAppMessage(shareParam);
+            }
         }
     }
 

package/src/Framework/Definition/AnalyticsDefinition.ts

@@ -20,6 +20,78 @@ 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 接口定义
  * 
@@ -28,6 +100,8 @@ export interface UmengConfig {
  * 已移除：revenue, stage, level, rc（插件方法）
  * 
  * 使用方式：SDK 在 game.js 中初始化后，通过 wx.uma 全局实例访问
+ * 
+ * 关卡行为上报通过 wx.uma.stage 对象访问
  */
 export interface UmaSDK {
     /** 恢复会话（onShow 时调用） */
@@ -52,15 +126,14 @@ export interface UmaSDK {
     onShareAppMessage(callback: () => object): void;
     /** 调用分享 */
     shareAppMessage(options: object): void;
+    /** 关卡行为上报（stage 对象） */
+    stage: UmaStageSDK;
 }
 
 // ==================== 预定义事件 ID ====================
 
 /** 预定义事件 ID */
 export enum AnalyticsEventId {
-    LevelStart = "level_start",
-    LevelComplete = "level_complete",
-    LevelFail = "level_fail",
     AdShow = "ad_show",
     AdClick = "ad_click",
     AdComplete = "ad_complete",
@@ -75,7 +148,6 @@ export enum AnalyticsEventId {
 
 /** 事件参数键名 */
 export enum AnalyticsParamKey {
-    Level = "level",
     Score = "score",
     Duration = "duration",
     Reason = "reason",

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 } from "../Definition/AnalyticsDefinition";
+import { UmengConfig, EventParams, AnalyticsEventId, AnalyticsParamKey, UmaSDK, UmaStageSDK, StageEventType, StageRunningEventType, StageEndParams, StageRunningParams } from "../Definition/AnalyticsDefinition";
 import { EventMgr } from "./EventMgr";
 import { FrameworkBase } from "../Definition/FrameworkBase";
 
@@ -19,6 +19,8 @@ export class AnalyticsMgr extends BaseMgr {
     private _isEnabled: boolean = false;
     /** 当前平台对应的 SDK 实例（通过 wx.uma 全局访问） */
     private _sdk: UmaSDK = null;
+    /** 关卡 SDK 实例 */
+    private _stageSdk: UmaStageSDK = null;
 
     onLoad(): void {
         super.onLoad();
@@ -74,6 +76,7 @@ export class AnalyticsMgr extends BaseMgr {
         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;
@@ -223,37 +226,21 @@ export class AnalyticsMgr extends BaseMgr {
         }
     }
 
-    // ==================== 游戏特定事件 ====================
-
-    /** 关卡开始 */
-    public trackLevelStart(level: string | number, extraParams?: EventParams): void {
-        const params: Record<string, any> = {
-            [AnalyticsParamKey.Level]: level,
-            ...this._flattenParams(extraParams),
-        };
-        this.trackEvent(AnalyticsEventId.LevelStart, params);
-    }
-
-    /** 关卡完成 */
-    public trackLevelComplete(level: string | number, score?: number, duration?: number, extraParams?: EventParams): void {
-        const params: Record<string, any> = {
-            [AnalyticsParamKey.Level]: level,
-            ...(score !== undefined ? { [AnalyticsParamKey.Score]: score } : {}),
-            ...(duration !== undefined ? { [AnalyticsParamKey.Duration]: duration } : {}),
-            ...this._flattenParams(extraParams),
-        };
-        this.trackEvent(AnalyticsEventId.LevelComplete, params);
+    /** 调用友盟 trackShare，返回带统计参数的分享对象 */
+    public trackShare(shareOptions: object): object | null {
+        if (!this._isEnabled) return null;
+        try {
+            return this._sdk.trackShare(shareOptions);
+        } catch (e) {
+            LogUtils.Instance.error(AnalyticsMgr.TAG, FwkErrorCode.Analytics.SDKCallFailed, {
+                operation: "trackShare",
+                reason: String(e),
+            });
+            return null;
+        }
     }
 
-    /** 关卡失败 */
-    public trackLevelFail(level: string | number, reason?: string, extraParams?: EventParams): void {
-        const params: Record<string, any> = {
-            [AnalyticsParamKey.Level]: level,
-            ...(reason ? { [AnalyticsParamKey.Reason]: reason } : {}),
-            ...this._flattenParams(extraParams),
-        };
-        this.trackEvent(AnalyticsEventId.LevelFail, params);
-    }
+    // ==================== 游戏特定事件 ====================
 
     /** 广告展示 */
     public trackAdShow(adType: string, adId: string, extraParams?: EventParams): void {
@@ -275,13 +262,155 @@ export class AnalyticsMgr extends BaseMgr {
         this.trackEvent(AnalyticsEventId.AdClick, params);
     }
 
-    /** 分享 */
-    public trackShare(shareType: string, shareContent?: string): void {
-        const params: Record<string, any> = {
-            [AnalyticsParamKey.ShareType]: shareType,
-            ...(shareContent ? { [AnalyticsParamKey.ShareContent]: shareContent } : {}),
-        };
-        this.trackEvent(AnalyticsEventId.Share, 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,
+            });
+        }
     }
 
     // ==================== 状态查询 ====================