keytops-game-framework 2.0.0 → 2.1.1

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,16 +42,13 @@ export type AnalyticsData = {
      * number类型，定义偏向计数数值，可以用于模型行为的计数、数量等。
      */
     count?: number;
-    [key: string]: string | boolean | number;
+    [key: string]: AnalyticsEventValue;
+};
+export type AnalyticsMappedEvent = {
+    eventName: string;
+    data: AnalyticsEventData;
 };
-export type AnalyticsUserPropertyMode = "event" | "sender";
 export interface IAnalyticsSender {
-    /**
-     * 用户属性的承载方式。
-     * - event: 将用户属性合并到每个事件中（默认，兼容旧 Sender）
-     * - sender: 由 Sender 通过 setUserProperty 独立处理
-     */
-    readonly userPropertyMode?: AnalyticsUserPropertyMode;
     /**
      * 是否需要发送
      * @param eventName
@@ -51,15 +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>;
     /**
-     * 设置平台用户标识。
+     * 将框架语义事件转换成统计平台的物理事件。
      */
-    setUserId?(userId: string | null): void;
+    mapEvent(eventName: string, eventData: AnalyticsEventData): AnalyticsMappedEvent;
     /**
-     * 设置或清除平台用户属性，value 为 null 时表示清除。
+     * 设置平台用户标识。
      */
-    setUserProperty?(key: string, value: string | number | boolean | null): void;
+    setUserId?(userId: string | null): void;
 }
 export declare class EmptyAnalyticsSender implements IAnalyticsSender {
     protected _exclude: string[];
@@ -73,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>;
 }
 /**
  * 统计分析能力
@@ -86,9 +100,9 @@ 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;
@@ -101,10 +115,7 @@ export declare class AnalyticsAble {
      */
     init(senders: IAnalyticsSender[], debugMode?: boolean): AnalyticsAble;
     private _initSenderList;
-    private _usesSenderUserProperties;
     private _getUserProperties;
-    private _syncSenderUserState;
-    private _notifyUserProperty;
     /**
      * 设置排除
      * @param excludeEvents 排除事件名称或者名称列表。
@@ -212,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,24 @@ 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";
+/**
+ * 自定义统计能力构造器。
+ *
+ * 自定义能力通过构造参数复用 AnalyticsManager 的基础统计能力，
+ * 从而共享 Sender、公共属性、用户属性和调试配置。
+ */
+export type AnalyticsAbilityConstructor<T> = new (baseAble: AnalyticsAble) => T;
 declare class AnalyticsManager {
     private hasRelayUrl;
     private hasAliDirectConfig;
@@ -42,6 +56,23 @@ declare class AnalyticsManager {
      * 社交统计能力
      */
     get social(): SocialAnalyticsAble;
+    private _tutorial;
+    /**
+     * 新手引导统计能力
+     */
+    get tutorial(): TutorialAnalyticsAble;
+    private _pay;
+    /**
+     * 支付漏斗统计能力
+     */
+    get pay(): PayAnalyticsAble;
+    private _abilityMap;
+    /**
+     * 获取由 AnalyticsManager 代管的自定义统计能力。
+     *
+     * 同一个构造器只会创建一个实例；自定义能力应通过构造参数接收基础统计能力。
+     */
+    getAbility<T>(abilityClass: AnalyticsAbilityConstructor<T>): T;
     /**
      * 启用统计（基础统计能力）
      * @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';