@adstage/web-sdk 2.0.0 → 2.1.2

package/dist/index.cjs.js

@@ -19,15 +19,8 @@ var Platform;
 // 광고 이벤트 타입
 var AdEventType;
 (function (AdEventType) {
-    AdEventType["IMPRESSION"] = "IMPRESSION";
-    AdEventType["CLICK"] = "CLICK";
-    AdEventType["HOVER"] = "HOVER";
     AdEventType["VIEWABLE"] = "VIEWABLE";
-    AdEventType["VIEWABLE_IMPRESSION"] = "VIEWABLE_IMPRESSION";
-    AdEventType["COMPLETED"] = "COMPLETED";
-    AdEventType["VIDEO_START"] = "VIDEO_START";
-    AdEventType["VIDEO_COMPLETE"] = "VIDEO_COMPLETE";
-    AdEventType["ERROR"] = "ERROR";
+    AdEventType["CLICK"] = "CLICK";
 })(AdEventType || (AdEventType = {}));
 // 디바이스 타입
 var DeviceType;
@@ -949,7 +942,7 @@ class CarouselSliderManager {
             }
             // 현재 슬라이드의 광고에 대해 노출 이벤트 추적
             if (actualIndex > 0) { // 첫 번째는 이미 loadSlot에서 추적됨
-                trackEventCallback(advertisements[actualIndex]._id, slot.id, AdEventType.IMPRESSION);
+                trackEventCallback(advertisements[actualIndex]._id, slot.id, AdEventType.VIEWABLE);
             }
         };
         // 무한 루프 처리 함수
@@ -1269,7 +1262,7 @@ class TextTransitionManager {
             currentSlide = index;
             // 현재 슬라이드의 광고에 대해 노출 이벤트 추적
             if (currentSlide > 0) { // 첫 번째는 이미 loadSlot에서 추적됨
-                trackEventCallback(advertisements[currentSlide]._id, slot.id, AdEventType.IMPRESSION);
+                trackEventCallback(advertisements[currentSlide]._id, slot.id, AdEventType.VIEWABLE);
             }
         };
         // 자동 슬라이드
@@ -1335,57 +1328,58 @@ class TextTransitionManager {
 }
 
 /**
- * 노출 추적 및 중복 방지 관리 클래스
+ * VIEWABLE 이벤트 추적 및 중복 방지 관리 클래스
  * - 메모리 기반 중복 확인
  * - 세션 스토리지 기반 영구 추적
  * - 자동 정리 기능
+ * - ViewabilityTracker와 함께 사용하여 중복 viewable 이벤트 방지
  */
-class ImpressionTracker {
+class ViewableEventTracker {
     /**
-     * 중복 노출 여부 확인
+     * 중복 viewable 이벤트 여부 확인
      */
-    static isDuplicateImpression(adId, slotId, debug = false) {
+    static isDuplicateViewable(adId, slotId, debug = false) {
         const key = `${adId}_${slotId}`;
         const now = Date.now();
         // 메모리 기반 중복 확인 (새로고침 시 초기화됨)
-        const lastImpression = ImpressionTracker.impressionTracker.get(key);
-        if (lastImpression && (now - lastImpression) < ImpressionTracker.IMPRESSION_COOLDOWN) {
+        const lastViewable = ViewableEventTracker.viewableTracker.get(key);
+        if (lastViewable && (now - lastViewable) < ViewableEventTracker.VIEWABLE_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`);
+                console.log(`Duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - lastViewable)) / 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) {
+        const sessionKey = `adstage_viewable_${key}`;
+        const sessionViewable = sessionStorage.getItem(sessionKey);
+        if (sessionViewable) {
+            const sessionTime = parseInt(sessionViewable, 10);
+            if (!isNaN(sessionTime) && (now - sessionTime) < ViewableEventTracker.VIEWABLE_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`);
+                    console.log(`Session-based duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - sessionTime)) / 1000)}s remaining`);
                 }
                 // 메모리에도 기록하여 이후 요청 최적화
-                ImpressionTracker.impressionTracker.set(key, sessionTime);
+                ViewableEventTracker.viewableTracker.set(key, sessionTime);
                 return true;
             }
         }
-        // 노출 시점 기록 (메모리 + 세션 스토리지)
-        ImpressionTracker.impressionTracker.set(key, now);
+        // viewable 이벤트 시점 기록 (메모리 + 세션 스토리지)
+        ViewableEventTracker.viewableTracker.set(key, now);
         sessionStorage.setItem(sessionKey, now.toString());
         // 오래된 세션 스토리지 데이터 정리 (선택적)
-        ImpressionTracker.cleanupOldImpressions();
+        ViewableEventTracker.cleanupOldViewables();
         return false;
     }
     /**
-     * 오래된 노출 추적 데이터 정리
+     * 오래된 viewable 추적 데이터 정리
      */
-    static cleanupOldImpressions() {
+    static cleanupOldViewables() {
         const now = Date.now();
-        const cleanupThreshold = ImpressionTracker.IMPRESSION_COOLDOWN * 2; // 쿨다운의 2배 시간이 지난 데이터 정리
+        const cleanupThreshold = ViewableEventTracker.VIEWABLE_COOLDOWN * 2; // 쿨다운의 2배 시간이 지난 데이터 정리
         // 세션 스토리지 정리
         for (let i = 0; i < sessionStorage.length; i++) {
             const key = sessionStorage.key(i);
-            if (key && key.startsWith('adstage_impression_')) {
+            if (key && key.startsWith('adstage_viewable_')) {
                 const timestamp = sessionStorage.getItem(key);
                 if (timestamp) {
                     const time = parseInt(timestamp, 10);
@@ -1397,9 +1391,9 @@ class ImpressionTracker {
             }
         }
         // 메모리 정리
-        for (const [key, timestamp] of ImpressionTracker.impressionTracker.entries()) {
+        for (const [key, timestamp] of ViewableEventTracker.viewableTracker.entries()) {
             if ((now - timestamp) > cleanupThreshold) {
-                ImpressionTracker.impressionTracker.delete(key);
+                ViewableEventTracker.viewableTracker.delete(key);
             }
         }
     }
@@ -1407,11 +1401,11 @@ class ImpressionTracker {
      * 모든 추적 데이터 정리
      */
     static clear() {
-        ImpressionTracker.impressionTracker.clear();
+        ViewableEventTracker.viewableTracker.clear();
     }
 }
-ImpressionTracker.impressionTracker = new Map();
-ImpressionTracker.IMPRESSION_COOLDOWN = 300000; // 5분 쿨다운
+ViewableEventTracker.viewableTracker = new Map();
+ViewableEventTracker.VIEWABLE_COOLDOWN = 300000; // 5분 쿨다운
 
 /**
  * 디바이스 정보 수집 클래스
@@ -1549,12 +1543,12 @@ class ApiHeaders {
 }
 
 /**
- * 이벤트 추적 관리 클래스
- * - 광고 이벤트 추적 및 전송
- * - 중복 노출 방지 통합
- * - 서버 API 통신
+ * 광고 이벤트 추적 관리 클래스
+ * - 광고 전용 이벤트 추적 및 전송
+ * - Viewable 이벤트 중복 방지 통합
+ * - 광고 서버 API 통신
  */
-class EventTracker {
+class AdvertisementEventTracker {
     constructor(baseUrl, apiKey, debug, slots) {
         this.baseUrl = baseUrl;
         this.apiKey = apiKey;
@@ -1562,21 +1556,21 @@ class EventTracker {
         this.slots = slots;
     }
     /**
-     * 이벤트 추적
+     * 광고 이벤트 추적 - viewability 데이터 지원
      */
-    async trackEvent(adId, slotId, eventType) {
+    async trackAdvertisementEvent(adId, slotId, eventType, additionalData) {
         try {
-            // 노출 이벤트의 경우 중복 확인
-            if (eventType === AdEventType.IMPRESSION) {
-                if (ImpressionTracker.isDuplicateImpression(adId, slotId, this.debug)) {
-                    return; // 중복 노출이므로 추적하지 않음
+            // VIEWABLE 이벤트의 경우 중복 확인
+            if (eventType === AdEventType.VIEWABLE) {
+                if (ViewableEventTracker.isDuplicateViewable(adId, slotId, this.debug)) {
+                    return; // 중복 viewable 이벤트이므로 추적하지 않음
                 }
             }
             // 현재 슬롯 정보 가져오기
             const slot = this.slots.get(slotId);
             // 디바이스 정보 수집
             const deviceInfo = DeviceInfoCollector.collectDeviceInfo();
-            // 이벤트 데이터 구성 (MongoDB 스키마에 맞춤)
+            // 광고 이벤트 데이터 구성 (DTO 구조에 맞춤)
             const eventData = {
                 // 서버에서 자동 설정: orgId, advertisementId, action
                 // 하지만 DTO 검증을 위해 임시값 제공
@@ -1586,40 +1580,40 @@ class EventTracker {
                 // 필수 필드들
                 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,
+                // 디바이스 정보는 deviceInfo 객체로 래핑
+                deviceInfo: deviceInfo,
                 // 페이지 및 슬롯 정보
                 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),
+                slotWidth: AdvertisementEventTracker.parseNumericValue(slot?.width),
+                slotHeight: AdvertisementEventTracker.parseNumericValue(slot?.height),
                 sessionId: deviceInfo.sessionId,
                 // 성능 메트릭
                 pageLoadTime: performance.now(),
-                timestamp: new Date().toISOString(),
                 // 추가 메타데이터
                 metadata: {
                     eventType,
                     sdkVersion: '1.0.0',
                     timestamp: Date.now(),
                 },
+                // viewable 관련 추가 데이터 (DTO 필드명과 매칭)
+                ...(additionalData?.viewabilityMetrics && {
+                    isViewable: additionalData.viewabilityMetrics.isViewable,
+                    exposureTime: additionalData.viewabilityMetrics.exposureTime,
+                    maxVisibilityRatio: additionalData.viewabilityMetrics.maxVisibilityRatio,
+                    firstViewableTime: additionalData.viewabilityMetrics.firstViewableTime,
+                    // IAB 표준 준수 여부
+                    iabCompliant: additionalData.viewabilityMetrics.isViewable,
+                }),
+                // fraud 관련 데이터 (DTO 필드명과 매칭)
+                ...(additionalData?.fraudScore !== undefined && {
+                    fraudScore: additionalData.fraudScore,
+                    fraudReasons: additionalData.fraudReasons,
+                    riskLevel: additionalData.riskLevel,
+                }),
             };
             await fetch(`${this.baseUrl}/advertisements/events/${adId}/${eventType}`, {
                 method: 'POST',
@@ -1627,11 +1621,11 @@ class EventTracker {
                 body: JSON.stringify(eventData),
             });
             if (this.debug) {
-                console.log(`Tracked event: ${eventType} for ad ${adId}`, eventData);
+                console.log(`Tracked advertisement event: ${eventType} for ad ${adId}`, eventData);
             }
         }
         catch (error) {
-            console.error('Failed to track event:', error);
+            console.error('Failed to track advertisement event:', error);
         }
     }
     /**
@@ -1650,6 +1644,298 @@ class EventTracker {
     }
 }
 
+/**
+ * IAB 표준 준수 viewable impression 측정
+ */
+// 광고 타입별 IAB 표준 설정
+const VIEWABILITY_STANDARDS = {
+    BANNER: {
+        threshold: 0.5,
+        minDuration: 1000,
+        maxMeasureTime: 30000
+    },
+    VIDEO: {
+        threshold: 0.5,
+        minDuration: 2000,
+        maxMeasureTime: 60000
+    },
+    NATIVE: {
+        threshold: 0.5,
+        minDuration: 1000,
+        maxMeasureTime: 30000
+    },
+    INTERSTITIAL: {
+        threshold: 0.5,
+        minDuration: 1000,
+        maxMeasureTime: 10000
+    },
+    TEXT: {
+        threshold: 0.5,
+        minDuration: 1000,
+        maxMeasureTime: 30000
+    },
+    POPUP: {
+        threshold: 0.5,
+        minDuration: 1000,
+        maxMeasureTime: 10000
+    }
+};
+class ViewabilityTracker {
+    constructor(element, adType, onViewable) {
+        this.observer = null;
+        this.viewabilityTimer = null;
+        this.maxVisibilityTimer = null;
+        this.startTime = 0;
+        this.maxVisibilityRatio = 0;
+        this.firstViewableTime = null;
+        this.isViewableAchieved = false;
+        this.element = element;
+        this.config = VIEWABILITY_STANDARDS[adType] || VIEWABILITY_STANDARDS.BANNER;
+        this.onViewableCallback = onViewable;
+        this.startTime = performance.now();
+        this.initIntersectionObserver();
+        this.initMaxMeasureTimer();
+    }
+    initIntersectionObserver() {
+        // IntersectionObserver 지원 확인
+        if (!('IntersectionObserver' in window)) {
+            console.warn('IntersectionObserver not supported, viewability tracking disabled');
+            return;
+        }
+        this.observer = new IntersectionObserver((entries) => this.handleIntersection(entries), {
+            threshold: [0, 0.1, 0.25, 0.5, 0.75, 1.0],
+            rootMargin: '0px'
+        });
+        this.observer.observe(this.element);
+    }
+    handleIntersection(entries) {
+        entries.forEach(entry => {
+            const visibilityRatio = entry.intersectionRatio;
+            const isVisible = this.isDocumentVisible();
+            // 최대 가시성 비율 추적
+            this.maxVisibilityRatio = Math.max(this.maxVisibilityRatio, visibilityRatio);
+            // Viewable 조건 확인 (50% 이상 + 문서 가시성)
+            if (visibilityRatio >= this.config.threshold && isVisible) {
+                this.startViewabilityTimer();
+            }
+            else {
+                this.stopViewabilityTimer();
+            }
+        });
+    }
+    isDocumentVisible() {
+        // 단순한 문서 가시성 확인
+        return !document.hidden && document.visibilityState === 'visible';
+    }
+    startViewabilityTimer() {
+        if (this.viewabilityTimer || this.isViewableAchieved)
+            return;
+        if (this.firstViewableTime === null) {
+            this.firstViewableTime = performance.now();
+        }
+        this.viewabilityTimer = setTimeout(() => {
+            this.onViewabilityAchieved();
+        }, this.config.minDuration);
+    }
+    stopViewabilityTimer() {
+        if (this.viewabilityTimer) {
+            clearTimeout(this.viewabilityTimer);
+            this.viewabilityTimer = null;
+        }
+    }
+    initMaxMeasureTimer() {
+        // 최대 측정 시간 후 자동 종료
+        this.maxVisibilityTimer = setTimeout(() => {
+            this.destroy();
+        }, this.config.maxMeasureTime);
+    }
+    onViewabilityAchieved() {
+        if (this.isViewableAchieved)
+            return;
+        this.isViewableAchieved = true;
+        const metrics = this.calculateMetrics();
+        if (this.onViewableCallback) {
+            this.onViewableCallback(metrics);
+        }
+    }
+    calculateMetrics() {
+        const currentTime = performance.now();
+        const exposureTime = this.firstViewableTime
+            ? currentTime - this.firstViewableTime
+            : 0;
+        return {
+            isViewable: this.isViewableAchieved,
+            exposureTime,
+            maxVisibilityRatio: this.maxVisibilityRatio,
+            firstViewableTime: this.firstViewableTime,
+            measureStartTime: this.startTime,
+        };
+    }
+    getMetrics() {
+        return this.calculateMetrics();
+    }
+    destroy() {
+        this.stopViewabilityTimer();
+        if (this.maxVisibilityTimer) {
+            clearTimeout(this.maxVisibilityTimer);
+            this.maxVisibilityTimer = null;
+        }
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = null;
+        }
+    }
+}
+
+/**
+ * BasicFraudDetector - 현실적 구현 버전
+ * 기본적인 봇 탐지 및 간단한 행동 패턴 분석
+ */
+class BasicFraudDetector {
+    constructor() {
+        this.mouseEvents = 0;
+        this.keyboardEvents = 0;
+        this.scrollEvents = 0;
+        this.startTime = Date.now();
+        this.initBasicTracking();
+    }
+    initBasicTracking() {
+        // 기본적인 사용자 상호작용 추적
+        document.addEventListener('mousemove', () => this.mouseEvents++, { passive: true });
+        document.addEventListener('keydown', () => this.keyboardEvents++, { passive: true });
+        document.addEventListener('scroll', () => this.scrollEvents++, { passive: true });
+    }
+    calculateFraudScore() {
+        let score = 0;
+        const reasons = [];
+        // 1. 웹드라이버 탐지 (기본)
+        if (this.detectWebDriver()) {
+            score += 50;
+            reasons.push('WebDriver detected');
+        }
+        // 2. 헤드리스 브라우저 기본 탐지
+        if (this.detectBasicHeadless()) {
+            score += 40;
+            reasons.push('Headless browser signatures');
+        }
+        // 3. 사용자 상호작용 부족
+        const sessionTime = Date.now() - this.startTime;
+        if (sessionTime > 5000) { // 5초 이상 경과
+            if (this.mouseEvents === 0) {
+                score += 20;
+                reasons.push('No mouse interaction');
+            }
+            if (this.scrollEvents === 0 && sessionTime > 10000) {
+                score += 15;
+                reasons.push('No scroll activity');
+            }
+        }
+        // 4. 브라우저 환경 이상 징후
+        const browserCheck = this.checkBrowserEnvironment();
+        score += browserCheck.score;
+        reasons.push(...browserCheck.reasons);
+        // 5. 시간 패턴 이상 (너무 빠른 페이지 로드 후 즉시 클릭)
+        if (sessionTime < 1000) {
+            score += 25;
+            reasons.push('Suspiciously fast interaction');
+        }
+        const finalScore = Math.min(score, 100);
+        return {
+            score: finalScore,
+            riskLevel: this.getRiskLevel(finalScore),
+            reasons: reasons
+        };
+    }
+    detectWebDriver() {
+        // 기본적인 웹드라이버 탐지
+        return !!(window.webdriver ||
+            navigator.webdriver ||
+            window.__webdriver_evaluate ||
+            window.__selenium_evaluate ||
+            window.__webdriver_script_function ||
+            window.__webdriver_script_func ||
+            window.__webdriver_script_fn ||
+            window.__fxdriver_evaluate ||
+            window.__driver_unwrapped ||
+            window.__webdriver_unwrapped ||
+            window.__driver_evaluate ||
+            window.__selenium_unwrapped ||
+            window.__fxdriver_unwrapped);
+    }
+    detectBasicHeadless() {
+        const signatures = [];
+        // PhantomJS 탐지
+        if (window._phantom || window.phantom) {
+            signatures.push('PhantomJS');
+        }
+        // Chrome headless 기본 탐지
+        if (navigator.userAgent.includes('HeadlessChrome')) {
+            signatures.push('Chrome Headless');
+        }
+        // 플러그인 없음 (일반적이지 않음)
+        if (navigator.plugins.length === 0) {
+            signatures.push('No plugins');
+        }
+        return signatures.length > 0;
+    }
+    checkBrowserEnvironment() {
+        let score = 0;
+        const reasons = [];
+        // 언어 설정 이상
+        if (!navigator.language || navigator.language === 'C') {
+            score += 10;
+            reasons.push('Unusual language setting');
+        }
+        // 쿠키 비활성화
+        if (!navigator.cookieEnabled) {
+            score += 15;
+            reasons.push('Cookies disabled');
+        }
+        // 화면 해상도 이상
+        if (screen.width === 0 || screen.height === 0) {
+            score += 20;
+            reasons.push('Invalid screen resolution');
+        }
+        // 시간대 정보 없음
+        try {
+            const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+            if (!timezone || timezone === 'UTC') {
+                score += 5;
+                reasons.push('No timezone info');
+            }
+        }
+        catch (e) {
+            score += 10;
+            reasons.push('Timezone detection failed');
+        }
+        return { score, reasons };
+    }
+    getRiskLevel(score) {
+        if (score >= 70)
+            return 'CRITICAL';
+        if (score >= 50)
+            return 'HIGH';
+        if (score >= 30)
+            return 'MEDIUM';
+        return 'LOW';
+    }
+    getBrowserInfo() {
+        return {
+            userAgent: navigator.userAgent,
+            language: navigator.language,
+            platform: navigator.platform,
+            cookieEnabled: navigator.cookieEnabled,
+            doNotTrack: navigator.doNotTrack,
+            timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+            screenResolution: `${screen.width}x${screen.height}`,
+            viewportSize: `${window.innerWidth}x${window.innerHeight}`
+        };
+    }
+    destroy() {
+        // 이벤트 리스너 정리는 생략 (메모리 누수 방지를 위해 필요시 구현)
+    }
+}
+
 /**
  * AdStage SDK 엔드포인트 상수 관리
  * 모든 API URL을 중앙에서 관리
@@ -1734,15 +2020,16 @@ class AdsModule {
         this._isReady = false;
         this._config = null;
         this.slots = new Map();
-        this.eventTracker = null;
+        // Advertisement 이벤트 추적 관련
+        this.advertisementEventTracker = null;
     }
     /**
      * Ads 모듈 초기화 (동기)
      */
     init(config) {
         this._config = config;
-        // EventTracker 초기화 (환경 자동 감지된 엔드포인트 사용)
-        this.eventTracker = new EventTracker(endpoints.getBaseUrl(), config.apiKey, config.debug || false, this.slots);
+        // AdvertisementEventTracker 초기화 (환경 자동 감지된 엔드포인트 사용)
+        this.advertisementEventTracker = new AdvertisementEventTracker(endpoints.getBaseUrl(), config.apiKey, config.debug || false, this.slots);
         this._isReady = true;
         if (config.debug) {
             console.log('🎯 Ads module initialized (sync mode)');
@@ -1770,7 +2057,11 @@ class AdsModule {
             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);
     }
@@ -1782,7 +2073,11 @@ class AdsModule {
         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);
     }
@@ -1838,6 +2133,14 @@ class AdsModule {
         if (!slot) {
             throw new Error(`Ad slot not found: ${slotId}`);
         }
+        // ViewabilityTracker 정리
+        if (slot.viewabilityTracker) {
+            slot.viewabilityTracker.destroy();
+        }
+        // BasicFraudDetector 정리
+        if (slot.fraudDetector) {
+            slot.fraudDetector.destroy();
+        }
         // DOM에서 제거
         const container = document.getElementById(slot.containerId);
         if (container) {
@@ -1902,8 +2205,8 @@ class AdsModule {
         // 백그라운드에서 광고 로드
         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;
     }
@@ -1914,6 +2217,10 @@ class AdsModule {
         const adElement = document.createElement('div');
         adElement.id = slotId;
         adElement.className = `adstage-slot adstage-${type.toLowerCase()}`;
+        // 확실한 컨테이너 식별을 위한 데이터 속성 추가
+        adElement.setAttribute('data-adstage-container', 'true');
+        adElement.setAttribute('data-adstage-type', type);
+        adElement.setAttribute('data-adstage-slot', slotId);
         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';
@@ -1947,6 +2254,8 @@ class AdsModule {
                 // 광고가 1개면 일반 렌더링
                 slot.advertisement = adstageData[0];
                 await this.renderAdElement(slot, adstageData[0]);
+                // ✅ 신규: Viewable impression 추적 시작 (기존 즉시 추적 대신)
+                this.startBasicViewabilityTracking(slot, adstageData[0]);
             }
             slot.isLoaded = true;
             if (this._config?.debug) {
@@ -1959,15 +2268,158 @@ class AdsModule {
         }
     }
     /**
-     * Fallback 광고 렌더링
+     * 기본 viewability 추적 시작
+     */
+    startBasicViewabilityTracking(slot, ad) {
+        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.viewabilityTracker = tracker;
+        slot.fraudDetector = fraudDetector;
+        if (this._config?.debug) {
+            console.log(`🎯 Viewability tracking started for slot: ${slot.id}`);
+        }
+    }
+    /**
+     * Viewable 이벤트 처리
+     */
+    async handleViewableEvent(ad, slot, metrics, fraudDetector) {
+        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 광고 렌더링 - AdStage 확실한 컨테이너 우선 탐지
      */
     renderFallback(slot) {
         const element = document.getElementById(slot.id);
         if (element) {
-            element.innerHTML = `<span>Ad not available</span>`;
-            element.style.color = '#999';
+            // 1순위: AdStage가 생성한 확실한 컨테이너들 (데이터 속성 기반)
+            const adstageContainers = [
+                element.querySelector('[data-adstage-container="true"]'), // 내부 AdStage 컨테이너
+                element.closest('[data-adstage-container="true"]'), // 상위 AdStage 컨테이너
+                element, // 자기 자신이 AdStage 컨테이너인 경우
+            ].filter(el => el && el.hasAttribute('data-adstage-container'));
+            // 2순위: AdStage 클래스 기반 컨테이너들
+            const classBasedContainers = [
+                element.closest('.adstage-slot'),
+                element.closest('.adstage-banner'),
+                element.closest('.adstage-text'),
+                element.closest('.adstage-video'),
+                element.closest('.adstage-native'),
+                element.closest('.adstage-interstitial'),
+            ].filter(Boolean);
+            // 3순위: 일반적인 광고 컨테이너 패턴들 (fallback)
+            const generalContainers = [
+                element.closest('[class*="ad"]'),
+                element.closest('[class*="banner"]'),
+                element.closest('[class*="container"]'),
+                element.closest('div[style*="height"]'),
+                element.closest('div[style*="min-height"]'),
+                element.parentElement
+            ].filter(Boolean);
+            // 우선순위에 따라 컨테이너 선택
+            const possibleContainers = [
+                ...adstageContainers,
+                ...classBasedContainers,
+                ...generalContainers
+            ];
+            // 가장 적절한 컨테이너 선택
+            const targetContainer = possibleContainers[0];
+            if (targetContainer) {
+                // 컨테이너 타입 로깅
+                let containerType = 'unknown';
+                if (targetContainer.hasAttribute('data-adstage-container')) {
+                    containerType = 'adstage-official';
+                }
+                else if (targetContainer.classList.contains('adstage-slot')) {
+                    containerType = 'adstage-class';
+                }
+                else {
+                    containerType = 'generic';
+                }
+                targetContainer.style.cssText += `
+          height: 0px !important;
+          min-height: 0px !important;
+          padding: 0px !important;
+          margin: 0px !important;
+          border: none !important;
+          overflow: hidden !important;
+          display: block !important;
+        `;
+                // 내부 모든 요소 제거
+                targetContainer.innerHTML = '';
+                // 빈 상태임을 표시하는 속성 추가
+                targetContainer.setAttribute('data-adstage-empty', 'true');
+                if (this._config?.debug) {
+                    console.warn(`⚠️ Ad container collapsed (${containerType}): ${slot.id}`, targetContainer);
+                }
+            }
+            else {
+                // 컨테이너를 찾지 못한 경우 새로운 빈 컨테이너 생성
+                this.createEmptyContainer(slot);
+            }
+        }
+        // 슬롯 상태 업데이트 (제거하지 않고 빈 상태로 마킹)
+        slot.advertisement = undefined;
+        slot.isEmpty = true;
+    }
+    /**
+     * 빈 컨테이너 생성 (컨테이너를 찾지 못한 경우)
+     */
+    createEmptyContainer(slot) {
+        const originalContainer = document.getElementById(slot.containerId);
+        if (originalContainer) {
+            // 기존 내용 제거
+            originalContainer.innerHTML = '';
+            // 빈 AdStage 컨테이너 생성
+            const emptyElement = document.createElement('div');
+            emptyElement.id = slot.id;
+            emptyElement.className = 'adstage-slot adstage-empty';
+            emptyElement.setAttribute('data-adstage-container', 'true');
+            emptyElement.setAttribute('data-adstage-empty', 'true');
+            emptyElement.setAttribute('data-adstage-slot', slot.id);
+            emptyElement.style.cssText = `
+        height: 0px !important;
+        min-height: 0px !important;
+        padding: 0px !important;
+        margin: 0px !important;
+        border: none !important;
+        overflow: hidden !important;
+        display: block !important;
+      `;
+            originalContainer.appendChild(emptyElement);
             if (this._config?.debug) {
-                console.warn(`⚠️ Fallback rendered for slot: ${slot.id}`);
+                console.warn(`⚠️ Created empty AdStage container: ${slot.id}`);
             }
         }
     }
@@ -1981,8 +2433,16 @@ class AdsModule {
         // GET 요청용 query parameters 구성
         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()}`;
         const response = await fetch(url, {
             method: 'GET',
@@ -1992,7 +2452,15 @@ class AdsModule {
             throw new Error(`Failed to fetch ad data: ${response.status}`);
         }
         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;
     }
     /**
      * 광고 슬라이더 렌더링 (여러 광고 또는 autoSlide 옵션)
@@ -2005,19 +2473,19 @@ class AdsModule {
         // 이벤트 추적 콜백 함수 (중복 노출 방지 포함)
         const trackEventCallback = (adId, slotId, eventType) => {
             // 노출 이벤트인 경우 중복 확인
-            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}`);
             }
         };
         let sliderElement;
@@ -2122,8 +2590,8 @@ class AdsModule {
                 slot.advertisement = newAdData[0]; // 첫 번째 광고로 업데이트
                 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);
                 }
             }
         }