@anker-in/analysis 0.4.0 → 0.4.1

package/dist/index.d.mts

@@ -0,0 +1,512 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Gtag 平台 Track 类型定义
+ * 专注于转化事件追踪
+ */
+
+/** 转化事件名称 */
+type GtagEventName = "conversion" | "generate_lead" | "sign_up" | "purchase" | "add_to_cart" | "remove_from_cart" | "begin_checkout" | "view_item" | string;
+/**
+ * Gtag 转化事件参数
+ * 对应 gtag('event', eventName, eventParams)
+ */
+interface GtagTrackParams {
+    eventName: GtagEventName;
+    send_to?: string;
+    value?: number;
+    currency?: Currency;
+    transaction_id?: string;
+    transactionId?: string;
+    measurementId?: string;
+    [key: string]: any;
+}
+/**
+ * Gtag Config 配置
+ * 对应 gtag('config', measurementId, configParams)
+ */
+interface GtagConfigParams {
+    command: "config";
+    measurementId: string;
+    configParams?: {
+        send_page_view?: boolean;
+        [key: string]: any;
+    };
+}
+
+/**
+ * Meta Pixel 平台 Track 类型定义
+ */
+interface MetaTrackParams {
+    event: string;
+    data?: Record<string, any>;
+}
+
+/**
+ * Track 通用类型定义
+ */
+
+/**
+ * 货币类型
+ */
+type Currency = "CNY" | "USD" | "EUR" | string;
+/**
+ * 平台参数映射
+ */
+type PlatformTrackParamsMap = {
+    gtag: GtagTrackParams;
+    meta: MetaTrackParams;
+};
+/**
+ * Track 配置类型
+ */
+type TrackConfig<P extends PlatformType> = {
+    platform: P;
+} & PlatformTrackParamsMap[P];
+/**
+ * withTracking 配置选项
+ */
+interface WithTrackingConfig<P extends PlatformType = PlatformType> {
+    /**
+     * 埋点配置
+     * - 可以是静态配置对象
+     * - 可以是函数，接收原函数参数和返回值，动态生成配置
+     */
+    trackConfig?: TrackConfig<P> | ((args: any[], result?: any) => TrackConfig<P> | TrackConfig<P>[]);
+    /**
+     * 触发时机
+     * - before: 函数执行前触发（默认）
+     * - after: 函数执行后触发
+     * - both: 执行前后都触发
+     */
+    timing?: "before" | "after" | "both";
+    /**
+     * 条件判断：返回 true 才触发埋点
+     */
+    condition?: (args: any[], result?: any) => boolean;
+    /**
+     * 错误处理：函数执行失败时是否仍然上报
+     */
+    trackOnError?: boolean;
+    /**
+     * 错误时的埋点配置
+     */
+    errorTrackConfig?: (error: Error, args: any[]) => TrackConfig<P>;
+    /**
+     * 防抖时间（毫秒），避免重复上报
+     */
+    debounce?: number;
+    /**
+     * 节流时间（毫秒），限制上报频率
+     */
+    throttle?: number;
+    /**
+     * 用于 AST 解析的标识
+     */
+    trackPoint?: string;
+}
+
+/**
+ * TrackByTags 相关类型定义
+ */
+/**
+ * TrackByTags 事件数据接口
+ */
+interface TrackByTagsData {
+    [key: string]: any;
+}
+/**
+ * TrackByTags 函数参数接口
+ */
+interface TrackByTagsParams {
+    tags: string[];
+    data?: TrackByTagsData[];
+}
+/**
+ * 解析后的标签结构（内部使用）
+ */
+interface ParsedTag {
+    media: string;
+    event: string;
+    target: string | null;
+}
+
+/**
+ * 埋点平台类型
+ */
+type PlatformType = "gtag" | "meta";
+/**
+ * 埋点事件类型
+ */
+type TrackEventType = "ads" | "pv" | "click" | "buynow" | "add2cart" | "checkout" | "purchase" | "search" | "view_item";
+/**
+ * 平台配置基础接口
+ */
+interface BasePlatformConfig {
+    pixelIds: string | Array<string>;
+    cookieConsentEnabled: boolean;
+    debug?: boolean;
+    strategy?: "lazyOnload" | "afterInteractive" | "beforeInteractive" | "worker";
+    onPixelLoaded?: () => void;
+}
+interface PixelsManagerConfig extends BasePlatformConfig {
+    type: PlatformType;
+}
+/**
+ * Gtag 配置
+ */
+interface GtagConfig extends BasePlatformConfig {
+}
+/**
+ * Meta Pixel 配置
+ */
+interface MetaPixelConfig extends BasePlatformConfig {
+}
+/**
+ * TikTok Pixel 配置
+ */
+interface TikTokPixelConfig extends BasePlatformConfig {
+    pixelId: string;
+}
+/**
+ * Scarab 配置
+ */
+interface ScarabConfig extends BasePlatformConfig {
+    customerId: string;
+    [key: string]: any;
+}
+/**
+ * SDK 初始化配置
+ */
+interface AnalysisConfig {
+    gtag?: GtagConfig;
+    metaPixel?: MetaPixelConfig;
+    tiktokPixel?: TikTokPixelConfig;
+    scarab?: ScarabConfig;
+    debug?: boolean;
+}
+/**
+ * 埋点参数
+ */
+interface TrackParams {
+    type: TrackEventType;
+    params?: Record<string, any>;
+    platform?: PlatformType[];
+}
+/**
+ * Tracker 实例
+ */
+interface Tracker {
+    platform: PlatformType;
+    isReady: boolean;
+    init: (config: any) => Promise<void> | void;
+    track: (type: TrackEventType, params?: Record<string, any>) => void;
+}
+/**
+ * 自动埋点配置
+ */
+interface AutoTrackConfig {
+    pv?: boolean;
+    click?: boolean;
+    clickSelector?: string;
+}
+
+/**
+ * 埋点调度器模块
+ * 负责根据平台类型分发事件到对应的适配器
+ */
+
+declare function track(config: TrackConfig<"gtag">): void;
+declare function track(config: TrackConfig<"meta">): void;
+
+/**
+ * 埋点装饰器模块
+ * 提供函数包装器和 React Hooks，为业务函数添加埋点能力
+ */
+
+declare function withTracking<T extends (...args: any[]) => any>(fn: T, config: WithTrackingConfig): T;
+/**
+ * React Hooks 专用
+ *
+ * 为 React 组件提供埋点 Hook
+ *
+ * @example
+ * ```typescript
+ * function ProductCard({ product }) {
+ *   const trackAddToCart = useTracking({
+ *     trackConfig: {
+ *       platform: "gtag",
+ *       eventName: "add_to_cart"
+ *     }
+ *   });
+ *
+ *   const handleClick = () => {
+ *     trackAddToCart(() => {
+ *       addToCart(product.id);
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Add to Cart</button>;
+ * }
+ * ```
+ */
+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 - 事件数据数组，包含事件相关的额外数据
+ *
+ * @example
+ * ```typescript
+ * trackByTags({
+ *   tags: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
+ *   data: [{ event: 'custom' }]
+ * });
+ * ```
+ */
+declare function trackByTags({ tags, data }: TrackByTagsParams): void;
+
+declare const logger: {
+    setEnabled(value: boolean): void;
+    log(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+};
+
+/**
+ * 更新脚本的 type 属性配置
+ */
+interface UpdateScriptTypeOptions {
+    /** 脚本元素的 ID */
+    id: string;
+    /** 是否启用脚本 */
+    enabled: boolean;
+    /** 是否在启用时重新执行脚本内容 */
+    executeOnEnable?: boolean;
+    /** 错误处理回调 */
+    onError?: (error: Error) => void;
+}
+/**
+ * 动态更新脚本的 type 属性
+ * 用于根据 cookie consent 状态动态启用/禁用脚本
+ *
+ * @param options - 配置选项
+ * @returns 是否成功更新
+ */
+declare function updateScriptType(options: UpdateScriptTypeOptions): boolean;
+/**
+ * 批量更新多个脚本的 type 属性
+ *
+ * @param scriptIds - 脚本 ID 数组或生成 ID 的函数
+ * @param enabled - 是否启用脚本
+ * @param executeOnEnable - 是否在启用时重新执行脚本内容
+ * @returns 成功更新的脚本数量
+ */
+declare function updateScriptsType(scriptIds: string[] | ((index: number) => string), enabled: boolean, executeOnEnable?: boolean): number;
+
+/**
+ * 平台检测模块
+ * 检测各个埋点平台的可用性
+ */
+
+/**
+ * 检测指定平台是否可用
+ */
+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
+ * 专注于转化事件追踪
+ */
+/**
+ * gtag 命令类型
+ */
+type GtagCommand = "config" | "event" | "set" | "get";
+/**
+ * gtag 埋点函数
+ * 调用 window.gtag() 标准 API
+ */
+declare const gtagTrack: (command: GtagCommand, targetOrEventName: string, params?: Record<string, any>) => void;
+
+/**
+ * Meta Pixel 适配器
+ * 提供 Facebook/Meta Pixel 的埋点功能
+ */
+/**
+ * Meta Pixel 埋点函数
+ */
+declare const metaTrack: (event: string, data?: object) => void;
+
+interface UseDataTrackOptions {
+    /**
+     * 埋点标签映射对象
+     * 键为 data-track 属性值，值为标签数组
+     */
+    trackTags?: Record<string, string[]>;
+}
+/**
+ * 自动追踪带有 data-track 属性的元素点击事件的 Hook
+ *
+ * @param options - 配置选项
+ * @param options.trackTags - 埋点标签映射对象，键为 data-track 属性值，值为标签数组
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useDataTrack({
+ *     trackTags: {
+ *       'add-to-cart': ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
+ *       'checkout': ['fbq:checkout:1234567890']
+ *     }
+ *   });
+ *
+ *   return (
+ *     <button data-track="add-to-cart">Add to Cart</button>
+ *   );
+ * }
+ * ```
+ */
+declare function useDataTrack({ trackTags }: UseDataTrackOptions): void;
+
+interface GtagPixelProps extends GtagConfig, React.ScriptHTMLAttributes<HTMLScriptElement> {
+}
+declare const GtagPixel: (props: GtagPixelProps) => react_jsx_runtime.JSX.Element;
+
+interface MetaPixelProps extends BasePlatformConfig, React.ScriptHTMLAttributes<HTMLScriptElement> {
+}
+declare const MetaPixel: (props: MetaPixelProps) => react_jsx_runtime.JSX.Element;
+
+declare const PixelsManager: React.FC<PixelsManagerConfig>;
+
+/**
+ * 标签版本映射表
+ * 用于兼容旧版本标签，将旧事件名映射到新事件名
+ */
+declare const TrackTagsVersionMap: {
+    readonly "fbq:act": "fbq:atc";
+    readonly "gtag:conversion": "gtag:atc";
+};
+
+declare const _default: {
+    track: typeof track;
+    trackByTags: typeof trackByTags;
+    withTracking: typeof withTracking;
+    useTracking: typeof useTracking;
+    logger: {
+        setEnabled(value: boolean): void;
+        log(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    };
+    isPlatformAvailable: (platform: PlatformType) => boolean;
+    updateScriptType: typeof updateScriptType;
+    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, type TrackTagsConfig, TrackTagsVersionMap, type Tracker, type TriggerTrackOptions, type UpdateScriptTypeOptions, type UseDataTrackOptions, clearTrackTags, _default as default, gtagTrack, hasTrackPoint, isPlatformAvailable, logger, metaTrack, setTrackTags, track, trackByTags, triggerTrack, triggerTrackBatch, updateScriptType, updateScriptsType, useDataTrack, useTracking, withTracking };

package/dist/index.d.ts

@@ -0,0 +1,512 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+
+/**
+ * Gtag 平台 Track 类型定义
+ * 专注于转化事件追踪
+ */
+
+/** 转化事件名称 */
+type GtagEventName = "conversion" | "generate_lead" | "sign_up" | "purchase" | "add_to_cart" | "remove_from_cart" | "begin_checkout" | "view_item" | string;
+/**
+ * Gtag 转化事件参数
+ * 对应 gtag('event', eventName, eventParams)
+ */
+interface GtagTrackParams {
+    eventName: GtagEventName;
+    send_to?: string;
+    value?: number;
+    currency?: Currency;
+    transaction_id?: string;
+    transactionId?: string;
+    measurementId?: string;
+    [key: string]: any;
+}
+/**
+ * Gtag Config 配置
+ * 对应 gtag('config', measurementId, configParams)
+ */
+interface GtagConfigParams {
+    command: "config";
+    measurementId: string;
+    configParams?: {
+        send_page_view?: boolean;
+        [key: string]: any;
+    };
+}
+
+/**
+ * Meta Pixel 平台 Track 类型定义
+ */
+interface MetaTrackParams {
+    event: string;
+    data?: Record<string, any>;
+}
+
+/**
+ * Track 通用类型定义
+ */
+
+/**
+ * 货币类型
+ */
+type Currency = "CNY" | "USD" | "EUR" | string;
+/**
+ * 平台参数映射
+ */
+type PlatformTrackParamsMap = {
+    gtag: GtagTrackParams;
+    meta: MetaTrackParams;
+};
+/**
+ * Track 配置类型
+ */
+type TrackConfig<P extends PlatformType> = {
+    platform: P;
+} & PlatformTrackParamsMap[P];
+/**
+ * withTracking 配置选项
+ */
+interface WithTrackingConfig<P extends PlatformType = PlatformType> {
+    /**
+     * 埋点配置
+     * - 可以是静态配置对象
+     * - 可以是函数，接收原函数参数和返回值，动态生成配置
+     */
+    trackConfig?: TrackConfig<P> | ((args: any[], result?: any) => TrackConfig<P> | TrackConfig<P>[]);
+    /**
+     * 触发时机
+     * - before: 函数执行前触发（默认）
+     * - after: 函数执行后触发
+     * - both: 执行前后都触发
+     */
+    timing?: "before" | "after" | "both";
+    /**
+     * 条件判断：返回 true 才触发埋点
+     */
+    condition?: (args: any[], result?: any) => boolean;
+    /**
+     * 错误处理：函数执行失败时是否仍然上报
+     */
+    trackOnError?: boolean;
+    /**
+     * 错误时的埋点配置
+     */
+    errorTrackConfig?: (error: Error, args: any[]) => TrackConfig<P>;
+    /**
+     * 防抖时间（毫秒），避免重复上报
+     */
+    debounce?: number;
+    /**
+     * 节流时间（毫秒），限制上报频率
+     */
+    throttle?: number;
+    /**
+     * 用于 AST 解析的标识
+     */
+    trackPoint?: string;
+}
+
+/**
+ * TrackByTags 相关类型定义
+ */
+/**
+ * TrackByTags 事件数据接口
+ */
+interface TrackByTagsData {
+    [key: string]: any;
+}
+/**
+ * TrackByTags 函数参数接口
+ */
+interface TrackByTagsParams {
+    tags: string[];
+    data?: TrackByTagsData[];
+}
+/**
+ * 解析后的标签结构（内部使用）
+ */
+interface ParsedTag {
+    media: string;
+    event: string;
+    target: string | null;
+}
+
+/**
+ * 埋点平台类型
+ */
+type PlatformType = "gtag" | "meta";
+/**
+ * 埋点事件类型
+ */
+type TrackEventType = "ads" | "pv" | "click" | "buynow" | "add2cart" | "checkout" | "purchase" | "search" | "view_item";
+/**
+ * 平台配置基础接口
+ */
+interface BasePlatformConfig {
+    pixelIds: string | Array<string>;
+    cookieConsentEnabled: boolean;
+    debug?: boolean;
+    strategy?: "lazyOnload" | "afterInteractive" | "beforeInteractive" | "worker";
+    onPixelLoaded?: () => void;
+}
+interface PixelsManagerConfig extends BasePlatformConfig {
+    type: PlatformType;
+}
+/**
+ * Gtag 配置
+ */
+interface GtagConfig extends BasePlatformConfig {
+}
+/**
+ * Meta Pixel 配置
+ */
+interface MetaPixelConfig extends BasePlatformConfig {
+}
+/**
+ * TikTok Pixel 配置
+ */
+interface TikTokPixelConfig extends BasePlatformConfig {
+    pixelId: string;
+}
+/**
+ * Scarab 配置
+ */
+interface ScarabConfig extends BasePlatformConfig {
+    customerId: string;
+    [key: string]: any;
+}
+/**
+ * SDK 初始化配置
+ */
+interface AnalysisConfig {
+    gtag?: GtagConfig;
+    metaPixel?: MetaPixelConfig;
+    tiktokPixel?: TikTokPixelConfig;
+    scarab?: ScarabConfig;
+    debug?: boolean;
+}
+/**
+ * 埋点参数
+ */
+interface TrackParams {
+    type: TrackEventType;
+    params?: Record<string, any>;
+    platform?: PlatformType[];
+}
+/**
+ * Tracker 实例
+ */
+interface Tracker {
+    platform: PlatformType;
+    isReady: boolean;
+    init: (config: any) => Promise<void> | void;
+    track: (type: TrackEventType, params?: Record<string, any>) => void;
+}
+/**
+ * 自动埋点配置
+ */
+interface AutoTrackConfig {
+    pv?: boolean;
+    click?: boolean;
+    clickSelector?: string;
+}
+
+/**
+ * 埋点调度器模块
+ * 负责根据平台类型分发事件到对应的适配器
+ */
+
+declare function track(config: TrackConfig<"gtag">): void;
+declare function track(config: TrackConfig<"meta">): void;
+
+/**
+ * 埋点装饰器模块
+ * 提供函数包装器和 React Hooks，为业务函数添加埋点能力
+ */
+
+declare function withTracking<T extends (...args: any[]) => any>(fn: T, config: WithTrackingConfig): T;
+/**
+ * React Hooks 专用
+ *
+ * 为 React 组件提供埋点 Hook
+ *
+ * @example
+ * ```typescript
+ * function ProductCard({ product }) {
+ *   const trackAddToCart = useTracking({
+ *     trackConfig: {
+ *       platform: "gtag",
+ *       eventName: "add_to_cart"
+ *     }
+ *   });
+ *
+ *   const handleClick = () => {
+ *     trackAddToCart(() => {
+ *       addToCart(product.id);
+ *     });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Add to Cart</button>;
+ * }
+ * ```
+ */
+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 - 事件数据数组，包含事件相关的额外数据
+ *
+ * @example
+ * ```typescript
+ * trackByTags({
+ *   tags: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
+ *   data: [{ event: 'custom' }]
+ * });
+ * ```
+ */
+declare function trackByTags({ tags, data }: TrackByTagsParams): void;
+
+declare const logger: {
+    setEnabled(value: boolean): void;
+    log(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+};
+
+/**
+ * 更新脚本的 type 属性配置
+ */
+interface UpdateScriptTypeOptions {
+    /** 脚本元素的 ID */
+    id: string;
+    /** 是否启用脚本 */
+    enabled: boolean;
+    /** 是否在启用时重新执行脚本内容 */
+    executeOnEnable?: boolean;
+    /** 错误处理回调 */
+    onError?: (error: Error) => void;
+}
+/**
+ * 动态更新脚本的 type 属性
+ * 用于根据 cookie consent 状态动态启用/禁用脚本
+ *
+ * @param options - 配置选项
+ * @returns 是否成功更新
+ */
+declare function updateScriptType(options: UpdateScriptTypeOptions): boolean;
+/**
+ * 批量更新多个脚本的 type 属性
+ *
+ * @param scriptIds - 脚本 ID 数组或生成 ID 的函数
+ * @param enabled - 是否启用脚本
+ * @param executeOnEnable - 是否在启用时重新执行脚本内容
+ * @returns 成功更新的脚本数量
+ */
+declare function updateScriptsType(scriptIds: string[] | ((index: number) => string), enabled: boolean, executeOnEnable?: boolean): number;
+
+/**
+ * 平台检测模块
+ * 检测各个埋点平台的可用性
+ */
+
+/**
+ * 检测指定平台是否可用
+ */
+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
+ * 专注于转化事件追踪
+ */
+/**
+ * gtag 命令类型
+ */
+type GtagCommand = "config" | "event" | "set" | "get";
+/**
+ * gtag 埋点函数
+ * 调用 window.gtag() 标准 API
+ */
+declare const gtagTrack: (command: GtagCommand, targetOrEventName: string, params?: Record<string, any>) => void;
+
+/**
+ * Meta Pixel 适配器
+ * 提供 Facebook/Meta Pixel 的埋点功能
+ */
+/**
+ * Meta Pixel 埋点函数
+ */
+declare const metaTrack: (event: string, data?: object) => void;
+
+interface UseDataTrackOptions {
+    /**
+     * 埋点标签映射对象
+     * 键为 data-track 属性值，值为标签数组
+     */
+    trackTags?: Record<string, string[]>;
+}
+/**
+ * 自动追踪带有 data-track 属性的元素点击事件的 Hook
+ *
+ * @param options - 配置选项
+ * @param options.trackTags - 埋点标签映射对象，键为 data-track 属性值，值为标签数组
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useDataTrack({
+ *     trackTags: {
+ *       'add-to-cart': ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
+ *       'checkout': ['fbq:checkout:1234567890']
+ *     }
+ *   });
+ *
+ *   return (
+ *     <button data-track="add-to-cart">Add to Cart</button>
+ *   );
+ * }
+ * ```
+ */
+declare function useDataTrack({ trackTags }: UseDataTrackOptions): void;
+
+interface GtagPixelProps extends GtagConfig, React.ScriptHTMLAttributes<HTMLScriptElement> {
+}
+declare const GtagPixel: (props: GtagPixelProps) => react_jsx_runtime.JSX.Element;
+
+interface MetaPixelProps extends BasePlatformConfig, React.ScriptHTMLAttributes<HTMLScriptElement> {
+}
+declare const MetaPixel: (props: MetaPixelProps) => react_jsx_runtime.JSX.Element;
+
+declare const PixelsManager: React.FC<PixelsManagerConfig>;
+
+/**
+ * 标签版本映射表
+ * 用于兼容旧版本标签，将旧事件名映射到新事件名
+ */
+declare const TrackTagsVersionMap: {
+    readonly "fbq:act": "fbq:atc";
+    readonly "gtag:conversion": "gtag:atc";
+};
+
+declare const _default: {
+    track: typeof track;
+    trackByTags: typeof trackByTags;
+    withTracking: typeof withTracking;
+    useTracking: typeof useTracking;
+    logger: {
+        setEnabled(value: boolean): void;
+        log(...args: any[]): void;
+        warn(...args: any[]): void;
+        error(...args: any[]): void;
+    };
+    isPlatformAvailable: (platform: PlatformType) => boolean;
+    updateScriptType: typeof updateScriptType;
+    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, type TrackTagsConfig, TrackTagsVersionMap, type Tracker, type TriggerTrackOptions, type UpdateScriptTypeOptions, type UseDataTrackOptions, clearTrackTags, _default as default, gtagTrack, hasTrackPoint, isPlatformAvailable, logger, metaTrack, setTrackTags, track, trackByTags, triggerTrack, triggerTrackBatch, updateScriptType, updateScriptsType, useDataTrack, useTracking, withTracking };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anker-in/analysis",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Unified analytics SDK for multi-platform tracking (Google Analytics, Meta Pixel, TikTok Pixel)",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -50,8 +50,8 @@
     "eslint": "^9.34.0",
     "tsup": "^8.5.1",
     "typescript": "5.9.2",
-    "@repo/eslint-config": "0.0.1",
-    "@repo/typescript-config": "0.0.1"
+    "@repo/typescript-config": "0.0.1",
+    "@repo/eslint-config": "0.0.1"
   },
   "dependencies": {
     "react": "^19.1.0",