connectbase-client 3.3.1 → 3.4.0

package/dist/index.d.mts

@@ -314,6 +314,18 @@ declare class SessionManager {
     touch(): void;
     /** 세션 강제 리셋 */
     reset(): void;
+    /**
+     * visitor_uid 를 새로 발급하고 세션도 함께 초기화.
+     *
+     * 사용 시점:
+     * - 사용자 로그아웃 (이전 사용자 활동이 다음 사용자에 attribution 되는 것 방지)
+     * - 다른 사용자 로그인 감지 (link-member 가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답)
+     *
+     * localStorage 의 `__cb_visitor_uid` 가 새 UUID 로 교체되며 sessionStorage 의
+     * 세션 키도 같이 비워진다. 이후의 모든 batch 는 새 visitor 로 기록되어 멤버 간
+     * 데이터 오염이 차단된다.
+     */
+    regenerateVisitorUid(): string;
     private ensureSession;
     private loadOrCreateVisitorUid;
 }
@@ -368,6 +380,11 @@ declare class AnalyticsAPI {
      * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
      * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
      *
+     * **사용자 전환 자동 처리 (1.13.0+)**: 동일 브라우저에서 다른 사용자가 로그인해
+     * 백엔드가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답을 보내면, 큐를 비우고
+     * `visitor_uid` 를 새로 발급한 뒤 link-member 를 한 번 더 호출해 새 visitor 가
+     * 즉시 회원으로 기록되도록 자가 복구한다.
+     *
      * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
      *
      * @example
@@ -378,11 +395,30 @@ declare class AnalyticsAPI {
      * ```
      */
     identify(memberId: string): void;
+    /**
+     * 로그아웃 / 사용자 전환 시 호출. 익명 상태로 복귀하면서 visitor_uid 를 새로
+     * 발급해 다음 사용자의 활동이 이전 사용자에게 attribution 되는 데이터 오염을 차단.
+     *
+     * 동작:
+     * 1. memberId 를 null 로 설정 (이후 batch 는 익명으로 기록)
+     * 2. 큐에 쌓인 미전송 이벤트 폐기 (이전 visitor 로 가는 것을 막기 위함)
+     * 3. localStorage `__cb_visitor_uid` 새 UUID 로 교체 + sessionStorage 세션 키 정리
+     * 4. heatmap 큐도 함께 비움
+     *
+     * @example
+     * ```ts
+     * // 로그아웃 핸들러
+     * await cb.auth.signOut()
+     * cb.analytics.reset()
+     * ```
+     */
+    reset(): void;
     /**
      * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
      *
      * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
-     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
+     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃 시에는
+     * 데이터 오염 방지를 위해 `reset()` 를 권장).
      */
     setMemberId(memberId: string | null): void;
     /**
@@ -390,6 +426,9 @@ declare class AnalyticsAPI {
      *
      * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
      *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+     * - 다른 멤버에 이미 연결된 visitor 인 경우 (`VISITOR_LINKED_TO_OTHER_MEMBER`)
+     *   visitor_uid 를 자동 재발급하고 link-member 를 한 번 더 호출 — 한 단계의 자가
+     *   복구로 끝나며 무한 재귀를 막기 위해 두 번째 시도는 응답을 더 보지 않는다.
      * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
      */
     private linkMemberSilent;
@@ -510,7 +549,13 @@ declare class AnalyticsAPI {
     private createBaseEvent;
     private enqueue;
     private flushQueue;
-    /** sendBeacon으로 동기 flush (beforeunload용) */
+    /**
+     * sendBeacon 으로 동기 flush (beforeunload 용).
+     *
+     * sendBeacon 은 일반 fetch 와 달리 User-Agent 헤더가 신뢰할 수 있지만, 백엔드 봇
+     * 탐지가 body 의 `user_agent` 필드 첫 번째 값만 보므로 여기서도 동일하게 채워
+     * 첫 방문이 unload 타이밍에 도달했을 때 봇으로 오판되는 것을 방지한다.
+     */
     private flushSync;
     private trackSessionStart;
     private startBatchTimer;

package/dist/index.d.ts

@@ -314,6 +314,18 @@ declare class SessionManager {
     touch(): void;
     /** 세션 강제 리셋 */
     reset(): void;
+    /**
+     * visitor_uid 를 새로 발급하고 세션도 함께 초기화.
+     *
+     * 사용 시점:
+     * - 사용자 로그아웃 (이전 사용자 활동이 다음 사용자에 attribution 되는 것 방지)
+     * - 다른 사용자 로그인 감지 (link-member 가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답)
+     *
+     * localStorage 의 `__cb_visitor_uid` 가 새 UUID 로 교체되며 sessionStorage 의
+     * 세션 키도 같이 비워진다. 이후의 모든 batch 는 새 visitor 로 기록되어 멤버 간
+     * 데이터 오염이 차단된다.
+     */
+    regenerateVisitorUid(): string;
     private ensureSession;
     private loadOrCreateVisitorUid;
 }
@@ -368,6 +380,11 @@ declare class AnalyticsAPI {
      * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
      * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
      *
+     * **사용자 전환 자동 처리 (1.13.0+)**: 동일 브라우저에서 다른 사용자가 로그인해
+     * 백엔드가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답을 보내면, 큐를 비우고
+     * `visitor_uid` 를 새로 발급한 뒤 link-member 를 한 번 더 호출해 새 visitor 가
+     * 즉시 회원으로 기록되도록 자가 복구한다.
+     *
      * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
      *
      * @example
@@ -378,11 +395,30 @@ declare class AnalyticsAPI {
      * ```
      */
     identify(memberId: string): void;
+    /**
+     * 로그아웃 / 사용자 전환 시 호출. 익명 상태로 복귀하면서 visitor_uid 를 새로
+     * 발급해 다음 사용자의 활동이 이전 사용자에게 attribution 되는 데이터 오염을 차단.
+     *
+     * 동작:
+     * 1. memberId 를 null 로 설정 (이후 batch 는 익명으로 기록)
+     * 2. 큐에 쌓인 미전송 이벤트 폐기 (이전 visitor 로 가는 것을 막기 위함)
+     * 3. localStorage `__cb_visitor_uid` 새 UUID 로 교체 + sessionStorage 세션 키 정리
+     * 4. heatmap 큐도 함께 비움
+     *
+     * @example
+     * ```ts
+     * // 로그아웃 핸들러
+     * await cb.auth.signOut()
+     * cb.analytics.reset()
+     * ```
+     */
+    reset(): void;
     /**
      * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
      *
      * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
-     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
+     * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃 시에는
+     * 데이터 오염 방지를 위해 `reset()` 를 권장).
      */
     setMemberId(memberId: string | null): void;
     /**
@@ -390,6 +426,9 @@ declare class AnalyticsAPI {
      *
      * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
      *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+     * - 다른 멤버에 이미 연결된 visitor 인 경우 (`VISITOR_LINKED_TO_OTHER_MEMBER`)
+     *   visitor_uid 를 자동 재발급하고 link-member 를 한 번 더 호출 — 한 단계의 자가
+     *   복구로 끝나며 무한 재귀를 막기 위해 두 번째 시도는 응답을 더 보지 않는다.
      * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
      */
     private linkMemberSilent;
@@ -510,7 +549,13 @@ declare class AnalyticsAPI {
     private createBaseEvent;
     private enqueue;
     private flushQueue;
-    /** sendBeacon으로 동기 flush (beforeunload용) */
+    /**
+     * sendBeacon 으로 동기 flush (beforeunload 용).
+     *
+     * sendBeacon 은 일반 fetch 와 달리 User-Agent 헤더가 신뢰할 수 있지만, 백엔드 봇
+     * 탐지가 body 의 `user_agent` 필드 첫 번째 값만 보므로 여기서도 동일하게 채워
+     * 첫 방문이 unload 타이밍에 도달했을 때 봇으로 오판되는 것을 방지한다.
+     */
     private flushSync;
     private trackSessionStart;
     private startBatchTimer;

package/dist/index.js

@@ -8034,6 +8034,29 @@ var SessionManager = class {
     } catch {
     }
   }
+  /**
+   * visitor_uid 를 새로 발급하고 세션도 함께 초기화.
+   *
+   * 사용 시점:
+   * - 사용자 로그아웃 (이전 사용자 활동이 다음 사용자에 attribution 되는 것 방지)
+   * - 다른 사용자 로그인 감지 (link-member 가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답)
+   *
+   * localStorage 의 `__cb_visitor_uid` 가 새 UUID 로 교체되며 sessionStorage 의
+   * 세션 키도 같이 비워진다. 이후의 모든 batch 는 새 visitor 로 기록되어 멤버 간
+   * 데이터 오염이 차단된다.
+   */
+  regenerateVisitorUid() {
+    const newUid = generateId();
+    this._visitorUid = newUid;
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.setItem(VISITOR_KEY, newUid);
+      }
+    } catch {
+    }
+    this.reset();
+    return newUid;
+  }
   ensureSession() {
     const now = Date.now();
     if (!this._sessionId) {
@@ -8239,6 +8262,11 @@ var AnalyticsAPI = class {
    * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
    * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
    *
+   * **사용자 전환 자동 처리 (1.13.0+)**: 동일 브라우저에서 다른 사용자가 로그인해
+   * 백엔드가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답을 보내면, 큐를 비우고
+   * `visitor_uid` 를 새로 발급한 뒤 link-member 를 한 번 더 호출해 새 visitor 가
+   * 즉시 회원으로 기록되도록 자가 복구한다.
+   *
    * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
    *
    * @example
@@ -8249,14 +8277,42 @@ var AnalyticsAPI = class {
    * ```
    */
   identify(memberId) {
+    if (this.memberId && this.memberId !== memberId) {
+      this.reset();
+    }
     this.setMemberId(memberId);
     this.linkMemberSilent(memberId);
   }
+  /**
+   * 로그아웃 / 사용자 전환 시 호출. 익명 상태로 복귀하면서 visitor_uid 를 새로
+   * 발급해 다음 사용자의 활동이 이전 사용자에게 attribution 되는 데이터 오염을 차단.
+   *
+   * 동작:
+   * 1. memberId 를 null 로 설정 (이후 batch 는 익명으로 기록)
+   * 2. 큐에 쌓인 미전송 이벤트 폐기 (이전 visitor 로 가는 것을 막기 위함)
+   * 3. localStorage `__cb_visitor_uid` 새 UUID 로 교체 + sessionStorage 세션 키 정리
+   * 4. heatmap 큐도 함께 비움
+   *
+   * @example
+   * ```ts
+   * // 로그아웃 핸들러
+   * await cb.auth.signOut()
+   * cb.analytics.reset()
+   * ```
+   */
+  reset() {
+    this.setMemberId(null);
+    this.eventQueue = [];
+    this.heatmapQueue = [];
+    const newUid = this.session.regenerateVisitorUid();
+    this.log("Analytics reset", { newVisitorUid: newUid });
+  }
   /**
    * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
    *
    * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
-   * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
+   * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃 시에는
+   * 데이터 오염 방지를 위해 `reset()` 를 권장).
    */
   setMemberId(memberId) {
     this.memberId = memberId || null;
@@ -8278,9 +8334,12 @@ var AnalyticsAPI = class {
    *
    * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
    *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+   * - 다른 멤버에 이미 연결된 visitor 인 경우 (`VISITOR_LINKED_TO_OTHER_MEMBER`)
+   *   visitor_uid 를 자동 재발급하고 link-member 를 한 번 더 호출 — 한 단계의 자가
+   *   복구로 끝나며 무한 재귀를 막기 위해 두 번째 시도는 응답을 더 보지 않는다.
    * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
    */
-  linkMemberSilent(memberId) {
+  linkMemberSilent(memberId, isRetry = false) {
     if (!this.storageWebId) return;
     const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
     this.http.post(
@@ -8289,7 +8348,18 @@ var AnalyticsAPI = class {
         visitor_uid: this.session.visitorUid,
         app_member_id: memberId
       }
-    ).catch(() => {
+    ).then((resp) => {
+      if (!resp) return;
+      this.log("link-member response", resp);
+      if (!isRetry && resp.success === false && resp.code === "VISITOR_LINKED_TO_OTHER_MEMBER") {
+        this.log("user-switch detected \u2014 regenerating visitor_uid");
+        this.eventQueue = [];
+        this.heatmapQueue = [];
+        this.session.regenerateVisitorUid();
+        this.linkMemberSilent(memberId, true);
+      }
+    }).catch((err) => {
+      this.log("link-member silent fail", err);
     });
   }
   /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
@@ -8523,6 +8593,7 @@ var AnalyticsAPI = class {
   createBaseEvent(type) {
     return {
       type,
+      event_id: generateId(),
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       session_id: this.session.sessionId,
       visitor_uid: this.session.visitorUid
@@ -8545,6 +8616,7 @@ var AnalyticsAPI = class {
           visitor_uid: this.session.visitorUid,
           ...this.memberId ? { app_member_id: this.memberId } : {},
           events: events.map((e) => ({
+            event_id: e.event_id,
             timestamp: e.timestamp,
             page_path: e.page_path || "",
             page_url: e.page_url || "",
@@ -8574,7 +8646,13 @@ var AnalyticsAPI = class {
       this.log("Flush failed", err);
     }
   }
-  /** sendBeacon으로 동기 flush (beforeunload용) */
+  /**
+   * sendBeacon 으로 동기 flush (beforeunload 용).
+   *
+   * sendBeacon 은 일반 fetch 와 달리 User-Agent 헤더가 신뢰할 수 있지만, 백엔드 봇
+   * 탐지가 body 의 `user_agent` 필드 첫 번째 값만 보므로 여기서도 동일하게 채워
+   * 첫 방문이 unload 타이밍에 도달했을 때 봇으로 오판되는 것을 방지한다.
+   */
   flushSync() {
     if (this.eventQueue.length === 0 || !this.storageWebId) return;
     if (typeof navigator === "undefined" || !navigator.sendBeacon) return;
@@ -8582,20 +8660,30 @@ var AnalyticsAPI = class {
     const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
     const baseUrl = this.http.getBaseUrl();
     const url = `${baseUrl}${prefix}/storages/web/${this.storageWebId}/visitors/batch`;
+    const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
     const body = JSON.stringify({
       visitor_uid: this.session.visitorUid,
       ...this.memberId ? { app_member_id: this.memberId } : {},
       events: events.map((e) => ({
+        event_id: e.event_id,
         timestamp: e.timestamp,
         page_path: e.page_path || "",
         page_url: e.page_url || "",
         page_title: e.page_title || "",
         referrer: e.referrer || "",
+        user_agent: ua,
+        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
+        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
       }))
     });
     try {

package/dist/index.mjs

@@ -7994,6 +7994,29 @@ var SessionManager = class {
     } catch {
     }
   }
+  /**
+   * visitor_uid 를 새로 발급하고 세션도 함께 초기화.
+   *
+   * 사용 시점:
+   * - 사용자 로그아웃 (이전 사용자 활동이 다음 사용자에 attribution 되는 것 방지)
+   * - 다른 사용자 로그인 감지 (link-member 가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답)
+   *
+   * localStorage 의 `__cb_visitor_uid` 가 새 UUID 로 교체되며 sessionStorage 의
+   * 세션 키도 같이 비워진다. 이후의 모든 batch 는 새 visitor 로 기록되어 멤버 간
+   * 데이터 오염이 차단된다.
+   */
+  regenerateVisitorUid() {
+    const newUid = generateId();
+    this._visitorUid = newUid;
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.setItem(VISITOR_KEY, newUid);
+      }
+    } catch {
+    }
+    this.reset();
+    return newUid;
+  }
   ensureSession() {
     const now = Date.now();
     if (!this._sessionId) {
@@ -8199,6 +8222,11 @@ var AnalyticsAPI = class {
    * 백엔드 `link-member` 엔드포인트를 한 번 호출합니다 (1.11.0+). 호출 실패는
    * silent — 다음 batch 가 닿을 때 백엔드 자동 매핑이 동일하게 처리하므로 자가 복구.
    *
+   * **사용자 전환 자동 처리 (1.13.0+)**: 동일 브라우저에서 다른 사용자가 로그인해
+   * 백엔드가 `VISITOR_LINKED_TO_OTHER_MEMBER` 응답을 보내면, 큐를 비우고
+   * `visitor_uid` 를 새로 발급한 뒤 link-member 를 한 번 더 호출해 새 visitor 가
+   * 즉시 회원으로 기록되도록 자가 복구한다.
+   *
    * 산업 표준(GA4 User-ID, Mixpanel/PostHog `identify`) 과 동작 정합.
    *
    * @example
@@ -8209,14 +8237,42 @@ var AnalyticsAPI = class {
    * ```
    */
   identify(memberId) {
+    if (this.memberId && this.memberId !== memberId) {
+      this.reset();
+    }
     this.setMemberId(memberId);
     this.linkMemberSilent(memberId);
   }
+  /**
+   * 로그아웃 / 사용자 전환 시 호출. 익명 상태로 복귀하면서 visitor_uid 를 새로
+   * 발급해 다음 사용자의 활동이 이전 사용자에게 attribution 되는 데이터 오염을 차단.
+   *
+   * 동작:
+   * 1. memberId 를 null 로 설정 (이후 batch 는 익명으로 기록)
+   * 2. 큐에 쌓인 미전송 이벤트 폐기 (이전 visitor 로 가는 것을 막기 위함)
+   * 3. localStorage `__cb_visitor_uid` 새 UUID 로 교체 + sessionStorage 세션 키 정리
+   * 4. heatmap 큐도 함께 비움
+   *
+   * @example
+   * ```ts
+   * // 로그아웃 핸들러
+   * await cb.auth.signOut()
+   * cb.analytics.reset()
+   * ```
+   */
+  reset() {
+    this.setMemberId(null);
+    this.eventQueue = [];
+    this.heatmapQueue = [];
+    const newUid = this.session.regenerateVisitorUid();
+    this.log("Analytics reset", { newVisitorUid: newUid });
+  }
   /**
    * 방문자 트래커에 현재 회원 ID 설정 (로그인/게스트 가입 시 호출).
    *
    * `identify()` 와 달리 즉시 backfill 호출은 하지 않습니다 — 단순히 이후 batch 의
-   * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃).
+   * `app_member_id` 값만 갱신. null 을 넘기면 익명 상태로 복귀 (로그아웃 시에는
+   * 데이터 오염 방지를 위해 `reset()` 를 권장).
    */
   setMemberId(memberId) {
     this.memberId = memberId || null;
@@ -8238,9 +8294,12 @@ var AnalyticsAPI = class {
    *
    * - 첫 페이지뷰가 아직 백엔드에 닿기 전이면 visitor 가 없어 404. 무시 — 다음 batch 가
    *   가면 백엔드 BatchRecordVisit 가 자동 LinkMember 를 호출.
+   * - 다른 멤버에 이미 연결된 visitor 인 경우 (`VISITOR_LINKED_TO_OTHER_MEMBER`)
+   *   visitor_uid 를 자동 재발급하고 link-member 를 한 번 더 호출 — 한 단계의 자가
+   *   복구로 끝나며 무한 재귀를 막기 위해 두 번째 시도는 응답을 더 보지 않는다.
    * - storage_web_id 가 init 안 됐거나 모든 종류의 네트워크 오류 — silent fail.
    */
-  linkMemberSilent(memberId) {
+  linkMemberSilent(memberId, isRetry = false) {
     if (!this.storageWebId) return;
     const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
     this.http.post(
@@ -8249,7 +8308,18 @@ var AnalyticsAPI = class {
         visitor_uid: this.session.visitorUid,
         app_member_id: memberId
       }
-    ).catch(() => {
+    ).then((resp) => {
+      if (!resp) return;
+      this.log("link-member response", resp);
+      if (!isRetry && resp.success === false && resp.code === "VISITOR_LINKED_TO_OTHER_MEMBER") {
+        this.log("user-switch detected \u2014 regenerating visitor_uid");
+        this.eventQueue = [];
+        this.heatmapQueue = [];
+        this.session.regenerateVisitorUid();
+        this.linkMemberSilent(memberId, true);
+      }
+    }).catch((err) => {
+      this.log("link-member silent fail", err);
     });
   }
   /** 현재 설정된 회원 ID 조회 (미설정 시 null) */
@@ -8483,6 +8553,7 @@ var AnalyticsAPI = class {
   createBaseEvent(type) {
     return {
       type,
+      event_id: generateId(),
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       session_id: this.session.sessionId,
       visitor_uid: this.session.visitorUid
@@ -8505,6 +8576,7 @@ var AnalyticsAPI = class {
           visitor_uid: this.session.visitorUid,
           ...this.memberId ? { app_member_id: this.memberId } : {},
           events: events.map((e) => ({
+            event_id: e.event_id,
             timestamp: e.timestamp,
             page_path: e.page_path || "",
             page_url: e.page_url || "",
@@ -8534,7 +8606,13 @@ var AnalyticsAPI = class {
       this.log("Flush failed", err);
     }
   }
-  /** sendBeacon으로 동기 flush (beforeunload용) */
+  /**
+   * sendBeacon 으로 동기 flush (beforeunload 용).
+   *
+   * sendBeacon 은 일반 fetch 와 달리 User-Agent 헤더가 신뢰할 수 있지만, 백엔드 봇
+   * 탐지가 body 의 `user_agent` 필드 첫 번째 값만 보므로 여기서도 동일하게 채워
+   * 첫 방문이 unload 타이밍에 도달했을 때 봇으로 오판되는 것을 방지한다.
+   */
   flushSync() {
     if (this.eventQueue.length === 0 || !this.storageWebId) return;
     if (typeof navigator === "undefined" || !navigator.sendBeacon) return;
@@ -8542,20 +8620,30 @@ var AnalyticsAPI = class {
     const prefix = this.http.hasPublicKey() ? "/v1/public" : "/v1";
     const baseUrl = this.http.getBaseUrl();
     const url = `${baseUrl}${prefix}/storages/web/${this.storageWebId}/visitors/batch`;
+    const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
     const body = JSON.stringify({
       visitor_uid: this.session.visitorUid,
       ...this.memberId ? { app_member_id: this.memberId } : {},
       events: events.map((e) => ({
+        event_id: e.event_id,
         timestamp: e.timestamp,
         page_path: e.page_path || "",
         page_url: e.page_url || "",
         page_title: e.page_title || "",
         referrer: e.referrer || "",
+        user_agent: ua,
+        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
+        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
       }))
     });
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",