@adstage/web-sdk 2.6.1 → 2.6.2

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

@@ -0,0 +1,183 @@
+/**
+ * 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
+    };
+  }
+}

package/src/managers/events/event-user-collector.ts

@@ -0,0 +1,166 @@
+/**
+ * AdStage SDK - 이벤트용 사용자 정보 수집기
+ * Events API 스키마에 최적화된 사용자 정보 수집
+ */
+
+import { DOMUtils } from '../../utils/dom-utils';
+
+export class EventUserCollector {
+  private static _userProperties: {
+    gender?: 'male' | 'female' | 'other' | 'unknown';
+    country?: string;
+    city?: string;
+    age?: string;
+    language?: string;
+    [key: string]: any;
+  } = {};
+
+  /**
+   * Events API용 사용자 정보 반환
+   * TrackEventDto.UserAttributesInput 형태에 맞춤
+   */
+  static getUserInfo(): {
+    gender?: 'male' | 'female' | 'other' | 'unknown';
+    country?: string;
+    city?: string;
+    age?: string;
+    language?: string;
+  } {
+    const baseInfo = EventUserCollector.getBaseUserInfo();
+    
+    // 설정된 사용자 속성과 병합
+    return {
+      ...baseInfo,
+      ...EventUserCollector._userProperties
+    };
+  }
+
+  /**
+   * 기본 사용자 정보 수집 (브라우저 기반)
+   */
+  private static getBaseUserInfo(): {
+    language?: string;
+    country?: string;
+  } {
+    if (!DOMUtils.isBrowser()) {
+      return {
+        language: 'ko-KR',
+        country: 'KR'
+      };
+    }
+
+    // 브라우저 언어 설정에서 국가 추출
+    const language = navigator.language || 'ko-KR';
+    const country = EventUserCollector.extractCountryFromLanguage(language);
+
+    return {
+      language,
+      country
+    };
+  }
+
+  /**
+   * 언어 코드에서 국가 추출
+   */
+  private static extractCountryFromLanguage(language: string): string {
+    const countryMap: { [key: string]: string } = {
+      'ko': 'KR',
+      'ko-KR': 'KR',
+      'en': 'US',
+      'en-US': 'US',
+      'en-GB': 'GB',
+      'ja': 'JP',
+      'ja-JP': 'JP',
+      'zh': 'CN',
+      'zh-CN': 'CN',
+      'zh-TW': 'TW',
+      'de': 'DE',
+      'de-DE': 'DE',
+      'fr': 'FR',
+      'fr-FR': 'FR'
+    };
+
+    // 정확한 매칭 시도
+    if (countryMap[language]) {
+      return countryMap[language];
+    }
+
+    // 언어 코드만 추출해서 매칭
+    const langCode = language.split('-')[0];
+    return countryMap[langCode] || 'KR';
+  }
+
+  /**
+   * 사용자 속성 설정
+   */
+  static setUserProperties(properties: {
+    gender?: 'male' | 'female' | 'other' | 'unknown';
+    country?: string;
+    city?: string;
+    age?: string;
+    language?: string;
+    [key: string]: any;
+  }): void {
+    EventUserCollector._userProperties = {
+      ...EventUserCollector._userProperties,
+      ...properties
+    };
+  }
+
+  /**
+   * 특정 사용자 속성 설정
+   */
+  static setUserProperty(key: string, value: any): void {
+    EventUserCollector._userProperties[key] = value;
+  }
+
+  /**
+   * 사용자 속성 초기화
+   */
+  static clearUserProperties(): void {
+    EventUserCollector._userProperties = {};
+  }
+
+  /**
+   * 현재 설정된 사용자 속성 반환
+   */
+  static getCurrentUserProperties(): typeof EventUserCollector._userProperties {
+    return { ...EventUserCollector._userProperties };
+  }
+
+  /**
+   * 사용자 지역 정보 추정 (타임존 기반)
+   */
+  static estimateLocation(): {
+    timezone: string;
+    estimatedCountry?: string;
+  } {
+    if (!DOMUtils.isBrowser()) {
+      return {
+        timezone: 'UTC',
+        estimatedCountry: 'KR'
+      };
+    }
+
+    const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    
+    // 타임존 기반 국가 추정
+    const timezoneCountryMap: { [key: string]: string } = {
+      'Asia/Seoul': 'KR',
+      'Asia/Tokyo': 'JP',
+      'Asia/Shanghai': 'CN',
+      'Asia/Hong_Kong': 'HK',
+      'Asia/Taipei': 'TW',
+      'America/New_York': 'US',
+      'America/Los_Angeles': 'US',
+      'Europe/London': 'GB',
+      'Europe/Berlin': 'DE',
+      'Europe/Paris': 'FR'
+    };
+
+    return {
+      timezone,
+      estimatedCountry: timezoneCountryMap[timezone] || 'KR'
+    };
+  }
+}

package/src/modules/events/events-module.ts

@@ -1,9 +1,14 @@
 /**
- * AdStage SDK - Events 모듈 (기본 구조)
- * 이벤트 추적 시스템 - Q1 2025 구현 예정
+ * AdStage SDK - Events 모듈
+ * 이벤트 추적 시스템
  */
 
 import { AdStageConfig, BaseModule } from '../../types/config';
+import { endpoints } from '../../constants/endpoints';
+import { ApiHeaders } from '../../utils/api-headers';
+import { EventDeviceCollector } from '../../managers/events/event-device-collector';
+import { EventUserCollector } from '../../managers/events/event-user-collector';
+import { EventSessionManager } from '../../managers/events/event-session-manager';
 
 export interface EventProperties {
   [key: string]: any;
@@ -28,7 +33,7 @@ export class EventsModule implements BaseModule {
     this._isReady = true;
 
     if (config.debug) {
-      console.log('📊 Events module initialized (sync mode)');
+      console.log('📊 Events module initialized');
     }
   }
 
@@ -46,61 +51,109 @@ export class EventsModule implements BaseModule {
     return this._config;
   }
 
-  // === 향후 구현 예정 메소드들 ===
-
   /**
-   * 커스텀 이벤트 추적
-   * @example AdStage.events.track('page_view', { page: '/products' })
+   * 사용자 ID 설정
    */
-  async track(eventName: string, properties?: EventProperties): Promise<void> {
-    console.log('🚧 [TODO] Event tracking:', { eventName, properties });
-    // TODO: Q1 2025 구현 예정
+  setUserId(userId: string): void {
+    EventSessionManager.setUserId(userId);
+    
+    if (this._config?.debug) {
+      console.log('👤 User ID set:', userId);
+    }
   }
 
   /**
-   * 페이지 뷰 이벤트
-   * @example AdStage.events.pageView({ page: '/home', title: 'Homepage' })
+   * 현재 사용자 ID 반환
    */
-  async pageView(pageData?: PageData): Promise<void> {
-    console.log('🚧 [TODO] Page view tracking:', pageData);
-    // TODO: Q1 2025 구현 예정
+  getUserId(): string | undefined {
+    return EventSessionManager.getUserId();
   }
 
   /**
-   * 사용자 액션 이벤트
-   * @example AdStage.events.userAction('button_click', { button_id: 'cta' })
+   * 이벤트 추적
+   * @param eventName 이벤트 이름
+   * @param properties 이벤트 속성
    */
-  async userAction(actionType: string, metadata?: EventProperties): Promise<void> {
-    console.log('🚧 [TODO] User action tracking:', { actionType, metadata });
-    // TODO: Q1 2025 구현 예정
+  async track(eventName: string, properties?: EventProperties): Promise<void> {
+    if (!this._isReady) {
+      console.warn('Events module not initialized. Call AdStage.init() first.');
+      return;
+    }
+
+    if (!this._config?.apiKey) {
+      console.warn('API key not configured for event tracking.');
+      return;
+    }
+
+    try {
+      const eventData = {
+        eventName,
+        userId: EventSessionManager.getUserId(),
+        sessionId: EventSessionManager.getSessionId(),
+        device: EventDeviceCollector.getDeviceInfo(),
+        user: EventUserCollector.getUserInfo(),
+        params: properties || {}
+      };
+
+      await this.sendEventToServer(eventData);
+
+      if (this._config.debug) {
+        console.log('✅ Event tracked:', eventName, properties);
+      }
+    } catch (error) {
+      console.error('❌ Failed to track event:', error);
+      
+      if (this._config.debug) {
+        console.error('Event data:', { eventName, properties });
+      }
+    }
   }
 
   /**
-   * 컨버전 이벤트
-   * @example AdStage.events.conversion({ type: 'purchase', value: 99.99 })
+   * 페이지 뷰 이벤트 (track의 편의 메소드)
    */
-  async conversion(conversionData: EventProperties): Promise<void> {
-    console.log('🚧 [TODO] Conversion tracking:', conversionData);
-    // TODO: Q1 2025 구현 예정
+  async pageView(pageData?: PageData): Promise<void> {
+    const properties: EventProperties = {};
+    
+    if (pageData?.page) properties.page = pageData.page;
+    if (pageData?.title) properties.title = pageData.title;
+    if (pageData?.category) properties.category = pageData.category;
+    
+    // pageData의 다른 속성들도 포함
+    if (pageData) {
+      Object.keys(pageData).forEach(key => {
+        if (key !== 'page' && key !== 'title' && key !== 'category') {
+          properties[key] = pageData[key];
+        }
+      });
+    }
+    
+    // 현재 페이지 정보 자동 수집
+    if (typeof window !== 'undefined') {
+      if (!properties.page) properties.page = window.location.pathname;
+      if (!properties.title) properties.title = document.title;
+      properties.url = window.location.href;
+      properties.referrer = document.referrer;
+    }
+
+    await this.track('page_view', properties);
   }
 
-  // === 배치 처리 (향후 구현) ===
-  batch = {
-    start: () => {
-      console.log('🚧 [TODO] Batch events start');
-    },
-    add: (eventName: string, properties: EventProperties) => {
-      console.log('🚧 [TODO] Batch events add:', { eventName, properties });
-    },
-    flush: async () => {
-      console.log('🚧 [TODO] Batch events flush');
-    }
-  };
+  /**
+   * 서버에 이벤트 전송
+   */
+  private async sendEventToServer(eventData: any): Promise<void> {
+    const response = await fetch(endpoints.events.track(), {
+      method: 'POST',
+      headers: {
+        ...ApiHeaders.create(this._config!.apiKey),
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(eventData)
+    });
 
-  // === 실시간 이벤트 (향후 구현) ===
-  realtime = {
-    track: async (eventName: string, properties: EventProperties) => {
-      console.log('🚧 [TODO] Realtime event tracking:', { eventName, properties });
+    if (!response.ok) {
+      throw new Error(`Event tracking failed: ${response.status} ${response.statusText}`);
     }
-  };
+  }
 }

package/src/types/config.ts

@@ -26,6 +26,9 @@ export interface AdStageConfig {
   
   /** 플레이스홀더 스타일 모드 (기본값: 'subtle') */
   placeholderMode?: 'invisible' | 'transparent' | 'subtle' | 'minimal' | 'debug' | 'legacy';
+  
+  /** 고객 앱 버전 (선택사항, 기본값: '1.0.0') */
+  appVersion?: string;
 }
 
 /**

package/src/utils/config-utils.ts

@@ -0,0 +1,69 @@
+/**
+ * AdStage SDK - 설정 유틸리티
+ * 전역 설정에 대한 접근 기능 제공
+ */
+
+import { AdStageConfig } from '../types/config';
+
+export class ConfigUtils {
+  /**
+   * AdStage 전역 설정 반환
+   */
+  static getConfig(): AdStageConfig | null {
+    // AdStage 클래스 동적 임포트로 순환 참조 방지
+    try {
+      const { AdStage } = require('../core/adstage');
+      return AdStage.getConfig();
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 고객 앱 버전 반환
+   */
+  static getAppVersion(): string {
+    const config = ConfigUtils.getConfig();
+    return config?.appVersion || '1.0.0';
+  }
+
+  /**
+   * 디버그 모드 여부 확인
+   */
+  static isDebugMode(): boolean {
+    const config = ConfigUtils.getConfig();
+    return config?.debug || false;
+  }
+
+  /**
+   * API 키 반환
+   */
+  static getApiKey(): string | undefined {
+    const config = ConfigUtils.getConfig();
+    return config?.apiKey;
+  }
+
+  /**
+   * 타임아웃 값 반환
+   */
+  static getTimeout(): number {
+    const config = ConfigUtils.getConfig();
+    return config?.timeout || 30000;
+  }
+
+  /**
+   * 플레이스홀더 모드 반환
+   */
+  static getPlaceholderMode(): 'invisible' | 'transparent' | 'subtle' | 'minimal' | 'debug' | 'legacy' {
+    const config = ConfigUtils.getConfig();
+    return config?.placeholderMode || 'subtle';
+  }
+
+  /**
+   * 활성화된 모듈 목록 반환
+   */
+  static getEnabledModules(): string[] {
+    const config = ConfigUtils.getConfig();
+    return config?.modules || ['ads', 'events', 'config'];
+  }
+}