keytops-game-framework 1.0.25 → 2.0.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/AnalyticsAble.d.ts

@@ -28,7 +28,14 @@ export type AnalyticsData = {
     count?: number;
     [key: string]: string | boolean | number;
 };
+export type AnalyticsUserPropertyMode = "event" | "sender";
 export interface IAnalyticsSender {
+    /**
+     * 用户属性的承载方式。
+     * - event: 将用户属性合并到每个事件中（默认，兼容旧 Sender）
+     * - sender: 由 Sender 通过 setUserProperty 独立处理
+     */
+    readonly userPropertyMode?: AnalyticsUserPropertyMode;
     /**
      * 是否需要发送
      * @param eventName
@@ -45,6 +52,14 @@ export interface IAnalyticsSender {
      * @param data 事件数据
      */
     send(eventName: string, data: any): Promise<void>;
+    /**
+     * 设置平台用户标识。
+     */
+    setUserId?(userId: string | null): void;
+    /**
+     * 设置或清除平台用户属性，value 为 null 时表示清除。
+     */
+    setUserProperty?(key: string, value: string | number | boolean | null): void;
 }
 export declare class EmptyAnalyticsSender implements IAnalyticsSender {
     protected _exclude: string[];
@@ -79,11 +94,17 @@ export declare class AnalyticsAble {
         once: boolean;
         offset: number;
     }>;
+    private _userId;
+    private _hasSetUserId;
     /**
      * 初始化
      */
     init(senders: IAnalyticsSender[], debugMode?: boolean): AnalyticsAble;
     private _initSenderList;
+    private _usesSenderUserProperties;
+    private _getUserProperties;
+    private _syncSenderUserState;
+    private _notifyUserProperty;
     /**
      * 设置排除
      * @param excludeEvents 排除事件名称或者名称列表。
@@ -115,6 +136,10 @@ export declare class AnalyticsAble {
      * @param dynamicCall 动态属性的生成函数，事件上报时实时调用
      */
     setDynamicProperties(dynamicCall: () => AnalyticsData): void;
+    /**
+     * 设置平台用户标识。该值不会自动作为事件参数发送。
+     */
+    setUserId(userId: string | null): void;
     /**
      * 对于一般的用户属性，您可以调用 userSet 来进行设置。
      * 使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致。
@@ -168,7 +193,7 @@ export declare class AnalyticsAble {
     /**
      * 开始事件计时
      * 如果您需要记录某个事件的持续时长，可以调用 timeEvent 来开始计时。
-     * 配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 _dt_ 这一属性来表示记录的时长，单位为秒。
+     * 配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 duration 属性来表示记录的时长，单位为秒。
      * 需要注意的是，同一个事件名只能有一个在计时的任务。
      * @param eventName
      */