@clipto/reporter 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -52,30 +52,7 @@ var QUEUE_KEY = "pending";
 var LS_KEY = "clipto_report_pending_queue";
 function buildPayload(events) {
   return {
-    // attempts 为 SDK 内部字段,不上报;name 输出为 eventName(对齐旧 SDK)
-    events: events.map(
-      ({
-        id,
-        name,
-        timestamp,
-        sessionId,
-        userId,
-        deviceId,
-        properties,
-        category,
-        context
-      }) => ({
-        id,
-        eventName: name,
-        timestamp,
-        sessionId,
-        userId,
-        deviceId,
-        properties,
-        category,
-        context
-      })
-    ),
+    events,
     metadata: {
       sdkVersion: SDK_VERSION,
       timestamp: Date.now(),
@@ -84,17 +61,26 @@ function buildPayload(events) {
     }
   };
 }
-function createBrowserTransport(endpoint, headers) {
+async function signHeaders(payload, signer) {
+  if (!signer) return {};
+  return signer(JSON.stringify(payload));
+}
+function createBrowserTransport(endpoint, headers, signer) {
   const commonHeaders = {
     "Content-Type": "application/json",
     ...headers ?? {}
   };
   return {
     async send(events) {
+      const payload = buildPayload(events);
+      const requestHeaders = {
+        ...commonHeaders,
+        ...await signHeaders(payload, signer)
+      };
       const response = await fetch(endpoint, {
         method: "POST",
-        headers: commonHeaders,
-        body: JSON.stringify(buildPayload(events)),
+        headers: requestHeaders,
+        body: JSON.stringify(payload),
         keepalive: true
       });
       if (!response.ok) {
@@ -102,7 +88,7 @@ function createBrowserTransport(endpoint, headers) {
       }
     },
     sendSync(events) {
-      if (typeof navigator === "undefined" || typeof navigator.sendBeacon !== "function") {
+      if (typeof navigator === "undefined" || typeof navigator.sendBeacon !== "function" || signer) {
         return false;
       }
       try {
@@ -116,12 +102,16 @@ function createBrowserTransport(endpoint, headers) {
     }
   };
 }
-async function createNodeTransport(endpoint, headers) {
+async function createNodeTransport(endpoint, headers, signer) {
   const { default: axios } = await import("axios");
   return {
     async send(events) {
-      await axios.post(endpoint, buildPayload(events), {
-        headers,
+      const payload = buildPayload(events);
+      await axios.post(endpoint, payload, {
+        headers: {
+          ...headers ?? {},
+          ...await signHeaders(payload, signer)
+        },
         timeout: 1e4
       });
     }
@@ -199,6 +189,167 @@ async function createNodeStorage(persistDir) {
   };
 }
 
+// src/collect.ts
+var import_ua_parser_js = require("ua-parser-js");
+function parseUserAgent(ua) {
+  const parsed = new import_ua_parser_js.UAParser(ua);
+  const browser = parsed.getBrowser();
+  const os = parsed.getOS();
+  const info = {};
+  if (browser.name) {
+    info.browserName = browser.name === "Mobile Safari" ? "Safari" : browser.name === "Mobile Chrome" ? "Chrome" : browser.name;
+  }
+  if (browser.version) info.browserVersion = browser.version;
+  if (os.name) info.osName = os.name === "Mac OS" ? "macOS" : os.name;
+  if (os.version) info.osVersion = os.version;
+  return info;
+}
+function collectBrowserDevice() {
+  if (typeof navigator === "undefined") return {};
+  const { browserName, browserVersion, osName, osVersion } = parseUserAgent(
+    navigator.userAgent || ""
+  );
+  const device = {};
+  if (browserName) device.browserName = browserName;
+  if (browserVersion) device.browserVersion = browserVersion;
+  if (osName) device.osName = osName;
+  if (osVersion) device.osVersion = osVersion;
+  const uaData = navigator.userAgentData;
+  if (uaData?.platform) device.platform = uaData.platform;
+  else if (navigator.platform) device.platform = navigator.platform;
+  if (navigator.language) device.language = navigator.language;
+  return device;
+}
+async function collectNodeDevice() {
+  try {
+    const os = await import("os");
+    const device = {
+      platform: os.platform(),
+      osVersion: os.release(),
+      arch: os.arch(),
+      memSize: Math.round(os.totalmem() / 1024 ** 3)
+      // 统一 GB
+    };
+    const type = os.type();
+    device.osName = type === "Darwin" ? "macOS" : type === "Windows_NT" ? "Windows" : type;
+    const cpu = os.cpus()[0]?.model;
+    if (cpu) device.cpu = cpu;
+    return device;
+  } catch {
+    return {};
+  }
+}
+function collectPageSnapshot() {
+  if (typeof document === "undefined") return {};
+  const page = {};
+  if (location.href) page.url = location.href;
+  if (document.title) page.title = document.title;
+  if (document.referrer) page.referrer = document.referrer;
+  return page;
+}
+
+// src/page.ts
+var SCROLL_GESTURE_GAP_MS = 500;
+var IDLE_PAUSE_MS = 6e4;
+var METRIC_TICK_MS = 1e3;
+function createPageTracker(onActivity) {
+  let visit = null;
+  let interval = null;
+  const touch = () => {
+    if (!visit) return;
+    visit.lastActivityAt = Date.now();
+    onActivity();
+  };
+  const updateMaxDepth = () => {
+    if (!visit) return;
+    const doc = document.documentElement;
+    if (!doc) return;
+    const total = Math.max(doc.scrollHeight, 1);
+    const depth = Math.round(
+      (window.scrollY + window.innerHeight) / total * 100
+    );
+    visit.maxScrollDepthPct = Math.max(
+      visit.maxScrollDepthPct,
+      Math.min(depth, 100)
+    );
+  };
+  const onScroll = () => {
+    if (!visit) return;
+    const now = Date.now();
+    if (now - visit.lastScrollAt > SCROLL_GESTURE_GAP_MS) {
+      visit.scrollCount += 1;
+    }
+    visit.lastScrollAt = now;
+    touch();
+    updateMaxDepth();
+  };
+  const onInput = () => touch();
+  const tick = () => {
+    if (!visit) return;
+    if (document.visibilityState === "visible" && Date.now() - visit.lastActivityAt <= IDLE_PAUSE_MS) {
+      visit.activeMs += METRIC_TICK_MS;
+    }
+    updateMaxDepth();
+  };
+  const removeListeners = () => {
+    window.removeEventListener("scroll", onScroll);
+    window.removeEventListener("pointerdown", onInput, { capture: true });
+    window.removeEventListener("keydown", onInput, { capture: true });
+    if (interval) {
+      clearInterval(interval);
+      interval = null;
+    }
+  };
+  const startVisit = () => {
+    if (visit) return;
+    const now = Date.now();
+    visit = {
+      pageViewId: `pv_${generateEventId()}`,
+      enteredAt: now,
+      snapshot: collectPageSnapshot(),
+      activeMs: 0,
+      scrollCount: 0,
+      maxScrollDepthPct: 0,
+      lastActivityAt: now,
+      lastScrollAt: 0
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("pointerdown", onInput, {
+      capture: true,
+      passive: true
+    });
+    window.addEventListener("keydown", onInput, { capture: true, passive: true });
+    interval = setInterval(tick, METRIC_TICK_MS);
+  };
+  const endVisit = (reason) => {
+    if (!visit) return void 0;
+    removeListeners();
+    const finished = visit;
+    visit = null;
+    if (document.title) {
+      finished.snapshot.title = document.title;
+    }
+    return {
+      ...finished.snapshot,
+      pageViewId: finished.pageViewId,
+      durationMs: Date.now() - finished.enteredAt,
+      activeMs: finished.activeMs,
+      scrollCount: finished.scrollCount,
+      maxScrollDepthPct: finished.maxScrollDepthPct,
+      endReason: reason
+    };
+  };
+  return {
+    get active() {
+      return visit !== null;
+    },
+    startVisit,
+    endVisit,
+    pageViewId: () => visit?.pageViewId,
+    dispose: removeListeners
+  };
+}
+
 // src/reporter.ts
 var DEFAULT_FLUSH_INTERVAL = 2e3;
 var DEFAULT_MAX_BATCH_SIZE = 10;
@@ -207,11 +358,33 @@ var DEFAULT_MAX_QUEUE_SIZE = 1e3;
 var DEFAULT_MAX_ATTEMPTS = 3;
 var DEFAULT_BACKOFF_MS = 1e3;
 var STORAGE_WRITE_THROTTLE_MS = 500;
+var VISIT_IDLE_TIMEOUT_MS = 30 * 60 * 1e3;
+var SESSION_SAVE_THROTTLE_MS = 1e4;
+var ANONYMOUS_ID_KEY = "clipto_report_anonymous_id";
+var CLIENT_ID_KEY = "clipto_report_client_id";
+var SESSION_KEY = "clipto_report_session";
+function normalizeContext(context) {
+  if (typeof context === "function") return context;
+  return () => context ?? {};
+}
+function stripAttempts(events) {
+  return events.map((event) => {
+    const { attempts: _attempts, ...rest } = event;
+    return rest;
+  });
+}
 var Reporter = class {
   constructor(options) {
-    /** 会话 / 设备 id 兜底:enrich 未提供时按实例生成(对齐旧 SDK 格式) */
-    this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
-    this.deviceId = `device_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+    /** 会话落盘时间戳(节流用);声明在 session 之前:session 初始化会触发强制落盘 */
+    this.sessionSaveAt = 0;
+    /** 会话共享读时间戳(节流用):多 tab 共享会话,活动时定期重读 localStorage 最新值 */
+    this.sessionReadAt = 0;
+    /** Node 端设备快照(init 时采集一次,避免每次入队动态加载 os) */
+    this.nodeDevice = {};
+    /** 页面访问跟踪(browser + autoPageView 时启用) */
+    this.pageTracker = null;
+    /** history 补丁的原始引用(dispose 时还原) */
+    this.historyPatch = null;
     /** 待发队列(内存中的事实源,持久化是它的影子) */
     this.queue = [];
     this.flushTimer = null;
@@ -224,13 +397,31 @@ var Reporter = class {
       this.fire(this.dispose());
     };
     this.onPageHide = () => {
+      this.endPageVisit(this.session.visitId, "close");
       this.fire(this.dispose());
     };
+    this.onPageShow = () => {
+      if (document.visibilityState === "visible") {
+        this.pageTracker?.startVisit();
+      }
+    };
     this.onVisibilityChange = () => {
       if (document.visibilityState === "hidden") {
+        this.endPageVisit(this.session.visitId, "background");
         this.fire(this.flush());
-      } else if (this.opts.autoPageView) {
-        this.track("page_view");
+      } else {
+        this.pageTracker?.startVisit();
+      }
+    };
+    this.onPopState = () => {
+      this.endPageVisit(this.session.visitId, "back");
+      this.pageTracker?.startVisit();
+    };
+    this.onStorage = (event) => {
+      if (event.key !== SESSION_KEY || !event.newValue) return;
+      try {
+        this.adoptSharedSession(JSON.parse(event.newValue));
+      } catch {
       }
     };
     if (!options.endpoint) {
@@ -238,6 +429,7 @@ var Reporter = class {
     }
     this.opts = options;
     this.platform = options.platform ?? (typeof window !== "undefined" ? "browser" : "node");
+    this.contextFn = normalizeContext(options.context);
     this.flushInterval = options.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
     this.maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
     this.maxBatchBytes = options.maxBatchBytes ?? DEFAULT_MAX_BATCH_BYTES;
@@ -246,16 +438,20 @@ var Reporter = class {
     this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
     this.backoffMs = options.backoffMs ?? DEFAULT_BACKOFF_MS;
     this.flushOnExit = options.flushOnExit ?? true;
+    this._anonymousId = this.loadOrCreateAnonymousId();
+    this._clientId = this.loadOrCreateClientId();
+    this.session = this.loadOrCreateSession();
     if (options.transport) {
       this.transportPromise = Promise.resolve(options.transport);
     } else if (this.platform === "browser") {
       this.transportPromise = Promise.resolve(
-        createBrowserTransport(options.endpoint, options.headers)
+        createBrowserTransport(options.endpoint, options.headers, options.signer)
       );
     } else {
       this.transportPromise = createNodeTransport(
         options.endpoint,
-        options.headers
+        options.headers,
+        options.signer
       );
     }
     if (options.storage) {
@@ -271,35 +467,20 @@ var Reporter = class {
     }
     this.fire(this.init());
   }
-  track(name, properties, options) {
+  track(eventName, properties, options) {
     if (this.disposed) {
-      this.log("dispose \u540E\u5FFD\u7565\u65B0\u4E8B\u4EF6:", name);
+      this.log("dispose \u540E\u5FFD\u7565\u65B0\u4E8B\u4EF6:", eventName);
       return "";
     }
-    const enriched = this.opts.enrich?.() ?? {};
-    const event = {
-      id: generateEventId(),
-      name,
-      properties: {
-        ...this.opts.baseProperties ?? {},
-        ...this.opts.context?.() ?? {},
-        ...properties ?? {}
-      },
-      timestamp: options?.timestamp ?? Date.now(),
-      attempts: 0,
-      sessionId: enriched.sessionId ?? this.sessionId,
-      userId: enriched.userId ?? null,
-      deviceId: enriched.deviceId ?? this.deviceId,
-      category: options?.category ?? "custom",
-      context: enriched.context ?? {}
-    };
-    if (typeof name !== "string" || name.length === 0) {
-      this.opts.onDropped?.([event], "invalid");
+    if (typeof eventName !== "string" || eventName.length === 0) {
+      this.opts.onDropped?.([this.buildEvent("", properties)], "invalid");
       return "";
     }
+    this.touchSession();
+    const event = this.buildEvent(eventName, properties);
     if (options?.immediate) {
-      this.fire(this.sendBatch([event]));
-      return event.id;
+      this.fire(this.sendBatch([{ ...event, attempts: 0 }]));
+      return event.eventId;
     }
     this.enqueue(event);
     if (this.flushInterval <= 0) {
@@ -307,7 +488,7 @@ var Reporter = class {
     } else {
       this.scheduleFlush();
     }
-    return event.id;
+    return event.eventId;
   }
   flush() {
     if (!this.flushPromise) {
@@ -324,6 +505,22 @@ var Reporter = class {
   get size() {
     return this.queue.length;
   }
+  /** 匿名 id(只读):首次生成后持久化不变;供外部转化跟踪等场景读取 */
+  get anonymousId() {
+    return this._anonymousId;
+  }
+  /** 设备 / 安装实例 id(只读):Web&PC 与 google client id 一致;供外部转化跟踪等场景读取 */
+  get clientId() {
+    return this._clientId;
+  }
+  /** 当前会话 id(只读):会话轮换后返回新值;供外部转化跟踪等场景读取 */
+  get visitId() {
+    return this.session.visitId;
+  }
+  /** 当前登录账号 id(只读):实时调用 userId provider,未提供恒为 null */
+  get userId() {
+    return this.opts.userId?.() ?? null;
+  }
   async dispose() {
     if (this.disposed) return;
     this.disposed = true;
@@ -341,7 +538,16 @@ var Reporter = class {
     }
     if (this.platform === "browser") {
       window.removeEventListener("pagehide", this.onPageHide);
+      window.removeEventListener("pageshow", this.onPageShow);
+      window.removeEventListener("storage", this.onStorage);
       document.removeEventListener("visibilitychange", this.onVisibilityChange);
+      this.restoreHistory();
+      if (this.pageTracker) {
+        this.endPageVisit(this.session.visitId, "unknown");
+        this.pageTracker.dispose();
+        this.pageTracker = null;
+      }
+      this.saveSession(true);
     } else {
       const exitProcess = this.getExitProcess();
       exitProcess.off("beforeExit", this.onExit);
@@ -357,17 +563,18 @@ var Reporter = class {
     }
     if (this.flushOnExit) {
       const pending = this.queue.splice(0);
-      if (transport.sendSync?.(pending) ?? false) {
-        this.opts.onFlushed?.(pending);
+      const wire = stripAttempts(pending);
+      if (transport.sendSync?.(wire) ?? false) {
+        this.opts.onFlushed?.(wire);
         await this.persistNow([]);
         return;
       }
       try {
-        await transport.send(pending);
-        this.opts.onFlushed?.(pending);
+        await transport.send(wire);
+        this.opts.onFlushed?.(wire);
         await this.persistNow([]);
       } catch (error) {
-        this.opts.onFailed?.(pending, error);
+        this.opts.onFailed?.(wire, error);
         this.queue.push(...pending);
         await this.persistNow();
       }
@@ -377,9 +584,12 @@ var Reporter = class {
       await this.persistNow();
     }
   }
-  /** 异步初始化:创建内置持久化、恢复上次会话队列、挂载退出兜底 */
+  /** 异步初始化:创建内置持久化、采集 Node 设备快照、恢复上次会话队列、挂载退出兜底 */
   async init() {
     this.storage = await this.storagePromise;
+    if (this.platform === "node") {
+      this.nodeDevice = await collectNodeDevice();
+    }
     if (this.disposed) return;
     if (this.storage) {
       try {
@@ -393,6 +603,7 @@ var Reporter = class {
     }
     if (this.disposed) return;
     if (this.platform === "browser") {
+      window.addEventListener("storage", this.onStorage);
       if (this.flushOnExit) {
         window.addEventListener("pagehide", this.onPageHide);
       }
@@ -400,7 +611,10 @@ var Reporter = class {
         document.addEventListener("visibilitychange", this.onVisibilityChange);
       }
       if (this.opts.autoPageView) {
-        this.track("page_view");
+        this.pageTracker = createPageTracker(() => this.touchSession());
+        this.pageTracker.startVisit();
+        this.patchHistory();
+        window.addEventListener("pageshow", this.onPageShow);
       }
     } else if (this.flushOnExit) {
       const exitProcess = this.getExitProcess();
@@ -413,9 +627,118 @@ var Reporter = class {
       this.schedulePersist();
     }
   }
-  /** 恢复队列入队:历史事件放队头保证先到先发,超限按溢出丢弃 */
+  /** 组装上报事件:身份字段由 SDK 填充,业务节点 = SDK 采集 + context 合并(接入方值优先) */
+  buildEvent(eventName, properties, overrides) {
+    const context = this.contextFn();
+    const device = {
+      ...this.nodeDevice,
+      ...collectBrowserDevice(),
+      ...context.device ?? {}
+    };
+    const page = {
+      ...collectPageSnapshot(),
+      ...this.pageSnapshot(),
+      ...context.page ?? {}
+    };
+    const mergedProperties = { ...context.properties ?? {}, ...properties ?? {} };
+    if (!context.app) {
+      this.log("context \u672A\u63D0\u4F9B app \u8282\u70B9,\u4EE5\u7A7A\u5BF9\u8C61\u4E0A\u62A5");
+    }
+    return {
+      eventId: generateEventId(),
+      eventName,
+      userId: this.opts.userId?.() ?? null,
+      anonymousId: this._anonymousId,
+      visitId: this.session.visitId,
+      clientId: this._clientId,
+      timestamp: Date.now(),
+      app: context.app ?? {},
+      ...Object.keys(device).length > 0 ? { device } : {},
+      ...Object.keys(page).length > 0 ? { page } : {},
+      ...context.user ? { user: context.user } : {},
+      ...Object.keys(mergedProperties).length > 0 ? { properties: mergedProperties } : {},
+      ...overrides
+    };
+  }
+  /** 进行中页面访问的 pageViewId(非访问期返回空) */
+  pageSnapshot() {
+    if (!this.pageTracker?.active) return {};
+    const pageViewId = this.pageTracker.pageViewId();
+    return pageViewId ? { pageViewId } : {};
+  }
+  /** 会话活跃:track 调用与页面交互均触发;超时轮换 visitId 并结束旧页面访问 */
+  touchSession() {
+    const now = Date.now();
+    if (now - this.sessionReadAt >= SESSION_SAVE_THROTTLE_MS) {
+      this.sessionReadAt = now;
+      this.refreshSessionFromShared();
+    }
+    if (now - this.session.lastActivityMs > VISIT_IDLE_TIMEOUT_MS) {
+      const oldVisitId = this.session.visitId;
+      this.endPageVisit(oldVisitId, "sessionTimeout");
+      this.session = { visitId: this.newId("visit"), lastActivityMs: now };
+      this.saveSession(true);
+      this.pageTracker?.startVisit();
+    } else {
+      this.session.lastActivityMs = now;
+      this.saveSession();
+    }
+  }
+  /** 结束当前页面访问并上报 pageView 汇总事件(复用进入页面时的 visitId) */
+  endPageVisit(visitId, reason) {
+    if (!this.pageTracker?.active) return;
+    const summary = this.pageTracker.endVisit(reason);
+    if (!summary) return;
+    const context = this.contextFn();
+    this.enqueue(
+      this.buildEvent("pageView", void 0, {
+        visitId,
+        page: { ...summary, ...context.page ?? {} }
+      })
+    );
+    this.scheduleFlush();
+  }
+  /** SPA 路由变化检测:pushState / replaceState 视为 routeChange,popstate 视为 back */
+  patchHistory() {
+    if (this.historyPatch) return;
+    const endVisit = (reason) => {
+      this.endPageVisit(this.session.visitId, reason);
+      this.pageTracker?.startVisit();
+    };
+    const pushState = history.pushState.bind(history);
+    const replaceState = history.replaceState.bind(history);
+    history.pushState = function(...args) {
+      const result = pushState(...args);
+      endVisit("routeChange");
+      return result;
+    };
+    history.replaceState = function(...args) {
+      const result = replaceState(...args);
+      endVisit("routeChange");
+      return result;
+    };
+    window.addEventListener("popstate", this.onPopState);
+    this.historyPatch = { pushState, replaceState };
+  }
+  restoreHistory() {
+    if (!this.historyPatch) return;
+    history.pushState = this.historyPatch.pushState;
+    history.replaceState = this.historyPatch.replaceState;
+    window.removeEventListener("popstate", this.onPopState);
+    this.historyPatch = null;
+  }
+  /** 恢复队列入队:历史事件放队头保证先到先发,超限按溢出丢弃;过滤旧格式(无 eventId)事件 */
   enqueueRestored(events) {
-    let accepted = events;
+    let accepted = events.filter(
+      (event) => typeof event.eventId === "string" && typeof event.eventName === "string"
+    );
+    if (accepted.length < events.length) {
+      this.log(`\u8DF3\u8FC7 ${events.length - accepted.length} \u6761\u65E7\u683C\u5F0F\u6301\u4E45\u5316\u4E8B\u4EF6`);
+    }
+    accepted = accepted.map((event) => ({
+      ...event,
+      attempts: typeof event.attempts === "number" ? event.attempts : 0
+    }));
     if (accepted.length > this.maxQueueSize) {
       this.opts.onDropped?.(accepted.slice(this.maxQueueSize), "overflow");
       accepted = accepted.slice(0, this.maxQueueSize);
@@ -423,6 +746,7 @@ var Reporter = class {
     this.queue.unshift(...accepted);
   }
   enqueue(event) {
+    const queued = { ...event, attempts: 0 };
     if (this.queue.length >= this.maxQueueSize) {
       if (this.overflowPolicy === "drop-newest") {
         this.opts.onDropped?.([event], "overflow");
@@ -434,7 +758,7 @@ var Reporter = class {
         this.fire(this.flush());
       }
     }
-    this.queue.push(event);
+    this.queue.push(queued);
     this.schedulePersist();
   }
   /** 攒批定时:延迟上报的实现,窗口内事件合并为一批 */
@@ -467,12 +791,13 @@ var Reporter = class {
   }
   async sendBatch(batch) {
     const transport = await this.transportPromise;
+    const wire = stripAttempts(batch);
     try {
-      await transport.send(batch);
-      this.opts.onFlushed?.(batch);
+      await transport.send(wire);
+      this.opts.onFlushed?.(wire);
       this.schedulePersist();
     } catch (error) {
-      this.opts.onFailed?.(batch, error);
+      this.opts.onFailed?.(wire, error);
       this.log("send batch failed:", error);
       const updated = batch.map((event) => ({
         ...event,
@@ -526,6 +851,99 @@ var Reporter = class {
       this.log("persist queue failed:", error);
     }
   }
+  // ============================================================
+  // 身份与会话持久化(browser: localStorage;Node: 进程内)。
+  // 会话存 localStorage 而非 sessionStorage:同源多 tab 共享一个会话,
+  // "连续 30 分钟无活动"是用户级语义,不应按 tab 拆分;跨 tab 同步靠
+  // storage 事件(实时)+ 活动时重读(兜底)。
+  // ============================================================
+  /** 匿名 id:localStorage 持久化,首次匿名访问生成后保留;Node 无持久化介质,进程内生成 */
+  loadOrCreateAnonymousId() {
+    const stored = this.readPersistent(ANONYMOUS_ID_KEY);
+    if (stored) return stored;
+    const fresh = this.newId("anonymous");
+    this.writePersistent(ANONYMOUS_ID_KEY, fresh);
+    return fresh;
+  }
+  /** clientId:Web&PC 与 google client id(_ga cookie)一致;否则本地生成并持久化 */
+  loadOrCreateClientId() {
+    if (typeof document !== "undefined") {
+      const ga = document.cookie.match(/(?:^|;\s*)_ga=GA1\.\d\.([^;]+)/);
+      if (ga?.[1]) return ga[1];
+      const stored = this.readPersistent(CLIENT_ID_KEY);
+      if (stored) return stored;
+    }
+    const fresh = this.newId("client");
+    this.writePersistent(CLIENT_ID_KEY, fresh);
+    return fresh;
+  }
+  /** 会话恢复:localStorage(同源多 tab 共享)中 30 分钟窗口内的会话复用,否则新建 */
+  loadOrCreateSession() {
+    const now = Date.now();
+    try {
+      const text = this.readPersistent(SESSION_KEY);
+      if (text) {
+        const stored = JSON.parse(text);
+        if (stored.visitId && now - stored.lastActivityMs <= VISIT_IDLE_TIMEOUT_MS) {
+          return stored;
+        }
+      }
+    } catch {
+    }
+    const fresh = { visitId: this.newId("visit"), lastActivityMs: now };
+    this.session = fresh;
+    this.saveSession(true);
+    return fresh;
+  }
+  /** 会话落盘(localStorage):节流 10s,避免滚动等高频活动频繁写;force 用于轮换 / 退出兜底 */
+  saveSession(force = false) {
+    const now = Date.now();
+    if (!force && this.sessionSaveAt > 0 && now - this.sessionSaveAt < SESSION_SAVE_THROTTLE_MS) {
+      return;
+    }
+    this.sessionSaveAt = now;
+    this.writePersistent(SESSION_KEY, JSON.stringify(this.session));
+  }
+  /** 采纳共享会话:visitId 变化视为其他 tab 轮换了会话,结束本 tab 旧页面访问并开启新访问 */
+  adoptSharedSession(stored) {
+    if (!stored.visitId || stored.visitId === this.session.visitId) {
+      if (stored.visitId) this.session = stored;
+      return;
+    }
+    const oldVisitId = this.session.visitId;
+    this.endPageVisit(oldVisitId, "sessionTimeout");
+    this.pageTracker?.startVisit();
+    this.session = stored;
+  }
+  /** 活动时重读共享会话(兜底 storage 事件丢失):storage 事件只在其他 tab 触发 */
+  refreshSessionFromShared() {
+    try {
+      const text = this.readPersistent(SESSION_KEY);
+      if (text) {
+        this.adoptSharedSession(JSON.parse(text));
+      }
+    } catch {
+    }
+  }
+  readPersistent(key) {
+    if (this.platform !== "browser") return null;
+    try {
+      return localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  }
+  writePersistent(key, value) {
+    if (this.platform !== "browser") return;
+    try {
+      localStorage.setItem(key, value);
+    } catch {
+    }
+  }
+  /** 生成带前缀的实例 id(格式对齐旧 SDK session_ / device_) */
+  newId(prefix) {
+    return `${prefix}_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+  }
   log(...args) {
     if (this.opts.debug) {
       console.log("[reporter]", ...args);