@adstage/web-sdk 3.0.9 → 3.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "3.0.9",
+  "version": "3.0.11",
   "description": "AdStage Web SDK - Production-ready marketing platform SDK with React Provider support for seamless integration",
   "type": "module",
   "main": "dist/index.cjs.js",

package/src/constants/endpoints.ts

@@ -9,9 +9,9 @@
 export const API_ENDPOINTS = {
   /** 프로덕션 환경 */
   production: 'https://api.adstage.app',
-  
+
   /** 베타 환경 (기본값) */
-  beta: 'https://beta-api.adstage.app'
+  beta: 'https://beta-api.adstage.app',
 } as const;
 
 /**
@@ -27,13 +27,14 @@ export const API_PATHS = {
   advertisements: {
     list: '/advertisements/list',
     detail: '/advertisements',
-    events: '/advertisements/events'
+    events: '/advertisements/events',
   },
-  
+
   /** 이벤트 관련 */
   events: {
     track: '/events/track',
-  }
+    registerAttribution: '/events/register/attribution',
+  },
 } as const;
 
 /**
@@ -67,8 +68,7 @@ export class EndpointBuilder {
   advertisements = {
     list: () => `${this.baseUrl}${API_PATHS.advertisements.list}`,
     detail: (adId: string) => `${this.baseUrl}${API_PATHS.advertisements.detail}/${adId}`,
-    events: (adId: string, eventType: string) => 
-      `${this.baseUrl}${API_PATHS.advertisements.events}/${adId}/${eventType}`
+    events: (adId: string, eventType: string) => `${this.baseUrl}${API_PATHS.advertisements.events}/${adId}/${eventType}`,
   };
 
   /**
@@ -76,6 +76,7 @@ export class EndpointBuilder {
    */
   events = {
     track: () => `${this.baseUrl}${API_PATHS.events.track}`,
+    registerAttribution: () => `${this.baseUrl}${API_PATHS.events.registerAttribution}`,
   };
 
   /**

package/src/core/adstage.ts

@@ -9,12 +9,13 @@ import { ConfigModule } from '../modules/config/config-module';
 import { EventsModule } from '../modules/events/events-module';
 import { ViewableEventTracker } from '../managers/ads/viewable-event-tracker';
 import { endpoints } from '../constants/endpoints';
+import { TrackingParamsModule } from '../modules/tracking/tracking-params';
 
 export class AdStage {
   private static instance: AdStage;
   private _isInitialized = false;
   private _config: AdStageConfig | null = null;
-  
+
   // 모듈 인스턴스들
   public readonly ads: AdsModule;
   public readonly config: ConfigModule;
@@ -36,7 +37,7 @@ export class AdStage {
     }
 
     const instance = AdStage.instance;
-    
+
     // 설정 검증
     if (!config.apiKey) {
       throw new Error('API key is required for AdStage initialization');
@@ -47,7 +48,7 @@ export class AdStage {
       timeout: 30000,
       debug: false,
       modules: ['ads', 'events', 'config'],
-      ...config
+      ...config,
     };
 
     // 🔧 baseUrl이 설정된 경우 전역 endpoints 객체 업데이트
@@ -60,7 +61,7 @@ export class AdStage {
 
     // 모듈 동기 초기화
     const enabledModules = instance._config.modules || ['ads', 'events', 'config'];
-    
+
     for (const moduleName of enabledModules) {
       const module = instance[moduleName as keyof AdStage] as any;
       if (module && typeof module.init === 'function') {
@@ -70,12 +71,151 @@ export class AdStage {
 
     instance._isInitialized = true;
 
+    // 🎯 URL에서 추적 파라미터 자동 추출 (브라우저 환경에만)
+    if (typeof window !== 'undefined') {
+      const trackingParams = TrackingParamsModule.captureFromUrl();
+      if (trackingParams && config.debug) {
+        console.log('📊 Tracking parameters captured:', trackingParams);
+      }
+
+      // 🔎 리다이렉트 단계에서 전달된 attributionId(attribution_id) 우선 사용
+      const aidFromUrl = (() => {
+        try {
+          const search = new URLSearchParams(window.location.search);
+          const hash = new URLSearchParams((window.location.hash || '').replace(/^#/, ''));
+          return search.get('attribution_id') || hash.get('attribution_id');
+        } catch {
+          return null;
+        }
+      })();
+
+      if (aidFromUrl) {
+        try {
+          localStorage.setItem('adstage_attribution_id', aidFromUrl);
+          if (config.debug) {
+            console.log('🔗 Using attributionId from URL (attribution_id):', aidFromUrl);
+          }
+        } catch (_) {
+          // no-op: storage might be unavailable in some contexts
+        }
+      }
+
+      // 🎯 Click 이벤트 자동 전송 (새로운 클릭 ID 발견 시)
+      const shouldSend = TrackingParamsModule.shouldSendClickEvent();
+      if (config.debug) {
+        console.log('🔍 Should send click event:', shouldSend);
+        if (!shouldSend) {
+          console.log('⏭️ Skipping click event (duplicate or no click ID)');
+        }
+      }
+
+      // � 서버에 Attribution 자동 등록 (클릭 ID가 있는 경우, 단 URL로 이미 전달된 경우는 생략)
+      if (!aidFromUrl && trackingParams && TrackingParamsModule.hasClickId()) {
+        // Attribution 등록을 Promise로 처리
+        const attributionPromise = (async () => {
+          try {
+            // Device ID 생성 (브라우저 fingerprint 또는 랜덤)
+            const deviceId = instance.generateDeviceId();
+
+            const attribution = await instance.events.registerAttribution(deviceId);
+
+            if (attribution && config.debug) {
+              console.log('✅ Attribution registered:', {
+                attributionId: attribution.attributionId,
+                channel: attribution.channel,
+                campaign: attribution.campaign,
+                expiresAt: attribution.expiresAt,
+              });
+            }
+
+            return attribution;
+          } catch (err) {
+            console.error('❌ Failed to register attribution:', err);
+            return null;
+          }
+        })();
+
+        // Click 이벤트는 Attribution 등록이 완료된 후에만 전송
+        if (shouldSend) {
+          attributionPromise.then((attribution) => {
+            try {
+              const trackingParams = TrackingParamsModule.get();
+              const attributionObj = TrackingParamsModule.toAttributionObject();
+
+              if (config.debug) {
+                console.log('🎯 Sending click event after attribution registration', {
+                  attributionId: attribution?.attributionId,
+                  hasAttribution: !!attribution,
+                });
+              }
+
+              // Click 이벤트 전송 (추적 파라미터는 EventsModule에서 자동 주입)
+              instance.events
+                .track('click', {
+                  _autoGenerated: true,
+                  _source: 'tracking_params',
+                  _timestamp: new Date().toISOString(),
+                  _platform: 'web',
+                })
+                .then(() => {
+                  TrackingParamsModule.markClickEventSent();
+
+                  if (config.debug) {
+                    console.log('✅ Auto-tracked click event with tracking params:', {
+                      attribution: attributionObj,
+                      trackingParams,
+                    });
+                  }
+                })
+                .catch((err) => {
+                  console.error('❌ Failed to auto-track click event:', err);
+                });
+            } catch (err) {
+              console.error('❌ Error in click event auto-tracking:', err);
+            }
+          });
+        }
+      } else if (shouldSend) {
+        // Attribution 등록이 필요없는 경우 (aidFromUrl이 있거나 클릭 ID가 없음)
+        // 기존 방식대로 Click 이벤트만 전송
+        setTimeout(() => {
+          try {
+            const trackingParams = TrackingParamsModule.get();
+            const attribution = TrackingParamsModule.toAttributionObject();
+
+            instance.events
+              .track('click', {
+                _autoGenerated: true,
+                _source: 'tracking_params',
+                _timestamp: new Date().toISOString(),
+                _platform: 'web',
+              })
+              .then(() => {
+                TrackingParamsModule.markClickEventSent();
+
+                if (config.debug) {
+                  console.log('✅ Auto-tracked click event with tracking params:', {
+                    attribution,
+                    trackingParams,
+                  });
+                }
+              })
+              .catch((err) => {
+                console.error('❌ Failed to auto-track click event:', err);
+              });
+          } catch (err) {
+            console.error('❌ Error in click event auto-tracking:', err);
+          }
+        }, 100);
+      }
+    }
+
     if (config.debug) {
       console.log('🚀 AdStage SDK initialized (sync mode)', {
         version: '2.0.0',
         modules: enabledModules,
         apiKey: config.apiKey.substring(0, 8) + '...',
-        mode: 'development'
+        mode: 'development',
       });
     }
   }
@@ -144,6 +284,46 @@ export class AdStage {
     }
   }
 
+  /**
+   * Device ID 생성 (브라우저 fingerprint 기반)
+   * localStorage에 저장하여 재사용
+   */
+  private generateDeviceId(): string {
+    if (typeof window === 'undefined') {
+      return 'server-' + Math.random().toString(36).substring(2, 15);
+    }
+
+    // 기존 Device ID 확인
+    const existingId = localStorage.getItem('adstage_device_id');
+    if (existingId) {
+      return existingId;
+    }
+
+    // 새 Device ID 생성 (브라우저 fingerprint 기반)
+    const fingerprint = [
+      navigator.userAgent,
+      navigator.language,
+      screen.width + 'x' + screen.height,
+      new Date().getTimezoneOffset(),
+      navigator.hardwareConcurrency || 0,
+    ].join('|');
+
+    // 간단한 해시 생성
+    let hash = 0;
+    for (let i = 0; i < fingerprint.length; i++) {
+      const char = fingerprint.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+
+    const deviceId = 'web-' + Math.abs(hash).toString(36) + '-' + Date.now().toString(36);
+
+    // localStorage에 저장
+    localStorage.setItem('adstage_device_id', deviceId);
+
+    return deviceId;
+  }
+
   /**
    * 디버그용 메서드들
    */
@@ -170,9 +350,9 @@ export class AdStage {
     getViewableStatus: (): void => {
       console.log('📊 AdStage Debug: 현재 viewable 추적 상태', {
         trackedCount: (ViewableEventTracker as any).viewableTracker.size,
-        trackedItems: Array.from((ViewableEventTracker as any).viewableTracker)
+        trackedItems: Array.from((ViewableEventTracker as any).viewableTracker),
       });
-    }
+    },
   };
 }
 

package/src/events/global-events.ts

@@ -10,7 +10,7 @@ import type { EventProperties } from '../modules/events/events-module';
  * 이벤트 추적 (메인 함수)
  * @param eventName 이벤트 이름
  * @param properties 이벤트 속성
- * 
+ *
  * @example
  * track('purchase', {
  *   transaction_id: 'T123',
@@ -23,44 +23,14 @@ export function track(eventName: string, properties?: EventProperties): Promise<
     console.warn('AdStage not initialized. Call AdStage.init() first.');
     return Promise.resolve();
   }
-  
-  return AdStage.events.track(eventName, properties);
-}
-
-
-
-/**
- * 사용자 ID 설정
- * @param userId 사용자 ID
- * 
- * @example
- * setUserId('user123');
- */
-export function setUserId(userId: string): void {
-  if (!AdStage.isReady()) {
-    console.warn('AdStage not initialized. Call AdStage.init() first.');
-    return;
-  }
-  
-  AdStage.events.setUserId(userId);
-}
 
-/**
- * 현재 사용자 ID 반환
- */
-export function getUserId(): string | undefined {
-  if (!AdStage.isReady()) {
-    console.warn('AdStage not initialized. Call AdStage.init() first.');
-    return undefined;
-  }
-  
-  return AdStage.events.getUserId();
+  return AdStage.events.track(eventName, properties);
 }
 
 /**
  * 사용자 속성 설정
  * @param properties 사용자 속성 객체
- * 
+ *
  * @example
  * setUserProperties({
  *   gender: 'male',
@@ -73,7 +43,7 @@ export function setUserProperties(properties: import('../types/events').UserProp
     console.warn('AdStage not initialized. Call AdStage.init() first.');
     return;
   }
-  
+
   AdStage.events.setUserProperties(properties);
 }
 
@@ -85,6 +55,6 @@ export function getUserProperties(): any {
     console.warn('AdStage not initialized. Call AdStage.init() first.');
     return undefined;
   }
-  
+
   return AdStage.events.getUserProperties();
 }

package/src/index.ts

@@ -8,7 +8,7 @@ export { default as AdStage } from './core/adstage';
 import AdStageCore from './core/adstage';
 
 // 전역 이벤트 함수들 (Firebase 스타일)
-export { track, setUserId, getUserId, setUserProperties, getUserProperties } from './events/global-events';
+export { track, setUserProperties, getUserProperties } from './events/global-events';
 
 // React 통합
 export { AdStageProvider, useAdStageContext, useAdStageInstance } from './react';
@@ -19,6 +19,8 @@ export type { AdStageConfig, ModuleName, BaseModule, ApiResponse, OrganizationIn
 // 모듈별 타입
 export type { AdOptions } from './modules/ads/ads-module';
 export type { EventProperties, UserProperties } from './modules/events/events-module';
+export type { TrackingParams } from './modules/tracking/tracking-params';
+export { TrackingParamsModule } from './modules/tracking/tracking-params';
 
 // 광고 관련 타입
 export type { AdType, AdEventType, Advertisement, AdSlot } from './types/advertisement';

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

@@ -9,7 +9,7 @@ import { ApiHeaders } from '../../utils/api-headers';
 import { getSDKVersion } from '../../utils/version';
 import { EventDeviceCollector } from '../../managers/events/event-device-collector';
 import { EventUserCollector } from '../../managers/events/event-user-collector';
-import { EventSessionManager } from '../../managers/events/event-session-manager';
+import { TrackingParamsModule } from '../tracking/tracking-params';
 import type { UserProperties, EventProperties } from '../../types/events';
 
 export type { EventProperties, UserProperties };
@@ -44,30 +44,12 @@ export class EventsModule implements BaseModule {
     return this._config;
   }
 
-  /**
-   * 사용자 ID 설정
-   */
-  setUserId(userId: string): void {
-    EventSessionManager.setUserId(userId);
-    
-    if (this._config?.debug) {
-      console.log('👤 User ID set:', userId);
-    }
-  }
-
-  /**
-   * 현재 사용자 ID 반환
-   */
-  getUserId(): string | undefined {
-    return EventSessionManager.getUserId();
-  }
-
   /**
    * 사용자 속성 설정
    */
   setUserProperties(properties: UserProperties): void {
     EventUserCollector.setUserProperties(properties);
-    
+
     if (this._config?.debug) {
       console.log('👤 User properties set:', properties);
     }
@@ -83,15 +65,17 @@ export class EventsModule implements BaseModule {
   /**
    * 디바이스 정보 설정
    */
-  setDeviceInfo(deviceInfo: Partial<{
-    category: 'mobile' | 'desktop' | 'tablet' | 'other';
-    platform: string;
-    model: string;
-    appVersion: string;
-    osVersion: string;
-  }>): void {
+  setDeviceInfo(
+    deviceInfo: Partial<{
+      category: 'mobile' | 'desktop' | 'tablet' | 'other';
+      platform: string;
+      model: string;
+      appVersion: string;
+      osVersion: string;
+    }>,
+  ): void {
     EventDeviceCollector.setDeviceInfo(deviceInfo);
-    
+
     if (this._config?.debug) {
       console.log('📱 Device info set:', deviceInfo);
     }
@@ -102,7 +86,7 @@ export class EventsModule implements BaseModule {
    */
   setDeviceProperty(key: 'category' | 'platform' | 'model' | 'appVersion' | 'osVersion', value: string): void {
     EventDeviceCollector.setDeviceProperty(key, value);
-    
+
     if (this._config?.debug) {
       console.log('📱 Device property set:', key, value);
     }
@@ -113,7 +97,7 @@ export class EventsModule implements BaseModule {
    */
   clearDeviceInfo(): void {
     EventDeviceCollector.clearDeviceInfo();
-    
+
     if (this._config?.debug) {
       console.log('📱 User provided device info cleared');
     }
@@ -164,47 +148,209 @@ export class EventsModule implements BaseModule {
     }
 
     try {
+      // 🆔 저장된 Attribution ID 확인
+      const attributionId = this.getAttributionId();
+
+      // Attribution ID가 있으면 서버에서 조회하도록 전달
+      if (attributionId) {
+        const eventData = {
+          eventName,
+          sdkVersion: getSDKVersion(),
+          device: EventDeviceCollector.getDeviceInfo(),
+          user: EventUserCollector.getUserInfo(),
+          attributionId, // 서버가 이 ID로 attribution 조회
+          params: properties || {},
+        };
+
+        await this.sendEventToServer(eventData);
+
+        if (this._config.debug) {
+          console.log('✅ Event tracked with attribution ID:', eventName, attributionId);
+        }
+        return;
+      }
+
+      // Attribution ID가 없으면 기존 방식 (URL 파라미터 직접 전달)
+      const trackingParams = TrackingParamsModule.toAttributionObject();
+
       const eventData = {
         eventName,
-        userId: EventSessionManager.getUserId(),
-        sessionId: EventSessionManager.getSessionId(),
         sdkVersion: getSDKVersion(),
         device: EventDeviceCollector.getDeviceInfo(),
         user: EventUserCollector.getUserInfo(),
-        params: properties || {}
+
+        // attribution 필드에 추적 파라미터 자동 포함
+        ...(trackingParams && { attribution: trackingParams }),
+
+        params: properties || {},
       };
 
       await this.sendEventToServer(eventData);
 
       if (this._config.debug) {
         console.log('✅ Event tracked:', eventName, properties);
+        if (trackingParams) {
+          console.log('📊 Attribution included:', trackingParams);
+        }
       }
     } catch (error) {
       console.error('❌ Failed to track event:', error);
-      
+
       if (this._config.debug) {
         console.error('Event data:', { eventName, properties });
       }
     }
   }
 
+  /**
+   * Attribution 등록 (서버 기반 Attribution ID 패턴)
+   *
+   * 사용 사례:
+   * 1. 앱 설치 시 Install Referrer 전송
+   * 2. 웹 첫 방문 시 URL 파라미터 전송
+   *
+   * @param deviceId 디바이스 고유 ID
+   * @returns Attribution ID 및 파싱된 정보
+   */
+  async registerAttribution(deviceId: string): Promise<{
+    attributionId: string;
+    channel: string;
+    campaign?: string;
+    attribution: Record<string, any>;
+    installedAt: Date;
+    expiresAt: Date;
+  } | null> {
+    if (!this._isReady) {
+      console.warn('Events module not initialized. Call AdStage.init() first.');
+      return null;
+    }
+
+    if (!this._config?.apiKey) {
+      console.warn('API key not configured for attribution registration.');
+      return null;
+    }
+
+    try {
+      // 현재 URL의 추적 파라미터 가져오기
+      const trackingParams = TrackingParamsModule.get();
+
+      if (!trackingParams || Object.keys(trackingParams).length === 0) {
+        if (this._config.debug) {
+          console.log('⏭️ No tracking parameters found, skipping attribution registration');
+        }
+        return null;
+      }
+
+      // 서버에 Attribution 등록
+      const response = await this.sendAttributionToServer({
+        deviceId,
+        referrerParams: trackingParams,
+      });
+
+      if (this._config.debug) {
+        console.log('✅ Attribution registered:', response);
+      }
+
+      // Attribution ID를 localStorage + sessionStorage에 저장 (세션 종료 후에도 유지)
+      if (response.attributionId) {
+        try { localStorage.setItem('adstage_attribution_id', response.attributionId); } catch (_) {}
+        try { sessionStorage.setItem('adstage_attribution_id', response.attributionId); } catch (_) {}
+      }
+
+      return response;
+    } catch (error) {
+      console.error('❌ Failed to register attribution:', error);
+      return null;
+    }
+  }
+
+  /**
+   * 저장된 Attribution ID 반환
+   * 우선순위: sessionStorage (현재 세션) > localStorage (영속 저장)
+   */
+  getAttributionId(): string | null {
+    if (typeof window === 'undefined') {
+      return null;
+    }
+
+    try {
+      const fromSession = sessionStorage.getItem('adstage_attribution_id');
+      if (fromSession) return fromSession;
+    } catch (_) {}
 
+    try {
+      return localStorage.getItem('adstage_attribution_id');
+    } catch (_) {}
+
+    return null;
+  }
+
+  /**
+   * Attribution ID로 이벤트 전송 (별칭 메서드)
+   * track() 메서드가 자동으로 Attribution ID를 사용하므로 동일하게 동작
+   * @param eventName 이벤트 이름
+   * @param properties 이벤트 속성
+   */
+  async trackWithAttributionId(eventName: string, properties?: EventProperties): Promise<void> {
+    // track() 메서드로 위임 (자동으로 Attribution ID 사용)
+    return this.track(eventName, properties);
+  }
 
   /**
    * 서버에 이벤트 전송
    */
   private async sendEventToServer(eventData: any): Promise<void> {
+    const headers = {
+      ...ApiHeaders.create(this._config!.apiKey),
+      'Content-Type': 'application/json',
+    };
+
+    if (this._config?.debug) {
+      console.log('🔑 Request headers:', headers);
+      console.log('📡 Request URL:', endpoints.events.track());
+      console.log('📦 Request body:', eventData);
+    }
+
     const response = await fetch(endpoints.events.track(), {
       method: 'POST',
-      headers: {
-        ...ApiHeaders.create(this._config!.apiKey),
-        'Content-Type': 'application/json'
-      },
-      body: JSON.stringify(eventData)
+      headers,
+      body: JSON.stringify(eventData),
     });
 
     if (!response.ok) {
+      const errorText = await response.text();
+      console.error('❌ API Error Response:', errorText);
       throw new Error(`Event tracking failed: ${response.status} ${response.statusText}`);
     }
   }
+
+  /**
+   * 서버에 Attribution 등록
+   */
+  private async sendAttributionToServer(data: { deviceId: string; referrerParams: Record<string, any> }): Promise<any> {
+    const headers = {
+      ...ApiHeaders.create(this._config!.apiKey),
+      'Content-Type': 'application/json',
+    };
+
+    if (this._config?.debug) {
+      console.log('🔑 Attribution request headers:', headers);
+      console.log('📡 Attribution request URL:', endpoints.events.registerAttribution());
+      console.log('📦 Attribution request body:', data);
+    }
+
+    const response = await fetch(endpoints.events.registerAttribution(), {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(data),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      console.error('❌ API Error Response:', errorText);
+      throw new Error(`Attribution registration failed: ${response.status} ${response.statusText}`);
+    }
+
+    return response.json();
+  }
 }