@adstage/web-sdk 1.3.4 → 1.4.0

package/src/managers/{slider-manager.ts → carousel-slider-manager.ts}

@@ -3,18 +3,19 @@ import type { AdSlot, Advertisement } from '../types/advertisement';
 import { AdRendererFactory } from '../renderers';
 
 /**
- * 슬라이더 관리 클래스
- * - 다중 광고 슬라이더 생성 및 관리
- * - 무한 루프 슬라이더 지원
+ * 캐러셀 슬라이더 관리 클래스
+ * - 배너/비디오 광고용 가로 슬라이드 (횡 스크롤)
+ * - 무한 루프 캐러셀 지원
  * - 터치 제스처 및 자동 슬라이드 기능
+ * - 도트 인디케이터 포함
  */
-export class SliderManager {
+export class CarouselSliderManager {
   /**
-   * 슬라이더 컨테이너 생성
+   * Create carousel slider container with dot indicators and navigation
    */
   static createSliderContainer(
     slot: AdSlot,
-    advertisements: Advertisement[],
+    advertisements: any[],
     options: any,
     trackEventCallback: (adId: string, slotId: string, eventType: AdEventType) => void
   ): HTMLElement {
@@ -175,7 +176,7 @@ export class SliderManager {
     const isAllTextAds = advertisements.every(ad => ad.adType === AdType.TEXT);
     
     // 무채색 도트 인디케이터 생성 (원본 광고 수만큼) - 텍스트 광고가 아닐 때만
-    const dotContainer = isAllTextAds ? null : SliderManager.createMinimalDotIndicator(advertisements.length);
+    const dotContainer = isAllTextAds ? null : this.createMinimalDotIndicator(advertisements.length);
     
     // 슬라이더 상태 관리
     let currentSlide = 0;
@@ -261,7 +262,7 @@ export class SliderManager {
     });
 
     // 터치 제스처 지원 수정 (무한 루프 지원)
-    SliderManager.addTouchSupport(slideContainer, moveToSlide, () => currentSlide, totalSlides, handleInfiniteLoop);
+    this.addTouchSupport(slideContainer, moveToSlide, () => currentSlide, totalSlides, handleInfiniteLoop);
 
     // 요소들 조립 (화살표 제거, 도트는 텍스트 광고가 아닐 때만 추가)
     sliderWrapper.appendChild(slideContainer);

package/src/managers/event-tracker.ts

@@ -3,6 +3,7 @@ import type { AdSlot } from '../types/advertisement';
 import { ImpressionTracker } from './impression-tracker';
 import { DeviceInfoCollector } from './device-info-collector';
 import { DOMUtils } from '../utils/dom-utils';
+import { ApiHeaders } from '../utils/api-headers';
 
 /**
  * 이벤트 추적 관리 클래스
@@ -96,10 +97,7 @@ export class EventTracker {
         `${this.baseUrl}/advertisements/events/${adId}/${eventType}`,
         {
           method: 'POST',
-          headers: {
-            'x-api-key': this.apiKey,
-            'Content-Type': 'application/json',
-          },
+          headers: ApiHeaders.createForEvents(this.apiKey, eventData),
           body: JSON.stringify(eventData),
         }
       );

package/src/managers/{fade-slider-manager.ts → text-transition-manager.ts}

@@ -3,16 +3,16 @@ import type { AdSlot, Advertisement } from '../types/advertisement';
 import { AdRendererFactory } from '../renderers';
 
 /**
- * 페이드 슬라이더 관리 클래스
- * - 텍스트 광고 전용 페이드 인/아웃 슬라이더
- * - 상하 교차 효과 (위에서 아래로, 아래서 위로)
+ * 텍스트 전환 효과 관리 클래스
+ * - 텍스트 광고 전용 페이드 인/아웃 + 상하 움직임 효과
+ * - 부드러운 전환 애니메이션 (vertical transition)
  * - 무한 루프 지원
  */
-export class FadeSliderManager {
+export class TextTransitionManager {
   /**
-   * 페이드 슬라이더 컨테이너 생성
+   * 텍스트 전환 슬라이더 컨테이너 생성
    */
-  static createFadeSliderContainer(
+  static createTextTransitionContainer(
     slot: AdSlot,
     advertisements: Advertisement[],
     options: any,
@@ -219,7 +219,7 @@ export class FadeSliderManager {
     });
 
     // 터치 제스처 지원
-    FadeSliderManager.addTouchSupport(sliderWrapper, moveToSlide, () => currentSlide, totalSlides);
+    TextTransitionManager.addTouchSupport(sliderWrapper, moveToSlide, () => currentSlide, totalSlides);
 
     // 요소들 조립
     sliderWrapper.appendChild(slideContainer);

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.');
+    }
+  }
+}