keytops-game-framework 1.0.26 → 2.1.0

package/README.md

@@ -1,5 +1,18 @@
 # keytops-game-framework
 
+## 2.0 Analytics 迁移
+
+从 2.0.0 开始，`App.launch()` 不再自动启用统计。游戏必须在框架启动完成后、首次访问 `analytics.launch`、`analytics.level`、`analytics.ad`、`analytics.session` 或 `analytics.social` 前显式初始化：
+
+```typescript
+await App.launch(true, { injects: [] });
+analytics.enable(true, [sender]);
+```
+
+`IAnalyticsSender.userPropertyMode` 默认为 `event`，原有 Sender 会继续将用户属性合并到事件。需要使用平台原生用户属性能力的 Sender 应设置为 `sender`，并实现 `setUserProperty()`；这类用户属性不会再重复写入事件参数。
+
+2.0.0 同时将 Analytics 内部公共字段改为可跨平台使用的合法名称，例如 `_dt_` 改为 `duration`、`_av_` 改为 `app_version`。本版本不再双写旧字段，依赖旧字段的报表和查询需要同步迁移。
+
 `keytops-game-framework` 是面向 Cocos Creator 项目的游戏开发框架，提供应用生命周期、网络通信、平台能力、存储、计时器、ECS、FSM、任务、埋点、视图、资源和音频等基础设施。这个包定位于框架层，适合需要直接使用底层模块和引擎适配能力的项目，不是精简 facade SDK。
 
 ## 适用场景

package/dist/app/module/analytics/ALiAnalyticsSender.d.ts

@@ -1,4 +1,4 @@
-import { EmptyAnalyticsSender } from "./AnalyticsAble";
+import { AnalyticsEventData, AnalyticsMappedEvent, AnalyticsUserProperties, EmptyAnalyticsSender } from "./AnalyticsAble";
 /**
  * 阿里云日志时间配置
  */
@@ -55,5 +55,6 @@ export declare class ALiAnalyticsSender extends EmptyAnalyticsSender {
     private _addListen;
     private _restoreEvents;
     protected _doReport(maxCount?: number, store?: boolean): boolean;
-    send(eventName: string, data: any): Promise<void>;
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+    send(eventName: string, eventData: AnalyticsEventData, userProperties: AnalyticsUserProperties): Promise<void>;
 }

package/dist/app/module/analytics/AnalyticsAble.d.ts

@@ -1,7 +1,23 @@
 /**
  * 上报数据通用格式定义,方便项目间的通用数据统计
  */
-export type AnalyticsData = {
+export type AnalyticsScalar = string | boolean | number;
+export type AnalyticsItemData = {
+    itemId: string;
+    itemName?: string;
+    itemCategory?: string;
+    price: number;
+    quantity?: number;
+    [key: string]: AnalyticsScalar;
+};
+export type AnalyticsEventValue = AnalyticsScalar | AnalyticsItemData[];
+export type AnalyticsEventData = {
+    [key: string]: AnalyticsEventValue;
+};
+export type AnalyticsUserProperties = {
+    [key: string]: AnalyticsScalar;
+};
+export type AnalyticsData = AnalyticsEventData & {
     /**
      * 标记型ID，可用于关卡id、道具\装备id、广告id等的标记
      */
@@ -26,7 +42,11 @@ export type AnalyticsData = {
      * number类型，定义偏向计数数值，可以用于模型行为的计数、数量等。
      */
     count?: number;
-    [key: string]: string | boolean | number;
+    [key: string]: AnalyticsEventValue;
+};
+export type AnalyticsMappedEvent = {
+    eventName: string;
+    data: AnalyticsEventData;
 };
 export interface IAnalyticsSender {
     /**
@@ -44,7 +64,15 @@ export interface IAnalyticsSender {
      * @param eventName 事件名称
      * @param data 事件数据
      */
-    send(eventName: string, data: any): Promise<void>;
+    send(eventName: string, eventData: AnalyticsEventData, userProperties: AnalyticsUserProperties): Promise<void>;
+    /**
+     * 将框架语义事件转换成统计平台的物理事件。
+     */
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+    /**
+     * 设置平台用户标识。
+     */
+    setUserId?(userId: string | null): void;
 }
 export declare class EmptyAnalyticsSender implements IAnalyticsSender {
     protected _exclude: string[];
@@ -58,7 +86,8 @@ export declare class EmptyAnalyticsSender implements IAnalyticsSender {
      */
     exclude(...excludeList: string[]): void;
     sendAble(eventName: string): boolean;
-    send(eventName: string, data: any): Promise<void>;
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+    send(eventName: string, eventData: AnalyticsEventData, userProperties: AnalyticsUserProperties): Promise<void>;
 }
 /**
  * 统计分析能力
@@ -71,19 +100,22 @@ export declare class AnalyticsAble {
     protected _senderList: IAnalyticsSender[];
     protected _staticProperties: AnalyticsData;
     protected _dynamicCalls: (() => AnalyticsData)[];
-    protected _userProperties: AnalyticsData;
-    protected _userOnceProperties: AnalyticsData;
-    protected _userAddProperties: AnalyticsData;
+    protected _userProperties: AnalyticsUserProperties;
+    protected _userOnceProperties: AnalyticsUserProperties;
+    protected _userAddProperties: AnalyticsUserProperties;
     protected _timeEvents: Map<string, {
         start: number;
         once: boolean;
         offset: number;
     }>;
+    private _userId;
+    private _hasSetUserId;
     /**
      * 初始化
      */
     init(senders: IAnalyticsSender[], debugMode?: boolean): AnalyticsAble;
     private _initSenderList;
+    private _getUserProperties;
     /**
      * 设置排除
      * @param excludeEvents 排除事件名称或者名称列表。
@@ -115,6 +147,10 @@ export declare class AnalyticsAble {
      * @param dynamicCall 动态属性的生成函数，事件上报时实时调用
      */
     setDynamicProperties(dynamicCall: () => AnalyticsData): void;
+    /**
+     * 设置平台用户标识。该值不会自动作为事件参数发送。
+     */
+    setUserId(userId: string | null): void;
     /**
      * 对于一般的用户属性，您可以调用 userSet 来进行设置。
      * 使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致。
@@ -168,7 +204,7 @@ export declare class AnalyticsAble {
     /**
      * 开始事件计时
      * 如果您需要记录某个事件的持续时长，可以调用 timeEvent 来开始计时。
-     * 配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 _dt_ 这一属性来表示记录的时长，单位为秒。
+     * 配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 duration 属性来表示记录的时长，单位为秒。
      * 需要注意的是，同一个事件名只能有一个在计时的任务。
      * @param eventName
      */
@@ -187,5 +223,5 @@ export declare class AnalyticsAble {
     report(eventName: string, data?: AnalyticsData): Promise<void>;
     private _sendAble;
     private _copyToData;
-    protected _sendReport(eventName: string, data: any): Promise<void>;
+    protected _sendReport(eventName: string, data: AnalyticsEventData): Promise<void>;
 }

package/dist/app/module/analytics/AnalyticsEvent.d.ts

@@ -0,0 +1,39 @@
+import { AnalyticsEventData, AnalyticsMappedEvent } from "./AnalyticsAble";
+/**
+ * 框架内部统一使用的业务语义事件名。
+ * Sender 负责将它们转换成统计平台实际接收的事件名和参数。
+ */
+export declare enum AnalyticsBehavior {
+    APP_LAUNCH = "app.launch",
+    APP_SHOW = "app.show",
+    APP_HIDE = "app.hide",
+    APP_ERROR = "app.error",
+    SESSION_LOGIN = "session.login",
+    LEVEL_START = "level.start",
+    LEVEL_END = "level.end",
+    LEVEL_PAUSE = "level.pause",
+    LEVEL_TIMEOUT = "level.timeout",
+    LEVEL_ITEM_USE = "level.item_use",
+    AD_LIFECYCLE = "ad.lifecycle",
+    AD_IMPRESSION = "ad.impression",
+    SOCIAL_SHARE = "social.share",
+    SOCIAL_SUBSCRIBE_SHOW = "social.subscribe_show",
+    SOCIAL_SUBSCRIBE = "social.subscribe",
+    TUTORIAL_BEGIN = "tutorial.begin",
+    TUTORIAL_COMPLETE = "tutorial.complete",
+    TUTORIAL_SKIP = "tutorial.skip",
+    PAY_BEGIN = "pay.begin",
+    PAY_PURCHASE = "pay.purchase",
+    PAY_PENDING = "pay.pending",
+    PAY_CANCEL = "pay.cancel",
+    PAY_FAIL = "pay.fail"
+}
+/**
+ * Keytops/Ali 当前服务端仍使用的物理协议。
+ * 兼容逻辑集中在 Sender 边界，业务层无需继续依赖旧事件字符串。
+ */
+export declare function mapCanonicalEventToLegacy(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+/**
+ * 小游戏平台通常不接受点号事件名，统一转换为下划线。
+ */
+export declare function mapCanonicalEventToFlatName(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;

package/dist/app/module/analytics/KeytopsAnalyticsSender.d.ts

@@ -1,4 +1,4 @@
-import { EmptyAnalyticsSender } from "./AnalyticsAble";
+import { AnalyticsEventData, AnalyticsMappedEvent, AnalyticsUserProperties, EmptyAnalyticsSender } from "./AnalyticsAble";
 export interface KeytopsAnalyticsConfig {
     /**
      * 上报地址
@@ -62,6 +62,7 @@ export declare class KeytopsAnalyticsSender extends EmptyAnalyticsSender {
     private _sendBatch;
     private _sendBatchWithRetry;
     protected _doReport(maxCount?: number, store?: boolean): Promise<boolean>;
-    send(eventName: string, data: any): Promise<void>;
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+    send(eventName: string, eventData: AnalyticsEventData, userProperties: AnalyticsUserProperties): Promise<void>;
 }
 export {};

package/dist/app/module/analytics/ad/ADBehaviorReporter.d.ts

@@ -86,5 +86,5 @@ export declare class ADBehaviorReporter {
      * @param from 广告来源
      * @param msg 广告失败原因
      */
-    report(type: ADType, event: ADEvent, from: AdFrom, msg?: string): void;
+    report(type: ADType, event: ADEvent, from: AdFrom, msg?: string, impression?: boolean): void;
 }

package/dist/app/module/analytics/firebase/FirebaseAnalyticsSender.d.ts

@@ -0,0 +1,39 @@
+import { AnalyticsEventData, AnalyticsMappedEvent, AnalyticsUserProperties, EmptyAnalyticsSender } from "../AnalyticsAble";
+export interface FirebaseAnalyticsSenderConfig {
+    /**
+     * 游戏工程内 FirebaseAnalyticsBridge 的完整 Java 类名。
+     */
+    bridgeClassName: string;
+    collectionEnabled?: boolean;
+    ignoredParameters?: string[];
+    maxParameters?: number;
+    /**
+     * Java Bridge 是否已支持把 items 转成 Bundle[]。
+     */
+    supportsStructuredItems?: boolean;
+    debug?: boolean;
+}
+/**
+ * Firebase Android Analytics 上报器。
+ *
+ * TS 端属于框架，Java Bridge 仍由具体游戏工程提供。非原生环境会安全忽略调用。
+ */
+export declare class FirebaseAnalyticsSender extends EmptyAnalyticsSender {
+    private readonly _config;
+    private readonly _ignoredParameters;
+    private _lastUserId;
+    private _lastUserProperties;
+    constructor(config: FirebaseAnalyticsSenderConfig, exclude?: string[]);
+    get canSend(): boolean;
+    setUserId(userId: string | null): void;
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+    send(eventName: string, eventData: AnalyticsEventData, userProperties: AnalyticsUserProperties): Promise<void>;
+    private mapParameters;
+    private syncUserProperties;
+    private setUserProperty;
+    private normalizeParameters;
+    private normalizeValue;
+    private isValidName;
+    private truncate;
+    private warn;
+}

package/dist/app/module/analytics/index.d.ts

@@ -4,10 +4,17 @@ import { LevelAnalyticsAble } from "./level/LevelAnalyticsAble";
 import { LaunchAnalyticsAble } from "./launch/LaunchAnalyticsAble";
 import { SessionAnalyticsAble } from "./session/SessionAnalyticsAble";
 import { SocialAnalyticsAble } from "./social/SocialAnalyticsAble";
+import { TutorialAnalyticsAble } from "./tutorial/TutorialAnalyticsAble";
+import { PayAnalyticsAble } from "./pay/PayAnalyticsAble";
 export * from "./AnalyticsAble";
+export * from "./AnalyticsEvent";
 export * from "./ALiAnalyticsSender";
 export * from "./KeytopsAnalyticsSender";
 export * from "./launch/LaunchAnalyticsAble";
+export * from "./social/SocialAnalyticsAble";
+export * from "./tutorial/TutorialAnalyticsAble";
+export * from "./pay/PayAnalyticsAble";
+export * from "./firebase/FirebaseAnalyticsSender";
 declare class AnalyticsManager {
     private hasRelayUrl;
     private hasAliDirectConfig;
@@ -42,6 +49,16 @@ declare class AnalyticsManager {
      * 社交统计能力
      */
     get social(): SocialAnalyticsAble;
+    private _tutorial;
+    /**
+     * 新手引导统计能力
+     */
+    get tutorial(): TutorialAnalyticsAble;
+    private _pay;
+    /**
+     * 支付漏斗统计能力
+     */
+    get pay(): PayAnalyticsAble;
     /**
      * 启用统计（基础统计能力）
      * @param debugMode 调试模式，是否打印日志信息，默认为false

package/dist/app/module/analytics/level/LevelAnalyticsAble.d.ts

@@ -28,7 +28,7 @@ export declare class LevelAnalyticsAble {
      * @param gameFlag 关卡所属玩法标识
      * @param params 关卡参数, 会从端口下发的配置level_config中获取, 也允许手动指定，其他未指定的字段会采用配置中的值。
      */
-    onStart(id: string, index: number, gameFlag?: string, data?: Omit<AnalyticsData, 'id' | 'index' | 'type' | 'progress' | 'code'>): Promise<void>;
+    onStart(id: string, index: number, gameFlag?: string, data?: Omit<AnalyticsData, 'levelId' | 'levelIndex' | 'gameId' | 'progress' | 'repeatCount'>): Promise<void>;
     /**
      * 记录用户操作(包括有效和无效操作)
      * @param progress 关卡进度 0.0 - 1.0

package/dist/app/module/analytics/level/LevelBehaviorReporter.d.ts

@@ -1,13 +1,13 @@
 import { AnalyticsAble, AnalyticsData } from "../AnalyticsAble";
 import { GameDimension } from "../level/GameDimension";
 export declare enum GameLeaveType {
-    success = "lv_success",
-    fail = "lv_fail",
-    leave = "lv_leave",
-    skip = "lv_skip",
-    revive = "lv_revive",
-    break = "lv_break",
-    retry = "lv_retry"
+    success = "success",
+    fail = "fail",
+    leave = "leave",
+    skip = "skip",
+    revive = "revive",
+    break = "break",
+    retry = "retry"
 }
 /**
  * 关卡行为自动上报器

package/dist/app/module/analytics/pay/PayAnalyticsAble.d.ts

@@ -0,0 +1,27 @@
+import { AnalyticsAble, AnalyticsData, AnalyticsItemData } from "../AnalyticsAble";
+export type AnalyticsPayItem = AnalyticsItemData;
+export type PayStage = "create_order" | "native_purchase" | "verify";
+export type PayEventData = AnalyticsData & {
+    transactionId: string;
+    currency: string;
+    items: AnalyticsPayItem[];
+    paymentType?: string;
+    stage?: PayStage;
+    code?: number;
+    reason?: string;
+};
+/**
+ * 支付漏斗统计能力。价格由业务提供，value 由框架按商品明细统一计算。
+ */
+export declare class PayAnalyticsAble {
+    private readonly _baseAble;
+    constructor(_baseAble: AnalyticsAble);
+    begin(data: PayEventData): void;
+    purchase(data: PayEventData): void;
+    pending(data: PayEventData): void;
+    cancel(data: PayEventData): void;
+    fail(data: PayEventData): void;
+    private report;
+    private normalize;
+    private invalid;
+}

package/dist/app/module/analytics/social/SocialAnalyticsAble.d.ts

@@ -1,9 +1,20 @@
 import { AnalyticsAble } from "../AnalyticsAble";
 import { AnalyticsData } from "../AnalyticsAble";
+export type SharePhase = "begin" | "success" | "fail";
+export type ShareEventData = AnalyticsData & {
+    method?: string;
+    contentType?: string;
+    itemId?: string | number;
+    phase: SharePhase;
+};
 export declare class SocialAnalyticsAble {
     private _baseAble;
     private _socialDimension;
     constructor(baseAble: AnalyticsAble);
+    share(data: ShareEventData): void;
+    /**
+     * @deprecated 请改用 share，并明确传入分享阶段。
+     */
     recordShare(data: AnalyticsData): void;
     recordInvite(success?: boolean): void;
     recordFriendAdd(count?: number): void;

package/dist/app/module/analytics/tutorial/TutorialAnalyticsAble.d.ts

@@ -0,0 +1,16 @@
+import { AnalyticsAble, AnalyticsData } from "../AnalyticsAble";
+export type TutorialEventData = AnalyticsData & {
+    tutorialId: string;
+    stepId?: string | number;
+    reason?: string;
+};
+/**
+ * 新手引导统计能力。只提供稳定的业务动作，不维护引导流程状态。
+ */
+export declare class TutorialAnalyticsAble {
+    private readonly _baseAble;
+    constructor(_baseAble: AnalyticsAble);
+    begin(data: TutorialEventData): void;
+    complete(data: TutorialEventData): void;
+    skip(data: TutorialEventData): void;
+}

package/dist/app/module/publisher/IShareAble.d.ts

@@ -1,4 +1,4 @@
-import { AnalyticsData } from "../analytics/index";
+import { AnalyticsData, SharePhase } from "../analytics/index";
 import { KSShareParameters } from "./ks/KSShare";
 import { TTShareParameters } from "./tt/TTShare";
 import { WXShareParameters } from "./wx/WXShare";
@@ -21,7 +21,7 @@ export declare class IShareAble {
     protected _getShareQuery(analyticsName: string | {
         name: string;
     } & AnalyticsData, query?: string): string;
-    protected _report(analyticsName: string | AnalyticsData, msg: string): void;
+    protected _report(analyticsName: string | AnalyticsData, phase: SharePhase, method?: string): void;
     /**
      * 分享图片或者文字
      * @param analyticsName 玩法发起分享的动作来源，用于统计。

package/dist/app/module/publisher/native/NativeAnalyticsSender.d.ts

@@ -1,9 +1,10 @@
-import { EmptyAnalyticsSender } from "../../analytics/index";
+import { AnalyticsEventData, AnalyticsMappedEvent, AnalyticsUserProperties, EmptyAnalyticsSender } from "../../analytics/index";
 /**
  * 原生平台事件上报器
  */
 export declare class NativeAnalyticsSender extends EmptyAnalyticsSender {
     protected _className: string;
     constructor(className?: string, exclude?: string[]);
-    send(eventName: string, data: object): Promise<void>;
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+    send(eventName: string, eventData: AnalyticsEventData, userProperties: AnalyticsUserProperties): Promise<void>;
 }

package/dist/app/module/publisher/tk/TKAnalyticsSender.d.ts

@@ -1,7 +1,8 @@
-import { EmptyAnalyticsSender } from "../../analytics/index";
+import { AnalyticsEventData, AnalyticsMappedEvent, AnalyticsUserProperties, EmptyAnalyticsSender } from "../../analytics/index";
 /**
  * TK事件上报器(window['tt'].reportAnalytics)
  */
 export declare class TKAnalyticsSender extends EmptyAnalyticsSender {
-    send(eventName: string, data: any): Promise<void>;
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+    send(eventName: string, eventData: AnalyticsEventData, userProperties: AnalyticsUserProperties): Promise<void>;
 }

package/dist/app/module/publisher/tt/TTAnalyticsSender.d.ts

@@ -1,7 +1,8 @@
-import { EmptyAnalyticsSender } from "../../analytics/index";
+import { AnalyticsEventData, AnalyticsMappedEvent, AnalyticsUserProperties, EmptyAnalyticsSender } from "../../analytics/index";
 /**
  * 字节事件上报器(window['tt'].reportAnalytics)
  */
 export declare class TTAnalyticsSender extends EmptyAnalyticsSender {
-    send(eventName: string, data: any): Promise<void>;
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+    send(eventName: string, eventData: AnalyticsEventData, userProperties: AnalyticsUserProperties): Promise<void>;
 }

package/dist/app/module/publisher/wx/WXAnalyticsSender.d.ts

@@ -1,7 +1,8 @@
-import { EmptyAnalyticsSender } from "../../analytics/index";
+import { AnalyticsEventData, AnalyticsMappedEvent, AnalyticsUserProperties, EmptyAnalyticsSender } from "../../analytics/index";
 /**
  * 微信事件上报器(window['wx'].reportEvent)
  */
 export declare class WXAnalyticsSender extends EmptyAnalyticsSender {
-    send(eventName: string, data: any): Promise<void>;
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
+    send(eventName: string, eventData: AnalyticsEventData, userProperties: AnalyticsUserProperties): Promise<void>;
 }

package/dist/index.d.ts

@@ -108,6 +108,7 @@ export * from './app/module/analytics/AnalyticsAbleConst';
 export * from './app/module/analytics/KeytopsAnalyticsSender';
 export * from './app/module/analytics/ALiAnalyticsSender';
 export * from './app/module/analytics/AnalyticsAble';
+export * from './app/module/analytics/AnalyticsEvent';
 export * from './app/module/analytics/index';
 export * from './app/module/analytics/ad/ADBehaviorReporter';
 export * from './app/module/analytics/ad/AdDimension';
@@ -122,6 +123,9 @@ export * from './app/module/analytics/level/LevelBehaviorReporter';
 export * from './app/module/analytics/level/PlayerAbilityDimension';
 export * from './app/module/analytics/session/SessionDimension';
 export * from './app/module/analytics/session/SessionAnalyticsAble';
+export * from './app/module/analytics/tutorial/TutorialAnalyticsAble';
+export * from './app/module/analytics/pay/PayAnalyticsAble';
+export * from './app/module/analytics/firebase/FirebaseAnalyticsSender';
 export * from './app/base/base';
 export * from './app/base/RuntimeApplicationImpl';
 export * from './app/base/utils/MathUtils';