@adstage/web-sdk 2.6.1 → 2.6.3

package/dist/index.esm.js

@@ -317,6 +317,80 @@ class DOMUtils {
     }
 }
 
+/**
+ * AdStage SDK - 버전 정보 유틸리티
+ */
+// package.json에서 버전 정보 가져오기 (빌드 시 자동으로 교체됨)
+const SDK_VERSION$1 = '"2.6.3"';
+/**
+ * SDK 버전 정보 반환
+ */
+function getSDKVersion() {
+    return SDK_VERSION$1;
+}
+
+/**
+ * AdStage SDK - 설정 유틸리티
+ * 전역 설정에 대한 접근 기능 제공
+ */
+class ConfigUtils {
+    /**
+     * AdStage 전역 설정 반환
+     */
+    static getConfig() {
+        // AdStage 클래스 동적 임포트로 순환 참조 방지
+        try {
+            const { AdStage } = require('../core/adstage');
+            return AdStage.getConfig();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 고객 앱 버전 반환
+     */
+    static getAppVersion() {
+        const config = ConfigUtils.getConfig();
+        return config?.appVersion || '1.0.0';
+    }
+    /**
+     * 디버그 모드 여부 확인
+     */
+    static isDebugMode() {
+        const config = ConfigUtils.getConfig();
+        return config?.debug || false;
+    }
+    /**
+     * API 키 반환
+     */
+    static getApiKey() {
+        const config = ConfigUtils.getConfig();
+        return config?.apiKey;
+    }
+    /**
+     * 타임아웃 값 반환
+     */
+    static getTimeout() {
+        const config = ConfigUtils.getConfig();
+        return config?.timeout || 30000;
+    }
+    /**
+     * 플레이스홀더 모드 반환
+     */
+    static getPlaceholderMode() {
+        const config = ConfigUtils.getConfig();
+        return config?.placeholderMode || 'subtle';
+    }
+    /**
+     * 활성화된 모듈 목록 반환
+     */
+    static getEnabledModules() {
+        const config = ConfigUtils.getConfig();
+        return config?.modules || ['ads', 'events', 'config'];
+    }
+}
+
 /**
  * 디바이스 정보 수집 클래스
  * - 브라우저 환경 정보 수집
@@ -351,15 +425,19 @@ class DeviceInfoCollector {
         return sessionId;
     }
     /**
-     * 모바일 디바이스 여부 확인
+     * 모바일 디바이스 여부 확인 (SSR 안전)
      */
     static isMobile() {
+        if (!DOMUtils.isBrowser())
+            return false;
         return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
     }
     /**
-     * 플랫폼 타입 반환 (서버 enum에 맞춤)
+     * 플랫폼 타입 반환 (서버 enum에 맞춤, SSR 안전)
      */
     static getPlatform() {
+        if (!DOMUtils.isBrowser())
+            return 'web';
         const userAgent = navigator.userAgent.toLowerCase();
         if (/iphone|ipad|ipod/.test(userAgent)) {
             return 'ios';
@@ -382,8 +460,8 @@ class DeviceInfoCollector {
             sessionId: DeviceInfoCollector.generateSessionId(),
             osVersion: DOMUtils.isBrowser() ? navigator.platform : 'SSR',
             deviceModel: DOMUtils.isBrowser() ? navigator.platform : 'SSR',
-            appVersion: '1.0.0',
-            sdkVersion: '1.0.0',
+            appVersion: ConfigUtils.getAppVersion(), // AdStage.init()에서 설정 또는 기본값 '1.0.0'
+            sdkVersion: getSDKVersion(), // package.json에서 동적 로드
             language: DOMUtils.isBrowser() ? (navigator.language || 'ko') : 'ko',
             country: 'KR', // 기본값
             ipAddress: '', // 서버에서 자동으로 설정됨
@@ -452,18 +530,6 @@ class ApiHeaders {
     }
 }
 
-/**
- * AdStage SDK - 버전 정보 유틸리티
- */
-// package.json에서 버전 정보 가져오기 (빌드 시 자동으로 교체됨)
-const SDK_VERSION$1 = '"2.6.1"';
-/**
- * SDK 버전 정보 반환
- */
-function getSDKVersion() {
-    return SDK_VERSION$1;
-}
-
 /**
  * 광고 이벤트 추적 관리 클래스
  * - 광고 전용 이벤트 추적 및 전송
@@ -655,7 +721,6 @@ const API_PATHS = {
     /** 이벤트 관련 */
     events: {
         track: '/events/track',
-        batch: '/events/batch'
     }
 };
 /**
@@ -676,7 +741,6 @@ class EndpointBuilder {
          */
         this.events = {
             track: () => `${this.baseUrl}${API_PATHS.events.track}`,
-            batch: () => `${this.baseUrl}${API_PATHS.events.batch}`
         };
         // 기본값은 베타 환경 사용
         this.baseUrl = baseUrl || API_ENDPOINTS.production;
@@ -3866,31 +3930,358 @@ class ConfigModule {
 }
 
 /**
- * AdStage SDK - Events 모듈 (기본 구조)
- * 이벤트 추적 시스템 - Q1 2025 구현 예정
+ * AdStage SDK - 이벤트용 디바이스 정보 수집기
+ * Events API 스키마에 최적화된 디바이스 정보 수집
+ * DeviceInfoCollector를 재사용하여 중복 제거
+ */
+class EventDeviceCollector {
+    /**
+     * Events API용 디바이스 정보 반환
+     * TrackEventDto.DeviceInfoInput 형태에 맞춤
+     */
+    static getDeviceInfo() {
+        if (!DOMUtils.isBrowser()) {
+            return {
+                category: 'other',
+                platform: 'SSR',
+                model: 'SSR',
+                appVersion: ConfigUtils.getAppVersion(), // AdStage.init()에서 설정 또는 기본값 '1.0.0'
+                osVersion: 'SSR'
+            };
+        }
+        const userAgent = navigator.userAgent.toLowerCase();
+        let category = 'desktop';
+        // 디바이스 카테고리 판별 (DeviceInfoCollector 재사용)
+        if (/tablet|ipad/.test(userAgent)) {
+            category = 'tablet';
+        }
+        else if (DeviceInfoCollector.isMobile()) {
+            category = 'mobile';
+        }
+        // 플랫폼 정보 매핑 (Events API용)
+        const platformType = DeviceInfoCollector.getPlatform();
+        const platformString = EventDeviceCollector.mapPlatformForEvents(platformType);
+        return {
+            category,
+            platform: platformString,
+            model: navigator.platform,
+            appVersion: ConfigUtils.getAppVersion(), // AdStage.init()에서 설정 또는 기본값 '1.0.0'
+            osVersion: navigator.platform
+        };
+    }
+    /**
+     * 플랫폼 타입을 Events API용 문자열로 매핑
+     */
+    static mapPlatformForEvents(platformType) {
+        switch (platformType) {
+            case 'ios': return 'ios';
+            case 'android': return 'android';
+            case 'web': return 'mobile-web';
+            case 'desktop': return 'desktop-web';
+            default: return 'unknown';
+        }
+    }
+    /**
+     * 디바이스 상세 정보 (디버깅용)
+     */
+    static getDetailedInfo() {
+        if (!DOMUtils.isBrowser()) {
+            return {
+                userAgent: 'SSR',
+                language: 'ko-KR',
+                platform: 'SSR',
+                cookieEnabled: false,
+                onLine: true,
+                screenResolution: '0x0',
+                viewportSize: '0x0'
+            };
+        }
+        const viewportInfo = DOMUtils.getViewportInfo();
+        return {
+            userAgent: navigator.userAgent,
+            language: navigator.language || 'ko-KR',
+            platform: navigator.platform,
+            cookieEnabled: navigator.cookieEnabled,
+            onLine: navigator.onLine,
+            screenResolution: `${screen.width}x${screen.height}`,
+            viewportSize: `${viewportInfo.width}x${viewportInfo.height}`
+        };
+    }
+}
+
+/**
+ * AdStage SDK - 이벤트용 사용자 정보 수집기
+ * Events API 스키마에 최적화된 사용자 정보 수집
+ */
+class EventUserCollector {
+    /**
+     * Events API용 사용자 정보 반환
+     * TrackEventDto.UserAttributesInput 형태에 맞춤
+     */
+    static getUserInfo() {
+        const baseInfo = EventUserCollector.getBaseUserInfo();
+        // 설정된 사용자 속성과 병합
+        return {
+            ...baseInfo,
+            ...EventUserCollector._userProperties
+        };
+    }
+    /**
+     * 기본 사용자 정보 수집 (브라우저 기반)
+     */
+    static getBaseUserInfo() {
+        if (!DOMUtils.isBrowser()) {
+            return {
+                language: 'ko-KR',
+                country: 'KR'
+            };
+        }
+        // 브라우저 언어 설정에서 국가 추출
+        const language = navigator.language || 'ko-KR';
+        const country = EventUserCollector.extractCountryFromLanguage(language);
+        return {
+            language,
+            country
+        };
+    }
+    /**
+     * 언어 코드에서 국가 추출
+     */
+    static extractCountryFromLanguage(language) {
+        const countryMap = {
+            '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) {
+        EventUserCollector._userProperties = {
+            ...EventUserCollector._userProperties,
+            ...properties
+        };
+    }
+    /**
+     * 특정 사용자 속성 설정
+     */
+    static setUserProperty(key, value) {
+        EventUserCollector._userProperties[key] = value;
+    }
+    /**
+     * 사용자 속성 초기화
+     */
+    static clearUserProperties() {
+        EventUserCollector._userProperties = {};
+    }
+    /**
+     * 현재 설정된 사용자 속성 반환
+     */
+    static getCurrentUserProperties() {
+        return { ...EventUserCollector._userProperties };
+    }
+    /**
+     * 사용자 지역 정보 추정 (타임존 기반)
+     */
+    static estimateLocation() {
+        if (!DOMUtils.isBrowser()) {
+            return {
+                timezone: 'UTC',
+                estimatedCountry: 'KR'
+            };
+        }
+        const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        // 타임존 기반 국가 추정
+        const timezoneCountryMap = {
+            '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'
+        };
+    }
+}
+EventUserCollector._userProperties = {};
+
+/**
+ * AdStage SDK - 이벤트용 세션 관리자
+ * 세션 ID 생성 및 사용자 ID 관리
+ */
+class EventSessionManager {
+    /**
+     * 세션 ID 생성 및 반환 (SSR 안전)
+     */
+    static getSessionId() {
+        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) {
+        EventSessionManager._userId = userId;
+        if (DOMUtils.isBrowser()) {
+            localStorage.setItem('adstage_user_id', userId);
+        }
+    }
+    /**
+     * 현재 사용자 ID 반환
+     */
+    static getUserId() {
+        // 메모리에 있는 값 우선 반환
+        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() {
+        EventSessionManager._userId = undefined;
+        if (DOMUtils.isBrowser()) {
+            localStorage.removeItem('adstage_user_id');
+        }
+    }
+    /**
+     * 세션 정보 전체 반환
+     */
+    static getSessionInfo() {
+        const sessionId = EventSessionManager.getSessionId();
+        const userId = EventSessionManager.getUserId();
+        const isNewSession = EventSessionManager.isNewSession();
+        const sessionDuration = EventSessionManager.getSessionDuration();
+        return {
+            sessionId,
+            userId,
+            sessionDuration,
+            isNewSession
+        };
+    }
+    /**
+     * 새 세션인지 확인
+     */
+    static isNewSession() {
+        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() {
+        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() {
+        if (DOMUtils.isBrowser()) {
+            sessionStorage.removeItem('adstage_session_id');
+            sessionStorage.removeItem('adstage_session_start');
+        }
+        EventSessionManager._sessionStartTime = undefined;
+        return EventSessionManager.getSessionId();
+    }
+    /**
+     * 세션 만료 확인 (24시간 기준)
+     */
+    static isSessionExpired(maxDurationHours = 24) {
+        const duration = EventSessionManager.getSessionDuration();
+        const maxDuration = maxDurationHours * 60 * 60 * 1000; // ms 변환
+        return duration > maxDuration;
+    }
+    /**
+     * 세션 통계 반환 (디버깅용)
+     */
+    static getSessionStats() {
+        const sessionId = EventSessionManager.getSessionId();
+        const userId = EventSessionManager.getUserId();
+        const duration = EventSessionManager.getSessionDuration();
+        const isExpired = EventSessionManager.isSessionExpired();
+        const isNewSession = EventSessionManager.isNewSession();
+        let startTime;
+        if (DOMUtils.isBrowser()) {
+            const stored = sessionStorage.getItem('adstage_session_start');
+            startTime = stored ? parseInt(stored, 10) : undefined;
+        }
+        return {
+            sessionId,
+            userId,
+            startTime,
+            duration,
+            isExpired,
+            isNewSession
+        };
+    }
+}
+
+/**
+ * AdStage SDK - Events 모듈
+ * 이벤트 추적 시스템
  */
 class EventsModule {
     constructor() {
         this._isReady = false;
         this._config = null;
-        // === 배치 처리 (향후 구현) ===
-        this.batch = {
-            start: () => {
-                console.log('🚧 [TODO] Batch events start');
-            },
-            add: (eventName, properties) => {
-                console.log('🚧 [TODO] Batch events add:', { eventName, properties });
-            },
-            flush: async () => {
-                console.log('🚧 [TODO] Batch events flush');
-            }
-        };
-        // === 실시간 이벤트 (향후 구현) ===
-        this.realtime = {
-            track: async (eventName, properties) => {
-                console.log('🚧 [TODO] Realtime event tracking:', { eventName, properties });
-            }
-        };
     }
     /**
      * Events 모듈 초기화 (동기)
@@ -3899,7 +4290,7 @@ class EventsModule {
         this._config = config;
         this._isReady = true;
         if (config.debug) {
-            console.log('📊 Events module initialized (sync mode)');
+            console.log('📊 Events module initialized');
         }
     }
     /**
@@ -3914,38 +4305,116 @@ class EventsModule {
     getConfig() {
         return this._config;
     }
-    // === 향후 구현 예정 메소드들 ===
     /**
-     * 커스텀 이벤트 추적
-     * @example AdStage.events.track('page_view', { page: '/products' })
+     * 사용자 ID 설정
      */
-    async track(eventName, properties) {
-        console.log('🚧 [TODO] Event tracking:', { eventName, properties });
-        // TODO: Q1 2025 구현 예정
+    setUserId(userId) {
+        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) {
-        console.log('🚧 [TODO] Page view tracking:', pageData);
-        // TODO: Q1 2025 구현 예정
+    getUserId() {
+        return EventSessionManager.getUserId();
+    }
+    /**
+     * 사용자 속성 설정
+     */
+    setUserProperties(properties) {
+        EventUserCollector.setUserProperties(properties);
+        if (this._config?.debug) {
+            console.log('👤 User properties set:', properties);
+        }
+    }
+    /**
+     * 현재 사용자 속성 반환
+     */
+    getUserProperties() {
+        return EventUserCollector.getCurrentUserProperties();
+    }
+    /**
+     * 이벤트 추적
+     * @param eventName 이벤트 이름
+     * @param properties 이벤트 속성
+     */
+    async track(eventName, properties) {
+        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.userAction('button_click', { button_id: 'cta' })
+     * 페이지 뷰 이벤트 (track의 편의 메소드)
      */
-    async userAction(actionType, metadata) {
-        console.log('🚧 [TODO] User action tracking:', { actionType, metadata });
-        // TODO: Q1 2025 구현 예정
+    async pageView(pageData) {
+        const properties = {};
+        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);
     }
     /**
-     * 컨버전 이벤트
-     * @example AdStage.events.conversion({ type: 'purchase', value: 99.99 })
+     * 서버에 이벤트 전송
      */
-    async conversion(conversionData) {
-        console.log('🚧 [TODO] Conversion tracking:', conversionData);
-        // TODO: Q1 2025 구현 예정
+    async sendEventToServer(eventData) {
+        const response = await fetch(endpoints.events.track(), {
+            method: 'POST',
+            headers: {
+                ...ApiHeaders.create(this._config.apiKey),
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(eventData)
+        });
+        if (!response.ok) {
+            throw new Error(`Event tracking failed: ${response.status} ${response.statusText}`);
+        }
     }
 }
 
@@ -4078,6 +4547,68 @@ AdStage.debug = {
     }
 };
 
+/**
+ * AdStage SDK - 전역 이벤트 함수들
+ * Firebase Analytics와 유사한 간단한 API 제공
+ */
+/**
+ * 이벤트 추적 (메인 함수)
+ * @param eventName 이벤트 이름
+ * @param properties 이벤트 속성
+ *
+ * @example
+ * track('purchase', {
+ *   transaction_id: 'T123',
+ *   value: 99.99,
+ *   currency: 'USD'
+ * });
+ */
+function track(eventName, properties) {
+    if (!AdStage.isReady()) {
+        console.warn('AdStage not initialized. Call AdStage.init() first.');
+        return Promise.resolve();
+    }
+    return AdStage.events.track(eventName, properties);
+}
+/**
+ * 페이지 뷰 추적
+ * @param pageData 페이지 정보
+ *
+ * @example
+ * pageView({ page: '/products', title: 'Products Page' });
+ */
+function pageView(pageData) {
+    if (!AdStage.isReady()) {
+        console.warn('AdStage not initialized. Call AdStage.init() first.');
+        return Promise.resolve();
+    }
+    return AdStage.events.pageView(pageData);
+}
+/**
+ * 사용자 ID 설정
+ * @param userId 사용자 ID
+ *
+ * @example
+ * setUserId('user123');
+ */
+function setUserId(userId) {
+    if (!AdStage.isReady()) {
+        console.warn('AdStage not initialized. Call AdStage.init() first.');
+        return;
+    }
+    AdStage.events.setUserId(userId);
+}
+/**
+ * 현재 사용자 ID 반환
+ */
+function getUserId() {
+    if (!AdStage.isReady()) {
+        console.warn('AdStage not initialized. Call AdStage.init() first.');
+        return undefined;
+    }
+    return AdStage.events.getUserId();
+}
+
 const AdStageContext = createContext(null);
 function AdStageProvider({ children, config }) {
     const [isInitialized, setIsInitialized] = useState(false);
@@ -4168,4 +4699,4 @@ if (typeof window !== 'undefined') {
     window.AdStage = AdStage;
 }
 
-export { AdStage, AdStageProvider, SDK_VERSION, SUPPORTED_MODULES, useAdStageContext, useAdStageInstance };
+export { AdStage, AdStageProvider, SDK_VERSION, SUPPORTED_MODULES, getUserId, pageView, setUserId, track, useAdStageContext, useAdStageInstance };