@adstage/web-sdk 2.0.0 → 2.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "2.0.0",
+  "version": "2.1.2",
   "description": "AdStage Web SDK - Production-ready marketing platform SDK with namespace architecture for ads, events, and config management",
   "type": "module",
   "main": "dist/index.cjs.js",

package/src/managers/ads/advertisement-event-tracker.ts

@@ -0,0 +1,142 @@
+import { AdEventType } from '../../types/advertisement';
+import type { AdSlot } from '../../types/advertisement';
+import { ViewableEventTracker } from './viewable-event-tracker';
+import { DeviceInfoCollector } from '../device-info-collector';
+import { DOMUtils } from '../../utils/dom-utils';
+import { ApiHeaders } from '../../utils/api-headers';
+import type { ViewabilityMetrics } from './viewability-tracker';
+
+/**
+ * 광고 이벤트 추적 관리 클래스
+ * - 광고 전용 이벤트 추적 및 전송
+ * - Viewable 이벤트 중복 방지 통합
+ * - 광고 서버 API 통신
+ */
+export class AdvertisementEventTracker {
+  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;
+  }
+
+  /**
+   * 광고 이벤트 추적 - viewability 데이터 지원
+   */
+  async trackAdvertisementEvent(
+    adId: string, 
+    slotId: string, 
+    eventType: AdEventType,
+    additionalData?: {
+      viewabilityMetrics?: ViewabilityMetrics;
+      fraudScore?: number;
+      fraudReasons?: string[];
+      riskLevel?: string;
+    }
+  ): Promise<void> {
+    try {
+      // VIEWABLE 이벤트의 경우 중복 확인
+      if (eventType === AdEventType.VIEWABLE) {
+        if (ViewableEventTracker.isDuplicateViewable(adId, slotId, this.debug)) {
+          return; // 중복 viewable 이벤트이므로 추적하지 않음
+        }
+      }
+      
+      // 현재 슬롯 정보 가져오기
+      const slot = this.slots.get(slotId);
+      
+      // 디바이스 정보 수집
+      const deviceInfo = DeviceInfoCollector.collectDeviceInfo();
+
+      // 광고 이벤트 데이터 구성 (DTO 구조에 맞춤)
+      const eventData = {
+        // 서버에서 자동 설정: orgId, advertisementId, action
+        // 하지만 DTO 검증을 위해 임시값 제공
+        orgId: 'temp', // 서버에서 API 키로부터 덮어씀
+        advertisementId: adId, // 서버에서 URL 파라미터로부터 덮어씀
+        action: eventType, // 서버에서 URL 파라미터로부터 덮어씀
+        
+        // 필수 필드들
+        adType: slot?.adType || 'BANNER',
+        platform: deviceInfo.platform,
+        
+        // 디바이스 정보는 deviceInfo 객체로 래핑
+        deviceInfo: deviceInfo,
+        
+        // 페이지 및 슬롯 정보
+        pageUrl: DOMUtils.getPageInfo().url,
+        pageTitle: DOMUtils.getPageInfo().title,
+        referrer: DOMUtils.getPageInfo().referrer,
+        slotId,
+        slotPosition: DeviceInfoCollector.getSlotPosition(slot?.containerId || ''),
+        slotWidth: AdvertisementEventTracker.parseNumericValue(slot?.width),
+        slotHeight: AdvertisementEventTracker.parseNumericValue(slot?.height),
+        sessionId: deviceInfo.sessionId,
+        
+        // 성능 메트릭
+        pageLoadTime: performance.now(),
+        
+        // 추가 메타데이터
+        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',
+          headers: ApiHeaders.createForEvents(this.apiKey, eventData),
+          body: JSON.stringify(eventData),
+        }
+      );
+
+      if (this.debug) {
+        console.log(`Tracked advertisement event: ${eventType} for ad ${adId}`, eventData);
+      }
+    } catch (error) {
+      console.error('Failed to track advertisement 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/ads/basic-fraud-detector.ts

@@ -0,0 +1,191 @@
+/**
+ * BasicFraudDetector - 현실적 구현 버전
+ * 기본적인 봇 탐지 및 간단한 행동 패턴 분석
+ */
+
+export interface FraudScore {
+  score: number;           // 0-100
+  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  reasons: string[];
+}
+
+export interface BasicBrowserInfo {
+  userAgent: string;
+  language: string;
+  platform: string;
+  cookieEnabled: boolean;
+  doNotTrack: string | null;
+  timezone: string;
+  screenResolution: string;
+  viewportSize: string;
+}
+
+export class BasicFraudDetector {
+  private startTime: number;
+  private mouseEvents: number = 0;
+  private keyboardEvents: number = 0;
+  private scrollEvents: number = 0;
+  
+  constructor() {
+    this.startTime = Date.now();
+    this.initBasicTracking();
+  }
+  
+  private initBasicTracking(): void {
+    // 기본적인 사용자 상호작용 추적
+    document.addEventListener('mousemove', () => this.mouseEvents++, { passive: true });
+    document.addEventListener('keydown', () => this.keyboardEvents++, { passive: true });
+    document.addEventListener('scroll', () => this.scrollEvents++, { passive: true });
+  }
+  
+  public calculateFraudScore(): FraudScore {
+    let score = 0;
+    const reasons: string[] = [];
+    
+    // 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
+    };
+  }
+  
+  private detectWebDriver(): boolean {
+    // 기본적인 웹드라이버 탐지
+    return !!(
+      (window as any).webdriver ||
+      (navigator as any).webdriver ||
+      (window as any).__webdriver_evaluate ||
+      (window as any).__selenium_evaluate ||
+      (window as any).__webdriver_script_function ||
+      (window as any).__webdriver_script_func ||
+      (window as any).__webdriver_script_fn ||
+      (window as any).__fxdriver_evaluate ||
+      (window as any).__driver_unwrapped ||
+      (window as any).__webdriver_unwrapped ||
+      (window as any).__driver_evaluate ||
+      (window as any).__selenium_unwrapped ||
+      (window as any).__fxdriver_unwrapped
+    );
+  }
+  
+  private detectBasicHeadless(): boolean {
+    const signatures: string[] = [];
+    
+    // PhantomJS 탐지
+    if ((window as any)._phantom || (window as any).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;
+  }
+  
+  private checkBrowserEnvironment(): { score: number; reasons: string[] } {
+    let score = 0;
+    const reasons: string[] = [];
+    
+    // 언어 설정 이상
+    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 };
+  }
+  
+  private getRiskLevel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+    if (score >= 70) return 'CRITICAL';
+    if (score >= 50) return 'HIGH';
+    if (score >= 30) return 'MEDIUM';
+    return 'LOW';
+  }
+  
+  public getBrowserInfo(): BasicBrowserInfo {
+    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}`
+    };
+  }
+  
+  public destroy(): void {
+    // 이벤트 리스너 정리는 생략 (메모리 누수 방지를 위해 필요시 구현)
+  }
+}

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

@@ -1,6 +1,6 @@
-import { AdType, AdEventType } from '../types/advertisement';
-import type { AdSlot, Advertisement } from '../types/advertisement';
-import { AdRendererFactory } from '../renderers';
+import { AdType, AdEventType } from '../../types/advertisement';
+import type { AdSlot, Advertisement } from '../../types/advertisement';
+import { AdRendererFactory } from '../../renderers';
 
 /**
  * 캐러셀 슬라이더 관리 클래스
@@ -219,7 +219,7 @@ export class CarouselSliderManager {
 
       // 현재 슬라이드의 광고에 대해 노출 이벤트 추적
       if (actualIndex > 0) { // 첫 번째는 이미 loadSlot에서 추적됨
-        trackEventCallback(advertisements[actualIndex]._id, slot.id, AdEventType.IMPRESSION);
+        trackEventCallback(advertisements[actualIndex]._id, slot.id, AdEventType.VIEWABLE);
       }
     };
 

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

@@ -1,6 +1,6 @@
-import { AdType, AdEventType } from '../types/advertisement';
-import type { AdSlot, Advertisement } from '../types/advertisement';
-import { AdRendererFactory } from '../renderers';
+import { AdType, AdEventType } from '../../types/advertisement';
+import type { AdSlot, Advertisement } from '../../types/advertisement';
+import { AdRendererFactory } from '../../renderers';
 
 /**
  * 텍스트 전환 효과 관리 클래스
@@ -196,7 +196,7 @@ export class TextTransitionManager {
 
       // 현재 슬라이드의 광고에 대해 노출 이벤트 추적
       if (currentSlide > 0) { // 첫 번째는 이미 loadSlot에서 추적됨
-        trackEventCallback(advertisements[currentSlide]._id, slot.id, AdEventType.IMPRESSION);
+        trackEventCallback(advertisements[currentSlide]._id, slot.id, AdEventType.VIEWABLE);
       }
     };
 

package/src/managers/ads/viewability-tracker.ts

@@ -0,0 +1,189 @@
+/**
+ * IAB 표준 준수 viewable impression 측정
+ */
+
+export interface ViewabilityConfig {
+  threshold: number;        // 노출 비율 (0.5 = 50%)
+  minDuration: number;      // 최소 지속 시간 (ms)
+  maxMeasureTime: number;   // 최대 측정 시간 (ms)
+}
+
+export interface ViewabilityMetrics {
+  isViewable: boolean;
+  exposureTime: number;
+  maxVisibilityRatio: number;
+  firstViewableTime: number | null;
+  measureStartTime: number;
+}
+
+// 광고 타입별 IAB 표준 설정
+export const VIEWABILITY_STANDARDS: Record<string, ViewabilityConfig> = {
+  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
+  }
+};
+
+export class ViewabilityTracker {
+  private config: ViewabilityConfig;
+  private element: HTMLElement;
+  private observer: IntersectionObserver | null = null;
+  private viewabilityTimer: NodeJS.Timeout | null = null;
+  private maxVisibilityTimer: NodeJS.Timeout | null = null;
+  private startTime: number = 0;
+  private maxVisibilityRatio: number = 0;
+  private firstViewableTime: number | null = null;
+  private isViewableAchieved: boolean = false;
+  
+  private onViewableCallback?: (metrics: ViewabilityMetrics) => void;
+  
+  constructor(
+    element: HTMLElement, 
+    adType: string,
+    onViewable?: (metrics: ViewabilityMetrics) => void
+  ) {
+    this.element = element;
+    this.config = VIEWABILITY_STANDARDS[adType] || VIEWABILITY_STANDARDS.BANNER;
+    this.onViewableCallback = onViewable;
+    
+    this.startTime = performance.now();
+    this.initIntersectionObserver();
+    this.initMaxMeasureTimer();
+  }
+  
+  private initIntersectionObserver(): void {
+    // 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);
+  }
+  
+  private handleIntersection(entries: IntersectionObserverEntry[]): void {
+    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();
+      }
+    });
+  }
+  
+  private isDocumentVisible(): boolean {
+    // 단순한 문서 가시성 확인
+    return !document.hidden && document.visibilityState === 'visible';
+  }
+  
+  private startViewabilityTimer(): void {
+    if (this.viewabilityTimer || this.isViewableAchieved) return;
+    
+    if (this.firstViewableTime === null) {
+      this.firstViewableTime = performance.now();
+    }
+    
+    this.viewabilityTimer = setTimeout(() => {
+      this.onViewabilityAchieved();
+    }, this.config.minDuration);
+  }
+  
+  private stopViewabilityTimer(): void {
+    if (this.viewabilityTimer) {
+      clearTimeout(this.viewabilityTimer);
+      this.viewabilityTimer = null;
+    }
+  }
+  
+  private initMaxMeasureTimer(): void {
+    // 최대 측정 시간 후 자동 종료
+    this.maxVisibilityTimer = setTimeout(() => {
+      this.destroy();
+    }, this.config.maxMeasureTime);
+  }
+  
+  private onViewabilityAchieved(): void {
+    if (this.isViewableAchieved) return;
+    
+    this.isViewableAchieved = true;
+    const metrics = this.calculateMetrics();
+    
+    if (this.onViewableCallback) {
+      this.onViewableCallback(metrics);
+    }
+  }
+  
+  private calculateMetrics(): ViewabilityMetrics {
+    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,
+    };
+  }
+  
+  public getMetrics(): ViewabilityMetrics {
+    return this.calculateMetrics();
+  }
+  
+  public destroy(): void {
+    this.stopViewabilityTimer();
+    
+    if (this.maxVisibilityTimer) {
+      clearTimeout(this.maxVisibilityTimer);
+      this.maxVisibilityTimer = null;
+    }
+    
+    if (this.observer) {
+      this.observer.disconnect();
+      this.observer = null;
+    }
+  }
+}

package/src/managers/ads/viewable-event-tracker.ts

@@ -0,0 +1,89 @@
+/**
+ * VIEWABLE 이벤트 추적 및 중복 방지 관리 클래스
+ * - 메모리 기반 중복 확인
+ * - 세션 스토리지 기반 영구 추적
+ * - 자동 정리 기능
+ * - ViewabilityTracker와 함께 사용하여 중복 viewable 이벤트 방지
+ */
+export class ViewableEventTracker {
+  private static viewableTracker = new Map<string, number>();
+  private static readonly VIEWABLE_COOLDOWN = 300000; // 5분 쿨다운
+
+  /**
+   * 중복 viewable 이벤트 여부 확인
+   */
+  static isDuplicateViewable(adId: string, slotId: string, debug = false): boolean {
+    const key = `${adId}_${slotId}`;
+    const now = Date.now();
+    
+    // 메모리 기반 중복 확인 (새로고침 시 초기화됨)
+    const lastViewable = ViewableEventTracker.viewableTracker.get(key);
+    if (lastViewable && (now - lastViewable) < ViewableEventTracker.VIEWABLE_COOLDOWN) {
+      if (debug) {
+        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_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 viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - sessionTime)) / 1000)}s remaining`);
+        }
+        // 메모리에도 기록하여 이후 요청 최적화
+        ViewableEventTracker.viewableTracker.set(key, sessionTime);
+        return true;
+      }
+    }
+    
+    // viewable 이벤트 시점 기록 (메모리 + 세션 스토리지)
+    ViewableEventTracker.viewableTracker.set(key, now);
+    sessionStorage.setItem(sessionKey, now.toString());
+    
+    // 오래된 세션 스토리지 데이터 정리 (선택적)
+    ViewableEventTracker.cleanupOldViewables();
+    
+    return false;
+  }
+
+  /**
+   * 오래된 viewable 추적 데이터 정리
+   */
+  private static cleanupOldViewables(): void {
+    const now = Date.now();
+    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_viewable_')) {
+        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 ViewableEventTracker.viewableTracker.entries()) {
+      if ((now - timestamp) > cleanupThreshold) {
+        ViewableEventTracker.viewableTracker.delete(key);
+      }
+    }
+  }
+
+  /**
+   * 모든 추적 데이터 정리
+   */
+  static clear(): void {
+    ViewableEventTracker.viewableTracker.clear();
+  }
+}