前端埋点与数据分析

What — 是什么

埋点

前端埋点（Tracking / Instrumentation）是在应用代码中植入数据采集逻辑的技术手段，目的是在用户与页面交互时自动记录行为数据，为后续分析提供原始素材。埋点是前端数据采集的核心手段，是整个数据分析链路的起点。

核心职责：

• 用户行为采集：点击、滚动、输入、页面跳转等操作
• 业务事件记录：下单、注册、分享、支付等关键业务动作
• 性能数据收集：页面加载耗时、接口响应时间、资源体积等
• 异常信息捕获：JS 错误、接口失败、白屏等故障数据
• 设备与环境信息：浏览器、操作系统、分辨率、网络状态等

数据分析

数据分析是埋点数据的消费端，通过对采集到的原始数据进行清洗、聚合、建模和可视化，驱动产品决策与业务增长。

分析维度：

埋点三大方式

核心概念

数据流转架构

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  用户交互     │────▶│  埋点 SDK     │────▶│  数据上报     │
│  点击/输入    │     │  事件采集     │     │  批量/离线    │
│  页面跳转     │     │  数据组装     │     │  sendBeacon  │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                 │
                                                 ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  数据可视化   │◀────│  数据分析     │◀────│  数据接收     │
│  Dashboard   │     │  漏斗/留存    │     │  日志服务     │
│  热力图      │     │  路径/分群    │     │  ETL 清洗    │
└──────────────┘     └──────────────┘     └──────────────┘

Why — 为什么用

三种埋点方式对比

产品决策需要数据支撑

没有埋点数据，产品决策只能靠”拍脑袋”：

• 功能优先级：埋点数据显示某功能使用率仅 2%，不应继续投入
• 用户流失点：漏斗分析发现注册第三步流失率 60%，需优化
• 界面改版效果：AB 测试数据显示新版本转化率提升 15%

典型使用场景

1. 用户行为分析：了解用户如何使用产品，哪些功能受欢迎
2. AB 测试：对比不同方案的效果差异，用数据做决策
3. 转化率优化：定位漏斗中的流失环节，针对性优化
4. 运营决策：活动效果评估、渠道质量对比、用户分群运营
5. 性能监控：页面加载速度、接口响应时间影响用户体验
6. 异常发现：某个页面错误率飙升，及时告警修复
7. 合规审计：关键操作留痕，满足监管要求

How — 怎么做

1. 埋点架构设计

SDK 整体架构

┌─────────────────────────────────────────────────┐
│                  埋点 SDK                        │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐ │
│  │ 事件采集  │  │ 数据组装  │  │  上报策略      │ │
│  │          │  │          │  │               │ │
│  │ ·手动埋点│  │ ·事件模型│  │ ·批量上报     │ │
│  │ ·自动采集│  │ ·公共属性│  │ ·离线缓存     │ │
│  │ ·曝光监听│  │ ·数据校验│  │ ·页面卸载上报 │ │
│  └──────────┘  └──────────┘  └───────────────┘ │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐ │
│  │ 插件系统  │  │ 配置中心  │  │  调试工具      │ │
│  │          │  │          │  │               │ │
│  │ ·生命周期│  │ ·采样率  │  │ ·事件日志     │ │
│  │ ·中间件  │  │ ·开关    │  │ ·数据校验     │ │
│  │ ·扩展钩子│  │ ·灰度    │  │ ·埋点检测     │ │
│  └──────────┘  └──────────┘  └───────────────┘ │
└─────────────────────────────────────────────────┘

事件模型设计

// tracker/types.ts
interface TrackEvent {
  // 事件基础信息
  eventId: string;           // 事件唯一 ID（UUID）
  eventType: string;         // 事件类型：click / pageview / expose / custom
  eventName: string;         // 事件名称：button_click / page_view / element_expose
  timestamp: number;         // 事件发生时间戳

  // 用户信息
  userId?: string;           // 登录用户 ID
  deviceId: string;          // 设备唯一标识（UV 识别）
  sessionId: string;         // 会话 ID

  // 页面信息
  pageUrl: string;           // 当前页面 URL
  pagePath: string;          // 路由路径
  referrer: string;          // 来源页面
  pageTitle: string;         // 页面标题

  // 业务数据
  properties: Record<string, unknown>;  // 自定义属性

  // 环境信息
  environment: {
    userAgent: string;       // 浏览器 UA
    viewport: string;        // 视口尺寸
    screen: string;          // 屏幕分辨率
    language: string;        // 语言
    platform: string;        // 操作系统
    networkType: string;     // 网络类型
    cookieEnabled: boolean;  // Cookie 是否可用
  };
}

SDK 核心类设计

// tracker/Tracker.ts
type EventName = string;
type Properties = Record<string, unknown>;
type Plugin = {
  name: string;
  beforeTrack?: (event: TrackEvent) => TrackEvent | null;
  afterTrack?: (event: TrackEvent) => void;
};

interface TrackerConfig {
  appId: string;              // 应用标识
  endpoint: string;           // 上报地址
  sampleRate?: number;        // 采样率 0-1
  batchSize?: number;         // 批量上报条数
  batchInterval?: number;     // 批量上报间隔（ms）
  enableAutoTrack?: boolean;  // 启用自动采集
  enableSPA?: boolean;        // SPA 路由监听
  debug?: boolean;            // 调试模式
}

class Tracker {
  private config: Required<TrackerConfig>;
  private queue: TrackEvent[] = [];
  private plugins: Plugin[] = [];
  private commonProperties: Properties = {};
  private timer: ReturnType<typeof setInterval> | null = null;
  private userId: string = '';
  private deviceId: string = '';
  private sessionId: string = '';

  constructor(config: TrackerConfig) {
    this.config = {
      sampleRate: 1,
      batchSize: 10,
      batchInterval: 5000,
      enableAutoTrack: false,
      enableSPA: false,
      debug: false,
      ...config,
    };

    this.deviceId = this.getOrCreateDeviceId();
    this.sessionId = this.createSessionId();
    this.initAutoTrack();
    this.startBatchTimer();
    this.bindUnloadEvent();
  }

  // 手动埋点
  track(eventName: EventName, properties: Properties = {}): void {
    // 采样率控制
    if (Math.random() > this.config.sampleRate) return;

    const event = this.buildEvent(eventName, properties);
    const processedEvent = this.runPlugins(event);
    if (!processedEvent) return;

    this.enqueue(processedEvent);
  }

  // 页面浏览
  pageView(properties: Properties = {}): void {
    this.track('page_view', {
      url: location.href,
      path: location.pathname,
      referrer: document.referrer,
      title: document.title,
      ...properties,
    });
  }

  // 设置用户 ID
  identify(userId: string): void {
    this.userId = userId;
  }

  // 设置公共属性
  setCommonProperties(properties: Properties): void {
    Object.assign(this.commonProperties, properties);
  }

  // 注册插件
  use(plugin: Plugin): void {
    this.plugins.push(plugin);
  }

  // 构建事件对象
  private buildEvent(eventName: EventName, properties: Properties): TrackEvent {
    return {
      eventId: this.generateId(),
      eventType: 'custom',
      eventName,
      timestamp: Date.now(),
      userId: this.userId || undefined,
      deviceId: this.deviceId,
      sessionId: this.sessionId,
      pageUrl: location.href,
      pagePath: location.pathname,
      referrer: document.referrer,
      pageTitle: document.title,
      properties: { ...this.commonProperties, ...properties },
      environment: this.collectEnvironment(),
    };
  }

  // 执行插件链
  private runPlugins(event: TrackEvent): TrackEvent | null {
    let result = event;
    for (const plugin of this.plugins) {
      if (plugin.beforeTrack) {
        result = plugin.beforeTrack(result);
        if (!result) return null; // 插件拦截，不上报
      }
    }
    return result;
  }

  // 入队
  private enqueue(event: TrackEvent): void {
    this.queue.push(event);
    if (this.config.debug) {
      console.log('[Tracker] event:', event);
    }
    if (this.queue.length >= this.config.batchSize) {
      this.flush();
    }
  }

  // 批量上报
  flush(): void {
    if (this.queue.length === 0) return;
    const events = this.queue.splice(0);
    this.send(events);
  }

  // 发送数据
  private send(events: TrackEvent[]): void {
    const data = JSON.stringify({
      appId: this.config.appId,
      events,
    });

    // 优先 sendBeacon
    if (navigator.sendBeacon) {
      const blob = new Blob([data], { type: 'application/json' });
      const success = navigator.sendBeacon(this.config.endpoint, blob);
      if (success) return;
    }

    // 降级 XMLHttpRequest
    const xhr = new XMLHttpRequest();
    xhr.open('POST', this.config.endpoint, true);
    xhr.setRequestHeader('Content-Type', 'application/json');
    xhr.send(data);
  }

  // 启动批量定时器
  private startBatchTimer(): void {
    this.timer = setInterval(() => this.flush(), this.config.batchInterval);
  }

  // 绑定页面卸载事件
  private bindUnloadEvent(): void {
    const handler = () => this.flush();
    window.addEventListener('visibilitychange', () => {
      if (document.visibilityState === 'hidden') handler();
    });
    window.addEventListener('pagehide', handler);
  }

  // 设备 ID（UV 识别）
  private getOrCreateDeviceId(): string {
    const KEY = '__tracker_device_id__';
    let id = localStorage.getItem(KEY);
    if (!id) {
      id = this.generateId();
      localStorage.setItem(KEY, id);
    }
    return id;
  }

  // 会话 ID
  private createSessionId(): string {
    const KEY = '__tracker_session_id__';
    const SESSION_TIMEOUT = 30 * 60 * 1000; // 30 分钟
    const stored = sessionStorage.getItem(KEY);
    if (stored) {
      const { id, timestamp } = JSON.parse(stored);
      if (Date.now() - timestamp < SESSION_TIMEOUT) {
        sessionStorage.setItem(KEY, JSON.stringify({ id, timestamp: Date.now() }));
        return id;
      }
    }
    const id = this.generateId();
    sessionStorage.setItem(KEY, JSON.stringify({ id, timestamp: Date.now() }));
    return id;
  }

  private generateId(): string {
    return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
  }

  private collectEnvironment(): TrackEvent['environment'] {
    const conn = (navigator as any).connection;
    return {
      userAgent: navigator.userAgent,
      viewport: `${window.innerWidth}x${window.innerHeight}`,
      screen: `${screen.width}x${screen.height}`,
      language: navigator.language,
      platform: navigator.platform,
      networkType: conn?.effectiveType || 'unknown',
      cookieEnabled: navigator.cookieEnabled,
    };
  }

  // SPA 自动采集初始化
  private initAutoTrack(): void {
    if (this.config.enableAutoTrack) {
      this.setupAutoClickTracking();
    }
    if (this.config.enableSPA) {
      this.setupSPARouting();
    }
  }

  private setupAutoClickTracking(): void {
    document.addEventListener('click', (e) => {
      const target = e.target as HTMLElement;
      const xpath = this.getXPath(target);
      this.track('auto_click', {
        tagName: target.tagName,
        xpath,
        text: target.innerText?.slice(0, 50),
        className: target.className,
      });
    }, true);
  }

  // 获取元素 XPath
  private getXPath(element: HTMLElement): string {
    if (element.id) return `//*[@id="${element.id}"]`;
    const parts: string[] = [];
    let node: HTMLElement | null = element;
    while (node && node.nodeType === Node.ELEMENT_NODE) {
      let selector = node.tagName.toLowerCase();
      if (node.id) {
        selector += `#${node.id}`;
        parts.unshift(selector);
        break;
      }
      const parent = node.parentElement;
      if (parent) {
        const siblings = Array.from(parent.children).filter(
          (c) => c.tagName === node!.tagName
        );
        if (siblings.length > 1) {
          const index = siblings.indexOf(node) + 1;
          selector += `[${index}]`;
        }
      }
      parts.unshift(selector);
      node = node.parentElement;
    }
    return '/' + parts.join('/');
  }

  private setupSPARouting(): void {
    // 见 PV/UV 统计章节
  }

  destroy(): void {
    this.flush();
    if (this.timer) clearInterval(this.timer);
  }
}

// 使用示例
const tracker = new Tracker({
  appId: 'my-app',
  endpoint: 'https://track.example.com/collect',
  batchSize: 20,
  batchInterval: 5000,
  enableAutoTrack: true,
  enableSPA: true,
  debug: process.env.NODE_ENV === 'development',
});

tracker.identify('user_12345');
tracker.setCommonProperties({ appVersion: '2.1.0', channel: 'official' });

2. 代码埋点实现

手动埋点函数

// tracker/manual.ts
class ManualTracker {
  // 按钮点击埋点
  trackButtonClick(buttonName: string, extra?: Properties): void {
    tracker.track('button_click', {
      button_name: buttonName,
      page_module: this.getCurrentModule(),
      ...extra,
    });
  }

  // 页面停留时长
  private enterTime: Record<string, number> = {};

  trackPageEnter(pageName: string): void {
    this.enterTime[pageName] = Date.now();
    tracker.track('page_enter', { page_name: pageName });
  }

  trackPageLeave(pageName: string): void {
    const enterTime = this.enterTime[pageName];
    if (enterTime) {
      const duration = Date.now() - enterTime;
      tracker.track('page_leave', {
        page_name: pageName,
        duration_ms: duration,
        duration_sec: Math.round(duration / 1000),
      });
      delete this.enterTime[pageName];
    }
  }

  // 接口请求埋点
  trackApiRequest(apiName: string, duration: number, success: boolean, extra?: Properties): void {
    tracker.track('api_request', {
      api_name: apiName,
      duration_ms: duration,
      success,
      ...extra,
    });
  }

  private getCurrentModule(): string {
    const path = location.pathname;
    const segments = path.split('/').filter(Boolean);
    return segments[0] || 'home';
  }
}

装饰器埋点（TypeScript）

// tracker/decorator.ts
function track(eventName: string, getProperties?: (...args: any[]) => Properties) {
  return function (
    _target: any,
    _propertyKey: string,
    descriptor: PropertyDescriptor
  ) {
    const originalMethod = descriptor.value;
    descriptor.value = function (...args: any[]) {
      const result = originalMethod.apply(this, args);
      const properties = getProperties ? getProperties(...args) : {};
      tracker.track(eventName, properties);
      return result;
    };
    return descriptor;
  };
}

// 使用示例
class OrderService {
  @track('order_submit', (order) => ({
    order_id: order.id,
    amount: order.amount,
    item_count: order.items.length,
  }))
  submitOrder(order: Order): Promise<Result> {
    return api.post('/orders', order);
  }

  @track('order_cancel', (orderId, reason) => ({
    order_id: orderId,
    cancel_reason: reason,
  }))
  cancelOrder(orderId: string, reason: string): Promise<Result> {
    return api.delete(`/orders/${orderId}`);
  }

  @track('order_pay', (orderId, method) => ({
    order_id: orderId,
    payment_method: method,
  }))
  payOrder(orderId: string, method: string): Promise<Result> {
    return api.post(`/orders/${orderId}/pay`, { method });
  }
}

React Hook 埋点

// tracker/react.ts
import { useEffect, useRef, useCallback } from 'react';

// 点击埋点 Hook
function useTrackClick(eventName: string, properties?: Properties) {
  return useCallback(() => {
    tracker.track(eventName, properties);
  }, [eventName, properties]);
}

// 使用示例
function BuyButton({ productId, price }: { productId: string; price: number }) {
  const handleClick = useTrackClick('buy_button_click', {
    product_id: productId,
    price,
  });

  return <button onClick={handleClick}>立即购买</button>;
}

// 页面浏览埋点 Hook
function useTrackPageView(pageName: string, properties?: Properties) {
  useEffect(() => {
    tracker.pageView({ page_name: pageName, ...properties });
  }, [pageName]); // 路由变化时重新触发
}

// 页面停留时长 Hook
function useTrackPageDuration(pageName: string) {
  const enterTimeRef = useRef(Date.now());

  useEffect(() => {
    enterTimeRef.current = Date.now();
    tracker.track('page_enter', { page_name: pageName });

    return () => {
      const duration = Date.now() - enterTimeRef.current;
      tracker.track('page_leave', {
        page_name: pageName,
        duration_ms: duration,
      });
    };
  }, [pageName]);
}

// 曝光埋点 Hook
function useTrackExposure(
  ref: React.RefObject<HTMLElement>,
  eventName: string,
  properties?: Properties,
  options?: { threshold?: number; trackOnce?: boolean }
) {
  const trackedRef = useRef(false);

  useEffect(() => {
    const element = ref.current;
    if (!element) return;
    if (options?.trackOnce && trackedRef.current) return;

    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          if (options?.trackOnce && trackedRef.current) return;
          trackedRef.current = true;
          tracker.track(eventName, properties);
        }
      },
      { threshold: options?.threshold ?? 0.5 }
    );

    observer.observe(element);
    return () => observer.disconnect();
  }, [ref, eventName]);
}

// 使用示例
function ProductCard({ product }: { product: Product }) {
  const cardRef = useRef<HTMLDivElement>(null);

  useTrackExposure(cardRef, 'product_card_expose', {
    product_id: product.id,
    product_name: product.name,
  });

  return (
    <div ref={cardRef}>
      <h3>{product.name}</h3>
      <p>¥{product.price}</p>
    </div>
  );
}

// 组合使用
function ProductPage() {
  useTrackPageView('product_page');
  useTrackPageDuration('product_page');

  return <ProductList />;
}

Vue 指令埋点

// tracker/vue.ts
import type { App, Directive, DirectiveBinding } from 'vue';

// v-track 点击埋点指令
const trackDirective: Directive = {
  mounted(el: HTMLElement, binding: DirectiveBinding) {
    const { arg, value } = binding;

    switch (arg) {
      case 'click':
        el.addEventListener('click', () => {
          tracker.track('element_click', typeof value === 'object' ? value : { name: value });
        });
        break;

      case 'expose':
        setupExposure(el, value);
        break;

      case 'input':
        el.addEventListener('change', () => {
          tracker.track('input_change', typeof value === 'object' ? value : { name: value });
        });
        break;
    }
  },
};

// 曝光指令
function setupExposure(el: HTMLElement, value: any) {
  const observer = new IntersectionObserver(
    ([entry]) => {
      if (entry.isIntersecting) {
        tracker.track('element_expose', typeof value === 'object' ? value : { name: value });
        observer.disconnect(); // 只曝光一次
      }
    },
    { threshold: 0.5 }
  );
  observer.observe(el);
}

// 注册插件
export const TrackerPlugin = {
  install(app: App) {
    app.directive('track', trackDirective);
  },
};

// 使用示例
// <button v-track:click="{ button_name: 'submit', module: 'form' }">提交</button>
// <div v-track:expose="{ element_name: 'banner', position: 'top' }">广告位</div>
// <input v-track:input="{ input_name: 'search' }" />

3. 无痕埋点

全局事件代理

// tracker/auto-track.ts
class AutoTracker {
  private trackedElements = new WeakSet<Element>();

  init(): void {
    this.proxyClickEvents();
    this.proxyInputEvents();
    this.autoTrackPV();
    this.trackPerformance();
  }

  // 代理所有点击事件
  private proxyClickEvents(): void {
    document.addEventListener(
      'click',
      (e: MouseEvent) => {
        const target = e.target as HTMLElement;
        if (!target) return;

        // 向上查找带埋点标识的元素
        const trackEl = target.closest('[data-track]') as HTMLElement;
        if (trackEl) {
          // 有 data-track 属性的元素做精确埋点
          const trackName = trackEl.dataset.track;
          const trackParams = trackEl.dataset.trackParams;
          tracker.track(trackName || 'click', {
            ...this.parseParams(trackParams),
            element_text: trackEl.innerText?.slice(0, 50),
          });
          return;
        }

        // 无标识元素做自动采集
        const xpath = this.getXPath(target);
        const selector = this.getCSSSelector(target);

        tracker.track('auto_click', {
          xpath,
          selector,
          tag_name: target.tagName.toLowerCase(),
          element_text: target.innerText?.slice(0, 50),
          element_class: target.className?.toString().slice(0, 100),
          element_id: target.id || undefined,
          page_x: e.pageX,
          page_y: e.pageY,
          viewport_x: e.clientX,
          viewport_y: e.clientY,
        });
      },
      true // 捕获阶段，最先执行
    );
  }

  // 代理输入事件
  private proxyInputEvents(): void {
    document.addEventListener(
      'focus',
      (e: FocusEvent) => {
        const target = e.target as HTMLInputElement;
        if (!target || !target.tagName) return;
        if (!['INPUT', 'TEXTAREA', 'SELECT'].includes(target.tagName)) return;

        tracker.track('auto_input_focus', {
          tag_name: target.tagName.toLowerCase(),
          input_type: target.type,
          input_name: target.name,
          xpath: this.getXPath(target),
        });
      },
      true
    );
  }

  // 自动采集 PV
  private autoTrackPV(): void {
    tracker.pageView();
  }

  // 解析 data-track-params
  private parseParams(paramsStr?: string): Properties {
    if (!paramsStr) return {};
    try {
      return JSON.parse(paramsStr);
    } catch {
      return { raw_params: paramsStr };
    }
  }

  // CSS 选择器定位
  private getCSSSelector(el: HTMLElement): string {
    const parts: string[] = [];
    let node: HTMLElement | null = el;
    while (node && node !== document.body) {
      let selector = node.tagName.toLowerCase();
      if (node.id) {
        selector += `#${CSS.escape(node.id)}`;
        parts.unshift(selector);
        break;
      }
      if (node.className && typeof node.className === 'string') {
        const classes = node.className.trim().split(/\s+/).slice(0, 2);
        if (classes.length) selector += '.' + classes.map(CSS.escape).join('.');
      }
      const parent = node.parentElement;
      if (parent) {
        const siblings = Array.from(parent.children).filter(
          (c) => c.tagName === node!.tagName
        );
        if (siblings.length > 1) {
          const index = siblings.indexOf(node) + 1;
          selector += `:nth-of-type(${index})`;
        }
      }
      parts.unshift(selector);
      node = node.parentElement;
    }
    return parts.join(' > ');
  }

  // XPath 定位（复用前文方法）
  private getXPath(element: HTMLElement): string {
    if (element.id) return `//*[@id="${element.id}"]`;
    const parts: string[] = [];
    let node: HTMLElement | null = element;
    while (node && node.nodeType === Node.ELEMENT_NODE) {
      let selector = node.tagName.toLowerCase();
      if (node.id) {
        selector += `#${node.id}`;
        parts.unshift(selector);
        break;
      }
      const parent = node.parentElement;
      if (parent) {
        const siblings = Array.from(parent.children).filter(
          (c) => c.tagName === node!.tagName
        );
        if (siblings.length > 1) {
          const index = siblings.indexOf(node) + 1;
          selector += `[${index}]`;
        }
      }
      parts.unshift(selector);
      node = node.parentElement;
    }
    return '/' + parts.join('/');
  }

  // 数据量控制：采样 + 限流
  private sendQueue: TrackEvent[] = [];
  private maxQPS = 5; // 每秒最多上报 5 条
  private lastSendTime = 0;

  private throttledTrack(event: TrackEvent): void {
    const now = Date.now();
    if (now - this.lastSendTime < 1000 / this.maxQPS) {
      // 限流，丢弃或入队
      return;
    }
    this.lastSendTime = now;
    this.sendQueue.push(event);
  }
}

HTML data 属性约定

<!-- 精确埋点：data-track 指定事件名 -->
<button data-track="submit_order" data-track-params='{"from":"cart"}'>
  提交订单
</button>

<!-- 自动采集：无 data-track 的元素由 SDK 自动采集 -->
<div class="product-card">
  <h3>商品名称</h3>
  <button>加入购物车</button>
</div>

<!-- 曝光埋点：data-track-expose -->
<div data-track-expose="banner_expose" data-track-params='{"banner_id":"home_top"}'>
  <img src="banner.jpg" alt="活动横幅" />
</div>

4. 曝光埋点

IntersectionObserver 实现

// tracker/exposure.ts
interface ExposureOptions {
  threshold?: number;        // 可见比例阈值，默认 0.5（50% 可见）
  trackOnce?: boolean;       // 是否只曝光一次，默认 true
  minDuration?: number;      // 最小曝光时长（ms），默认 0
  rootMargin?: string;       // 观察区域边距
}

interface ExposureTarget {
  element: HTMLElement;
  eventName: string;
  properties: Properties;
  options: Required<ExposureOptions>;
  enterTime: number | null;   // 进入视口的时间
  hasTracked: boolean;        // 是否已上报
}

class ExposureTracker {
  private observer: IntersectionObserver;
  private targets = new Map<HTMLElement, ExposureTarget>();

  constructor() {
    this.observer = new IntersectionObserver(
      (entries) => this.handleIntersection(entries),
      {
        threshold: [0, 0.25, 0.5, 0.75, 1],
        rootMargin: '0px',
      }
    );
  }

  // 注册曝光监听
  observe(
    element: HTMLElement,
    eventName: string,
    properties: Properties = {},
    options: ExposureOptions = {}
  ): void {
    const fullOptions: Required<ExposureOptions> = {
      threshold: 0.5,
      trackOnce: true,
      minDuration: 0,
      rootMargin: '0px',
      ...options,
    };

    this.targets.set(element, {
      element,
      eventName,
      properties,
      options: fullOptions,
      enterTime: null,
      hasTracked: false,
    });

    this.observer.observe(element);
  }

  // 取消监听
  unobserve(element: HTMLElement): void {
    this.targets.delete(element);
    this.observer.unobserve(element);
  }

  // 处理交叉变化
  private handleIntersection(entries: IntersectionObserverEntry[]): void {
    const now = Date.now();

    for (const entry of entries) {
      const target = this.targets.get(entry.target as HTMLElement);
      if (!target) continue;
      if (target.hasTracked && target.options.trackOnce) continue;

      const isVisible = entry.intersectionRatio >= target.options.threshold;

      if (isVisible && target.enterTime === null) {
        // 进入视口
        target.enterTime = now;
      } else if (!isVisible && target.enterTime !== null) {
        // 离开视口
        const duration = now - target.enterTime;
        target.enterTime = null;

        // 判断是否为有效曝光
        if (duration >= target.options.minDuration) {
          this.reportExposure(target, duration);
        }
      }
    }
  }

  // 上报曝光事件
  private reportExposure(target: ExposureTarget, duration: number): void {
    target.hasTracked = true;

    tracker.track(target.eventName, {
      ...target.properties,
      exposure_duration_ms: duration,
      exposure_duration_sec: Math.round(duration / 1000),
      is_valid_exposure: true,
    });

    if (target.options.trackOnce) {
      this.unobserve(target.element);
    }
  }

  // 销毁
  destroy(): void {
    this.observer.disconnect();
    this.targets.clear();
  }
}

列表曝光（虚拟滚动场景）

// tracker/list-exposure.ts
import { useEffect, useRef } from 'react';

interface ListExposureOptions {
  threshold?: number;
  minDuration?: number;
  trackOnce?: boolean;
}

function useTrackListExposure<T>(
  listRef: React.RefObject<HTMLElement>,
  items: T[],
  getItemId: (item: T) => string,
  eventName: string,
  getProperties: (item: T) => Properties,
  options?: ListExposureOptions
) {
  const exposureTracker = useRef(new ExposureTracker());
  const trackedIds = useRef(new Set<string>());

  useEffect(() => {
    const container = listRef.current;
    if (!container) return;

    const observer = new IntersectionObserver(
      (entries) => {
        for (const entry of entries) {
          const index = Number((entry.target as HTMLElement).dataset.index);
          const item = items[index];
          if (!item) continue;

          const itemId = getItemId(item);

          if (entry.isIntersecting) {
            if (options?.trackOnce && trackedIds.current.has(itemId)) continue;
            trackedIds.current.add(itemId);

            tracker.track(eventName, {
              ...getProperties(item),
              item_index: index,
              item_id: itemId,
              list_length: items.length,
            });
          }
        }
      },
      { threshold: options?.threshold ?? 0.5 }
    );

    // 观察列表中每个子元素
    const children = container.children;
    for (let i = 0; i < children.length; i++) {
      (children[i] as HTMLElement).dataset.index = String(i);
      observer.observe(children[i]);
    }

    return () => observer.disconnect();
  }, [items]);
}

// 使用示例：商品列表曝光
function ProductList({ products }: { products: Product[] }) {
  const listRef = useRef<HTMLDivElement>(null);

  useTrackListExposure(
    listRef,
    products,
    (p) => p.id,
    'product_list_expose',
    (p) => ({ product_id: p.id, product_name: p.name, price: p.price }),
    { trackOnce: true, minDuration: 500 }
  );

  return (
    <div ref={listRef} className="product-list">
      {products.map((product) => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
}

5. PV/UV 统计

SPA 路由变化监听

// tracker/spa-pv.ts
class SPAPVTracker {
  private currentPath: string = '';
  private enterTime: number = 0;

  init(): void {
    // 首次加载
    this.trackPV();

    // 监听 history 变化
    this.patchHistoryAPI();

    // 监听 hash 变化
    window.addEventListener('hashchange', () => {
      this.trackPV();
    });

    // 监听 popstate（浏览器前进/后退）
    window.addEventListener('popstate', () => {
      this.trackPV();
    });
  }

  // 劫持 history.pushState / replaceState
  private patchHistoryAPI(): void {
    const originalPushState = history.pushState.bind(history);
    const originalReplaceState = history.replaceState.bind(history);

    history.pushState = (...args: Parameters<typeof history.pushState>) => {
      originalPushState(...args);
      this.trackPV();
    };

    history.replaceState = (...args: Parameters<typeof history.replaceState>) => {
      originalReplaceState(...args);
      this.trackPV();
    };
  }

  // 记录 PV 并计算页面停留时长
  private trackPV(): void {
    const now = Date.now();
    const currentPath = location.pathname + location.search;

    // 上报上一页面的停留时长
    if (this.currentPath && this.enterTime) {
      const duration = now - this.enterTime;
      tracker.track('page_leave', {
        page_path: this.currentPath,
        duration_ms: duration,
      });
    }

    // 上报新页面 PV
    this.currentPath = currentPath;
    this.enterTime = now;

    tracker.track('page_view', {
      page_path: currentPath,
      page_url: location.href,
      referrer: document.referrer,
      page_title: document.title,
    });
  }
}

Vue Router 集成

// tracker/vue-router.ts
import type { Router } from 'vue-router';

function setupVueRouterTracking(router: Router) {
  router.afterEach((to, from) => {
    tracker.track('page_view', {
      page_path: to.path,
      page_name: to.name as string,
      page_url: location.href,
      referrer: from.fullPath,
      page_title: document.title,
      route_params: JSON.stringify(to.params),
      query_params: JSON.stringify(to.query),
    });
  });
}

// main.ts
const router = createRouter({ ... });
setupVueRouterTracking(router);

React Router 集成

// tracker/react-router.ts
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function RouteTracker() {
  const location = useLocation();

  useEffect(() => {
    tracker.track('page_view', {
      page_path: location.pathname,
      page_url: location.href,
      page_search: location.search,
      page_hash: location.hash,
      referrer: document.referrer,
      page_title: document.title,
    });
  }, [location]);

  return null;
}

// App.tsx
function App() {
  return (
    <BrowserRouter>
      <RouteTracker />
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/product/:id" element={<Product />} />
      </Routes>
    </BrowserRouter>
  );
}

UV 识别方案

// tracker/uv.ts
class UVTracker {
  private DEVICE_ID_KEY = '__uv_device_id__';
  private SESSION_KEY = '__uv_session__';

  // 设备级唯一标识（跨会话持久）
  getDeviceId(): string {
    let id = this.getCookie(this.DEVICE_ID_KEY);
    if (!id) {
      id = this.generateFingerprint();
      this.setCookie(this.DEVICE_ID_KEY, id, 365); // 365 天
    }
    return id;
  }

  // 会话级标识（30 分钟超时）
  getSessionId(): string {
    const stored = this.getCookie(this.SESSION_KEY);
    if (stored) {
      const { id, ts } = JSON.parse(stored);
      if (Date.now() - ts < 30 * 60 * 1000) {
        this.setCookie(this.SESSION_KEY, JSON.stringify({ id, ts: Date.now() }), 1);
        return id;
      }
    }
    const id = crypto.randomUUID?.() || this.generateId();
    this.setCookie(this.SESSION_KEY, JSON.stringify({ id, ts: Date.now() }), 1);
    return id;
  }

  // 浏览器指纹生成（Canvas + WebGL + 字体 + 插件等）
  private generateFingerprint(): string {
    const components = [
      navigator.userAgent,
      navigator.language,
      screen.width + 'x' + screen.height,
      screen.colorDepth,
      new Date().getTimezoneOffset(),
      navigator.plugins.length,
      this.getCanvasFingerprint(),
    ];
    return this.hash(components.join('||'));
  }

  // Canvas 指纹
  private getCanvasFingerprint(): string {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d')!;
    ctx.textBaseline = 'top';
    ctx.font = '14px Arial';
    ctx.fillText('fingerprint', 2, 2);
    return canvas.toDataURL().slice(-50);
  }

  // 简单哈希
  private hash(str: string): string {
    let hash = 0;
    for (let i = 0; i < str.length; i++) {
      const char = str.charCodeAt(i);
      hash = ((hash << 5) - hash) + char;
      hash |= 0;
    }
    return Math.abs(hash).toString(36);
  }

  private generateId(): string {
    return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
  }

  private getCookie(name: string): string | null {
    const match = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
    return match ? decodeURIComponent(match[1]) : null;
  }

  private setCookie(name: string, value: string, days: number): void {
    const expires = new Date(Date.now() + days * 86400000).toUTCString();
    document.cookie = `${name}=${encodeURIComponent(value)};expires=${expires};path=/;SameSite=Lax`;
  }
}

6. 性能数据采集

// tracker/performance.ts
class PerformanceCollector {
  collect(): void {
    this.collectNavigationTiming();
    this.collectWebVitals();
    this.collectResourceTiming();
    this.collectCustomMetrics();
  }

  // Navigation Timing：页面加载全链路
  private collectNavigationTiming(): void {
    const observer = new PerformanceObserver((list) => {
      for (const entry of list.getEntries()) {
        if (entry.entryType !== 'navigation') continue;
        const nav = entry as PerformanceNavigationTiming;

        tracker.track('performance_navigation', {
          // 关键时间节点
          dns_lookup_ms: nav.domainLookupEnd - nav.domainLookupStart,
          tcp_connect_ms: nav.connectEnd - nav.connectStart,
          ssl_handshake_ms: nav.secureConnectionStart
            ? nav.connectEnd - nav.secureConnectionStart
            : 0,
          ttfb_ms: nav.responseStart - nav.requestStart,         // Time to First Byte
          content_download_ms: nav.responseEnd - nav.responseStart,
          dom_parse_ms: nav.domInteractive - nav.responseEnd,
          dom_ready_ms: nav.domContentLoadedEventEnd - nav.fetchStart,
          page_load_ms: nav.loadEventEnd - nav.fetchStart,       // 完整加载时间

          // 传输数据量
          transfer_size: nav.transferSize,
          encoded_body_size: nav.encodedBodySize,
          decoded_body_size: nav.decodedBodySize,

          // 连接信息
          protocol: nav.nextHopProtocol,        // h2 / h3
          redirect_count: nav.redirectCount,
        });
      }
    });

    observer.observe({ type: 'navigation', buffered: true });
  }

  // Web Vitals：核心性能指标
  private collectWebVitals(): void {
    // FCP（First Contentful Paint）：首次内容绘制
    this.observeMetric('paint', (entry) => {
      if (entry.name === 'first-contentful-paint') {
        tracker.track('performance_fcp', {
          fcp_ms: entry.startTime,
          rating: this.rateFCP(entry.startTime),
        });
      }
    });

    // LCP（Largest Contentful Paint）：最大内容绘制
    this.observeMetric('largest-contentful-paint', (entry) => {
      tracker.track('performance_lcp', {
        lcp_ms: entry.startTime,
        rating: this.rateLCP(entry.startTime),
        element: entry.element?.tagName,
        url: (entry as any).url || undefined,
      });
    });

    // FID（First Input Delay）：首次输入延迟
    this.observeMetric('first-input', (entry) => {
      const fid = (entry as any).processingStart - entry.startTime;
      tracker.track('performance_fid', {
        fid_ms: fid,
        rating: this.rateFID(fid),
        event_type: entry.name,
      });
    });

    // CLS（Cumulative Layout Shift）：累积布局偏移
    let clsValue = 0;
    let clsEntries: any[] = [];
    let sessionValue = 0;
    let sessionEntries: any[] = [];

    this.observeMetric('layout-shift', (entry: any) => {
      if (!entry.hadRecentInput) {
        const firstSessionEntry = sessionEntries[0];
        const lastSessionEntry = sessionEntries[sessionEntries.length - 1];

        if (
          sessionValue &&
          entry.startTime - lastSessionEntry.startTime < 1000 &&
          entry.startTime - firstSessionEntry.startTime < 5000
        ) {
          sessionValue += entry.value;
          sessionEntries.push(entry);
        } else {
          sessionValue = entry.value;
          sessionEntries = [entry];
        }

        if (sessionValue > clsValue) {
          clsValue = sessionValue;
          clsEntries = [...sessionEntries];
        }
      }
    });

    // 页面隐藏时上报 CLS
    document.addEventListener('visibilitychange', () => {
      if (document.visibilityState === 'hidden' && clsValue > 0) {
        tracker.track('performance_cls', {
          cls_value: clsValue,
          rating: this.rateCLS(clsValue),
          shift_count: clsEntries.length,
        });
      }
    });

    // INP（Interaction to Next Paint）：交互到下一次绘制
    this.observeMetric('event', (entry: any) => {
      const duration = entry.duration;
      if (duration > 0) {
        tracker.track('performance_inp', {
          inp_ms: duration,
          event_type: entry.name,
          rating: this.rateINP(duration),
        });
      }
    });

    // TTFB（Time to First Byte）：首字节时间
    const navEntry = performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming;
    if (navEntry) {
      const ttfb = navEntry.responseStart - navEntry.requestStart;
      tracker.track('performance_ttfb', {
        ttfb_ms: ttfb,
        rating: this.rateTTFB(ttfb),
      });
    }
  }

  // 资源加载性能
  private collectResourceTiming(): void {
    const observer = new PerformanceObserver((list) => {
      for (const entry of list.getEntries()) {
        const resource = entry as PerformanceResourceTiming;
        // 只采集慢资源（> 1s）和关键资源
        if (resource.duration > 1000 || this.isCriticalResource(resource)) {
          tracker.track('performance_resource', {
            name: resource.name,
            type: resource.initiatorType,
            duration_ms: resource.duration,
            transfer_size: resource.transferSize,
            protocol: resource.nextHopProtocol,
            start_time: resource.startTime,
          });
        }
      }
    });
    observer.observe({ type: 'resource', buffered: true });
  }

  // 自定义业务指标
  private collectCustomMetrics(): void {
    // 使用 Performance Mark & Measure
    performance.mark('app_init_start');

    // ... 应用初始化逻辑 ...

    performance.mark('app_init_end');
    performance.measure('app_init_duration', 'app_init_start', 'app_init_end');

    const measures = performance.getEntriesByName('app_init_duration');
    if (measures.length) {
      tracker.track('performance_custom', {
        metric_name: 'app_init_duration',
        duration_ms: measures[0].duration,
      });
    }
  }

  private observeMetric(type: string, callback: (entry: any) => void): void {
    try {
      const observer = new PerformanceObserver((list) => {
        for (const entry of list.getEntries()) {
          callback(entry);
        }
      });
      observer.observe({ type, buffered: true });
    } catch {
      // 浏览器不支持该指标类型
    }
  }

  private isCriticalResource(resource: PerformanceResourceTiming): boolean {
    return ['script', 'link', 'xmlhttprequest', 'fetch'].includes(
      resource.initiatorType
    );
  }

  // 评级标准（基于 Google Web Vitals）
  private rateFCP(ms: number): 'good' | 'needs-improvement' | 'poor' {
    if (ms <= 1800) return 'good';
    if (ms <= 3000) return 'needs-improvement';
    return 'poor';
  }
  private rateLCP(ms: number): 'good' | 'needs-improvement' | 'poor' {
    if (ms <= 2500) return 'good';
    if (ms <= 4000) return 'needs-improvement';
    return 'poor';
  }
  private rateFID(ms: number): 'good' | 'needs-improvement' | 'poor' {
    if (ms <= 100) return 'good';
    if (ms <= 300) return 'needs-improvement';
    return 'poor';
  }
  private rateCLS(value: number): 'good' | 'needs-improvement' | 'poor' {
    if (value <= 0.1) return 'good';
    if (value <= 0.25) return 'needs-improvement';
    return 'poor';
  }
  private rateINP(ms: number): 'good' | 'needs-improvement' | 'poor' {
    if (ms <= 200) return 'good';
    if (ms <= 500) return 'needs-improvement';
    return 'poor';
  }
  private rateTTFB(ms: number): 'good' | 'needs-improvement' | 'poor' {
    if (ms <= 800) return 'good';
    if (ms <= 1800) return 'needs-improvement';
    return 'poor';
  }
}

7. 数据上报策略

// tracker/reporter.ts
interface ReporterConfig {
  endpoint: string;
  batchSize: number;
  batchInterval: number;
  maxRetryCount: number;
  enableOfflineCache: boolean;
  maxCacheSize: number;
}

class DataReporter {
  private queue: TrackEvent[] = [];
  private retryCount = 0;
  private db: IDBDatabase | null = null;
  private isOnline = navigator.onLine;

  constructor(private config: ReporterConfig) {
    this.initOfflineCache();
    this.bindEvents();
  }

  // 入队并判断是否立即上报
  enqueue(event: TrackEvent): void {
    this.queue.push(event);

    if (this.queue.length >= this.config.batchSize) {
      this.flush();
      return;
    }

    this.startTimer();
  }

  // 批量上报
  async flush(): Promise<void> {
    if (this.queue.length === 0) return;
    if (!this.isOnline) {
      await this.saveToCache(this.queue);
      this.queue = [];
      return;
    }

    const events = this.queue.splice(0);
    const success = await this.send(events);

    if (!success) {
      // 发送失败，放回队列或缓存
      this.queue.unshift(...events);
      this.retryCount++;
      if (this.retryCount > this.config.maxRetryCount) {
        await this.saveToCache(events);
        this.retryCount = 0;
      }
    } else {
      this.retryCount = 0;
    }
  }

  // 发送数据 — 多种策略
  private async send(events: TrackEvent[]): Promise<boolean> {
    const data = JSON.stringify({ events });

    // 策略 1：sendBeacon（页面卸载场景优先）
    if (navigator.sendBeacon) {
      const blob = new Blob([data], { type: 'application/json' });
      const success = navigator.sendBeacon(this.config.endpoint, blob);
      if (success) return true;
    }

    // 策略 2：1x1 GIF 图片（跨域友好）
    if (events.length <= 1) {
      try {
        return await this.sendViaImage(events[0]);
      } catch {
        // 降级
      }
    }

    // 策略 3：XMLHttpRequest / fetch（批量上报）
    return this.sendViaFetch(data);
  }

  // 1x1 GIF 上报
  private sendViaImage(event: TrackEvent): Promise<boolean> {
    return new Promise((resolve) => {
      const img = new Image();
      const params = new URLSearchParams({
        d: JSON.stringify(event),
      });
      img.onload = () => resolve(true);
      img.onerror = () => resolve(false);
      img.src = `${this.config.endpoint}/gif?${params.toString()}`;
    });
  }

  // Fetch 上报
  private async sendViaFetch(data: string): Promise<boolean> {
    try {
      const response = await fetch(this.config.endpoint, {
        method: 'POST',
        body: data,
        headers: { 'Content-Type': 'application/json' },
        keepalive: true, // 页面卸载时仍能发送
      });
      return response.ok;
    } catch {
      return false;
    }
  }

  // 页面卸载前上报
  private flushOnUnload(): void {
    if (this.queue.length === 0) return;
    const data = JSON.stringify({ events: this.queue });
    this.queue = [];

    // sendBeacon 是页面卸载时最可靠的上报方式
    if (navigator.sendBeacon) {
      const blob = new Blob([data], { type: 'application/json' });
      navigator.sendBeacon(this.config.endpoint, blob);
    }
  }

  // 离线缓存（IndexedDB）
  private async initOfflineCache(): Promise<void> {
    if (!this.config.enableOfflineCache) return;
    if (!window.indexedDB) return;

    const request = indexedDB.open('__tracker_offline__', 1);
    request.onupgradeneeded = () => {
      const db = request.result;
      if (!db.objectStoreNames.contains('events')) {
        db.createObjectStore('events', { autoIncrement: true });
      }
    };
    request.onsuccess = () => {
      this.db = request.result;
      this.sendCachedEvents();
    };
  }

  private async saveToCache(events: TrackEvent[]): Promise<void> {
    if (!this.db) return;
    const tx = this.db.transaction('events', 'readwrite');
    const store = tx.objectStore('events');
    for (const event of events) {
      store.add(event);
    }
  }

  private async sendCachedEvents(): Promise<void> {
    if (!this.db || !this.isOnline) return;
    const tx = this.db.transaction('events', 'readwrite');
    const store = tx.objectStore('events');
    const request = store.getAll();

    request.onsuccess = async () => {
      const events = request.result as TrackEvent[];
      if (events.length === 0) return;

      const success = await this.send(events);
      if (success) {
        store.clear(); // 发送成功后清除缓存
      }
    };
  }

  // 绑定网络状态与页面卸载事件
  private bindEvents(): void {
    window.addEventListener('online', () => {
      this.isOnline = true;
      this.sendCachedEvents();
      this.flush();
    });

    window.addEventListener('offline', () => {
      this.isOnline = false;
    });

    document.addEventListener('visibilitychange', () => {
      if (document.visibilityState === 'hidden') {
        this.flushOnUnload();
      }
    });

    window.addEventListener('pagehide', () => {
      this.flushOnUnload();
    });
  }

  private timer: ReturnType<typeof setTimeout> | null = null;
  private startTimer(): void {
    if (this.timer) return;
    this.timer = setTimeout(() => {
      this.flush();
      this.timer = null;
    }, this.config.batchInterval);
  }
}

上报策略对比

8. 数据处理与分析

漏斗分析

用户路径：
首页 → 搜索结果 → 商品详情 → 加入购物车 → 提交订单 → 支付成功

各步骤转化：
┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐
│ 首页  │──▶│ 搜索  │──▶│ 详情  │──▶│ 购物车│──▶│ 下单  │──▶│ 支付  │
│10000 │   │ 8000 │   │ 6000 │   │ 3000 │   │ 2000 │   │ 1800 │
└──────┘   └──────┘   └──────┘   └──────┘   └──────┘   └──────┘
  100%      80%        60%        30%        20%        18%

步骤转化率：
  首页→搜索：80%    搜索→详情：75%    详情→购物车：50%
  购物车→下单：66.7%  下单→支付：90%

整体转化率：18%（10000 → 1800）
最大流失点：详情→购物车（50% 流失）

// analyzer/funnel.ts
interface FunnelStep {
  eventName: string;
  displayName: string;
}

interface FunnelResult {
  steps: Array<{
    eventName: string;
    displayName: string;
    count: number;
    conversionRate: number;     // 该步相对上一步的转化率
    overallConversionRate: number; // 该步相对第一步的转化率
    dropOffRate: number;        // 该步相对上一步的流失率
  }>;
  totalConversionRate: number;
}

class FunnelAnalyzer {
  analyze(
    events: TrackEvent[],
    steps: FunnelStep[],
    timeWindow: number = 7 * 24 * 60 * 60 * 1000 // 7 天窗口
  ): FunnelResult {
    // 按用户分组
    const userEvents = this.groupByUser(events);

    let firstStepCount = 0;
    const stepCounts = new Array(steps.length).fill(0);

    for (const [, userEventList] of userEvents) {
      // 按时间排序
      userEventList.sort((a, b) => a.timestamp - b.timestamp);

      let stepIndex = 0;
      let lastStepTime = 0;

      for (const event of userEventList) {
        if (stepIndex >= steps.length) break;

        // 检查是否超时
        if (lastStepTime && event.timestamp - lastStepTime > timeWindow) {
          break;
        }

        if (event.eventName === steps[stepIndex].eventName) {
          if (stepIndex === 0) firstStepCount++;
          stepCounts[stepIndex]++;
          lastStepTime = event.timestamp;
          stepIndex++;
        }
      }
    }

    const result = steps.map((step, index) => ({
      eventName: step.eventName,
      displayName: step.displayName,
      count: stepCounts[index],
      conversionRate: index === 0
        ? 1
        : stepCounts[index - 1] > 0
          ? stepCounts[index] / stepCounts[index - 1]
          : 0,
      overallConversionRate: firstStepCount > 0
        ? stepCounts[index] / firstStepCount
        : 0,
      dropOffRate: index === 0
        ? 0
        : stepCounts[index - 1] > 0
          ? 1 - stepCounts[index] / stepCounts[index - 1]
          : 0,
    }));

    return {
      steps: result,
      totalConversionRate: firstStepCount > 0
        ? stepCounts[steps.length - 1] / firstStepCount
        : 0,
    };
  }

  private groupByUser(events: TrackEvent[]): Map<string, TrackEvent[]> {
    const map = new Map<string, TrackEvent[]>();
    for (const event of events) {
      const userId = event.userId || event.deviceId;
      if (!map.has(userId)) map.set(userId, []);
      map.get(userId)!.push(event);
    }
    return map;
  }
}