@adstage/web-sdk 2.0.0 → 2.1.0

package/src/modules/ads/AdsModule.ts

@@ -6,10 +6,13 @@
 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 { CarouselSliderManager } from '../../managers/ads/carousel-slider-manager';
+import { TextTransitionManager } from '../../managers/ads/text-transition-manager';
+import { ViewableEventTracker } from '../../managers/ads/viewable-event-tracker';
+import { AdvertisementEventTracker } from '../../managers/ads/advertisement-event-tracker';
+import { ViewabilityTracker, VIEWABILITY_STANDARDS } from '../../managers/ads/viewability-tracker';
+import { BasicFraudDetector } from '../../managers/ads/basic-fraud-detector';
+import type { ViewabilityMetrics } from '../../managers/ads/viewability-tracker';
 import { endpoints } from '../../constants/endpoints';
 import { ApiHeaders } from '../../utils/api-headers';
 
@@ -23,13 +26,18 @@ export interface AdOptions {
   autoplay?: boolean;
   muted?: boolean;
   onClick?: (adData: any) => void;
+  // 광고 필터링 옵션 (백엔드 API에서 실제 지원하는 것들만)
+  language?: 'ko' | 'en' | 'ja' | 'zh';
+  deviceType?: 'MOBILE' | 'DESKTOP';
+  country?: 'KR' | 'US' | 'JP' | 'CN' | 'DE';
 }
 
 export class AdsModule implements BaseModule {
   private _isReady = false;
   private _config: AdStageConfig | null = null;
   private slots = new Map<string, AdSlot>();
-  private eventTracker: EventTracker | null = null;
+  // Advertisement 이벤트 추적 관련
+  private advertisementEventTracker: AdvertisementEventTracker | null = null;
 
   /**
    * Ads 모듈 초기화 (동기)
@@ -37,8 +45,8 @@ export class AdsModule implements BaseModule {
   init(config: AdStageConfig): void {
     this._config = config;
     
-    // EventTracker 초기화 (환경 자동 감지된 엔드포인트 사용)
-    this.eventTracker = new EventTracker(
+    // AdvertisementEventTracker 초기화 (환경 자동 감지된 엔드포인트 사용)
+    this.advertisementEventTracker = new AdvertisementEventTracker(
       endpoints.getBaseUrl(),
       config.apiKey,
       config.debug || false,
@@ -77,7 +85,11 @@ export class AdsModule implements BaseModule {
       height: options?.height || 250,
       autoSlide: options?.autoSlide || false,
       slideInterval: options?.slideInterval || 5000,
-      onClick: options?.onClick
+      onClick: options?.onClick,
+      // 필터링 옵션들 전달
+      language: options?.language,
+      deviceType: options?.deviceType,
+      country: options?.country
     };
 
     return this.createAd(containerId, AdType.BANNER, adstageOptions);
@@ -92,7 +104,11 @@ export class AdsModule implements BaseModule {
     const adstageOptions = {
       maxLines: options?.maxLines || 3,
       style: options?.style || 'default',
-      onClick: options?.onClick
+      onClick: options?.onClick,
+      // 필터링 옵션들 전달
+      language: options?.language,
+      deviceType: options?.deviceType,
+      country: options?.country
     };
 
     return this.createAd(containerId, AdType.TEXT, adstageOptions);
@@ -163,6 +179,16 @@ export class AdsModule implements BaseModule {
       throw new Error(`Ad slot not found: ${slotId}`);
     }
 
+    // ViewabilityTracker 정리
+    if ((slot as any).viewabilityTracker) {
+      (slot as any).viewabilityTracker.destroy();
+    }
+
+    // BasicFraudDetector 정리
+    if ((slot as any).fraudDetector) {
+      (slot as any).fraudDetector.destroy();
+    }
+
     // DOM에서 제거
     const container = document.getElementById(slot.containerId);
     if (container) {
@@ -239,8 +265,8 @@ export class AdsModule implements BaseModule {
     this.loadAdContentInBackground(slot);
 
     // 이벤트 추적 준비
-    if (this.eventTracker && this._config?.debug) {
-      console.log(`📊 Event tracking enabled for slot: ${slotId}`);
+    if (this.advertisementEventTracker && this._config?.debug) {
+      console.log(`📊 Advertisement event tracking enabled for slot: ${slotId}`);
     }
 
     return slotId;
@@ -290,6 +316,9 @@ export class AdsModule implements BaseModule {
         // 광고가 1개면 일반 렌더링
         slot.advertisement = adstageData[0];
         await this.renderAdElement(slot, adstageData[0]);
+        
+        // ✅ 신규: Viewable impression 추적 시작 (기존 즉시 추적 대신)
+        this.startBasicViewabilityTracking(slot, adstageData[0]);
       }
       
       slot.isLoaded = true;
@@ -304,18 +333,92 @@ export class AdsModule implements BaseModule {
   }
 
   /**
-   * Fallback 광고 렌더링
+   * 기본 viewability 추적 시작
+   */
+  private startBasicViewabilityTracking(slot: AdSlot, ad: Advertisement): void {
+    const element = document.getElementById(slot.id);
+    if (!element) return;
+    
+    // 기본 fraud 검사
+    const fraudDetector = new BasicFraudDetector();
+    
+    // viewability 추적
+    const tracker = new ViewabilityTracker(element, slot.adType, (metrics) => {
+      this.handleViewableEvent(ad, slot, metrics, fraudDetector);
+    });
+    
+    // 정리를 위해 저장
+    (slot as any).viewabilityTracker = tracker;
+    (slot as any).fraudDetector = fraudDetector;
+
+    if (this._config?.debug) {
+      console.log(`🎯 Viewability tracking started for slot: ${slot.id}`);
+    }
+  }
+
+  /**
+   * Viewable 이벤트 처리
+   */
+  private async handleViewableEvent(
+    ad: Advertisement, 
+    slot: AdSlot, 
+    metrics: ViewabilityMetrics,
+    fraudDetector: BasicFraudDetector
+  ): Promise<void> {
+    try {
+      const fraudScore = fraudDetector.calculateFraudScore();
+      
+      // 높은 위험도면 차단
+      if (fraudScore.riskLevel === 'CRITICAL') {
+        if (this._config?.debug) {
+          console.warn(`🚫 Viewable blocked due to fraud risk: ${fraudScore.score}`, fraudScore.reasons);
+        }
+        return;
+      }
+      
+      // VIEWABLE 이벤트 전송
+      if (this.advertisementEventTracker) {
+        await this.advertisementEventTracker.trackAdvertisementEvent(
+          ad._id,
+          slot.id,
+          AdEventType.VIEWABLE,
+          {
+            viewabilityMetrics: metrics,
+            fraudScore: fraudScore.score,
+            fraudReasons: fraudScore.reasons,
+            riskLevel: fraudScore.riskLevel
+          }
+        );
+        
+        if (this._config?.debug) {
+          console.log(`✅ Viewable impression tracked for ad ${ad._id} (fraud score: ${fraudScore.score})`);
+        }
+      }
+      
+    } catch (error) {
+      console.error(`❌ Failed to track viewable impression:`, error);
+    }
+  }
+
+  /**
+   * Fallback 광고 렌더링 - DOM에서 완전 제거
    */
   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}`);
+      // 부모 컨테이너에서 광고 슬롯을 완전히 제거
+      const parentContainer = element.parentNode;
+      if (parentContainer) {
+        parentContainer.removeChild(element);
+        
+        if (this._config?.debug) {
+          console.warn(`⚠️ Ad slot completely removed from DOM: ${slot.id}`);
+        }
       }
     }
+    
+    // 슬롯 맵에서도 제거
+    this.slots.delete(slot.id);
   }
 
   /**
@@ -330,8 +433,18 @@ export class AdsModule implements BaseModule {
     const params = new URLSearchParams();
     params.append('adType', type);
     
-    // userAgent와 url은 header나 자동으로 처리되므로 query에서 제외
-    // 기타 옵션들을 필요시 query parameter로 추가 가능
+    // 백엔드 API에서 실제 지원하는 필터링 옵션들만 추가
+    if (options.language) {
+      params.append('language', options.language);
+    }
+    
+    if (options.deviceType) {
+      params.append('deviceType', options.deviceType);
+    }
+    
+    if (options.country) {
+      params.append('country', options.country);
+    }
     
     const url = `${endpoints.advertisements.list()}?${params.toString()}`;
     
@@ -345,7 +458,17 @@ export class AdsModule implements BaseModule {
     }
 
     const result = await response.json();
-    return result.advertisements || [];
+    const advertisements = result.advertisements || [];
+    
+    if (this._config?.debug) {
+      console.log(`📊 Fetched ${advertisements.length} ads for type: ${type}, filters:`, {
+        language: options.language,
+        deviceType: options.deviceType,
+        country: options.country
+      });
+    }
+    
+    return advertisements;
   }
 
   /**
@@ -360,21 +483,21 @@ export class AdsModule implements BaseModule {
     // 이벤트 추적 콜백 함수 (중복 노출 방지 포함)
     const trackEventCallback = (adId: string, slotId: string, eventType: AdEventType) => {
       // 노출 이벤트인 경우 중복 확인
-      if (eventType === AdEventType.IMPRESSION) {
-        if (ImpressionTracker.isDuplicateImpression(adId, slotId, this._config?.debug)) {
+      if (eventType === AdEventType.VIEWABLE) {
+        if (ViewableEventTracker.isDuplicateViewable(adId, slotId, this._config?.debug)) {
           if (this._config?.debug) {
-            console.log(`🚫 Duplicate impression blocked for ad ${adId} in slot ${slotId}`);
+            console.log(`🚫 Duplicate viewable blocked for ad ${adId} in slot ${slotId}`);
           }
           return; // 중복 노출이면 추적하지 않음
         }
         
         if (this._config?.debug) {
-          console.log(`✅ New impression recorded for ad ${adId} in slot ${slotId}`);
+          console.log(`✅ New viewable recorded for ad ${adId} in slot ${slotId}`);
         }
       }
       
-      if (this.eventTracker && this._config?.debug) {
-        console.log(`📊 Event tracked: ${eventType} for ad ${adId} in slot ${slotId}`);
+      if (this.advertisementEventTracker && this._config?.debug) {
+        console.log(`📊 Advertisement event tracked: ${eventType} for ad ${adId} in slot ${slotId}`);
       }
     };
 
@@ -505,8 +628,8 @@ export class AdsModule implements BaseModule {
         await this.renderAd(slot);
         
         // 새로운 노출 추적
-        if (this.eventTracker) {
-          console.log('New impression tracked for slot:', slot.id);
+        if (this.advertisementEventTracker) {
+          console.log('New advertisement viewable tracked for slot:', slot.id);
         }
       }
     } catch (error) {

package/src/types/advertisement.ts

@@ -16,15 +16,8 @@ export enum Platform {
 
 // 광고 이벤트 타입
 export enum AdEventType {
-  IMPRESSION = 'IMPRESSION',
-  CLICK = 'CLICK',
-  HOVER = 'HOVER',
   VIEWABLE = 'VIEWABLE',
-  VIEWABLE_IMPRESSION = 'VIEWABLE_IMPRESSION',
-  COMPLETED = 'COMPLETED',
-  VIDEO_START = 'VIDEO_START',
-  VIDEO_COMPLETE = 'VIDEO_COMPLETE',
-  ERROR = 'ERROR',
+  CLICK = 'CLICK',
 }
 
 // 디바이스 타입
@@ -79,7 +72,7 @@ export interface ViewabilityMetrics {
   isViewable: boolean;
   visibilityRatio: number;
   duration: number;
-  impressions: number;
+  viewables: number;
   attentionTime: number;
   scrollDepth: number;
   completionRate: number;
@@ -171,7 +164,7 @@ export interface AdSlot {
   config?: AdSlotConfig;
   advertisement?: Advertisement;
   isViewable?: boolean;
-  impressionSent?: boolean;
+  viewableSent?: boolean;
   loadTime?: number;
   renderTime?: number;
   events?: AdEvent[];
@@ -185,13 +178,7 @@ export interface AdSlot {
 
 // 광고 성과 지표
 export interface AdAnalytics {
-  impressions: number;
+  viewables: number;
   clicks: number;
-  hovers: number;
-  viewableImpressions: number;
-  errors: number;
   ctr: number; // Click Through Rate
-  viewabilityRate: number;
-  averageViewTime: number;
-  totalViewTime: number;
 }

package/src/types/api.ts

@@ -76,13 +76,9 @@ export interface AnalyticsRequest {
 
 // 광고 분석 응답
 export interface AnalyticsResponse {
-  impressions: number;
+  viewables: number;
   clicks: number;
-  hovers: number;
-  viewableImpressions: number;
-  errors: number;
   ctr: number;
-  viewabilityRate: number;
   breakdown?: Record<string, AdAnalytics>;
 }
 

package/src/managers/event-tracker.ts

@@ -1,129 +0,0 @@
-import { AdEventType } from '../types/advertisement';
-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';
-
-/**
- * 이벤트 추적 관리 클래스
- * - 광고 이벤트 추적 및 전송
- * - 중복 노출 방지 통합
- * - 서버 API 통신
- */
-export class EventTracker {
-  private baseUrl: string;
-  private apiKey: string;
-  private debug: boolean;
-  private slots: Map<string, AdSlot>;
-
-  constructor(baseUrl: string, apiKey: string, debug: boolean, slots: Map<string, AdSlot>) {
-    this.baseUrl = baseUrl;
-    this.apiKey = apiKey;
-    this.debug = debug;
-    this.slots = slots;
-  }
-
-  /**
-   * 이벤트 추적
-   */
-  async trackEvent(adId: string, slotId: string, eventType: AdEventType): Promise<void> {
-    try {
-      // 노출 이벤트의 경우 중복 확인
-      if (eventType === AdEventType.IMPRESSION) {
-        if (ImpressionTracker.isDuplicateImpression(adId, slotId, this.debug)) {
-          return; // 중복 노출이므로 추적하지 않음
-        }
-      }
-      
-      // 현재 슬롯 정보 가져오기
-      const slot = this.slots.get(slotId);
-      
-      // 디바이스 정보 수집
-      const deviceInfo = DeviceInfoCollector.collectDeviceInfo();
-
-      // 이벤트 데이터 구성 (MongoDB 스키마에 맞춤)
-      const eventData = {
-        // 서버에서 자동 설정: orgId, advertisementId, action
-        // 하지만 DTO 검증을 위해 임시값 제공
-        orgId: 'temp', // 서버에서 API 키로부터 덮어씀
-        advertisementId: adId, // 서버에서 URL 파라미터로부터 덮어씀
-        action: eventType, // 서버에서 URL 파라미터로부터 덮어씀
-        
-        // 필수 필드들
-        adType: slot?.adType || 'BANNER',
-        platform: deviceInfo.platform,
-        
-        // 디바이스 정보를 최상위로 플래튼
-        deviceId: deviceInfo.deviceId,
-        osVersion: deviceInfo.osVersion,
-        deviceModel: deviceInfo.deviceModel,
-        appVersion: deviceInfo.appVersion,
-        sdkVersion: deviceInfo.sdkVersion,
-        language: deviceInfo.language,
-        country: deviceInfo.country,
-        ipAddress: deviceInfo.ipAddress,
-        userAgent: deviceInfo.userAgent,
-        timezone: deviceInfo.timezone,
-        viewportWidth: deviceInfo.viewportWidth,
-        viewportHeight: deviceInfo.viewportHeight,
-        screenWidth: deviceInfo.screenWidth,
-        screenHeight: deviceInfo.screenHeight,
-        connectionType: deviceInfo.connectionType,
-        
-        // 페이지 및 슬롯 정보
-        pageUrl: DOMUtils.getPageInfo().url,
-        pageTitle: DOMUtils.getPageInfo().title,
-        referrer: DOMUtils.getPageInfo().referrer,
-        slotId,
-        slotPosition: DeviceInfoCollector.getSlotPosition(slot?.containerId || ''),
-        slotWidth: EventTracker.parseNumericValue(slot?.width),
-        slotHeight: EventTracker.parseNumericValue(slot?.height),
-        sessionId: deviceInfo.sessionId,
-        
-        // 성능 메트릭
-        pageLoadTime: performance.now(),
-        timestamp: new Date().toISOString(),
-        
-        // 추가 메타데이터
-        metadata: {
-          eventType,
-          sdkVersion: '1.0.0',
-          timestamp: Date.now(),
-        },
-      };
-
-      await fetch(
-        `${this.baseUrl}/advertisements/events/${adId}/${eventType}`,
-        {
-          method: 'POST',
-          headers: ApiHeaders.createForEvents(this.apiKey, eventData),
-          body: JSON.stringify(eventData),
-        }
-      );
-
-      if (this.debug) {
-        console.log(`Tracked event: ${eventType} for ad ${adId}`, eventData);
-      }
-    } catch (error) {
-      console.error('Failed to track event:', error);
-    }
-  }
-
-  /**
-   * 크기 값을 숫자로 변환 (서버 API용)
-   */
-  private static parseNumericValue(value: number | string | undefined): number {
-    if (typeof value === 'number') {
-      return value;
-    }
-    
-    if (typeof value === 'string') {
-      // px 단위 제거하고 숫자만 추출
-      const numericValue = parseFloat(value.replace(/px$/, ''));
-      return isNaN(numericValue) ? 0 : numericValue;
-    }
-    
-    return 0; // 기본값
-  }
-}

package/src/managers/impression-tracker.ts

@@ -1,88 +0,0 @@
-/**
- * 노출 추적 및 중복 방지 관리 클래스
- * - 메모리 기반 중복 확인
- * - 세션 스토리지 기반 영구 추적
- * - 자동 정리 기능
- */
-export class ImpressionTracker {
-  private static impressionTracker = new Map<string, number>();
-  private static readonly IMPRESSION_COOLDOWN = 300000; // 5분 쿨다운
-
-  /**
-   * 중복 노출 여부 확인
-   */
-  static isDuplicateImpression(adId: string, slotId: string, debug = false): boolean {
-    const key = `${adId}_${slotId}`;
-    const now = Date.now();
-    
-    // 메모리 기반 중복 확인 (새로고침 시 초기화됨)
-    const lastImpression = ImpressionTracker.impressionTracker.get(key);
-    if (lastImpression && (now - lastImpression) < ImpressionTracker.IMPRESSION_COOLDOWN) {
-      if (debug) {
-        console.log(`Duplicate impression blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ImpressionTracker.IMPRESSION_COOLDOWN - (now - lastImpression)) / 1000)}s remaining`);
-      }
-      return true;
-    }
-    
-    // 세션 스토리지 기반 중복 확인 (새로고침 시에도 유지)
-    const sessionKey = `adstage_impression_${key}`;
-    const sessionImpression = sessionStorage.getItem(sessionKey);
-    if (sessionImpression) {
-      const sessionTime = parseInt(sessionImpression, 10);
-      if (!isNaN(sessionTime) && (now - sessionTime) < ImpressionTracker.IMPRESSION_COOLDOWN) {
-        if (debug) {
-          console.log(`Session-based duplicate impression blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ImpressionTracker.IMPRESSION_COOLDOWN - (now - sessionTime)) / 1000)}s remaining`);
-        }
-        // 메모리에도 기록하여 이후 요청 최적화
-        ImpressionTracker.impressionTracker.set(key, sessionTime);
-        return true;
-      }
-    }
-    
-    // 노출 시점 기록 (메모리 + 세션 스토리지)
-    ImpressionTracker.impressionTracker.set(key, now);
-    sessionStorage.setItem(sessionKey, now.toString());
-    
-    // 오래된 세션 스토리지 데이터 정리 (선택적)
-    ImpressionTracker.cleanupOldImpressions();
-    
-    return false;
-  }
-
-  /**
-   * 오래된 노출 추적 데이터 정리
-   */
-  private static cleanupOldImpressions(): void {
-    const now = Date.now();
-    const cleanupThreshold = ImpressionTracker.IMPRESSION_COOLDOWN * 2; // 쿨다운의 2배 시간이 지난 데이터 정리
-    
-    // 세션 스토리지 정리
-    for (let i = 0; i < sessionStorage.length; i++) {
-      const key = sessionStorage.key(i);
-      if (key && key.startsWith('adstage_impression_')) {
-        const timestamp = sessionStorage.getItem(key);
-        if (timestamp) {
-          const time = parseInt(timestamp, 10);
-          if (!isNaN(time) && (now - time) > cleanupThreshold) {
-            sessionStorage.removeItem(key);
-            i--; // 인덱스 조정
-          }
-        }
-      }
-    }
-    
-    // 메모리 정리
-    for (const [key, timestamp] of ImpressionTracker.impressionTracker.entries()) {
-      if ((now - timestamp) > cleanupThreshold) {
-        ImpressionTracker.impressionTracker.delete(key);
-      }
-    }
-  }
-
-  /**
-   * 모든 추적 데이터 정리
-   */
-  static clear(): void {
-    ImpressionTracker.impressionTracker.clear();
-  }
-}