trackersdk2 1.0.0

package/src/core/TrackerSDK.ts

@@ -0,0 +1,561 @@
+import type { TrackerConfig, TrackEvent, TagNames } from "./types";
+import { onFCP, onLCP, onCLS, onTTFB } from "web-vitals";
+
+export class TrackerSDK {
+  private config: Required<TrackerConfig>;
+  private autoTrackClickHandler: null | ((e: MouseEvent) => void) = null;
+  // 事件队列
+  private eventQueue: TrackEvent[] = [];
+  // 批量上报定时器
+  private batchTimer: null | number = null;
+  // 页面卸载前是否已发送数据标识
+  private hasSentBeforeUnload: boolean = false;
+  // #region 构造函数 & 初始化
+  constructor() {
+    this.config = {
+      appId: "",
+      serverUrl: "",
+      userId: "",
+      debug: true,
+      enableAutoClickTagNameList: [],
+      autoTrack: false,
+      batchSize: 10,
+      batchInterval: 5000,
+    };
+  }
+  init(config: TrackerConfig): void {
+    if (!window || typeof window !== "object") {
+      console.warn("TrackerSDK 仅支持浏览器环境，当前环境已跳过初始化");
+      return;
+    }
+    if (!config.serverUrl) {
+      throw new Error("serverUrl is required");
+    }
+    if (!config.appId) {
+      throw new Error("appId is required");
+    }
+    this.config = {
+      ...this.config,
+      ...config,
+    };
+    this.setupErrorTracking();
+    this.setupPerformanceTracking();
+    this.trackUV();
+    // 监听页面卸载
+    this.setupPageUnloadHandler();
+    // 重试之前失败的批量上报
+    this.retryFailedBatches();
+  }
+  // #endregion
+  // #region 埋点api工具方法
+  /**
+   * @description 重试批量上报之前上报失败的数据
+   * @returns Promise<void>
+   */
+  private async retryFailedBatches(): Promise<void> {
+    try {
+      const key = "tracker_failed_batches";
+      const batchesStr = localStorage.getItem(key);
+      if (!batchesStr) return;
+      const batches: any[] = JSON.parse(batchesStr);
+      const remainingBatches: any[] = [];
+      for (const batch of batches) {
+        try {
+          await this.fallbackSendBatch(batch);
+        } catch (err) {
+          remainingBatches.push(batch);
+        }
+      }
+      if (remainingBatches.length) {
+        // 只保留3批
+        const toSave = remainingBatches.splice(-3);
+        localStorage.setItem(key, JSON.stringify(toSave));
+      } else {
+        localStorage.removeItem(key);
+      }
+    } catch (err) {
+      console.warn("Failed to retry batches:", err);
+    }
+  }
+  /**
+   * @description 监听页面卸载事件，确保数据上报
+   * @returns void
+   */
+  private setupPageUnloadHandler(): void {
+    const flushAndSend = () => {
+      if (this.hasSentBeforeUnload || this.eventQueue.length == 0) return;
+      // 清除定时器，防止内存泄漏
+      if (this.batchTimer) {
+        clearTimeout(this.batchTimer);
+        this.batchTimer = null;
+      }
+      // 标记为已上报
+      this.hasSentBeforeUnload = true;
+      const payload = { events: [...this.eventQueue] };
+      // 清空队列
+      this.eventQueue = [];
+      // this.sendBatch(payload.events);
+      if (navigator.sendBeacon) {
+        const blob = new Blob([JSON.stringify(payload)], {
+          type: "application/json",
+        });
+        if (!navigator.sendBeacon(this.config.serverUrl, blob)) {
+          this.fallbackSendBatch(payload);
+        }
+      } else {
+        this.fallbackSendBatch(payload);
+      }
+    };
+    // 页面级别卸载事件
+    // beforeunload safari不支持
+    window.addEventListener("beforeunload", flushAndSend);
+    // pagehide 兜底
+    window.addEventListener("pagehide", flushAndSend);
+    // 可选：页面最小化、切换页签时触发
+    // window.addEventListener("visibilitychange", () => {
+    //   if (document.hidden) flushAndSend();
+    // });
+  }
+  /**
+   * @description 获取设备id
+   */
+  private getDeviceId(): string {
+    let id = localStorage.getItem("tracker_device_id");
+    if (!id) {
+      id =
+        "device_" +
+        Date.now() +
+        "_" +
+        Math.random().toString(32).substring(2, 10);
+      localStorage.setItem("tracker_device_id", id);
+    }
+    return id;
+  }
+  /**
+   *  @description navigator.sendBeacon 和 fetch 双通道实现数据上报
+   *  @param data 上报的负载
+   */
+  private send(data: TrackEvent): void {
+    const payload = {
+      ...data,
+      userId: this.config.userId || this.getDeviceId(),
+      timestamp: Date.now(),
+      url: window.location.href,
+      title: document.title,
+      userAgent: navigator.userAgent,
+      appId: this.config.appId,
+    };
+    // 错误事件立即上报
+    if (data.eventType == "error") return this.sendImmediately(payload);
+    this.enqueue(payload);
+  }
+  /**
+   * @description 入队列
+   * @param payload 上报的负载
+   */
+  private enqueue(payload: any): void {
+    this.eventQueue.push(payload);
+    // 达到数量阈值，立即上报
+    if (this.eventQueue.length >= this.config.batchSize) {
+      return this.flush();
+    }
+    // 启动定时器
+    if (!this.batchTimer) {
+      this.batchTimer = setTimeout(() => {
+        this.flush();
+      }, this.config.batchInterval);
+    }
+  }
+  /**
+   * @description 刷新队列，批量上报
+   * @return void
+   */
+  private flush(): void {
+    if (this.eventQueue.length === 0) return;
+    const batchPayload = [...this.eventQueue];
+    this.eventQueue = [];
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+      this.batchTimer = null;
+    }
+    this.sendBatch(batchPayload);
+  }
+  /**
+   * @description navigator.sendBeacon单条错误上报失败的fetch回退方案
+   * @param payload any
+   * */
+  private async fallbackSend(payload: any): Promise<void> {
+    try {
+      await fetch(this.config.serverUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        keepalive: true,
+        // credentials: "include",
+      });
+    } catch (error) {
+      if (this.config.debug) {
+        console.error("Single event fallback send failed:", error);
+      }
+      this.saveFailedBatch({ events: [payload] });
+    }
+  }
+  /**
+   * @description 错误事件立即上报
+   * @param data 上报的负载
+   * @returns void
+   */
+  sendImmediately(payload: TrackEvent): void {
+    // if (navigator.sendBeacon) {
+    //   const blob = new Blob([JSON.stringify(payload)], {
+    //     type: "application/json",
+    //   });
+    //   if (!navigator.sendBeacon(this.config.serverUrl, blob)) {
+    //     this.fallbackSend(payload);
+    //   }
+    // } else {
+    //   this.fallbackSend(payload);
+    // }
+    /* 改用 fetch api */
+    this.fallbackSend(payload);
+  }
+  /**
+   * @description 批量上报
+   * @param events 上报的事件数组
+   * @returns Promise<void>
+   */
+  private async sendBatch(events: any[]): Promise<void> {
+    const payload = { events };
+    // if (navigator.sendBeacon) {
+    //   const blob = new Blob([JSON.stringify(payload)], {
+    //     type: "application/json",
+    //   });
+    //   if (!navigator.sendBeacon(this.config.serverUrl, blob)) {
+    //     await this.fallbackSendBatch(payload);
+    //   }
+    // } else {
+    //   await this.fallbackSendBatch(payload);
+    // }
+    /* 改用 fetch api */
+    await this.fallbackSendBatch(payload);
+  }
+  /**
+   * @description 批量上报的fetch回退方案
+   * @param payload 上报的负载
+   * @returns Promise<void>
+   */
+  private async fallbackSendBatch(payload: any): Promise<void> {
+    try {
+      await fetch(this.config.serverUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        keepalive: true,
+        // credentials: "include",
+      });
+    } catch (error) {
+      if (this.config.debug) {
+        console.error("[fallbackSendBatch] fecth批量上报失败:", error);
+      }
+      // 可选：存入 localStorage 用于下次重试
+      this.saveFailedBatch(payload);
+    }
+  }
+  private saveFailedBatch(payload: any): void {
+    try {
+      const key = "tracker_failed_batches";
+      const existing = localStorage.getItem(key);
+      const batches = existing ? JSON.parse(existing) : [];
+      batches.push(payload);
+      if (batches.length > 3) batches.shift(); // 限制最多3批
+      localStorage.setItem(key, JSON.stringify(batches));
+    } catch (e) {
+      // localStorage 可能满或禁用，静默忽略
+    }
+  }
+  /**
+   * @description 自定义点击事件
+   */
+  track(event: string, properties: Record<string, any> = {}): void {
+    this.send({
+      eventType: "custom",
+      event,
+      properties,
+    });
+  }
+  /**
+   * @description 用于自动点击埋点
+   *
+   * @param element 点击的DOM元素
+   */
+  trackClick(element: Element): void {
+    const tagName = element.tagName.toLowerCase();
+    const id = element.id || "";
+    const classes = Array.from(element.classList).join(" ");
+    const text = ["button", "a"].includes(tagName)
+      ? (element as HTMLElement).innerText?.trim().slice(0, 20)
+      : "";
+    if (this.config.enableAutoClickTagNameList.includes(tagName)) {
+      this.send({
+        eventType: "click",
+        event: "auto_click",
+        properties: {
+          tagName,
+          id,
+          classes,
+          text,
+        },
+      });
+    } else {
+      if (this.config.debug) {
+        console.log("点击元素不触发自动埋点");
+      }
+    }
+  }
+  // #endregion
+  // #region pv & uv
+  /**
+   * @description 自动pv
+   *
+   * @param path pv的页面路径
+   * @param properties 上报数据
+   */
+  trackPV(path: string, properties: Record<string, any> = {}): void {
+    this.send({
+      eventType: "pv",
+      properties: {
+        path,
+        referrer: document.referrer,
+        ...properties,
+      },
+    });
+  }
+  /**
+   * @description 统计uv（每天每个设备只上报一次）
+   *
+   */
+  trackUV(): void {
+    const deviceId = this.getDeviceId();
+    const now = new Date().getTime();
+    const beijingTime = new Date(now + 8 * 3600 * 1000);
+    const today = new Date(beijingTime).toISOString().split("T")[0];
+    const uvKey = `tracker_uv_${today}`;
+    if (!localStorage.getItem(uvKey)) {
+      this.send({
+        eventType: "uv",
+        properties: {
+          deviceId,
+          date: today,
+        },
+      });
+      localStorage.setItem(uvKey, "1");
+    }
+  }
+  // #endregion
+  // #region 错误监控
+  /** @description 初始化错误事件监听
+   *
+   */
+  setupErrorTracking() {
+    // 全局 JS 错误
+    window.addEventListener(
+      "error",
+      ({ message, filename, lineno, colno, error }) => {
+        console.log("🚀 ~ '全局 JS 错误捕获了'");
+        this.send({
+          eventType: "error",
+          event: "js_error",
+          properties: {
+            message,
+            filename,
+            lineno,
+            colno,
+            stack: error?.stack || "no stack",
+          },
+        });
+      }
+    );
+    // 资源加载错误
+    window.addEventListener(
+      "error",
+      (e: any) => {
+        if (e.target?.localName) {
+          let url = e.target.src || e.target.href || "";
+          url = url.trim();
+          const tag = e.target;
+          const originalSrc = tag.getAttribute("src");
+          const originalHref = tag.getAttribute("href");
+          // 如果原始值是空字符串(空 src 会被解析成当前页)、null、undefined，则是伪错误
+          if (
+            (originalSrc != null && originalSrc.trim() === "") ||
+            (originalHref != null && originalHref.trim() === "")
+          ) {
+            return false; // 过滤掉
+          }
+          if (url == "") return false;
+          try {
+            // 验证是否是合法 URL
+            new URL(url);
+            console.log("🚀 ~ '资源加载错误捕获了'");
+            this.send({
+              eventType: "error",
+              event: "resource_load_error",
+              properties: {
+                resourceUrl: url,
+                tageName: e.target.localName,
+              },
+            });
+          } catch (err) {
+            return false;
+          }
+        }
+      },
+      true
+    );
+    // Promise unhandled rejection
+    window.addEventListener("unhandledrejection", (event) => {
+      "Promise unhandled rejection捕获了";
+      console.log("🚀 ~ 'Promise unhandled rejection捕获了'");
+      this.send({
+        eventType: "error",
+        event: "promise_unhandled_rejection",
+        properties: {
+          reason: String(event.reason),
+          stack: event.reason?.stack || "no stack",
+        },
+      });
+      // 阻止打印报错信息
+      event.preventDefault();
+    });
+  }
+  /**
+   * @description vue3 全局错误处理器
+   */
+  setupVueErrorHandlder(app: any) {
+    app.config.errorHandler = (err: Error, instance: any, info: string) => {
+      console.log("🚀 ~ vue3 全局错误处理器捕获了");
+      // setTimeout(() => {
+      //   throw err;
+      // }, 0);
+      this.send({
+        eventType: "error",
+        event: "vue_component_error",
+        properties: {
+          message: err.message,
+          stack: err.stack || "no stack",
+          componentInfo: info,
+          componentName: instance?.$options?.name || "unknown",
+        },
+      });
+    };
+  }
+  // #endregion
+  // #region 性能监控
+  private setupPerformanceTracking(): void {
+    // if (!("performance" in window)) return;
+    // const perf: any = performance.getEntriesByType("navigation")[0];
+    // if (!perf) return;
+    // this.send({
+    //   eventType: "performance",
+    //   event: "page_performance",
+    //   properties: {
+    //     dns: perf.domainLookupEnd - perf.domainLookupStart,
+    //     tcpAndTls: perf.connectEnd - perf.connectStart,
+    //     domReady: perf.domContentLoadedEventEnd - perf.fetchStart,
+    //     load: perf.loadEventEnd - perf.fetchStart,
+    //   },
+    // });
+    this.observeFCP();
+    this.observeLCP();
+    this.observeCLS();
+    this.observeTTFB();
+  }
+  /**
+   * @description 监控FCP
+   * @returns void
+   */
+  private observeFCP(): void {
+    onFCP((metric: any) => {
+      this.send({
+        eventType: "performance",
+        event: "first_contentful_paint",
+        properties: metric,
+      });
+    });
+  }
+  /**
+   * @description 监控LCP
+   * @returns void
+   */
+  private observeLCP(): void {
+    onLCP((metric: any) => {
+      this.send({
+        eventType: "performance",
+        event: "largest_contentful_paint",
+        properties: metric,
+      });
+    });
+  }
+  /**
+   * @description 监控CLS
+   * @returns void
+   */
+  private observeCLS(): void {
+    onCLS((metric: any) => {
+      this.send({
+        eventType: "performance",
+        event: "cumulative_layout_shift",
+        properties: {
+          ...metric,
+          entries: undefined, // 去掉 entries，数据量可能很庞大
+        },
+      });
+    });
+  }
+  /**
+   * @description 监控TTFB
+   * @returns void
+   */
+  private observeTTFB(): void {
+    onTTFB((metric: any) => {
+      this.send({
+        eventType: "performance",
+        event: "time_to_first_byte",
+        properties: metric,
+      });
+    });
+  }
+  // #endregion
+  // #region 全埋点
+  /**
+   * @description 全埋点(谨慎使用,存在性能问题)
+   */
+  enableAutoTracking() {
+    // 防止重复绑定
+    if (this.autoTrackClickHandler) return;
+    this.autoTrackClickHandler = (e) => {
+      if (e.target instanceof Element) {
+        this.trackClick(e.target);
+      }
+    };
+    document.documentElement.addEventListener(
+      "click",
+      this.autoTrackClickHandler
+    );
+  }
+  /**
+   * @description: 设置可触发自动埋点的DOM元素标签名称白名单
+   */
+  setEnableAutoClickTagNameList(tagNameList: Array<TagNames>) {
+    if (this.config.autoTrack) {
+      this.config.enableAutoClickTagNameList = tagNameList;
+    }
+  }
+  // #endregion
+}
+// 单例导出
+export const tracker = new TrackerSDK();

package/src/core/index.ts

@@ -0,0 +1,16 @@
+import { tracker } from "./TrackerSDK";
+import type { TrackerConfig } from "./types";
+export default {
+  install(app: any, options: TrackerConfig) {
+    tracker.init(options);
+    app.provide("tracker", tracker);
+    // 自动化埋点，存在 performance
+    if (options.autoTrack) {
+      tracker.enableAutoTracking();
+    }
+  },
+};
+export function useTracker() {
+  return tracker;
+}
+export { tracker };

package/src/core/types.ts

@@ -0,0 +1,29 @@
+export type TagNames = string;
+export interface TrackerConfig {
+  serverUrl: string;
+  appId: string;
+  userId?: string;
+  autoTrack?: boolean;
+  enableAutoClickTagNameList?: Array<TagNames>;
+  debug?: boolean;
+  batchSize?: number;
+  batchInterval?: number;
+}
+
+interface TrackProperties {
+  [propName: string]: string | number | boolean | null | undefined;
+}
+
+type TrackerEventType =
+  | "custom"
+  | "click"
+  | "pv"
+  | "uv"
+  | "error"
+  | "performance";
+
+export interface TrackEvent {
+  eventType: TrackerEventType;
+  properties?: TrackProperties;
+  event?: string;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+    "compilerOptions": {
+      "target": "ES2018",
+      "module": "ESNext",
+      "lib": ["DOM", "ES2020"],
+      "moduleResolution": "node",
+      "declaration": true,
+      "outDir": "./dist",
+      "strict": true,
+      "esModuleInterop": true,
+      "skipLibCheck": true,
+      "forceConsistentCasingInFileNames": true
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules"]
+  }
+  
+  
+