@anker-in/analysis 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# @anker-in/analysis
+
+统一的埋点 SDK，支持多平台埋点接入、自动埋点、手动埋点等功能。
+
+## 特性
+
+- 🎯 **统一接口** - 屏蔽不同埋点平台的差异，提供统一的 API
+- 🚀 **自动埋点** - 支持自动采集 PV、点击等通用行为
+- 🔧 **手动埋点** - 提供简洁 API 供业务代码主动上报
+- ⚙️ **可配置** - 支持动态开启/关闭、平台开关等
+- 🔌 **可扩展** - 方便接入新的埋点平台
+- 📦 **类型安全** - 完整的 TypeScript 类型定义
+
+## 支持的平台
+
+- ✅ Google Analytics (gtag)
+- ✅ Meta (Facebook) Pixel
+- 🔜 TikTok Pixel (规划中)
+- 🔜 Scarab (规划中)
+
+## 安装
+
+```bash
+npm install @anker-in/analysis
+# 或
+pnpm add @anker-in/analysis
+# 或
+yarn add @anker-in/analysis
+```
+
+## 快速开始
+
+### 基础使用
+
+```typescript
+import { track } from "@anker-in/analysis";
+
+// Gtag 埋点
+track({
+  platform: "gtag",
+  eventName: "purchase",
+  items: [
+    {
+      item_id: "SKU123",
+      item_name: "Product Name",
+      price: 99.99,
+      quantity: 1,
+    },
+  ],
+  value: 99.99,
+  currency: "USD",
+  transactionId: "ORDER-123",
+});
+
+// Meta Pixel 埋点
+track({
+  platform: "meta",
+  event: "PageView",
+  data: {
+    page: "home",
+  },
+});
+```
+
+### TrackByTags 使用
+
+```typescript
+import { trackByTags } from "@anker-in/analysis";
+
+// 基于产品标签自动埋点
+trackByTags({
+  tags: ["fbq:atc:1234567890", "gtag:atc:AW-123456789/abc123"],
+  data: [{ event: "atc" }],
+});
+```
+
+### Pixels 组件使用
+
+```tsx
+import { GtagPixel, MetaPixel, PixelsManager } from '@anker-in/analysis';
+
+// 使用单个 Pixel 组件
+<GtagPixel
+  pixelIds={['G-XXXXXXXXXX']}
+  enabled={true}
+/>
+
+// 使用 PixelsManager
+<PixelsManager
+  type="gtag"
+  pixelIds={['G-XXXXXXXXXX']}
+  enabled={true}
+/>
+```
+
+## API 文档
+
+### track(config)
+
+统一的埋点上报函数。
+
+**参数：**
+
+```typescript
+// Gtag 埋点
+track({
+  platform: 'gtag',
+  eventName: 'purchase' | 'add_to_cart' | 'conversion' | ...,
+  // 转化事件
+  send_to?: string,
+  value?: number,
+  currency?: string,
+  transactionId?: string,
+  // 电商事件
+  items?: GtagItem[],
+  tax?: number,
+  shipping?: number,
+  coupon?: string,
+  // 通用参数
+  measurementId?: string,
+  nonInteraction?: boolean,
+  customParams?: Record<string, any>,
+});
+
+// Meta Pixel 埋点
+track({
+  platform: 'meta',
+  event: string,
+  data?: Record<string, any>,
+});
+```
+
+### trackByTags(params)
+
+基于标签的埋点功能。
+
+**参数：**
+
+```typescript
+trackByTags({
+  tags: string[], // 标签数组，格式: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123']
+  data: TrackByTagsData[], // 事件数据数组
+});
+```
+
+### Pixels 组件
+
+#### GtagPixel
+
+Google Analytics Pixel 组件。
+
+```tsx
+<GtagPixel
+  pixelIds={string | string[]}
+  enabled={boolean}
+  debug?: boolean
+/>
+```
+
+#### MetaPixel
+
+Meta Pixel 组件。
+
+```tsx
+<MetaPixel
+  pixelIds={string | string[]}
+  enabled={boolean}
+  debug?: boolean
+/>
+```
+
+#### PixelsManager
+
+Pixel 管理器组件，根据类型自动选择对应的 Pixel 组件。
+
+```tsx
+<PixelsManager
+  type="gtag" | "meta"
+  pixelIds={string | string[]}
+  enabled={boolean}
+  debug?: boolean
+/>
+```
+
+## 类型定义
+
+所有类型都可以从包中导入：
+
+```typescript
+import type {
+  TrackConfig,
+  GtagTrackParams,
+  MetaTrackParams,
+  TrackByTagsData,
+  TrackByTagsParams,
+  PlatformType,
+  // ... 更多类型
+} from "@anker-in/analysis";
+```
+
+## 导出路径
+
+包支持多个导出路径：
+
+```typescript
+// 主入口
+import { track } from "@anker-in/analysis";
+
+// 类型定义
+import type { TrackConfig } from "@anker-in/analysis/types";
+
+// 核心功能
+import { track } from "@anker-in/analysis/core";
+
+// Pixels 组件
+import { GtagPixel } from "@anker-in/analysis/pixels";
+
+// TrackByTags
+import { trackByTags } from "@anker-in/analysis/autoTrack";
+```
+
+## 开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 构建
+pnpm build
+
+# 类型检查
+pnpm check-types
+
+# 代码检查
+pnpm lint
+```
+
+## License
+
+MIT

package/dist/autoTrack/click.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=click.d.ts.map

package/dist/autoTrack/click.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"click.d.ts","sourceRoot":"","sources":["../../src/autoTrack/click.ts"],"names":[],"mappings":""}

package/dist/autoTrack/click.js

@@ -0,0 +1,80 @@
+// import { logger, throttle } from '../core/helpers';
+export {};
+// /**
+//  * 获取埋点数据
+//  */
+// function getTrackData(element: HTMLElement): Record<string, any> {
+//   const data: Record<string, any> = {};
+//   // 获取 data-track 属性
+//   const trackAttr = element.getAttribute('data-track');
+//   if (trackAttr) {
+//     try {
+//       // 尝试解析为 JSON
+//       Object.assign(data, JSON.parse(trackAttr));
+//     } catch {
+//       // 如果不是 JSON,作为普通字符串使用
+//       data.track_id = trackAttr;
+//     }
+//   }
+//   // 获取其他 data-track-* 属性
+//   Array.from(element.attributes).forEach(attr => {
+//     if (attr.name.startsWith('data-track-')) {
+//       const key = attr.name.replace('data-track-', '');
+//       data[key] = attr.value;
+//     }
+//   });
+//   // 补充基础信息
+//   data.element_tag = element.tagName.toLowerCase();
+//   data.element_text = element.textContent?.trim().substring(0, 100);
+//   data.element_id = element.id;
+//   data.element_class = element.className;
+//   return data;
+// }
+// /**
+//  * 点击自动埋点
+//  */
+// export function createClickAutoTrack(trackFn: (type: string, params: any) => void) {
+//   let enabled = false;
+//   let selector = '[data-track]';
+//   let clickHandler: ((e: Event) => void) | null = null;
+//   const handleClick = (e: Event) => {
+//     if (!enabled) return;
+//     const target = e.target as HTMLElement;
+//     if (!target) return;
+//     // 查找最近的匹配元素
+//     const element = target.closest(selector);
+//     if (!element) return;
+//     // 获取埋点数据
+//     const trackData = getTrackData(element as HTMLElement);
+//     trackFn('click', {
+//       ...trackData,
+//       timestamp: Date.now(),
+//     });
+//     logger.log('Click tracked:', trackData);
+//   };
+//   return {
+//     enable(customSelector?: string) {
+//       if (enabled) {
+//         logger.warn('Click auto track already enabled');
+//         return;
+//       }
+//       if (customSelector) {
+//         selector = customSelector;
+//       }
+//       enabled = true;
+//       // 使用事件委托监听点击
+//       clickHandler = throttle(handleClick, 300);
+//       document.addEventListener('click', clickHandler, true);
+//       logger.log(`Click auto track enabled with selector: ${selector}`);
+//     },
+//     disable() {
+//       if (!enabled) return;
+//       enabled = false;
+//       if (clickHandler) {
+//         document.removeEventListener('click', clickHandler, true);
+//         clickHandler = null;
+//       }
+//       logger.log('Click auto track disabled');
+//     },
+//   };
+// }

package/dist/autoTrack/index.d.ts

@@ -0,0 +1,2 @@
+export { trackByTags } from "./trackByTags";
+//# sourceMappingURL=index.d.ts.map

package/dist/autoTrack/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/autoTrack/index.ts"],"names":[],"mappings":"AAuDA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/autoTrack/index.js

@@ -0,0 +1,47 @@
+// import type { AutoTrackConfig } from "../types";
+// import { createPVAutoTrack } from "./pv";
+// import { createClickAutoTrack } from "./click";
+// import { logger } from "../core/helpers";
+// /**
+//  * 创建自动埋点管理器
+//  */
+// export function createAutoTrackManager(
+//   trackFn: (type: string, params: any) => void
+// ) {
+//   const pvTracker = createPVAutoTrack(trackFn);
+//   const clickTracker = createClickAutoTrack(trackFn);
+//   let config: AutoTrackConfig = {};
+//   return {
+//     init(autoTrackConfig: AutoTrackConfig = {}) {
+//       config = autoTrackConfig;
+//       // PV 自动埋点(默认开启)
+//       if (autoTrackConfig.pv !== false) {
+//         pvTracker.enable();
+//       }
+//       // 点击自动埋点
+//       if (autoTrackConfig.click) {
+//         clickTracker.enable(autoTrackConfig.clickSelector);
+//       }
+//       logger.log("AutoTrack initialized with config:", autoTrackConfig);
+//     },
+//     disable() {
+//       pvTracker.disable();
+//       clickTracker.disable();
+//       logger.log("All auto tracks disabled");
+//     },
+//     getConfig() {
+//       return config;
+//     },
+//     // 导出单独的 tracker 以便直接控制
+//     pv: pvTracker,
+//     click: clickTracker,
+//   };
+// }
+// export { createPVAutoTrack, createClickAutoTrack };
+// export {
+//   trackByTags,
+//   createTrackByTagsManager,
+//   type TrackByTagsData,
+//   TrackTagsVersionMap,
+// } from "./trackByTags";
+export { trackByTags } from "./trackByTags";

package/dist/autoTrack/pv.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pv.d.ts.map

package/dist/autoTrack/pv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pv.d.ts","sourceRoot":"","sources":["../../src/autoTrack/pv.ts"],"names":[],"mappings":""}

package/dist/autoTrack/pv.js

@@ -0,0 +1,57 @@
+// import { logger } from '../core/helpers';
+export {};
+// /**
+//  * PV 自动埋点
+//  */
+// export function createPVAutoTrack(trackFn: (type: string, params: any) => void) {
+//   let enabled = false;
+//   let tracked = false;
+//   const trackPageView = () => {
+//     if (!enabled) return;
+//     trackFn('pv', {
+//       page_url: window.location.href,
+//       page_title: document.title,
+//       referrer: document.referrer,
+//       timestamp: Date.now(),
+//     });
+//     tracked = true;
+//   };
+//   const setupRouteListener = () => {
+//     // 监听 history API
+//     const originalPushState = history.pushState;
+//     const originalReplaceState = history.replaceState;
+//     history.pushState = function (...args) {
+//       originalPushState.apply(this, args);
+//       trackPageView();
+//     };
+//     history.replaceState = function (...args) {
+//       originalReplaceState.apply(this, args);
+//       trackPageView();
+//     };
+//     // 监听 popstate 事件
+//     window.addEventListener('popstate', trackPageView);
+//     // 监听 hashchange 事件
+//     window.addEventListener('hashchange', trackPageView);
+//   };
+//   return {
+//     enable() {
+//       if (enabled) {
+//         logger.warn('PV auto track already enabled');
+//         return;
+//       }
+//       enabled = true;
+//       // 立即上报一次 PV
+//       trackPageView();
+//       // 监听路由变化(适配 SPA)
+//       setupRouteListener();
+//       logger.log('PV auto track enabled');
+//     },
+//     disable() {
+//       enabled = false;
+//       logger.log('PV auto track disabled');
+//     },
+//     isTracked() {
+//       return tracked;
+//     },
+//   };
+// }

package/dist/autoTrack/trackByTags.d.ts

@@ -0,0 +1,17 @@
+import type { TrackByTagsParams } from "../types";
+/**
+ * 基于标签进行埋点上报
+ *
+ * @param tags - 标签数组，格式: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123']
+ * @param data - 事件数据数组，每个元素包含 event 字段用于匹配标签
+ *
+ * @example
+ * ```typescript
+ * trackByTags(
+ *   ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
+ *   [{ event: 'atc' }]
+ * );
+ * ```
+ */
+export declare function trackByTags({ tags, data }: TrackByTagsParams): void;
+//# sourceMappingURL=trackByTags.d.ts.map

package/dist/autoTrack/trackByTags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackByTags.d.ts","sourceRoot":"","sources":["../../src/autoTrack/trackByTags.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA0B,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAmG1E;;;;;;;;;;;;;GAaG;AAEH,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,iBAAiB,GAAG,IAAI,CAgDnE"}

package/dist/autoTrack/trackByTags.js

@@ -0,0 +1,141 @@
+import { track } from "../core/tracking";
+import { logger } from "../core/helpers";
+import { TrackTagsVersionMap } from "../constants";
+/**
+ * 解析单个标签
+ */
+function parseTag(tag) {
+    const parts = tag.split(":");
+    if (parts.length < 2) {
+        return null;
+    }
+    return {
+        media: parts[0]?.toLowerCase() || "",
+        event: parts[1]?.toLowerCase() || "",
+        target: parts[2] || null,
+    };
+}
+/**
+ * 适配事件名称（版本兼容）
+ * 将旧版本的事件名替换为新版本的事件名
+ */
+function adaptEventName(tags) {
+    for (let i = 0; i < tags.length; i++) {
+        if (!tags[i]) {
+            continue;
+        }
+        for (const [oldEvent, newEvent] of Object.entries(TrackTagsVersionMap)) {
+            if (tags[i]?.includes(oldEvent)) {
+                tags[i] = tags[i]?.replace(oldEvent, newEvent) ?? "";
+                break;
+            }
+        }
+    }
+}
+/**
+ * 根据事件标识符过滤标签
+ */
+function filterTagsByEvent(tags, eventSymbol) {
+    return tags.filter((tag) => {
+        const parsed = parseTag(tag);
+        return parsed?.event === eventSymbol.toLowerCase();
+    });
+}
+/**
+ * 处理单个标签的埋点
+ */
+function handleTagTracking(parsedTag, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+eventData) {
+    const { media, event, target } = parsedTag;
+    if (!target) {
+        logger.warn(`Tag missing target: ${media}:${event}`);
+        return;
+    }
+    try {
+        switch (media) {
+            case "fbq":
+            case "meta": {
+                // Meta Pixel 埋点
+                const config = {
+                    platform: "meta",
+                    event: target, // target 作为事件名
+                    data: eventData,
+                };
+                track(config);
+                break;
+            }
+            case "gtag": {
+                // Gtag 转化事件埋点
+                const config = {
+                    platform: "gtag",
+                    eventName: "conversion",
+                    send_to: target, // target 作为转化目标ID
+                    value: eventData?.value ?? 1.0,
+                    currency: eventData?.currency,
+                    transactionId: eventData?.transactionId,
+                };
+                track(config);
+                break;
+            }
+            default:
+                logger.warn(`Unsupported media platform: ${media}`);
+        }
+    }
+    catch (error) {
+        logger.error(`Failed to track tag ${media}:${event}:${target}:`, error);
+    }
+}
+/**
+ * 基于标签进行埋点上报
+ *
+ * @param tags - 标签数组，格式: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123']
+ * @param data - 事件数据数组，每个元素包含 event 字段用于匹配标签
+ *
+ * @example
+ * ```typescript
+ * trackByTags(
+ *   ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
+ *   [{ event: 'atc' }]
+ * );
+ * ```
+ */
+export function trackByTags({ tags, data }) {
+    if (!tags || tags.length === 0) {
+        logger.warn("trackByTags: tags array is empty");
+        return;
+    }
+    if (!data || data.length === 0) {
+        logger.warn("trackByTags: data array is empty");
+        return;
+    }
+    // 数据清洗：兼容旧版本标签
+    const adaptedTags = [...tags];
+    adaptEventName(adaptedTags);
+    // 处理每个事件数据
+    data.forEach((trackData) => {
+        const eventSymbol = trackData.event?.toLowerCase();
+        if (!eventSymbol) {
+            logger.warn("trackByTags: event symbol is missing in trackData");
+            return;
+        }
+        // 根据事件标识符过滤标签
+        const matchedTags = filterTagsByEvent(adaptedTags, eventSymbol);
+        if (matchedTags.length === 0) {
+            logger.log(`trackByTags: No tags found for event: ${eventSymbol}`);
+            return;
+        }
+        // 提取事件数据（排除 event 字段）
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { event, ...eventData } = trackData;
+        // 处理每个匹配的标签
+        matchedTags.forEach((tag) => {
+            const parsed = parseTag(tag);
+            if (!parsed) {
+                logger.warn(`trackByTags: Invalid tag format: ${tag}`);
+                return;
+            }
+            handleTagTracking(parsed, eventData);
+        });
+    });
+}

package/dist/constants/index.d.ts

@@ -0,0 +1,2 @@
+export { TrackTagsVersionMap } from "./tagsMap";
+//# sourceMappingURL=index.d.ts.map

package/dist/constants/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC"}

package/dist/constants/index.js

@@ -0,0 +1 @@
+export { TrackTagsVersionMap } from "./tagsMap";

package/dist/constants/tagsMap.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 标签版本映射表
+ * 用于兼容旧版本标签，将旧事件名映射到新事件名
+ */
+export declare const TrackTagsVersionMap: {
+    readonly "fbq:act": "fbq:atc";
+    readonly "gtag:conversion": "gtag:atc";
+};
+//# sourceMappingURL=tagsMap.d.ts.map

package/dist/constants/tagsMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tagsMap.d.ts","sourceRoot":"","sources":["../../src/constants/tagsMap.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC"}

package/dist/constants/tagsMap.js

@@ -0,0 +1,8 @@
+/**
+ * 标签版本映射表
+ * 用于兼容旧版本标签，将旧事件名映射到新事件名
+ */
+export const TrackTagsVersionMap = {
+    "fbq:act": "fbq:atc",
+    "gtag:conversion": "gtag:atc",
+};

package/dist/core/adapters/gtag.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Google Analytics / gtag.js 适配器
+ * 使用标准的 window.gtag() API
+ * 专注于转化事件追踪
+ */
+/**
+ * gtag 命令类型
+ */
+type GtagCommand = "config" | "event" | "set" | "get";
+/**
+ * gtag 埋点函数
+ * 调用 window.gtag() 标准 API
+ */
+export declare const gtagTrack: (command: GtagCommand, targetOrEventName: string, params?: Record<string, any>) => void;
+/**
+ * 发送 gtag 事件
+ */
+export declare const gtagEvent: (eventName: string, eventParams?: Record<string, any>) => void;
+/**
+ * 发送 gtag config
+ */
+export declare const gtagConfig: (measurementId: string, configParams?: Record<string, any>) => void;
+/**
+ * 检测 gtag 是否可用
+ */
+export declare const isGtagAvailable: () => boolean;
+/**
+ * gtag 适配器对象
+ */
+export declare const gtagAdapter: {
+    track: (command: GtagCommand, targetOrEventName: string, params?: Record<string, any>) => void;
+    event: (eventName: string, eventParams?: Record<string, any>) => void;
+    config: (measurementId: string, configParams?: Record<string, any>) => void;
+    isAvailable: () => boolean;
+};
+export {};
+//# sourceMappingURL=gtag.d.ts.map

package/dist/core/adapters/gtag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gtag.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/gtag.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,KAAK,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,SAAS,GACpB,SAAS,WAAW,EACpB,mBAAmB,MAAM,EACzB,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAC3B,IAgBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,WAAW,MAAM,EACjB,cAAc,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAChC,IAEF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GACrB,eAAe,MAAM,EACrB,eAAe,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KACjC,IAEF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,QAAO,OAKlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW;qBAtDb,WAAW,qBACD,MAAM,WAChB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAC3B,IAAI;uBAsBM,MAAM,gBACH,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAChC,IAAI;4BAQU,MAAM,iBACN,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KACjC,IAAI;uBAO4B,OAAO;CAezC,CAAC"}