@anker-in/analysis

统一的埋点 SDK，支持多平台埋点接入、自动埋点、手动埋点等功能。

特性

• 🎯 统一接口 - 屏蔽不同埋点平台的差异，提供统一的 API
• 🚀 自动埋点 - 支持自动采集 PV、点击等通用行为
• 🔧 手动埋点 - 提供简洁 API 供业务代码主动上报
• ⚙️ 可配置 - 支持动态开启/关闭、平台开关等
• 🔌 可扩展 - 方便接入新的埋点平台
• 📦 类型安全 - 完整的 TypeScript 类型定义

支持的平台

• ✅ Google Analytics (gtag)
• ✅ Meta (Facebook) Pixel
• 🔜 TikTok Pixel (规划中)
• 🔜 Scarab (规划中)

安装

npm install @anker-in/analysis
# 或
pnpm add @anker-in/analysis
# 或
yarn add @anker-in/analysis

快速开始

基础使用

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 使用

import { trackByTags } from "@anker-in/analysis";

// 基于产品标签自动埋点
trackByTags({
  tags: ["fbq:atc:1234567890", "gtag:atc:AW-123456789/abc123"],
  data: [{ event: "atc" }],
});

useDataTrack Hook 使用

import { useDataTrack } from "@anker-in/analysis";

function ProductPage({ product }) {
  // 自动追踪带有 data-track 属性的元素点击事件
  useDataTrack({
    trackTags: {
      'add-to-cart': ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123'],
      'checkout': ['fbq:checkout:1234567890']
    },
    type: 'product',
    product: product
  });

  return (
    <div>
      <button data-track="add-to-cart">Add to Cart</button>
      <button data-track="checkout">Checkout</button>
    </div>
  );
}

Pixels 组件使用

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)

统一的埋点上报函数。

参数：

// 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)

基于标签的埋点功能。

参数：

trackByTags({
  tags: string[], // 标签数组，格式: ['fbq:atc:1234567890', 'gtag:atc:AW-123456789/abc123']
  data: TrackByTagsData[], // 事件数据数组
});

useDataTrack(options)

自动追踪带有 data-track 属性的元素点击事件的 React Hook。

参数：

useDataTrack({
  trackTags?: Record<string, string[]>, // 埋点标签映射对象
  type?: string, // 类型标识，当为 'product' 时会从 product 中获取额外的 trackTags
  product?: {
    variants?: Array<{
      metafields?: {
        trackTags?: Record<string, string[]>
      }
    }>
  }
});

特性：

• 自动向上查找最多 3 层父元素，寻找带有 data-track 属性的元素
• 支持从产品 metafields 中合并额外的 trackTags（当 type='product' 时）
• 自动将 trackTags 缓存到 sessionStorage
• 组件卸载时自动清理事件监听器

Pixels 组件

GtagPixel

Google Analytics Pixel 组件。

<GtagPixel
  pixelIds={string | string[]}
  enabled={boolean}
  debug?: boolean
/>

MetaPixel

Meta Pixel 组件。

<MetaPixel
  pixelIds={string | string[]}
  enabled={boolean}
  debug?: boolean
/>

PixelsManager

Pixel 管理器组件，根据类型自动选择对应的 Pixel 组件。

<PixelsManager
  type="gtag" | "meta"
  pixelIds={string | string[]}
  enabled={boolean}
  debug?: boolean
/>

类型定义

所有类型都可以从包中导入：

import type {
  TrackConfig,
  GtagTrackParams,
  MetaTrackParams,
  TrackByTagsData,
  TrackByTagsParams,
  UseDataTrackOptions,
  PlatformType,
  // ... 更多类型
} from "@anker-in/analysis";

导出路径

包支持多个导出路径：

// 主入口
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";

开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 类型检查
pnpm check-types

# 代码检查
pnpm lint

License

MIT