@adstage/web-sdk 1.3.4 → 2.0.0

package/src/modules/ads/AdsModule.ts

@@ -0,0 +1,525 @@
+/**
+ * AdStage SDK - Ads 모듈
+ * 광고 관리 및 렌더링 기능
+ */
+
+import { AdStageConfig, BaseModule } from '../../types/config';
+import { AdType, AdEventType } from '../../types/advertisement';
+import type { AdSlot, Advertisement } from '../../types/advertisement';
+import { CarouselSliderManager } from '../../managers/carousel-slider-manager';
+import { TextTransitionManager } from '../../managers/text-transition-manager';
+import { ImpressionTracker } from '../../managers/impression-tracker';
+import { EventTracker } from '../../managers/event-tracker';
+import { endpoints } from '../../constants/endpoints';
+import { ApiHeaders } from '../../utils/api-headers';
+
+export interface AdOptions {
+  width?: string | number;
+  height?: number;
+  autoSlide?: boolean;
+  slideInterval?: number;
+  maxLines?: number;
+  style?: string;
+  autoplay?: boolean;
+  muted?: boolean;
+  onClick?: (adData: any) => void;
+}
+
+export class AdsModule implements BaseModule {
+  private _isReady = false;
+  private _config: AdStageConfig | null = null;
+  private slots = new Map<string, AdSlot>();
+  private eventTracker: EventTracker | null = null;
+
+  /**
+   * Ads 모듈 초기화 (동기)
+   */
+  init(config: AdStageConfig): void {
+    this._config = config;
+    
+    // EventTracker 초기화 (환경 자동 감지된 엔드포인트 사용)
+    this.eventTracker = new EventTracker(
+      endpoints.getBaseUrl(),
+      config.apiKey,
+      config.debug || false,
+      this.slots
+    );
+
+    this._isReady = true;
+
+    if (config.debug) {
+      console.log('🎯 Ads module initialized (sync mode)');
+    }
+  }
+
+  /**
+   * 모듈 준비 상태 확인
+   */
+  isReady(): boolean {
+    return this._isReady;
+  }
+
+  /**
+   * 모듈 설정 반환
+   */
+  getConfig(): AdStageConfig | null {
+    return this._config;
+  }
+
+  /**
+   * 배너 광고 생성 (동기)
+   */
+  banner(containerId: string, options?: AdOptions): string {
+    this.ensureReady();
+    
+    const adstageOptions = {
+      width: options?.width || '100%',
+      height: options?.height || 250,
+      autoSlide: options?.autoSlide || false,
+      slideInterval: options?.slideInterval || 5000,
+      onClick: options?.onClick
+    };
+
+    return this.createAd(containerId, AdType.BANNER, adstageOptions);
+  }
+
+  /**
+   * 텍스트 광고 생성 (동기)
+   */
+  text(containerId: string, options?: AdOptions): string {
+    this.ensureReady();
+    
+    const adstageOptions = {
+      maxLines: options?.maxLines || 3,
+      style: options?.style || 'default',
+      onClick: options?.onClick
+    };
+
+    return this.createAd(containerId, AdType.TEXT, adstageOptions);
+  }
+
+  /**
+   * 비디오 광고 생성 (동기)
+   */
+  video(containerId: string, options?: AdOptions): string {
+    this.ensureReady();
+    
+    const adstageOptions = {
+      width: options?.width || 640,
+      height: options?.height || 360,
+      autoplay: options?.autoplay || false,
+      muted: options?.muted || true,
+      onClick: options?.onClick
+    };
+
+    return this.createAd(containerId, AdType.VIDEO, adstageOptions);
+  }
+
+  /**
+   * 네이티브 광고 생성 (동기)
+   */
+  native(containerId: string, options?: AdOptions): string {
+    this.ensureReady();
+    
+    return this.createAd(containerId, AdType.NATIVE, options || {});
+  }
+
+  /**
+   * 전면 광고 생성 (동기)
+   */
+  interstitial(containerId: string, options?: AdOptions): string {
+    this.ensureReady();
+    
+    return this.createAd(containerId, AdType.INTERSTITIAL, options || {});
+  }
+
+  /**
+   * 광고 새로고침
+   */
+  refresh(slotId: string): void {
+    this.ensureReady();
+    
+    const slot = this.slots.get(slotId);
+    if (!slot) {
+      throw new Error(`Ad slot not found: ${slotId}`);
+    }
+
+    // 광고 새로고침 로직
+    this.refreshAdSlot(slot);
+
+    if (this._config?.debug) {
+      console.log(`🔄 Ad slot refreshed: ${slotId}`);
+    }
+  }
+
+  /**
+   * 광고 제거
+   */
+  destroy(slotId: string): void {
+    this.ensureReady();
+    
+    const slot = this.slots.get(slotId);
+    if (!slot) {
+      throw new Error(`Ad slot not found: ${slotId}`);
+    }
+
+    // DOM에서 제거
+    const container = document.getElementById(slot.containerId);
+    if (container) {
+      container.innerHTML = '';
+    }
+
+    // 슬롯 제거
+    this.slots.delete(slotId);
+
+    if (this._config?.debug) {
+      console.log(`🗑️ Ad slot destroyed: ${slotId}`);
+    }
+  }
+
+  /**
+   * 모든 광고 슬롯 반환
+   */
+  getAllSlots(): AdSlot[] {
+    this.ensureReady();
+    return Array.from(this.slots.values());
+  }
+
+  /**
+   * 특정 광고 슬롯 반환
+   */
+  getSlotById(slotId: string): AdSlot | null {
+    this.ensureReady();
+    return this.slots.get(slotId) || null;
+  }
+
+  /**
+   * 광고 생성 내부 메소드 (동기 + Lazy 로딩)
+   */
+  private createAd(containerId: string, type: AdType, options: any): string {
+    if (!this._config?.apiKey) {
+      throw new Error('API key not configured');
+    }
+
+    const container = document.getElementById(containerId);
+    if (!container) {
+      throw new Error(`Container not found: ${containerId}`);
+    }
+
+    // 고유한 슬롯 ID 생성
+    const slotId = `adstage-${type}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+    // 즉시 placeholder 생성
+    this.createAdSlot(container, slotId, type, options);
+
+    // 광고 슬롯 정보 저장
+    const slot: AdSlot = {
+      id: slotId,
+      containerId,
+      adType: type,
+      width: options.width || '100%',
+      height: options.height || 250,
+      isLoaded: false,
+      isVisible: false,
+      refreshRate: 0,
+      lazyLoad: false,
+      targeting: {},
+      advertisement: undefined, // 나중에 로드
+      config: { type, ...options },
+      load: async () => this.fetchAdData(type, options).then(ads => ads[0] || null),
+      render: (ad: Advertisement) => this.renderAdElement(slot, ad),
+      refresh: async () => this.refreshAdSlot(slot),
+      destroy: () => this.destroy(slotId)
+    };
+
+    // 슬롯 저장
+    this.slots.set(slotId, slot);
+
+    // 백그라운드에서 광고 로드
+    this.loadAdContentInBackground(slot);
+
+    // 이벤트 추적 준비
+    if (this.eventTracker && this._config?.debug) {
+      console.log(`📊 Event tracking enabled for slot: ${slotId}`);
+    }
+
+    return slotId;
+  }
+
+  /**
+   * 즉시 광고 슬롯 생성 (placeholder)
+   */
+  private createAdSlot(container: HTMLElement, slotId: string, type: AdType, options: any): void {
+    const adElement = document.createElement('div');
+    adElement.id = slotId;
+    adElement.className = `adstage-slot adstage-${type.toLowerCase()}`;
+    adElement.style.width = typeof options.width === 'number' ? `${options.width}px` : (options.width || '100%');
+    adElement.style.height = typeof options.height === 'number' ? `${options.height}px` : (options.height || '250px');
+    adElement.style.border = '1px dashed #ccc';
+    adElement.style.display = 'flex';
+    adElement.style.alignItems = 'center';
+    adElement.style.justifyContent = 'center';
+    adElement.style.backgroundColor = '#f9f9f9';
+    adElement.style.color = '#666';
+    adElement.innerHTML = `<span>Loading ${type} ad...</span>`;
+
+    container.appendChild(adElement);
+
+    if (this._config?.debug) {
+      console.log(`📦 Placeholder created for slot: ${slotId}`);
+    }
+  }
+
+  /**
+   * 백그라운드에서 광고 콘텐츠 로드
+   */
+  private async loadAdContentInBackground(slot: AdSlot): Promise<void> {
+    try {
+      // 광고 데이터 가져오기 - 여러 개 로드
+      const adstageData = await this.fetchAdData(slot.adType, slot.config);
+      
+      if (!adstageData || adstageData.length === 0) {
+        this.renderFallback(slot);
+        return;
+      }
+
+      // 광고가 여러 개이거나 autoSlide 옵션이 있으면 슬라이더로 렌더링
+      if (adstageData.length > 1 || (slot.config as any)?.autoSlide) {
+        await this.renderAdSlider(slot, adstageData);
+      } else {
+        // 광고가 1개면 일반 렌더링
+        slot.advertisement = adstageData[0];
+        await this.renderAdElement(slot, adstageData[0]);
+      }
+      
+      slot.isLoaded = true;
+
+      if (this._config?.debug) {
+        console.log(`✅ Ad loaded for slot: ${slot.id} (${adstageData.length} ads)`);
+      }
+    } catch (error) {
+      console.error(`❌ Failed to load ad for slot: ${slot.id}`, error);
+      this.renderFallback(slot);
+    }
+  }
+
+  /**
+   * Fallback 광고 렌더링
+   */
+  private renderFallback(slot: AdSlot): void {
+    const element = document.getElementById(slot.id);
+    if (element) {
+      element.innerHTML = `<span>Ad not available</span>`;
+      element.style.color = '#999';
+      
+      if (this._config?.debug) {
+        console.warn(`⚠️ Fallback rendered for slot: ${slot.id}`);
+      }
+    }
+  }
+
+  /**
+   * 광고 데이터 가져오기
+   */
+  private async fetchAdData(type: AdType, options: any): Promise<Advertisement[]> {
+    if (!this._config?.apiKey) {
+      throw new Error('API key not configured');
+    }
+
+    // GET 요청용 query parameters 구성
+    const params = new URLSearchParams();
+    params.append('adType', type);
+    
+    // userAgent와 url은 header나 자동으로 처리되므로 query에서 제외
+    // 기타 옵션들을 필요시 query parameter로 추가 가능
+    
+    const url = `${endpoints.advertisements.list()}?${params.toString()}`;
+    
+    const response = await fetch(url, {
+      method: 'GET',
+      headers: ApiHeaders.create(this._config.apiKey)
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch ad data: ${response.status}`);
+    }
+
+    const result = await response.json();
+    return result.advertisements || [];
+  }
+
+  /**
+   * 광고 슬라이더 렌더링 (여러 광고 또는 autoSlide 옵션)
+   */
+  private async renderAdSlider(slot: AdSlot, advertisements: Advertisement[]): Promise<void> {
+    const container = document.getElementById(slot.containerId);
+    if (!container) {
+      throw new Error(`Container not found: ${slot.containerId}`);
+    }
+
+    // 이벤트 추적 콜백 함수 (중복 노출 방지 포함)
+    const trackEventCallback = (adId: string, slotId: string, eventType: AdEventType) => {
+      // 노출 이벤트인 경우 중복 확인
+      if (eventType === AdEventType.IMPRESSION) {
+        if (ImpressionTracker.isDuplicateImpression(adId, slotId, this._config?.debug)) {
+          if (this._config?.debug) {
+            console.log(`🚫 Duplicate impression blocked for ad ${adId} in slot ${slotId}`);
+          }
+          return; // 중복 노출이면 추적하지 않음
+        }
+        
+        if (this._config?.debug) {
+          console.log(`✅ New impression recorded for ad ${adId} in slot ${slotId}`);
+        }
+      }
+      
+      if (this.eventTracker && this._config?.debug) {
+        console.log(`📊 Event tracked: ${eventType} for ad ${adId} in slot ${slotId}`);
+      }
+    };
+
+    let sliderElement: HTMLElement;
+
+    // 텍스트 광고는 TextTransitionManager 사용, 그 외는 CarouselSliderManager 사용
+    if (slot.adType === AdType.TEXT) {
+      sliderElement = TextTransitionManager.createTextTransitionContainer(
+        slot,
+        advertisements,
+        {
+          autoSlideInterval: ((slot.config as any)?.slideInterval || 5000) / 1000,
+          ...slot.config
+        },
+        trackEventCallback
+      );
+      
+      if (this._config?.debug) {
+        console.log(`✨ Text transition created for TEXT slot: ${slot.id} with ${advertisements.length} ads`);
+      }
+    } else {
+      sliderElement = CarouselSliderManager.createSliderContainer(
+        slot,
+        advertisements,
+        {
+          autoSlideInterval: ((slot.config as any)?.slideInterval || 5000) / 1000,
+          ...slot.config
+        },
+        trackEventCallback
+      );
+      
+      if (this._config?.debug) {
+        console.log(`🎠 Carousel slider created for ${slot.adType} slot: ${slot.id} with ${advertisements.length} ads`);
+      }
+    }
+
+    // 기존 내용 제거하고 슬라이더 추가
+    container.innerHTML = '';
+    container.appendChild(sliderElement);
+  }
+
+  /**
+   * 광고 렌더링 (단일 광고용)
+   */
+  private async renderAd(slot: AdSlot): Promise<void> {
+    if (!slot.advertisement) {
+      throw new Error('No advertisement to render');
+    }
+
+    await this.renderAdElement(slot, slot.advertisement);
+    slot.isLoaded = true;
+  }
+
+  /**
+   * 광고 요소 렌더링 (기본 구현)
+   */
+  private async renderAdElement(slot: AdSlot, ad: Advertisement): Promise<void> {
+    const container = document.getElementById(slot.containerId);
+    if (!container) return;
+
+    // 기본 HTML 구조 생성
+    const adElement = document.createElement('div');
+    adElement.className = 'adstage-ad';
+    adElement.style.width = typeof slot.width === 'string' ? slot.width : `${slot.width}px`;
+    adElement.style.height = typeof slot.height === 'string' ? slot.height : `${slot.height}px`;
+
+    // 광고 타입별 렌더링
+    switch (slot.adType) {
+      case AdType.BANNER:
+        if (ad.imageUrl) {
+          const img = document.createElement('img');
+          img.src = ad.imageUrl;
+          img.alt = ad.title;
+          img.style.width = '100%';
+          img.style.height = '100%';
+          img.style.objectFit = 'cover';
+          adElement.appendChild(img);
+        }
+        break;
+      
+      case AdType.TEXT:
+        const textDiv = document.createElement('div');
+        textDiv.innerHTML = `
+          <h3>${ad.title}</h3>
+          ${ad.description ? `<p>${ad.description}</p>` : ''}
+          ${ad.textContent ? `<div>${ad.textContent}</div>` : ''}
+        `;
+        adElement.appendChild(textDiv);
+        break;
+      
+      case AdType.VIDEO:
+        if (ad.videoUrl) {
+          const video = document.createElement('video');
+          video.src = ad.videoUrl;
+          video.controls = true;
+          video.style.width = '100%';
+          video.style.height = '100%';
+          adElement.appendChild(video);
+        }
+        break;
+      
+      default:
+        adElement.innerHTML = `<div>${ad.title}</div>`;
+    }
+
+    // 클릭 이벤트 추가
+    if (ad.linkUrl) {
+      adElement.style.cursor = 'pointer';
+      adElement.addEventListener('click', () => {
+        window.open(ad.linkUrl, '_blank');
+      });
+    }
+
+    container.innerHTML = '';
+    container.appendChild(adElement);
+  }
+
+  /**
+   * 광고 슬롯 새로고침
+   */
+  private async refreshAdSlot(slot: AdSlot): Promise<void> {
+    try {
+      // 새로운 광고 데이터 가져오기 (config에서 타입과 옵션 정보 사용)
+      const newAdData = await this.fetchAdData(slot.adType, slot.config || {});
+      
+      if (newAdData && newAdData.length > 0) {
+        slot.advertisement = newAdData[0]; // 첫 번째 광고로 업데이트
+        await this.renderAd(slot);
+        
+        // 새로운 노출 추적
+        if (this.eventTracker) {
+          console.log('New impression tracked for slot:', slot.id);
+        }
+      }
+    } catch (error) {
+      console.error(`Failed to refresh ad slot: ${slot.id}`, error);
+    }
+  }
+
+  /**
+   * 모듈 준비 상태 확인
+   */
+  private ensureReady(): void {
+    if (!this._isReady) {
+      throw new Error('Ads module not initialized. Call AdStage.init() first.');
+    }
+  }
+}

package/src/modules/config/ConfigModule.ts

@@ -0,0 +1,124 @@
+/**
+ * AdStage SDK - Config 모듈
+ * 설정 관리 및 API 키 검증
+ */
+
+import { AdStageConfig, BaseModule, ApiResponse, OrganizationInfo } from '../../types/config';
+import { endpoints } from '../../constants/endpoints';
+import { ApiHeaders } from '../../utils/api-headers';
+
+export class ConfigModule implements BaseModule {
+  private _isReady = false;
+  private _config: AdStageConfig | null = null;
+  private _organizationInfo: OrganizationInfo | null = null;
+
+  /**
+   * Config 모듈 초기화 (동기)
+   */
+  init(config: AdStageConfig): void {
+    // 설정만 저장 (서버 검증 없음)
+    this._config = {
+      timeout: 30000,
+      debug: false,
+      modules: ['ads', 'events', 'config'],
+      validateOnInit: false,
+      fallbackMode: true,
+      offlineMode: false,
+      productionMode: false,
+      ...config
+    };
+    
+    // 사용자가 baseUrl을 제공한 경우 endpoints에 설정
+    if (config.baseUrl) {
+      endpoints.setBaseUrl(config.baseUrl);
+    }
+    
+    this._isReady = true;
+
+    if (config.debug) {
+      console.log('✅ Config module initialized (sync mode)', {
+        modules: this._config.modules,
+        endpoint: endpoints.getBaseUrl(),
+        mode: config.productionMode ? 'production' : 'development'
+      });
+    }
+  }
+
+  /**
+   * 모듈 준비 상태 확인
+   */
+  isReady(): boolean {
+    return this._isReady;
+  }
+
+  /**
+   * 현재 설정 반환
+   */
+  getConfig(): AdStageConfig | null {
+    return this._config;
+  }
+
+  /**
+   * 조직 정보 반환
+   */
+  getOrganizationInfo(): OrganizationInfo | null {
+    return this._organizationInfo;
+  }
+
+  /**
+   * API 엔드포인트 반환
+   */
+  getApiEndpoint(): string {
+    return endpoints.getBaseUrl();
+  }
+
+  /**
+   * 디버그 모드 여부 확인
+   */
+  isDebugMode(): boolean {
+    return this._config?.debug || false;
+  }
+
+  /**
+   * 활성화된 모듈 목록 반환
+   */
+  getEnabledModules(): string[] {
+    return this._config?.modules || [];
+  }
+
+  /**
+   * 특정 모듈이 활성화되어 있는지 확인
+   */
+  isModuleEnabled(moduleName: string): boolean {
+    return this.getEnabledModules().includes(moduleName);
+  }
+
+  /**
+   * 설정 업데이트 (런타임)
+   */
+  updateConfig(updates: Partial<AdStageConfig>): void {
+    if (!this._config) {
+      throw new Error('Config module not initialized');
+    }
+
+    this._config = {
+      ...this._config,
+      ...updates
+    };
+
+    if (this.isDebugMode()) {
+      console.log('🔄 Config updated', updates);
+    }
+  }
+
+  /**
+   * API 헤더 생성 (공통 유틸리티 사용)
+   */
+  getApiHeaders(): Record<string, string> {
+    if (!this._config?.apiKey) {
+      throw new Error('API key not available');
+    }
+
+    return ApiHeaders.create(this._config.apiKey);
+  }
+}