@adstage/web-sdk 3.0.9 → 3.0.11

package/src/modules/tracking/tracking-params.ts

@@ -0,0 +1,318 @@
+/**
+ * AdStage SDK - Tracking Parameters Module
+ * URL에서 광고 추적 파라미터를 자동으로 추출하여 저장
+ *
+ * 지원 파라미터:
+ * - 클릭 ID: gclid, fbclid, ttclid, nclid (플랫폼별)
+ * - 캠페인 정보: campaign, campaign_id, ad_group, ad_creative, term
+ * - UTM 파라미터: utm_source, utm_medium, utm_campaign, utm_content, utm_term
+ *
+ * 동작 방식:
+ * 1. SDK 초기화 시 URL에서 파라미터 자동 추출
+ * 2. sessionStorage에 저장 (SPA 페이지 전환 시에도 유지)
+ * 3. EventsModule에서 track() 호출 시 자동으로 attribution 정보 주입
+ */
+
+export interface TrackingParams {
+  // ========== 클릭 ID (광고 플랫폼별) ==========
+  gclid?: string; // Google Ads Click ID
+  fbclid?: string; // Meta Ads (Facebook) Click ID
+  ttclid?: string; // TikTok Ads Click ID
+  nclid?: string; // Naver SA Click ID
+  liclid?: string; // LinkedIn Ads Click ID
+  msclkid?: string; // Microsoft Ads Click ID
+  twclid?: string; // Twitter Ads Click ID
+
+  // ========== 광고 계층 정보 ==========
+  channel?: string; // 광고 채널 (google.ads, meta.ads, naver.searchad 등)
+  campaign?: string; // 캠페인명/ID
+  campaign_id?: string; // 캠페인 ID
+  ad_group?: string; // 광고그룹명/ID
+  ad_group_id?: string; // 광고그룹 ID
+  ad_creative?: string; // 광고소재명/ID
+  creative_id?: string; // 광고소재 ID
+  term?: string; // 키워드
+
+  // ========== UTM 파라미터 ==========
+  utm_source?: string; // 트래픽 소스 (예: google, facebook, newsletter)
+  utm_medium?: string; // 마케팅 매체 (예: cpc, banner, email)
+  utm_campaign?: string; // 캠페인 이름
+  utm_content?: string; // 광고 콘텐츠 구분자
+  utm_term?: string; // 검색 키워드
+}
+
+/**
+ * TrackingParams 모듈
+ * URL 파라미터 추출 및 저장 관리
+ */
+export class TrackingParamsModule {
+  private static readonly STORAGE_KEY = 'adstage_tracking_params';
+
+  // 추출할 파라미터 키 정의
+  private static readonly CLICK_ID_KEYS = ['gclid', 'fbclid', 'ttclid', 'nclid', 'liclid', 'msclkid', 'twclid'];
+
+  private static readonly CAMPAIGN_KEYS = ['campaign', 'campaign_id', 'ad_group', 'ad_group_id', 'ad_creative', 'creative_id', 'term'];
+
+  private static readonly UTM_KEYS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'];
+
+  private static readonly ALL_KEYS = [
+    ...TrackingParamsModule.CLICK_ID_KEYS,
+    ...TrackingParamsModule.CAMPAIGN_KEYS,
+    ...TrackingParamsModule.UTM_KEYS,
+  ];
+
+  /**
+   * 현재 URL에서 추적 파라미터 추출 및 저장
+   * SDK 초기화 시 자동 호출됨
+   *
+   * 지원 형식:
+   * 1. 일반 URL 파라미터: ?gclid=abc123&campaign=summer
+   * 2. adstage_referrer 인코딩 파라미터: ?adstage_referrer=channel%3Dgoogle.ads%26gclid%3Dabc123
+   */
+  public static captureFromUrl(): TrackingParams | null {
+    if (typeof window === 'undefined') {
+      return null; // SSR 환경에서는 실행 안 함
+    }
+
+    const urlParams = new URLSearchParams(window.location.search);
+    const params: TrackingParams = {};
+    let hasParams = false;
+
+    // 1️⃣ adstage_referrer 파라미터 우선 처리 (최종 URL 접미사 방식)
+    const adstageReferrer = urlParams.get('adstage_referrer');
+    if (adstageReferrer) {
+      try {
+        // URL 디코딩: channel%3Dgoogle.ads%26gclid%3Dabc123 → channel=google.ads&gclid=abc123
+        const decoded = decodeURIComponent(adstageReferrer);
+        const referrerParams = new URLSearchParams(decoded);
+
+        // 추적 파라미터 추출
+        for (const key of TrackingParamsModule.ALL_KEYS) {
+          const value = referrerParams.get(key);
+          if (value) {
+            params[key as keyof TrackingParams] = value;
+            hasParams = true;
+          }
+        }
+
+        // adstage=true 플래그 확인
+        const isAdstage = referrerParams.get('adstage');
+        if (isAdstage === 'true') {
+          hasParams = true; // Adstage 추적 확인
+        }
+      } catch (error) {
+        console.warn('Failed to parse adstage_referrer:', error);
+      }
+    }
+
+    // 2️⃣ 일반 URL 파라미터 추출 (추적 템플릿 방식 또는 직접 입력)
+    for (const key of TrackingParamsModule.ALL_KEYS) {
+      // adstage_referrer에서 이미 추출했으면 건너뛰기 (중복 방지)
+      if (params[key as keyof TrackingParams]) {
+        continue;
+      }
+
+      const value = urlParams.get(key);
+      if (value) {
+        params[key as keyof TrackingParams] = value;
+        hasParams = true;
+      }
+    }
+
+    // 파라미터가 있으면 저장
+    if (hasParams) {
+      // 클릭 ID 기반으로 channel 자동 추론 (channel이 없는 경우)
+      if (!params.channel) {
+        if (params.gclid) params.channel = 'google.ads';
+        else if (params.fbclid) params.channel = 'meta.ads';
+        else if (params.ttclid) params.channel = 'tiktok.ads';
+        else if (params.nclid) params.channel = 'naver.searchad';
+        else if (params.liclid) params.channel = 'linkedin.ads';
+        else if (params.msclkid) params.channel = 'microsoft.ads';
+        else if (params.twclid) params.channel = 'twitter.ads';
+      }
+
+      TrackingParamsModule.store(params);
+      return params;
+    }
+
+    return null;
+  }
+
+  /**
+   * 추적 파라미터를 sessionStorage + localStorage에 저장
+   * (SPA 페이지 전환 + 브라우저 재시작 시에도 유지)
+   */
+  public static store(params: TrackingParams): void {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    try {
+      // 기존 파라미터와 병합 (새 파라미터 우선)
+      const existing = TrackingParamsModule.get();
+      const merged = { ...existing, ...params };
+      const json = JSON.stringify(merged);
+
+      try { sessionStorage.setItem(TrackingParamsModule.STORAGE_KEY, json); } catch (_) {}
+      try { localStorage.setItem(TrackingParamsModule.STORAGE_KEY, json); } catch (_) {}
+    } catch (error) {
+      console.warn('Failed to store tracking params:', error);
+    }
+  }
+
+  /**
+   * 저장된 추적 파라미터 반환
+   * 우선순위: sessionStorage (현재 세션) > localStorage (영속 저장)
+   * EventsModule에서 track() 호출 시 사용됨
+   */
+  public static get(): TrackingParams | null {
+    if (typeof window === 'undefined') {
+      return null;
+    }
+
+    try {
+      const fromSession = sessionStorage?.getItem(TrackingParamsModule.STORAGE_KEY);
+      if (fromSession) return JSON.parse(fromSession) as TrackingParams;
+    } catch (_) {}
+
+    try {
+      const fromLocal = localStorage?.getItem(TrackingParamsModule.STORAGE_KEY);
+      if (fromLocal) return JSON.parse(fromLocal) as TrackingParams;
+    } catch (_) {}
+
+    return null;
+  }
+
+  /**
+   * 저장된 추적 파라미터 삭제
+   */
+  public static clear(): void {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    try { sessionStorage?.removeItem(TrackingParamsModule.STORAGE_KEY); } catch (_) {}
+    try { localStorage?.removeItem(TrackingParamsModule.STORAGE_KEY); } catch (_) {}
+  }
+
+  /**
+   * 현재 추적 파라미터 보유 여부 확인
+   */
+  public static hasParams(): boolean {
+    const params = TrackingParamsModule.get();
+    return params !== null && Object.keys(params).length > 0;
+  }
+
+  /**
+   * 특정 클릭 ID 보유 여부 확인
+   * 어트리뷰션이 가능한 상태인지 체크
+   */
+  public static hasClickId(): boolean {
+    const params = TrackingParamsModule.get();
+    if (!params) return false;
+
+    return TrackingParamsModule.CLICK_ID_KEYS.some((key) => params[key as keyof TrackingParams]);
+  }
+
+  /**
+   * Click 이벤트 자동 전송 여부 확인
+   * 새로운 클릭 ID가 발견되면 true 반환
+   */
+  public static shouldSendClickEvent(): boolean {
+    if (typeof window === 'undefined') {
+      return false;
+    }
+
+    const params = TrackingParamsModule.get();
+    if (!params || !TrackingParamsModule.hasClickId()) {
+      return false;
+    }
+
+    // 현재 클릭 ID 추출
+    const currentClickId =
+      params.gclid || params.fbclid || params.ttclid || params.nclid || params.liclid || params.msclkid || params.twclid;
+
+    if (!currentClickId) {
+      return false;
+    }
+
+    // 이미 처리된 클릭 ID인지 확인 (중복 방지)
+    const lastClickId = sessionStorage.getItem('adstage_last_click_id');
+
+    // 새로운 클릭 ID면 전송 필요
+    if (currentClickId !== lastClickId) {
+      sessionStorage.setItem('adstage_last_click_id', currentClickId);
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Click 이벤트 전송 완료 마킹
+   */
+  public static markClickEventSent(): void {
+    if (typeof window === 'undefined') {
+      return;
+    }
+
+    sessionStorage.setItem('adstage_click_event_sent', 'true');
+  }
+
+  /**
+   * Click 이벤트 전송 여부 확인
+   */
+  public static isClickEventSent(): boolean {
+    if (typeof window === 'undefined') {
+      return false;
+    }
+
+    return sessionStorage.getItem('adstage_click_event_sent') === 'true';
+  }
+
+  /**
+   * Event 스키마의 attribution 객체로 변환
+   * EventsModule에서 사용
+   *
+   * 변환 규칙:
+   * - 클릭 ID, channel: 그대로 전달
+   * - 광고 플랫폼 파라미터: snake_case → camelCase 변환 (웹 호환)
+   * - UTM 파라미터: snake_case 그대로 유지 (앱/웹 공통 표준)
+   */
+  public static toAttributionObject(): Record<string, any> | null {
+    const params = TrackingParamsModule.get();
+    if (!params) return null;
+
+    // API Event 스키마의 attribution 필드 형식으로 변환
+    const attribution: Record<string, any> = {};
+
+    // ========== 클릭 ID (플랫폼별 필드) ==========
+    if (params.gclid) attribution.gclid = params.gclid;
+    if (params.fbclid) attribution.fbclid = params.fbclid;
+    if (params.ttclid) attribution.ttclid = params.ttclid;
+    if (params.nclid) attribution.nclid = params.nclid;
+
+    // ========== 채널 정보 ==========
+    if (params.channel) attribution.channel = params.channel;
+
+    // ========== 광고 플랫폼 파라미터 (웹 변환용 - camelCase) ==========
+    // 웹 SDK에서는 utm_campaign을 campaign으로 매핑할 수 있음
+    if (params.campaign) attribution.campaign = params.campaign;
+    if (params.campaign_id) attribution.campaignId = params.campaign_id;
+    if (params.ad_group) attribution.adGroup = params.ad_group;
+    if (params.ad_group_id) attribution.adGroupId = params.ad_group_id;
+    if (params.ad_creative) attribution.adCreative = params.ad_creative;
+    if (params.creative_id) attribution.creativeId = params.creative_id;
+    if (params.term) attribution.term = params.term;
+
+    // ========== UTM 파라미터 (앱/웹 공통 - snake_case 유지) ==========
+    if (params.utm_source) attribution.utm_source = params.utm_source;
+    if (params.utm_medium) attribution.utm_medium = params.utm_medium;
+    if (params.utm_campaign) attribution.utm_campaign = params.utm_campaign;
+    if (params.utm_content) attribution.utm_content = params.utm_content;
+    if (params.utm_term) attribution.utm_term = params.utm_term;
+
+    return Object.keys(attribution).length > 0 ? attribution : null;
+  }
+}

package/src/types/events.ts

@@ -1,7 +1,5 @@
 // 이벤트 및 추적 관련 타입
 export interface SessionInfo {
-  sessionId: string;
-  userId?: string;
   startTime: number;
   lastActivity: number;
   pageViews: number;

package/src/managers/events/event-session-manager.ts

@@ -1,183 +0,0 @@
-/**
- * AdStage SDK - 이벤트용 세션 관리자
- * 세션 ID 생성 및 사용자 ID 관리
- */
-
-import { DOMUtils } from '../../utils/dom-utils';
-
-export class EventSessionManager {
-  private static _userId?: string;
-  private static _sessionStartTime?: number;
-
-  /**
-   * 세션 ID 생성 및 반환 (SSR 안전)
-   */
-  static getSessionId(): string {
-    if (!DOMUtils.isBrowser()) {
-      return 'ssr_session_' + Date.now();
-    }
-    
-    const stored = sessionStorage.getItem('adstage_session_id');
-    if (stored) {
-      return stored;
-    }
-    
-    const sessionId = 'session_' + Math.random().toString(36).substr(2, 9) + '_' + Date.now();
-    sessionStorage.setItem('adstage_session_id', sessionId);
-    
-    // 세션 시작 시간 기록
-    if (!EventSessionManager._sessionStartTime) {
-      EventSessionManager._sessionStartTime = Date.now();
-      if (DOMUtils.isBrowser()) {
-        sessionStorage.setItem('adstage_session_start', String(EventSessionManager._sessionStartTime));
-      }
-    }
-    
-    return sessionId;
-  }
-
-  /**
-   * 사용자 ID 설정
-   */
-  static setUserId(userId: string): void {
-    EventSessionManager._userId = userId;
-    
-    if (DOMUtils.isBrowser()) {
-      localStorage.setItem('adstage_user_id', userId);
-    }
-  }
-
-  /**
-   * 현재 사용자 ID 반환
-   */
-  static getUserId(): string | undefined {
-    // 메모리에 있는 값 우선 반환
-    if (EventSessionManager._userId) {
-      return EventSessionManager._userId;
-    }
-
-    // 로컬 스토리지에서 복원
-    if (DOMUtils.isBrowser()) {
-      const stored = localStorage.getItem('adstage_user_id');
-      if (stored) {
-        EventSessionManager._userId = stored;
-        return stored;
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * 사용자 ID 제거
-   */
-  static clearUserId(): void {
-    EventSessionManager._userId = undefined;
-    
-    if (DOMUtils.isBrowser()) {
-      localStorage.removeItem('adstage_user_id');
-    }
-  }
-
-  /**
-   * 세션 정보 전체 반환
-   */
-  static getSessionInfo(): {
-    sessionId: string;
-    userId?: string;
-    sessionDuration?: number;
-    isNewSession: boolean;
-  } {
-    const sessionId = EventSessionManager.getSessionId();
-    const userId = EventSessionManager.getUserId();
-    const isNewSession = EventSessionManager.isNewSession();
-    const sessionDuration = EventSessionManager.getSessionDuration();
-
-    return {
-      sessionId,
-      userId,
-      sessionDuration,
-      isNewSession
-    };
-  }
-
-  /**
-   * 새 세션인지 확인
-   */
-  static isNewSession(): boolean {
-    if (!DOMUtils.isBrowser()) return true;
-    
-    const sessionId = sessionStorage.getItem('adstage_session_id');
-    const sessionStart = sessionStorage.getItem('adstage_session_start');
-    
-    return !sessionId || !sessionStart;
-  }
-
-  /**
-   * 세션 지속 시간 반환 (ms)
-   */
-  static getSessionDuration(): number {
-    if (!DOMUtils.isBrowser()) return 0;
-    
-    const sessionStart = sessionStorage.getItem('adstage_session_start');
-    if (!sessionStart) return 0;
-    
-    return Date.now() - parseInt(sessionStart, 10);
-  }
-
-  /**
-   * 세션 새로고침 (새로운 세션 ID 생성)
-   */
-  static refreshSession(): string {
-    if (DOMUtils.isBrowser()) {
-      sessionStorage.removeItem('adstage_session_id');
-      sessionStorage.removeItem('adstage_session_start');
-    }
-    
-    EventSessionManager._sessionStartTime = undefined;
-    return EventSessionManager.getSessionId();
-  }
-
-  /**
-   * 세션 만료 확인 (24시간 기준)
-   */
-  static isSessionExpired(maxDurationHours: number = 24): boolean {
-    const duration = EventSessionManager.getSessionDuration();
-    const maxDuration = maxDurationHours * 60 * 60 * 1000; // ms 변환
-    
-    return duration > maxDuration;
-  }
-
-  /**
-   * 세션 통계 반환 (디버깅용)
-   */
-  static getSessionStats(): {
-    sessionId: string;
-    userId?: string;
-    startTime?: number;
-    duration: number;
-    isExpired: boolean;
-    isNewSession: boolean;
-  } {
-    const sessionId = EventSessionManager.getSessionId();
-    const userId = EventSessionManager.getUserId();
-    const duration = EventSessionManager.getSessionDuration();
-    const isExpired = EventSessionManager.isSessionExpired();
-    const isNewSession = EventSessionManager.isNewSession();
-    
-    let startTime: number | undefined;
-    if (DOMUtils.isBrowser()) {
-      const stored = sessionStorage.getItem('adstage_session_start');
-      startTime = stored ? parseInt(stored, 10) : undefined;
-    }
-
-    return {
-      sessionId,
-      userId,
-      startTime,
-      duration,
-      isExpired,
-      isNewSession
-    };
-  }
-}