@adstage/web-sdk 2.5.3 → 2.6.1

package/src/modules/ads/ad-renderer.ts

@@ -0,0 +1,259 @@
+/**
+ * AdRenderer - 광고 렌더링 팩토리 클래스
+ * 광고 타입별로 적절한 렌더러를 생성하고 관리
+ */
+
+import { AdSlot, Advertisement, AdType } from '../../types/advertisement';
+import { AdvertisementEventTracker } from '../../managers/ads/advertisement-event-tracker';
+import { IAdRenderer } from './interfaces/i-ad-renderer';
+import { BannerAdRenderer } from './renderers/banner-ad-renderer';
+import { TextAdRenderer } from './renderers/text-ad-renderer';
+import { VideoAdRenderer } from './renderers/video-ad-renderer';
+import { NativeAdRenderer } from './renderers/native-ad-renderer';
+import { InterstitialAdRenderer } from './renderers/interstitial-ad-renderer';
+
+export class AdRenderer {
+  private debug: boolean;
+  private advertisementEventTracker: AdvertisementEventTracker | null;
+  private renderers: Map<AdType, IAdRenderer> = new Map();
+
+  constructor(debug: boolean = false, advertisementEventTracker?: AdvertisementEventTracker | null) {
+    this.debug = debug;
+    this.advertisementEventTracker = advertisementEventTracker || null;
+    
+    // 각 광고 타입별 렌더러 초기화
+    this.initializeRenderers();
+  }
+
+  /**
+   * 광고 타입별 렌더러 초기화
+   */
+  private initializeRenderers(): void {
+    this.renderers.set(AdType.BANNER, new BannerAdRenderer(this.debug, this.advertisementEventTracker));
+    this.renderers.set(AdType.TEXT, new TextAdRenderer(this.debug, this.advertisementEventTracker));
+    this.renderers.set(AdType.VIDEO, new VideoAdRenderer(this.debug, this.advertisementEventTracker));
+    this.renderers.set(AdType.NATIVE, new NativeAdRenderer(this.debug, this.advertisementEventTracker));
+    this.renderers.set(AdType.INTERSTITIAL, new InterstitialAdRenderer(this.debug, this.advertisementEventTracker));
+    
+    if (this.debug) {
+      console.log(`🏭 AdRenderer factory initialized with ${this.renderers.size} renderers`);
+    }
+  }
+
+  /**
+   * 광고 요소를 동기적으로 생성해서 반환 (크기 측정 등을 위한 helper)
+   */
+  createAdElement(slot: AdSlot, advertisement: Advertisement): HTMLElement {
+    const renderer = this.getRenderer(slot.adType);
+    
+    // 기본 광고 요소 생성
+    const adElement = document.createElement('div');
+    adElement.className = `adstage-ad adstage-${String(slot.adType).toLowerCase()}`;
+    adElement.setAttribute('data-adstage-ad-id', advertisement._id);
+    adElement.setAttribute('data-adstage-slot-id', slot.id);
+    
+    // 광고 타입별 기본 컨테이너 설정
+    const { width, height } = renderer.calculateAdSize(
+      adElement,
+      slot.config || {},
+      advertisement
+    );
+    
+    adElement.style.width = width;
+    adElement.style.height = height;
+    adElement.style.display = 'block';
+    
+    // 간단한 내용 설정 (크기 측정용)
+    switch (slot.adType) {
+      case AdType.BANNER:
+        if (advertisement.imageUrl) {
+          const img = document.createElement('img');
+          img.src = advertisement.imageUrl;
+          img.style.width = '100%';
+          img.style.height = '100%';
+          img.style.objectFit = 'cover';
+          adElement.appendChild(img);
+        }
+        break;
+      case AdType.VIDEO:
+        if (advertisement.videoUrl) {
+          const video = document.createElement('video');
+          video.src = advertisement.videoUrl;
+          video.style.width = '100%';
+          video.style.height = '100%';
+          adElement.appendChild(video);
+        }
+        break;
+      case AdType.TEXT:
+        if (advertisement.textContent) {
+          const textDiv = document.createElement('div');
+          textDiv.textContent = advertisement.textContent || '';
+          textDiv.style.padding = '8px';
+          adElement.appendChild(textDiv);
+        }
+        break;
+      default:
+        // 기본 placeholder
+        adElement.style.border = '1px dashed #ccc';
+        adElement.style.backgroundColor = '#f9f9f9';
+        adElement.textContent = `${slot.adType} Ad`;
+    }
+    
+    return adElement;
+  }
+
+  /**
+   * 광고 타입에 따른 렌더러 획득
+   */
+  public getRenderer(adType: AdType): IAdRenderer {
+    const renderer = this.renderers.get(adType);
+    if (!renderer) {
+      throw new Error(`No renderer found for ad type: ${adType}`);
+    }
+    return renderer;
+  }
+
+  /**
+   * Placeholder(슬롯 컨테이너) 생성
+   */
+  createPlaceholder(
+    container: HTMLElement,
+    slotId: string,
+    type: AdType,
+    options: any,
+    config?: any
+  ): void {
+    const renderer = this.getRenderer(type);
+    renderer.createPlaceholder(container, slotId, options, config);
+  }
+
+  /**
+   * 배너 광고를 위한 컨테이너 최적화 (배너 전용)
+   */
+  async optimizeContainerForBannerAds(slot: AdSlot, advertisements: Advertisement[]): Promise<void> {
+    if (slot.adType !== AdType.BANNER) {
+      if (this.debug) {
+        console.warn(`⚠️ Container optimization is only supported for BANNER ads, got: ${slot.adType}`);
+      }
+      return;
+    }
+    
+    const bannerRenderer = this.getRenderer(AdType.BANNER) as BannerAdRenderer;
+    await bannerRenderer.optimizeContainerForBannerAds(slot, advertisements);
+  }
+
+  /**
+   * 광고 슬라이더 렌더링 (여러 광고 또는 autoSlide 옵션)
+   */
+  async renderAdSlider(slot: AdSlot, advertisements: Advertisement[]): Promise<void> {
+    const renderer = this.getRenderer(slot.adType);
+    await renderer.renderMultipleAds(slot, advertisements);
+  }
+
+  /**
+   * 광고 렌더링 (단일 광고용)
+   */
+  async renderAd(slot: AdSlot): Promise<void> {
+    if (!slot.advertisement) {
+      throw new Error('No advertisement to render');
+    }
+    
+    const renderer = this.getRenderer(slot.adType);
+    await renderer.renderAdElement(slot, slot.advertisement);
+    slot.isLoaded = true;
+  }
+
+  /**
+   * 광고 요소 렌더링 (기본 구현) - 호환성을 위해 유지
+   */
+  async renderAdElement(slot: AdSlot, ad: Advertisement): Promise<void> {
+    const renderer = this.getRenderer(slot.adType);
+    await renderer.renderAdElement(slot, ad);
+  }
+
+  /**
+   * Fallback 광고 렌더링 - 컨테이너 접기/생성
+   */
+  renderFallback(slot: AdSlot): void {
+    const renderer = this.getRenderer(slot.adType);
+    renderer.renderFallback(slot);
+  }
+
+  /**
+   * 광고 타입별 기본 높이 반환
+   */
+  getDefaultHeightForAdType(type: AdType): string {
+    const renderer = this.getRenderer(type);
+    return renderer.getDefaultHeight();
+  }
+
+  /**
+   * 컨테이너와 광고 타입에 따른 스마트한 크기 계산
+   */
+  calculateAdSize(container: HTMLElement, type: AdType, options: any, config: any): { width: string; height: string } {
+    const renderer = this.getRenderer(type);
+    return renderer.calculateAdSize(container, options, config);
+  }
+
+  /**
+   * 이미지 로드 및 실제 크기 획득 (배너 전용)
+   */
+  loadImageDimensions(imageUrl: string): Promise<{ width: number; height: number }> {
+    return new Promise((resolve, reject) => {
+      const img = new Image();
+      img.onload = () => {
+        resolve({ width: img.naturalWidth, height: img.naturalHeight });
+      };
+      img.onerror = () => {
+        reject(new Error(`Failed to load image: ${imageUrl}`));
+      };
+      img.src = imageUrl;
+    });
+  }
+
+  /**
+   * 배너 이미지 최적화 렌더링 (배너 전용)
+   */
+  async renderOptimizedBannerImage(
+    container: HTMLElement,
+    advertisement: Advertisement,
+    slot: AdSlot
+  ): Promise<HTMLImageElement> {
+    if (slot.adType !== AdType.BANNER) {
+      throw new Error('renderOptimizedBannerImage is only supported for BANNER ads');
+    }
+    
+    const bannerRenderer = this.getRenderer(AdType.BANNER) as BannerAdRenderer;
+    return await bannerRenderer.renderOptimizedBannerImage(container, advertisement, slot);
+  }
+
+  /**
+   * 여러 광고의 최적 컨테이너 크기 계산 (배너 전용)
+   */
+  async calculateOptimalContainerSize(
+    advertisements: Advertisement[],
+    containerWidth: number,
+    adType: AdType
+  ): Promise<{ width: string; height: string; aspectRatio: number }> {
+    if (adType !== AdType.BANNER) {
+      const renderer = this.getRenderer(adType);
+      return {
+        width: '100%',
+        height: renderer.getDefaultHeight(),
+        aspectRatio: 16 / 9
+      };
+    }
+    
+    const bannerRenderer = this.getRenderer(AdType.BANNER) as BannerAdRenderer;
+    return await bannerRenderer.calculateOptimalContainerSize(advertisements, containerWidth);
+  }
+
+  /**
+   * 디버그 로그 출력
+   */
+  private log(message: string, ...args: any[]): void {
+    if (this.debug) {
+      console.log(`[AdRenderer] ${message}`, ...args);
+    }
+  }
+}

package/src/modules/ads/{AdsModule.ts → ads-module.ts}

@@ -12,7 +12,7 @@ import { SimpleViewabilityTracker } from '../../managers/ads/viewability-tracker
 import { endpoints } from '../../constants/endpoints';
 import { ApiHeaders } from '../../utils/api-headers';
 // 새로 분리된 클래스들
-import { AdRenderer } from './AdRenderer';
+import { AdRenderer } from './ad-renderer';
 
 export interface AdOptions {
   width?: string | number;
@@ -23,6 +23,19 @@ export interface AdOptions {
   style?: string;
   autoplay?: boolean;
   muted?: boolean;
+  loop?: boolean;
+  playsinline?: boolean;
+  controls?: boolean; // 비디오 컨트롤 표시 여부
+  hideControls?: boolean; // 모든 컨트롤 숨기기
+  customControls?: {
+    hidePlayButton?: boolean;
+    hideProgressBar?: boolean;
+    hideCurrentTime?: boolean;
+    hideRemainingTime?: boolean;
+    hideVolumeSlider?: boolean;
+    hideMuteButton?: boolean;
+    hideFullscreenButton?: boolean;
+  };
   onClick?: (adData: any) => void;
   // 특정 광고 ID 지정
   adId?: string;
@@ -40,6 +53,8 @@ export class AdsModule implements BaseModule {
   private advertisementEventTracker: AdvertisementEventTracker | null = null;
   // 렌더링 관련
   private adRenderer: AdRenderer | null = null;
+  // DOM 변화 감지를 위한 MutationObserver
+  private mutationObserver: MutationObserver | null = null;
 
   /**
    * Ads 모듈 초기화 (동기)
@@ -58,10 +73,13 @@ export class AdsModule implements BaseModule {
     // AdRenderer 초기화
     this.adRenderer = new AdRenderer(config.debug || false, this.advertisementEventTracker);
 
+    // DOM 변화 감지를 위한 MutationObserver 설정
+    this.setupAutoCleanup();
+
     this._isReady = true;
 
     if (config.debug) {
-      console.log('🎯 Ads module initialized (sync mode)');
+      console.log('🎯 Ads module initialized (sync mode) with auto-cleanup');
     }
   }
 
@@ -82,7 +100,7 @@ export class AdsModule implements BaseModule {
   /**
    * 배너 광고 생성 (동기)
    */
-  banner(containerId: string, options?: AdOptions): string {
+  banner(containerId: string | HTMLElement, options?: AdOptions): string {
     this.ensureReady();
     
     const adstageOptions = {
@@ -105,7 +123,7 @@ export class AdsModule implements BaseModule {
   /**
    * 텍스트 광고 생성 (동기)
    */
-  text(containerId: string, options?: AdOptions): string {
+  text(containerId: string | HTMLElement, options?: AdOptions): string {
     this.ensureReady();
     
     const adstageOptions = {
@@ -124,17 +142,25 @@ export class AdsModule implements BaseModule {
   }
 
   /**
-   * 비디오 광고 생성 (동기)
+   * 비디오 광고 생성 (동기) - 단일 비디오만 지원
    */
-  video(containerId: string, options?: AdOptions): string {
+  video(containerId: string | HTMLElement, 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
+      autoplay: options?.autoplay !== undefined ? options.autoplay : true, // 기본값 true (사용자 요구사항)
+      muted: options?.muted !== undefined ? options.muted : true, // 기본값 true
+      loop: options?.loop !== undefined ? options.loop : true, // 기본값 true (사용자 요구사항)
+      playsinline: options?.playsinline !== false, // 기본값 true
+      controls: options?.controls !== undefined ? options.controls : false, // 기본값 false (사용자 요구사항)
+      hideControls: options?.hideControls || false,
+      customControls: options?.customControls,
+      autoSlide: false, // 비디오는 슬라이드 비활성화
+      maxAds: 1, // 하나의 비디오만 가져오기
+      onClick: options?.onClick,
+      ...(options?.adId && { adId: options.adId }) // 특정 비디오 ID가 있으면 사용
     };
 
     return this.createAd(containerId, AdType.VIDEO, adstageOptions);
@@ -226,21 +252,73 @@ export class AdsModule implements BaseModule {
   /**
    * 광고 생성 내부 메소드 (동기 + Lazy 로딩)
    */
-  private createAd(containerId: string, type: AdType, options: any): string {
+  private createAd(containerId: string | HTMLElement, 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)}`;
+    
+    // 비동기로 광고 생성 처리 (디바운싱 및 재시도 로직 포함)
+    this.createAdWithRetry(containerId, type, options, slotId, 0);
+    
+    return slotId;
+  }
+
+  private async createAdWithRetry(containerId: string | HTMLElement, type: AdType, options: any, slotId: string, attempt: number): Promise<void> {
+    const maxAttempts = 5;
+    const delays = [0, 50, 100, 200, 500]; // 점진적 지연
+    
+    let container: HTMLElement | null = null;
+    let containerIdString: string;
+    
+    // HTMLElement인지 string인지 구분
+    if (typeof containerId === 'string') {
+      // string인 경우 DOM에서 찾기
+      containerIdString = containerId;
+      container = document.getElementById(containerId);
+      
+      if (!container) {
+        if (attempt < maxAttempts - 1) {
+          if (this._config?.debug) {
+            console.warn(`Container not found: ${containerId}. Retrying in ${delays[attempt + 1]}ms... (attempt ${attempt + 1}/${maxAttempts})`);
+          }
+          
+          setTimeout(() => {
+            this.createAdWithRetry(containerId, type, options, slotId, attempt + 1);
+          }, delays[attempt + 1]);
+          return;
+        } else {
+          console.error(`Container not found after ${maxAttempts} attempts: ${containerId}`);
+          return;
+        }
+      }
+    } else {
+      // HTMLElement인 경우 직접 사용
+      container = containerId;
+      containerIdString = container.id || `auto-${slotId}`;
+      
+      // ID가 없으면 자동 생성
+      if (!container.id) {
+        container.id = containerIdString;
+      }
     }
 
-    // 고유한 슬롯 ID 생성
-    const slotId = `adstage-${type}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    // 컨테이너를 찾았으면 광고 생성
+    try {
+      this.createAdInternal(containerIdString, type, options, slotId, container);
+    } catch (error) {
+      console.error('광고 생성 중 오류 발생:', error);
+    }
+  }
 
-  // 즉시 placeholder 생성 (AdRenderer 위임)
-  this.adRenderer?.createPlaceholder(container, slotId, type, options, this._config);
+  private createAdInternal(containerId: string, type: AdType, options: any, slotId: string, container: HTMLElement): void {
+    // 컨테이너에 슬롯 ID 속성 추가 (MutationObserver가 감지할 수 있도록)
+    container.setAttribute('data-adstage-slot-id', slotId);
+    
+    // 즉시 placeholder 생성 (AdRenderer 위임)
+    this.adRenderer?.createPlaceholder(container, slotId, type, options, this._config);
 
     // 광고 슬롯 정보 저장
     const slot: AdSlot = {
@@ -248,7 +326,7 @@ export class AdsModule implements BaseModule {
       containerId,
       adType: type,
       width: options.width || '100%',
-      height: options.height || 250,
+      height: options.height || (type === AdType.TEXT ? 'auto' : 250), // 텍스트 광고는 콘텐츠 높이에 맞춤
       isLoaded: false,
       isVisible: false,
       refreshRate: 0,
@@ -257,7 +335,7 @@ export class AdsModule implements BaseModule {
       advertisement: undefined, // 나중에 로드
       config: { type, ...options },
       load: async () => this.fetchAdData(type, options).then(ads => ads[0] || null),
-  render: (ad: Advertisement) => this.adRenderer?.renderAdElement(slot, ad),
+      render: (ad: Advertisement) => this.adRenderer?.renderAdElement(slot, ad),
       refresh: async () => this.refreshAdSlot(slot),
       destroy: () => this.destroy(slotId)
     };
@@ -272,8 +350,6 @@ export class AdsModule implements BaseModule {
     if (this.advertisementEventTracker && this._config?.debug) {
       console.log(`📊 Advertisement event tracking enabled for slot: ${slotId}`);
     }
-
-    return slotId;
   }
 
   /**
@@ -495,4 +571,109 @@ export class AdsModule implements BaseModule {
       throw new Error('Ads module not initialized. Call AdStage.init() first.');
     }
   }
+
+  /**
+   * DOM 변화 감지를 통한 자동 정리 설정
+   */
+  private setupAutoCleanup(): void {
+    // 브라우저 환경에서만 실행
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+      return;
+    }
+
+    // 기존 observer가 있으면 해제
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+    }
+
+    // 새로운 MutationObserver 생성
+    this.mutationObserver = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        // 제거된 노드들 확인
+        mutation.removedNodes.forEach((node) => {
+          if (node.nodeType === Node.ELEMENT_NODE) {
+            this.handleRemovedElement(node as Element);
+          }
+        });
+      });
+    });
+
+    // document 전체를 관찰 (childList와 subtree 옵션 사용)
+    this.mutationObserver.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+
+    if (this._config?.debug) {
+      console.log('🔍 Auto-cleanup MutationObserver enabled');
+    }
+  }
+
+  /**
+   * 제거된 요소에서 광고 슬롯 정리
+   */
+  private handleRemovedElement(element: Element): void {
+    // 제거된 요소가 광고 컨테이너인지 확인
+    const slotId = element.getAttribute('data-adstage-slot-id');
+    if (slotId) {
+      this.autoDestroy(slotId);
+      return;
+    }
+
+    // 제거된 요소의 하위에 광고 컨테이너가 있는지 확인
+    const adContainers = element.querySelectorAll('[data-adstage-slot-id]');
+    adContainers.forEach((container) => {
+      const containerSlotId = container.getAttribute('data-adstage-slot-id');
+      if (containerSlotId) {
+        this.autoDestroy(containerSlotId);
+      }
+    });
+  }
+
+  /**
+   * 자동 정리 (로그 없이 조용히 정리)
+   */
+  private autoDestroy(slotId: string): void {
+    const slot = this.slots.get(slotId);
+    if (slot) {
+      try {
+        // 슬롯 정리 (로그 출력 최소화)
+        this.slots.delete(slotId);
+        
+        if (this._config?.debug) {
+          console.log(`🧹 Auto-cleanup: slot ${slotId} removed`);
+        }
+      } catch (error) {
+        if (this._config?.debug) {
+          console.warn(`Auto-cleanup failed for slot ${slotId}:`, error);
+        }
+      }
+    }
+  }
+
+  /**
+   * 모듈 종료 시 정리
+   */
+  destroyModule(): void {
+    const debugMode = this._config?.debug;
+
+    // MutationObserver 해제
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+      this.mutationObserver = null;
+    }
+
+    // 모든 슬롯 정리
+    this.slots.clear();
+
+    // 다른 리소스들 정리
+    this.advertisementEventTracker = null;
+    this.adRenderer = null;
+    this._isReady = false;
+    this._config = null;
+
+    if (debugMode) {
+      console.log('🗑️ Ads module destroyed');
+    }
+  }
 }

package/src/modules/ads/interfaces/i-ad-renderer.ts

@@ -0,0 +1,77 @@
+/**
+ * 광고 렌더러 공통 인터페이스
+ */
+
+import { AdSlot, Advertisement, AdType } from '../../../types/advertisement';
+
+export interface IAdRenderer {
+  /**
+   * 광고 타입 (이 렌더러가 처리하는 타입)
+   */
+  readonly adType: AdType;
+
+  /**
+   * 디버그 모드 여부
+   */
+  readonly debug: boolean;
+
+  /**
+   * Placeholder(슬롯 컨테이너) 생성
+   */
+  createPlaceholder(
+    container: HTMLElement,
+    slotId: string,
+    options: any,
+    config?: any
+  ): void;
+
+  /**
+   * 광고 요소 렌더링
+   */
+  renderAdElement(slot: AdSlot, advertisement: Advertisement): Promise<void>;
+
+  /**
+   * 다중 광고 렌더링 (슬라이더/전환 효과 포함)
+   */
+  renderMultipleAds(slot: AdSlot, advertisements: Advertisement[]): Promise<void>;
+
+  /**
+   * Fallback 렌더링 (광고가 없을 때)
+   */
+  renderFallback(slot: AdSlot): void;
+
+  /**
+   * 광고 크기 계산
+   */
+  calculateAdSize(container: HTMLElement, options: any, config: any): { width: string; height: string };
+
+  /**
+   * 광고 타입별 기본 높이 반환
+   */
+  getDefaultHeight(): string;
+}
+
+export interface AdRenderOptions {
+  width?: string | number;
+  height?: number;
+  autoSlide?: boolean;
+  slideInterval?: number;
+  autoplay?: boolean;
+  muted?: boolean;
+  loop?: boolean;
+  controls?: boolean;
+  hideControls?: boolean;
+  customControls?: {
+    hidePlayButton?: boolean;
+    hideProgressBar?: boolean;
+    hideCurrentTime?: boolean;
+    hideRemainingTime?: boolean;
+    hideVolumeSlider?: boolean;
+    hideMuteButton?: boolean;
+    hideFullscreenButton?: boolean;
+  };
+  maxLines?: number;
+  style?: string;
+  onClick?: (adData: any) => void;
+  placeholderMode?: 'invisible' | 'transparent' | 'subtle' | 'minimal' | 'debug' | 'legacy';
+}