@jctrans-materials/shared 1.0.37-beta.0 → 1.0.37-beta.2

package/dist/index.d.ts

@@ -35,6 +35,11 @@ export declare interface BaseResponse<T = any> {
     [k: string]: any;
 }
 
+/**
+ * 事件拦截回调
+ */
+export declare type BeforeSendCallback = (event: GioEvent) => GioEvent;
+
 /**
  * 验证验证码绑定第三方应用
  * @param data
@@ -120,6 +125,11 @@ export declare function completeCompRedirectApi(data: any): Promise<any>;
  */
 export declare function completeJoinCompanyRedirectApi(data: any): Promise<any>;
 
+/**
+ * 配置值回调
+ */
+export declare type ConfigCallback<T = GioConfigValue> = (value: T) => void;
+
 export declare function createRequest(driver: RequestDriver, options?: RequestOptions): RequestAdapter;
 
 export declare const currentConfig: {
@@ -138,6 +148,11 @@ export declare const currentConfig: {
  */
 export declare function Decrypt(word: string): string;
 
+/**
+ * 设备 ID 回调
+ */
+export declare type DeviceIdCallback = (deviceId: string) => void;
+
 export declare type DisplayInfo = "Continent" | "Country" | "Province" | "City" | "Seaport" | "Airport";
 
 export declare const emitter: Emitter<ModalEvents>;
@@ -368,6 +383,25 @@ export declare const getSharedConfig: () => {
  */
 export declare function getToken(): string | undefined;
 
+/**
+ * 安全的 tracker 访问函数
+ * 在组件中使用时，可以避免 SSR 阶段解构报错
+ *
+ * @example
+ * ```typescript
+ * // ❌ 错误：可能在 SSR 阶段解构报错
+ * const { $gio } = useNuxtApp();
+ *
+ * // ✅ 正确：使用 getTracker 安全访问
+ * const { $gio } = useNuxtApp();
+ * const gio = getTracker($gio);
+ * if (gio) {
+ *   gio.track('event');
+ * }
+ * ```
+ */
+export declare function getTracker<T extends GioTracker>(trackerInstance?: T): T | null;
+
 /**
  * 获取用户手机号邮箱信息
  * @param data
@@ -375,6 +409,329 @@ export declare function getToken(): string | undefined;
  */
 export declare function getUserInfoApi(data: any): Promise<any>;
 
+/**
+ * GIO 属性对象
+ */
+export declare interface GioAttributes {
+    [key: string]: GioAttributeValue;
+}
+
+/**
+ * GrowingIO SDK 类型定义
+ * 严格约束传参，防止业务侧传入深层嵌套对象导致埋点失效
+ */
+/**
+ * GIO 属性值类型
+ * 只允许 string, number 或一维数组
+ * 文档限制：key ≤ 100 字符，value ≤ 1000 字符，数组元素 ≤ 100 个
+ */
+export declare type GioAttributeValue = string | number | Array<string | number>;
+
+/**
+ * 回调函数类型
+ */
+export declare type GioCallback = () => void;
+
+/**
+ * SDK 配置项类型
+ */
+export declare type GioConfigKey = 'dataCollect' | 'debug' | 'serverUrl' | 'trackPage' | 'forceLogin' | 'idMapping' | 'version';
+
+/**
+ * SDK 配置值类型
+ */
+export declare type GioConfigValue = boolean | string | number | object;
+
+/**
+ * GIO 事件对象（用于拦截回调）
+ */
+export declare interface GioEvent {
+    eventType: 'CUSTOM' | 'PAGE' | 'VISIT' | string;
+    eventName: string;
+    attributes: GioAttributes;
+    path: string;
+    query: string;
+    title: string;
+    [key: string]: any;
+}
+
+/**
+ * 通用属性对象（支持静态值和动态函数）
+ * 动态函数支持返回：string, number, boolean, Array<string | number>
+ */
+export declare interface GioGeneralProps {
+    [key: string]: GioAttributeValue | (() => string | number | boolean | Array<string | number>);
+}
+
+/**
+ * GrowingIO SDK 初始化配置项
+ * 参考官方文档：https://help-center.growingio.com/@sdk-v4/docs/webjs/initSettings.html
+ */
+export declare interface GioInitOptions {
+    /** 应用版本号，默认 '1.0.0' */
+    version?: string;
+    /** 数据上报服务端地址，SaaS 客户默认 https://napi.growingio.com，OP 私有部署需填写 */
+    serverUrl?: string;
+    /** 是否开启调试模式，默认 false。开启后在浏览器控制台输出日志 */
+    debug?: boolean;
+    /** 是否开启数据采集，默认 true。关闭后不会采集和上报事件 */
+    dataCollect?: boolean;
+    /** 是否自动采集页面访问事件，默认 true。关闭后需手动 sendPage */
+    trackPage?: boolean;
+    /** 是否开启强制登录模式，默认 false。微信公众号 H5 需要使用 openId/unionId 时设为 true */
+    forceLogin?: boolean;
+    /** 是否开启多用户身份上报（ID-MAPPING），默认 false。需要设置 userKey 时开启 */
+    idMapping?: boolean;
+    /** 指定打通的移动端包名（APP 内嵌页面场景） */
+    packageName?: string;
+    /** 平台类型，默认 'Web'。其他场景：wxwv(微信公众号), alip(支付宝小程序), iOS, Android 等 */
+    platform?: 'Web' | 'wxwv' | 'alip' | 'baidup' | 'qq' | 'bytedance' | 'kuaishoup' | 'jdp' | 'Android' | 'iOS' | 'Minp';
+    /** 自定义 cookie 存储的域，默认为当前站点的一级域名 */
+    cookieDomain?: string;
+    /** SDK 信息持久化存储类型，默认 'cookie'。可选 'localStorage' */
+    storageType?: 'cookie' | 'localStorage';
+    /** 是否开启增强型 UA，默认 true。开启后能更准确识别 Windows 11，但会增加上报数据大小 */
+    extraUA?: boolean;
+    /** 是否开启 hash 解析，默认 false。SPA 使用 hash 路由时设为 true */
+    hashtag?: boolean;
+    /** 是否采集爬虫环境数据，默认 true */
+    trackBot?: boolean;
+    /** 访问事件是否使用原始进入数据，默认 true。关闭可解决跳出率异常问题 */
+    originalSource?: boolean;
+    /** 与小程序打通时是否自动删除 gioInfo 参数，默认 true */
+    rewriteQuery?: boolean;
+    /** 数据上报优先方式，默认 'beacon'。可选 'xhr', 'image' */
+    sendType?: 'beacon' | 'xhr' | 'image';
+    /** 请求超时时长（毫秒），默认 5000。仅对 XHR 和 image 生效 */
+    requestTimeout?: number;
+    /** 上报忽略字段，如 ['screenHeight', 'screenWidth'] */
+    ignoreFields?: string[];
+    /** 曝光比例（0-1），与曝光插件结合使用，默认 0 */
+    impressionScale?: number;
+    /** 与小程序打通时的配置项，SDK >= 4.3.0 支持 */
+    embeddedAdapter?: {
+        /** 圈选服务器地址，SaaS 客户不需要配置 */
+        circleServerUrl?: string;
+    };
+    /** 允许传入其他未列出的配置项 */
+    [key: string]: any;
+}
+
+/**
+ * 页面属性对象
+ */
+export declare interface GioPageProps {
+    path: string;
+    query: string;
+    title: string;
+}
+
+/**
+ * 事件计时器 ID 类型
+ */
+export declare type GioTimerId = string;
+
+declare class GioTracker {
+    private get shouldValidateAttributes();
+    /**
+     * 获取 window.gdp 方法
+     * 非浏览器环境（如 Nuxt SSR）返回空函数，确保服务端渲染不会报错
+     */
+    private get gdp();
+    /**
+     * 检查 SDK 是否已初始化
+     * 在 SSR 环境下返回 false
+     */
+    isInitialized(): boolean;
+    /**
+     * 检查当前是否在浏览器环境中
+     * 可用于组件中判断是否执行 GIO 相关逻辑
+     */
+    isBrowser(): boolean;
+    /**
+     * 初始化 GrowingIO SDK
+     * 使用官方 gio-webjs-sdk npm 包进行初始化
+     *
+     * @param accountId - 账户 ID（从 GrowingIO 平台获取）
+     * @param dataSourceId - 数据源 ID（从 GrowingIO 平台获取）
+     * @param options - 初始化配置项
+     * @param callback - 可选回调函数
+     *
+     * @example
+     * ```typescript
+     * // 基础初始化
+     * tracker.init('your-account-id', 'your-datasource-id', {
+     *   debug: true,
+     *   trackPage: false,
+     * });
+     *
+     * // 微信公众号 H5（需要 forceLogin）
+     * tracker.init('accountId', 'dataSourceId', 'appId', {
+     *   forceLogin: true,
+     *   debug: true,
+     * });
+     *
+     * // 私有化部署
+     * tracker.init('accountId', 'dataSourceId', {
+     *   serverUrl: 'https://your-growingio-server.com',
+     *   debug: true,
+     * });
+     * ```
+     */
+    init(accountId: string, dataSourceId: string, options?: GioInitOptions, callback?: GioCallback): void;
+    /**
+     * 初始化 GrowingIO SDK（微信公众号 H5 场景，需要 appId）
+     */
+    init(accountId: string, dataSourceId: string, appId: string, options: GioInitOptions, callback?: GioCallback): void;
+    /**
+     * 动态修改配置
+     */
+    setOption<T extends GioConfigValue>(key: GioConfigKey, value: T, callback?: GioCallback): void;
+    /**
+     * 获取 SDK 当前配置
+     */
+    getOption<T extends GioConfigValue>(key: GioConfigKey | "", callback: ConfigCallback<T>): void;
+    /**
+     * 获取 SDK 版本号
+     */
+    getVersion(callback: ConfigCallback<string>): void;
+    /**
+     * 获取增强型 UserAgent
+     */
+    getUserAgent(callback: (userAgent: string) => void): void;
+    /**
+     * 设置访问用户 ID（匿名用户 ID/设备 ID）
+     * 仅可合法调用一次，多次调用无效
+     * 需要在初始化时将 forceLogin 设置为 true
+     */
+    identify(deviceId: string, callback?: GioCallback): void;
+    /**
+     * 获取访问用户 ID（设备 ID）
+     */
+    getDeviceId(callback: DeviceIdCallback): void;
+    /**
+     * 设置登录用户 ID
+     * 需要在初始化时设置 idMapping: true
+     * @param userId 用户 ID，长度 0 < length ≤ 1000
+     * @param userKey 用户 ID 类型标识（用于 ID-MAPPING）
+     */
+    setUserId(userId: string | number, userKey?: string | number, callback?: GioCallback): void;
+    /**
+     * 清除登录用户 ID（登出时调用）
+     */
+    clearUserId(callback?: GioCallback): void;
+    /**
+     * 发送埋点事件
+     * @param eventName 事件名称（需在平台预先配置）
+     * @param attributes 事件属性
+     * @param callback 回调函数
+     */
+    track(eventName: string, attributes?: GioAttributes, callback?: GioCallback): void;
+    /**
+     * 设置用户属性（登录用户身份）
+     * @param userAttributes 用户属性对象
+     * @param callback 回调函数
+     */
+    setUserAttributes(userAttributes: GioUserAttributes, callback?: GioCallback): void;
+    /**
+     * 设置全局通用属性（对所有事件生效）
+     * 支持静态值和动态函数
+     * 可多次调用，同名属性会被覆盖（动态值优先级更高）
+     */
+    setGeneralProps(props: GioGeneralProps, callback?: GioCallback): void;
+    /**
+     * 清除全局通用属性
+     * @param propertyNames 要清除的属性名数组，传空数组清空所有
+     */
+    clearGeneralProps(propertyNames?: string[], callback?: GioCallback): void;
+    /**
+     * 设置页面变更回调
+     * SDK 触发页面变更时会调用该回调
+     * 建议配合关闭 trackPage 后手动 sendPage 使用
+     */
+    setPageListener(callback: PageListenerCallback): void;
+    /**
+     * 设置页面属性
+     * 仅生效于当前页面的页面浏览事件和无埋点事件
+     * 仅在关闭 trackPage 时可用
+     */
+    setPageAttributes(props: GioAttributes, callback?: GioCallback): void;
+    /**
+     * 清除页面属性
+     * @param propertyNames 要清除的属性名数组，传空数组清空所有
+     */
+    clearPageAttributes(propertyNames?: string[], callback?: GioCallback): void;
+    /**
+     * 手动发送页面访问事件
+     * 仅在关闭 trackPage 时可用
+     * ⚠️ 危险操作，容易导致页面访问时长、跳出率等数据异常
+     * 强烈建议配合 setPageListener 使用
+     */
+    sendPage(options?: {
+        title?: string;
+    }, callback?: GioCallback): void;
+    /**
+     * 设置事件发送前拦截回调
+     * 可修改 path、query、title、attributes
+     * SDK 版本 >= 4.2.2 支持
+     */
+    setBeforeSendListener(callback: BeforeSendCallback): void;
+    /**
+     * 初始化事件计时器
+     * @param eventName 事件名称
+     * @returns timerId 计时器唯一标识
+     */
+    trackTimerStart(eventName: string, callback?: (timerId: GioTimerId) => void): void;
+    /**
+     * 暂停事件计时器
+     */
+    trackTimerPause(timerId: GioTimerId, callback?: GioCallback): void;
+    /**
+     * 恢复事件计时器
+     */
+    trackTimerResume(timerId: GioTimerId, callback?: GioCallback): void;
+    /**
+     * 停止事件计时器
+     * 会自动发送事件并删除计时器
+     * @param timerId 计时器 ID
+     * @param attributes 事件属性（event_duration 会自动添加）
+     */
+    trackTimerEnd(timerId: GioTimerId, attributes?: GioAttributes, callback?: GioCallback): void;
+    /**
+     * 删除单个事件计时器
+     * 不会发送事件
+     */
+    removeTimer(timerId: GioTimerId, callback?: GioCallback): void;
+    /**
+     * 清除所有事件计时器
+     * 不会发送事件
+     * 注意：官方文档中此方法不接受参数
+     */
+    clearTrackTimer(callback?: GioCallback): void;
+    /**
+     * 注册插件
+     * 用于扩展功能（如性能监控、曝光追踪等）
+     * @param plugins 插件数组
+     * @param callback 可选回调函数
+     */
+    registerPlugins(plugins: any[], callback?: (registeredPlugins: any[]) => void): void;
+    /**
+     * 校验属性对象（开发环境使用）
+     * - 检查 key 长度 ≤ 100
+     * - 检查 value 长度 ≤ 1000
+     * - 检查数组长度 ≤ 100
+     * - 检查是否包含嵌套对象
+     */
+    private _validateAttributes;
+}
+
+/**
+ * 用户属性对象
+ */
+export declare interface GioUserAttributes {
+    [key: string]: GioAttributeValue;
+}
+
 export declare const HasLoginKey = "hasLogin";
 
 /**
@@ -393,6 +750,18 @@ declare interface IResponse<T> {
     data: T;
 }
 
+/**
+ * 检查 GIO 是否可用（浏览器环境且已初始化）
+ *
+ * @example
+ * ```typescript
+ * if (isGioAvailable($gio)) {
+ *   $gio.track('event');
+ * }
+ * ```
+ */
+export declare function isGioAvailable(trackerInstance?: typeof tracker): boolean;
+
 /**
  * 判断域名是否为 IP
  */
@@ -752,6 +1121,11 @@ export declare type ModalEvents = Record<ActionKeys, any> & {
 
 export declare type ModalOpenCallback = () => void;
 
+/**
+ * 页面变更回调
+ */
+export declare type PageListenerCallback = (pageProps: GioPageProps) => void;
+
 export declare interface PageParams {
     current?: number;
     size?: number;
@@ -1073,6 +1447,8 @@ export declare interface TokenData {
  */
 export declare const TokenKey = "JC-JAVA-Token-Root";
 
+export declare const tracker: GioTracker;
+
 /** 归一化之后的实体 */
 export declare interface UnifiedItem {
     id: number | string;