@anker-in/analysis 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -114,7 +114,6 @@ interface WithTrackingConfig<P extends PlatformType = PlatformType> {
  * TrackByTags 事件数据接口
  */
 interface TrackByTagsData {
-    event: string;
     [key: string]: any;
 }
 /**
@@ -122,7 +121,7 @@ interface TrackByTagsData {
  */
 interface TrackByTagsParams {
     tags: string[];
-    data: TrackByTagsData[];
+    data?: TrackByTagsData[];
 }
 /**
  * 解析后的标签结构（内部使用）
@@ -137,13 +136,6 @@ interface ParsedTag {
  * 埋点平台类型
  */
 type PlatformType = "gtag" | "meta";
-declare global {
-    interface Window {
-        gtag?: (...args: any[]) => void;
-        fbq?: (...args: any[]) => void;
-        dataLayer?: any[];
-    }
-}
 /**
  * 埋点事件类型
  */
@@ -262,17 +254,17 @@ declare function withTracking<T extends (...args: any[]) => any>(fn: T, config:
 declare function useTracking(config: WithTrackingConfig): <T extends (...args: any[]) => any>(fn: T) => T;
 
 /**
- * 基于标签进行埋点上报
+ * 基于标签进行埋点上报（简化版）
  *
  * @param tags - 标签数组，格式: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123']
- * @param data - 事件数据数组，每个元素包含 event 字段用于匹配标签
+ * @param data - 事件数据数组，包含事件相关的额外数据
  *
  * @example
  * ```typescript
- * trackByTags(
- *   ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
- *   [{ event: 'atc' }]
- * );
+ * trackByTags({
+ *   tags: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
+ *   data: [{ event: 'custom' }]
+ * });
  * ```
  */
 declare function trackByTags({ tags, data }: TrackByTagsParams): void;
@@ -325,6 +317,109 @@ declare function updateScriptsType(scriptIds: string[] | ((index: number) => str
  */
 declare const isPlatformAvailable: (platform: PlatformType) => boolean;
 
+/**
+ * 触发埋点上报工具
+ *
+ * 从 sessionStorage 读取 trackTags 配置，并根据 trackPoint 触发对应的埋点上报
+ */
+/**
+ * TrackTags 配置类型
+ * key: trackPoint 标识
+ * value: 标签数组
+ */
+interface TrackTagsConfig {
+    [trackPoint: string]: string[];
+}
+/**
+ * 埋点触发选项
+ */
+interface TriggerTrackOptions {
+    tags?: Array<string>;
+    /** 自定义事件数据 */
+    eventData?: Record<string, unknown>;
+    /** 自定义存储键名，默认为 'trackTags' */
+    storageKey?: string;
+    /** 是否静默失败（不输出警告日志），默认为 false */
+    silent?: boolean;
+}
+/**
+ * 触发埋点上报
+ *
+ * 从 sessionStorage 读取 trackTags 配置，根据 trackPoint 获取对应的标签数组，
+ * 然后调用 trackByTags 进行埋点上报。
+ *
+ * @param trackPoint - 埋点标识，对应 trackTags 中的 key
+ * @param options - 可选配置项
+ *
+ * @example
+ * ```typescript
+ * // 基础用法
+ * triggerTrack('add_to_cart');
+ *
+ * // 带自定义数据
+ * triggerTrack('purchase', {
+ *   eventData: {
+ *     value: 99.99,
+ *     currency: 'USD',
+ *     transactionId: 'ORDER-123'
+ *   }
+ * });
+ *
+ * // 使用自定义存储键
+ * triggerTrack('custom_event', {
+ *   storageKey: 'customTrackTags'
+ * });
+ * ```
+ */
+declare function triggerTrack(trackPoint: string, options?: TriggerTrackOptions): void;
+/**
+ * 批量触发多个埋点
+ *
+ * @param trackPoints - 埋点标识数组
+ * @param options - 可选配置项（应用到所有埋点）
+ *
+ * @example
+ * ```typescript
+ * // 批量触发多个埋点
+ * triggerTrackBatch(['view_item', 'add_to_cart']);
+ *
+ * // 带共享的事件数据
+ * triggerTrackBatch(['event1', 'event2'], {
+ *   eventData: { sessionId: '12345' }
+ * });
+ * ```
+ */
+declare function triggerTrackBatch(trackPoints: string[], options?: TriggerTrackOptions): void;
+/**
+ * 设置 trackTags 到 sessionStorage
+ *
+ * @param trackTags - TrackTags 配置对象
+ * @param storageKey - 存储键名，默认为 'trackTags'
+ *
+ * @example
+ * ```typescript
+ * setTrackTags({
+ *   'add_to_cart': ['fbq:atc:123456', 'gtag:atc:AW-123/abc'],
+ *   'purchase': ['fbq:purchase:123456', 'gtag:purchase:AW-123/xyz']
+ * });
+ * ```
+ */
+declare function setTrackTags(trackTags: TrackTagsConfig, storageKey?: string): void;
+/**
+ * 清除 trackTags
+ *
+ * @param storageKey - 存储键名，默认为 'trackTags'
+ */
+declare function clearTrackTags(storageKey?: string): void;
+/**
+ * 检查某个 trackPoint 是否存在
+ *
+ * @param trackPoint - 埋点标识
+ * @param storageKey - 存储键名，默认为 'trackTags'
+ * @returns 是否存在对应的标签配置
+ */
+declare function hasTrackPoint(trackPoint: string, storageKey?: string): boolean;
+
 /**
  * Google Analytics / gtag.js 适配器
  * 使用标准的 window.gtag() API
@@ -384,4 +479,4 @@ declare const _default: {
     updateScriptsType: typeof updateScriptsType;
 };
 
-export { type AnalysisConfig, type AutoTrackConfig, type BasePlatformConfig, type Currency, type GtagConfig, type GtagConfigParams, type GtagEventName, GtagPixel, type GtagTrackParams, MetaPixel, type MetaPixelConfig, type MetaTrackParams, type ParsedTag, PixelsManager, type PixelsManagerConfig, type PlatformType, type ScarabConfig, type TikTokPixelConfig, type TrackByTagsData, type TrackByTagsParams, type TrackConfig, type TrackEventType, type TrackParams, TrackTagsVersionMap, type Tracker, type UpdateScriptTypeOptions, _default as default, gtagTrack, isPlatformAvailable, logger, metaTrack, track, trackByTags, updateScriptType, updateScriptsType, useTracking, withTracking };
+export { type AnalysisConfig, type AutoTrackConfig, type BasePlatformConfig, type Currency, type GtagConfig, type GtagConfigParams, type GtagEventName, GtagPixel, type GtagTrackParams, MetaPixel, type MetaPixelConfig, type MetaTrackParams, type ParsedTag, PixelsManager, type PixelsManagerConfig, type PlatformType, type ScarabConfig, type TikTokPixelConfig, type TrackByTagsData, type TrackByTagsParams, type TrackConfig, type TrackEventType, type TrackParams, type TrackTagsConfig, TrackTagsVersionMap, type Tracker, type TriggerTrackOptions, type UpdateScriptTypeOptions, clearTrackTags, _default as default, gtagTrack, hasTrackPoint, isPlatformAvailable, logger, metaTrack, setTrackTags, track, trackByTags, triggerTrack, triggerTrackBatch, updateScriptType, updateScriptsType, useTracking, withTracking };

package/dist/index.d.ts

@@ -114,7 +114,6 @@ interface WithTrackingConfig<P extends PlatformType = PlatformType> {
  * TrackByTags 事件数据接口
  */
 interface TrackByTagsData {
-    event: string;
     [key: string]: any;
 }
 /**
@@ -122,7 +121,7 @@ interface TrackByTagsData {
  */
 interface TrackByTagsParams {
     tags: string[];
-    data: TrackByTagsData[];
+    data?: TrackByTagsData[];
 }
 /**
  * 解析后的标签结构（内部使用）
@@ -137,13 +136,6 @@ interface ParsedTag {
  * 埋点平台类型
  */
 type PlatformType = "gtag" | "meta";
-declare global {
-    interface Window {
-        gtag?: (...args: any[]) => void;
-        fbq?: (...args: any[]) => void;
-        dataLayer?: any[];
-    }
-}
 /**
  * 埋点事件类型
  */
@@ -262,17 +254,17 @@ declare function withTracking<T extends (...args: any[]) => any>(fn: T, config:
 declare function useTracking(config: WithTrackingConfig): <T extends (...args: any[]) => any>(fn: T) => T;
 
 /**
- * 基于标签进行埋点上报
+ * 基于标签进行埋点上报（简化版）
  *
  * @param tags - 标签数组，格式: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123']
- * @param data - 事件数据数组，每个元素包含 event 字段用于匹配标签
+ * @param data - 事件数据数组，包含事件相关的额外数据
  *
  * @example
  * ```typescript
- * trackByTags(
- *   ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
- *   [{ event: 'atc' }]
- * );
+ * trackByTags({
+ *   tags: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
+ *   data: [{ event: 'custom' }]
+ * });
  * ```
  */
 declare function trackByTags({ tags, data }: TrackByTagsParams): void;
@@ -325,6 +317,109 @@ declare function updateScriptsType(scriptIds: string[] | ((index: number) => str
  */
 declare const isPlatformAvailable: (platform: PlatformType) => boolean;
 
+/**
+ * 触发埋点上报工具
+ *
+ * 从 sessionStorage 读取 trackTags 配置，并根据 trackPoint 触发对应的埋点上报
+ */
+/**
+ * TrackTags 配置类型
+ * key: trackPoint 标识
+ * value: 标签数组
+ */
+interface TrackTagsConfig {
+    [trackPoint: string]: string[];
+}
+/**
+ * 埋点触发选项
+ */
+interface TriggerTrackOptions {
+    tags?: Array<string>;
+    /** 自定义事件数据 */
+    eventData?: Record<string, unknown>;
+    /** 自定义存储键名，默认为 'trackTags' */
+    storageKey?: string;
+    /** 是否静默失败（不输出警告日志），默认为 false */
+    silent?: boolean;
+}
+/**
+ * 触发埋点上报
+ *
+ * 从 sessionStorage 读取 trackTags 配置，根据 trackPoint 获取对应的标签数组，
+ * 然后调用 trackByTags 进行埋点上报。
+ *
+ * @param trackPoint - 埋点标识，对应 trackTags 中的 key
+ * @param options - 可选配置项
+ *
+ * @example
+ * ```typescript
+ * // 基础用法
+ * triggerTrack('add_to_cart');
+ *
+ * // 带自定义数据
+ * triggerTrack('purchase', {
+ *   eventData: {
+ *     value: 99.99,
+ *     currency: 'USD',
+ *     transactionId: 'ORDER-123'
+ *   }
+ * });
+ *
+ * // 使用自定义存储键
+ * triggerTrack('custom_event', {
+ *   storageKey: 'customTrackTags'
+ * });
+ * ```
+ */
+declare function triggerTrack(trackPoint: string, options?: TriggerTrackOptions): void;
+/**
+ * 批量触发多个埋点
+ *
+ * @param trackPoints - 埋点标识数组
+ * @param options - 可选配置项（应用到所有埋点）
+ *
+ * @example
+ * ```typescript
+ * // 批量触发多个埋点
+ * triggerTrackBatch(['view_item', 'add_to_cart']);
+ *
+ * // 带共享的事件数据
+ * triggerTrackBatch(['event1', 'event2'], {
+ *   eventData: { sessionId: '12345' }
+ * });
+ * ```
+ */
+declare function triggerTrackBatch(trackPoints: string[], options?: TriggerTrackOptions): void;
+/**
+ * 设置 trackTags 到 sessionStorage
+ *
+ * @param trackTags - TrackTags 配置对象
+ * @param storageKey - 存储键名，默认为 'trackTags'
+ *
+ * @example
+ * ```typescript
+ * setTrackTags({
+ *   'add_to_cart': ['fbq:atc:123456', 'gtag:atc:AW-123/abc'],
+ *   'purchase': ['fbq:purchase:123456', 'gtag:purchase:AW-123/xyz']
+ * });
+ * ```
+ */
+declare function setTrackTags(trackTags: TrackTagsConfig, storageKey?: string): void;
+/**
+ * 清除 trackTags
+ *
+ * @param storageKey - 存储键名，默认为 'trackTags'
+ */
+declare function clearTrackTags(storageKey?: string): void;
+/**
+ * 检查某个 trackPoint 是否存在
+ *
+ * @param trackPoint - 埋点标识
+ * @param storageKey - 存储键名，默认为 'trackTags'
+ * @returns 是否存在对应的标签配置
+ */
+declare function hasTrackPoint(trackPoint: string, storageKey?: string): boolean;
+
 /**
  * Google Analytics / gtag.js 适配器
  * 使用标准的 window.gtag() API
@@ -384,4 +479,4 @@ declare const _default: {
     updateScriptsType: typeof updateScriptsType;
 };
 
-export { type AnalysisConfig, type AutoTrackConfig, type BasePlatformConfig, type Currency, type GtagConfig, type GtagConfigParams, type GtagEventName, GtagPixel, type GtagTrackParams, MetaPixel, type MetaPixelConfig, type MetaTrackParams, type ParsedTag, PixelsManager, type PixelsManagerConfig, type PlatformType, type ScarabConfig, type TikTokPixelConfig, type TrackByTagsData, type TrackByTagsParams, type TrackConfig, type TrackEventType, type TrackParams, TrackTagsVersionMap, type Tracker, type UpdateScriptTypeOptions, _default as default, gtagTrack, isPlatformAvailable, logger, metaTrack, track, trackByTags, updateScriptType, updateScriptsType, useTracking, withTracking };
+export { type AnalysisConfig, type AutoTrackConfig, type BasePlatformConfig, type Currency, type GtagConfig, type GtagConfigParams, type GtagEventName, GtagPixel, type GtagTrackParams, MetaPixel, type MetaPixelConfig, type MetaTrackParams, type ParsedTag, PixelsManager, type PixelsManagerConfig, type PlatformType, type ScarabConfig, type TikTokPixelConfig, type TrackByTagsData, type TrackByTagsParams, type TrackConfig, type TrackEventType, type TrackParams, type TrackTagsConfig, TrackTagsVersionMap, type Tracker, type TriggerTrackOptions, type UpdateScriptTypeOptions, clearTrackTags, _default as default, gtagTrack, hasTrackPoint, isPlatformAvailable, logger, metaTrack, setTrackTags, track, trackByTags, triggerTrack, triggerTrackBatch, updateScriptType, updateScriptsType, useTracking, withTracking };