connectbase-client 0.13.0 → 0.15.0

package/dist/index.mjs

@@ -7422,6 +7422,594 @@ var QueueAPI = class {
   }
 };
 
+// src/api/analytics.ts
+var SESSION_TIMEOUT_MS = 30 * 60 * 1e3;
+var SESSION_KEY = "__cb_session";
+var VISITOR_KEY = "__cb_visitor_uid";
+var LAST_ACTIVITY_KEY = "__cb_last_activity";
+function generateId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+var SessionManager = class {
+  constructor() {
+    this._sessionId = null;
+    this._visitorUid = null;
+    this._lastActivity = 0;
+    this._isNewSession = false;
+  }
+  get sessionId() {
+    this.ensureSession();
+    return this._sessionId;
+  }
+  get visitorUid() {
+    if (!this._visitorUid) {
+      this._visitorUid = this.loadOrCreateVisitorUid();
+    }
+    return this._visitorUid;
+  }
+  get isNewSession() {
+    return this._isNewSession;
+  }
+  /** 활동 기록 — 세션 타임아웃 리셋 */
+  touch() {
+    this._lastActivity = Date.now();
+    this._isNewSession = false;
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        sessionStorage.setItem(LAST_ACTIVITY_KEY, String(this._lastActivity));
+      }
+    } catch {
+    }
+  }
+  /** 세션 강제 리셋 */
+  reset() {
+    this._sessionId = null;
+    this._isNewSession = false;
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        sessionStorage.removeItem(SESSION_KEY);
+        sessionStorage.removeItem(LAST_ACTIVITY_KEY);
+      }
+    } catch {
+    }
+  }
+  ensureSession() {
+    const now = Date.now();
+    if (!this._sessionId) {
+      try {
+        if (typeof sessionStorage !== "undefined") {
+          this._sessionId = sessionStorage.getItem(SESSION_KEY);
+          const lastStr = sessionStorage.getItem(LAST_ACTIVITY_KEY);
+          this._lastActivity = lastStr ? parseInt(lastStr, 10) : 0;
+        }
+      } catch {
+      }
+    }
+    if (!this._sessionId || this._lastActivity > 0 && now - this._lastActivity > SESSION_TIMEOUT_MS) {
+      this._sessionId = generateId();
+      this._isNewSession = true;
+      this._lastActivity = now;
+      try {
+        if (typeof sessionStorage !== "undefined") {
+          sessionStorage.setItem(SESSION_KEY, this._sessionId);
+          sessionStorage.setItem(LAST_ACTIVITY_KEY, String(now));
+        }
+      } catch {
+      }
+    }
+  }
+  loadOrCreateVisitorUid() {
+    try {
+      if (typeof localStorage !== "undefined") {
+        const existing = localStorage.getItem(VISITOR_KEY);
+        if (existing) return existing;
+        const uid = generateId();
+        localStorage.setItem(VISITOR_KEY, uid);
+        return uid;
+      }
+    } catch {
+    }
+    return generateId();
+  }
+};
+function parseUTM() {
+  if (typeof window === "undefined") return {};
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const utm = {};
+    for (const key of ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"]) {
+      const val = params.get(key);
+      if (val) utm[key] = val;
+    }
+    return utm;
+  } catch {
+    return {};
+  }
+}
+var AnalyticsAPI = class {
+  constructor(http) {
+    this.storageWebId = null;
+    this.eventQueue = [];
+    this.batchTimer = null;
+    this.isInitialized = false;
+    this.heartbeatTimer = null;
+    this.visibilityHandler = null;
+    this.unloadHeartbeatHandler = null;
+    this.popstateHandler = null;
+    this.beforeUnloadHandler = null;
+    this.origPushState = null;
+    this.origReplaceState = null;
+    this.heatmapClickHandler = null;
+    this.heatmapScrollHandler = null;
+    this.utm = {};
+    this.handleHeatmapClick = (e) => {
+      const xPercent = e.clientX / window.innerWidth * 100;
+      const yPercent = e.clientY / window.innerHeight * 100;
+      this.recordHeatmapEvent("click", xPercent, yPercent);
+    };
+    this.heatmapQueue = [];
+    this.http = http;
+    this.config = {
+      trackPageViews: true,
+      trackEvents: true,
+      trackSessions: true,
+      heatmap: false,
+      recording: false,
+      batchSize: 10,
+      flushInterval: 5e3,
+      respectDoNotTrack: true,
+      debug: false
+    };
+    this.consent = {
+      analytics: true,
+      heatmap: false,
+      recording: false
+    };
+    this.session = new SessionManager();
+  }
+  /**
+   * Analytics 초기화
+   * @param storageWebId 웹 스토리지 ID
+   * @param config 설정 (선택)
+   */
+  init(storageWebId, config) {
+    if (this.isInitialized) {
+      this.log("Analytics already initialized");
+      return;
+    }
+    if (typeof window === "undefined") {
+      this.log("Analytics only works in browser environment");
+      return;
+    }
+    if (config?.respectDoNotTrack !== false && this.isDNT()) {
+      this.log("Do Not Track enabled, analytics disabled");
+      return;
+    }
+    this.storageWebId = storageWebId;
+    Object.assign(this.config, config);
+    this.isInitialized = true;
+    this.utm = parseUTM();
+    if (this.config.trackSessions) {
+      this.trackSessionStart();
+      this.startHeartbeat();
+    }
+    if (this.config.trackPageViews) {
+      this.trackPageView();
+      this.setupAutoPageView();
+    }
+    this.startBatchTimer();
+    this.beforeUnloadHandler = () => this.flushSync();
+    window.addEventListener("beforeunload", this.beforeUnloadHandler);
+    this.log("Analytics initialized", { storageWebId });
+  }
+  /** Analytics 정리 */
+  destroy() {
+    if (!this.isInitialized) return;
+    this.stopBatchTimer();
+    this.stopHeartbeat();
+    this.removeAutoPageView();
+    this.removeHeatmapListeners();
+    if (this.beforeUnloadHandler) {
+      window.removeEventListener("beforeunload", this.beforeUnloadHandler);
+      this.beforeUnloadHandler = null;
+    }
+    this.flush();
+    this.isInitialized = false;
+    this.log("Analytics destroyed");
+  }
+  /**
+   * 동의 설정 변경
+   */
+  setConsent(consent) {
+    Object.assign(this.consent, consent);
+    this.log("Consent updated", consent);
+    if (consent.analytics === false && this.isInitialized) {
+      this.destroy();
+    }
+  }
+  /** 현재 동의 상태 조회 */
+  getConsent() {
+    return { ...this.consent };
+  }
+  /**
+   * 페이지뷰 수동 추적
+   */
+  trackPageView(path) {
+    if (!this.canTrack()) return;
+    this.session.touch();
+    const event = this.createBaseEvent("page_view");
+    event.page_path = path || window.location.pathname;
+    event.page_url = window.location.href;
+    event.page_title = document.title;
+    event.referrer = document.referrer || void 0;
+    event.screen_width = window.screen.width;
+    event.screen_height = window.screen.height;
+    Object.assign(event, this.utm);
+    this.enqueue(event);
+  }
+  /**
+   * 커스텀 이벤트 추적
+   */
+  trackEvent(name, properties) {
+    if (!this.canTrack() || !this.config.trackEvents) return;
+    this.session.touch();
+    const event = this.createBaseEvent("event");
+    event.event_name = name;
+    event.event_properties = properties;
+    event.page_path = window.location.pathname;
+    event.page_url = window.location.href;
+    this.enqueue(event);
+  }
+  /**
+   * 사용자 식별 (로그인 시)
+   */
+  identify(memberId) {
+    if (!this.canTrack()) return;
+    if (typeof window.__cbSetMember === "function") {
+      window.__cbSetMember(memberId);
+    }
+    this.log("User identified", { memberId });
+  }
+  /**
+   * 히트맵 수집 활성화 (opt-in)
+   */
+  enableHeatmap(options) {
+    if (!this.canTrack() || !this.consent.heatmap) return;
+    const trackClick = options?.click ?? true;
+    const trackScroll = options?.scroll ?? true;
+    if (trackClick) {
+      this.heatmapClickHandler = this.handleHeatmapClick;
+      document.addEventListener("click", this.heatmapClickHandler);
+    }
+    if (trackScroll) {
+      let scrollTimer = null;
+      let maxScrollDepth = 0;
+      this.heatmapScrollHandler = () => {
+        const depth = Math.round(
+          (window.scrollY + window.innerHeight) / document.documentElement.scrollHeight * 100
+        );
+        maxScrollDepth = Math.max(maxScrollDepth, depth);
+        if (scrollTimer) clearTimeout(scrollTimer);
+        scrollTimer = setTimeout(() => {
+          this.recordHeatmapEvent("scroll", 50, maxScrollDepth * (window.innerHeight / 100), maxScrollDepth);
+        }, 500);
+      };
+      window.addEventListener("scroll", this.heatmapScrollHandler, { passive: true });
+    }
+    this.log("Heatmap enabled", options);
+  }
+  /**
+   * 세션 heartbeat 자동 전송 시작 (30초 간격)
+   */
+  enableHeartbeat() {
+    if (!this.canTrack()) return;
+    if (this.heartbeatTimer) return;
+    const sendHeartbeat = () => {
+      if (!this.canTrack()) return;
+      const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
+      this.http.post(`${prefix}/storages/web/${this.storageWebId}/sessions/heartbeat`, {
+        visitor_uid: this.session.visitorUid,
+        session_id: this.session.sessionId
+      }).catch(() => {
+      });
+    };
+    this.heartbeatTimer = setInterval(sendHeartbeat, 3e4);
+    document.addEventListener("visibilitychange", () => {
+      if (document.hidden) {
+        if (this.heartbeatTimer) {
+          clearInterval(this.heartbeatTimer);
+          this.heartbeatTimer = null;
+        }
+      } else {
+        if (!this.heartbeatTimer) {
+          this.heartbeatTimer = setInterval(sendHeartbeat, 3e4);
+          sendHeartbeat();
+        }
+      }
+    });
+    window.addEventListener("beforeunload", () => {
+      if (typeof navigator !== "undefined" && navigator.sendBeacon && this.storageWebId) {
+        const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
+        const url = `${this.http.getBaseUrl()}${prefix}/storages/web/${this.storageWebId}/sessions/heartbeat`;
+        navigator.sendBeacon(url, JSON.stringify({
+          visitor_uid: this.session.visitorUid,
+          session_id: this.session.sessionId
+        }));
+      }
+    });
+    sendHeartbeat();
+    this.log("Heartbeat enabled (30s interval)");
+  }
+  /** 큐에 있는 이벤트 즉시 전송 */
+  async flush() {
+    await this.flushQueue();
+  }
+  /** 세션 매니저 접근 (고급) */
+  getSession() {
+    return this.session;
+  }
+  // ── Private ────────────────────────────────────────────────────
+  canTrack() {
+    if (!this.isInitialized || !this.storageWebId) return false;
+    if (!this.consent.analytics) return false;
+    return true;
+  }
+  isDNT() {
+    if (typeof navigator === "undefined") return false;
+    return navigator.doNotTrack === "1" || navigator.globalPrivacyControl === true;
+  }
+  createBaseEvent(type) {
+    return {
+      type,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      session_id: this.session.sessionId,
+      visitor_uid: this.session.visitorUid
+    };
+  }
+  enqueue(event) {
+    this.eventQueue.push(event);
+    if (this.eventQueue.length >= this.config.batchSize) {
+      this.flushQueue();
+    }
+  }
+  async flushQueue() {
+    if (this.eventQueue.length === 0 || !this.storageWebId) return;
+    const events = this.eventQueue.splice(0);
+    const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
+    try {
+      await this.http.post(
+        `${prefix}/storages/web/${this.storageWebId}/visitors/batch`,
+        {
+          visitor_uid: this.session.visitorUid,
+          events: events.map((e) => ({
+            timestamp: e.timestamp,
+            page_path: e.page_path || "",
+            page_url: e.page_url || "",
+            page_title: e.page_title || "",
+            referrer: e.referrer || "",
+            user_agent: typeof navigator !== "undefined" ? navigator.userAgent : "",
+            screen_width: e.screen_width || 0,
+            screen_height: e.screen_height || 0,
+            session_id: e.session_id,
+            session_start: e.type === "session_start",
+            is_page_view: e.type === "page_view",
+            event_name: e.event_name,
+            event_properties: e.event_properties,
+            utm_source: e.utm_source,
+            utm_medium: e.utm_medium,
+            utm_campaign: e.utm_campaign,
+            utm_content: e.utm_content,
+            utm_term: e.utm_term
+          }))
+        }
+      );
+      this.log(`Flushed ${events.length} events`);
+    } catch (err) {
+      if (this.eventQueue.length < this.config.batchSize * 3) {
+        this.eventQueue.unshift(...events);
+      }
+      this.log("Flush failed", err);
+    }
+  }
+  /** sendBeacon으로 동기 flush (beforeunload용) */
+  flushSync() {
+    if (this.eventQueue.length === 0 || !this.storageWebId) return;
+    if (typeof navigator === "undefined" || !navigator.sendBeacon) return;
+    const events = this.eventQueue.splice(0);
+    const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
+    const baseUrl = this.http.getBaseUrl();
+    const url = `${baseUrl}${prefix}/storages/web/${this.storageWebId}/visitors/batch`;
+    const body = JSON.stringify({
+      visitor_uid: this.session.visitorUid,
+      events: events.map((e) => ({
+        timestamp: e.timestamp,
+        page_path: e.page_path || "",
+        page_url: e.page_url || "",
+        page_title: e.page_title || "",
+        referrer: e.referrer || "",
+        session_id: e.session_id,
+        session_start: e.type === "session_start",
+        is_page_view: e.type === "page_view",
+        event_name: e.event_name,
+        event_properties: e.event_properties
+      }))
+    });
+    try {
+      navigator.sendBeacon(url, new Blob([body], { type: "application/json" }));
+    } catch {
+    }
+  }
+  trackSessionStart() {
+    const event = this.createBaseEvent("session_start");
+    event.page_path = window.location.pathname;
+    event.page_url = window.location.href;
+    event.referrer = document.referrer || void 0;
+    event.screen_width = window.screen.width;
+    event.screen_height = window.screen.height;
+    Object.assign(event, this.utm);
+    this.enqueue(event);
+  }
+  startBatchTimer() {
+    this.batchTimer = setInterval(() => this.flushQueue(), this.config.flushInterval);
+  }
+  stopBatchTimer() {
+    if (this.batchTimer) {
+      clearInterval(this.batchTimer);
+      this.batchTimer = null;
+    }
+  }
+  startHeartbeat() {
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.canTrack()) return;
+      this.sendHeartbeat();
+    }, 30 * 1e3);
+    if (typeof document !== "undefined") {
+      this.visibilityHandler = () => {
+        if (document.visibilityState === "hidden") {
+          this.sendHeartbeatBeacon();
+          if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+          }
+        } else if (document.visibilityState === "visible") {
+          if (!this.heartbeatTimer) {
+            this.sendHeartbeat();
+            this.heartbeatTimer = setInterval(() => {
+              if (!this.canTrack()) return;
+              this.sendHeartbeat();
+            }, 30 * 1e3);
+          }
+        }
+      };
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
+    if (typeof window !== "undefined") {
+      this.unloadHeartbeatHandler = () => this.sendHeartbeatBeacon();
+      window.addEventListener("beforeunload", this.unloadHeartbeatHandler);
+    }
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (typeof document !== "undefined" && this.visibilityHandler) {
+      document.removeEventListener("visibilitychange", this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    if (typeof window !== "undefined" && this.unloadHeartbeatHandler) {
+      window.removeEventListener("beforeunload", this.unloadHeartbeatHandler);
+      this.unloadHeartbeatHandler = null;
+    }
+  }
+  /** 하트비트를 큐에 넣어 배치 전송 */
+  sendHeartbeat() {
+    const event = this.createBaseEvent("heartbeat");
+    event.page_path = window.location.pathname;
+    this.enqueue(event);
+    if (this.storageWebId) {
+      const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
+      this.http.post(
+        `${prefix}/storages/web/${this.storageWebId}/sessions/heartbeat`,
+        {
+          visitor_uid: this.session.visitorUid,
+          session_id: this.session.sessionId
+        }
+      ).catch(() => {
+      });
+    }
+  }
+  /** sendBeacon으로 하트비트 전송 (unload/visibility hidden용) */
+  sendHeartbeatBeacon() {
+    if (!this.storageWebId) return;
+    if (typeof navigator === "undefined" || !navigator.sendBeacon) return;
+    const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
+    const baseUrl = this.http.getBaseUrl();
+    const url = `${baseUrl}${prefix}/storages/web/${this.storageWebId}/sessions/heartbeat`;
+    const body = JSON.stringify({
+      visitor_uid: this.session.visitorUid,
+      session_id: this.session.sessionId
+    });
+    try {
+      navigator.sendBeacon(url, new Blob([body], { type: "application/json" }));
+    } catch {
+    }
+  }
+  setupAutoPageView() {
+    this.popstateHandler = () => this.trackPageView();
+    window.addEventListener("popstate", this.popstateHandler);
+    this.origPushState = history.pushState.bind(history);
+    this.origReplaceState = history.replaceState.bind(history);
+    const self = this;
+    history.pushState = function(...args) {
+      self.origPushState(...args);
+      self.trackPageView();
+    };
+    history.replaceState = function(...args) {
+      self.origReplaceState(...args);
+      self.trackPageView();
+    };
+  }
+  removeAutoPageView() {
+    if (this.popstateHandler) {
+      window.removeEventListener("popstate", this.popstateHandler);
+      this.popstateHandler = null;
+    }
+    if (this.origPushState) {
+      history.pushState = this.origPushState;
+      this.origPushState = null;
+    }
+    if (this.origReplaceState) {
+      history.replaceState = this.origReplaceState;
+      this.origReplaceState = null;
+    }
+  }
+  removeHeatmapListeners() {
+    if (this.heatmapClickHandler) {
+      document.removeEventListener("click", this.heatmapClickHandler);
+      this.heatmapClickHandler = null;
+    }
+    if (this.heatmapScrollHandler) {
+      window.removeEventListener("scroll", this.heatmapScrollHandler);
+      this.heatmapScrollHandler = null;
+    }
+  }
+  recordHeatmapEvent(eventType, xPercent, yPercent, scrollDepth) {
+    if (!this.canTrack() || !this.storageWebId) return;
+    const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
+    this.heatmapQueue.push({
+      page_path: window.location.pathname,
+      event_type: eventType,
+      x_percent: Math.round(xPercent * 100) / 100,
+      y_percent: Math.round(yPercent * 100) / 100,
+      viewport_width: window.innerWidth,
+      viewport_height: window.innerHeight,
+      scroll_depth_percent: scrollDepth,
+      session_id: this.session.sessionId
+    });
+    if (this.heatmapQueue.length >= 50) {
+      const events = this.heatmapQueue.splice(0);
+      this.http.post(`${prefix}/storages/web/${this.storageWebId}/heatmap/batch`, {
+        visitor_uid: this.session.visitorUid,
+        events
+      }).catch(() => {
+      });
+    }
+  }
+  log(...args) {
+    if (this.config.debug) {
+      console.log("[Analytics]", ...args);
+    }
+  }
+};
+
 // src/api/game-transport.ts
 var WebTransportTransport = class {
   constructor(config, onMessage, onClose, onError) {
@@ -8101,6 +8689,7 @@ var ConnectBase = class {
     this.knowledge = new KnowledgeAPI(this.http);
     this.ai = new AIAPI(this.http);
     this.queue = new QueueAPI(this.http);
+    this.analytics = new AnalyticsAPI(this.http);
   }
   /**
    * 수동으로 토큰 설정 (기존 토큰으로 세션 복원 시)
@@ -8132,6 +8721,7 @@ export {
   GameRoom,
   GameRoomTransport,
   NativeAPI,
+  SessionManager,
   VideoProcessingError,
   index_default as default,
   isWebTransportSupported

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",
@@ -33,6 +33,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "test:types": "tsc --noEmit -p test/tsconfig.json",
     "release": "pnpm build && npm publish --access public"
   },
@@ -55,7 +56,8 @@
   "devDependencies": {
     "@types/node": "^22.15.18",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=16"