@adstage/web-sdk 1.1.0

package/src/types/config.ts

@@ -0,0 +1,174 @@
+// SDK 설정 타입 정의
+
+// 메인 SDK 설정
+/**
+ * SDK 설정
+ */
+export interface SDKConfig {
+  clientId: string;
+  baseUrl: string;
+  debug?: boolean;
+  batchSize?: number;
+  retryCount?: number;
+  timeout?: number;
+  cache?: {
+    enabled: boolean;
+    maxSize?: number;
+    ttl?: number;
+  };
+  viewability?: {
+    threshold?: number;
+    minDuration?: number;
+    scrollDepthTracking?: boolean;
+    attentionTracking?: boolean;
+  };
+}
+
+// 환경별 설정
+export interface EnvironmentConfig {
+  production: Partial<SDKConfig>;
+  development: Partial<SDKConfig>;
+  test: Partial<SDKConfig>;
+}
+
+// 로깅 설정
+export interface LoggingConfig {
+  level: 'debug' | 'info' | 'warn' | 'error' | 'silent';
+  enableConsole?: boolean;
+  enableRemote?: boolean;
+  remoteEndpoint?: string;
+  maxLogSize?: number;
+  enablePerformanceLogs?: boolean;
+}
+
+// 뷰어빌리티 엔진 설정
+export interface ViewabilityConfig {
+  threshold: number; // 0-1 (기본값: 0.5)
+  timeThreshold: number; // 밀리초 (기본값: 1000)
+  enableIABStandard?: boolean;
+  enableAttentionTracking?: boolean;
+  enableScrollTracking?: boolean;
+  intersectionThresholds?: number[];
+}
+
+// 렌더링 엔진 설정
+export interface RenderingConfig {
+  enableLazyLoading?: boolean;
+  lazyLoadThreshold?: number;
+  enableResponsive?: boolean;
+  breakpoints?: {
+    mobile: number;
+    tablet: number;
+    desktop: number;
+  };
+  enableAnimation?: boolean;
+  enableTemplating?: boolean;
+  templateEngine?: 'mustache' | 'handlebars' | 'custom';
+}
+
+// 타겟팅 설정
+export interface TargetingConfig {
+  enableGeoTargeting?: boolean;
+  enableDeviceTargeting?: boolean;
+  enableBehavioralTargeting?: boolean;
+  enableContextualTargeting?: boolean;
+  enableTimeTargeting?: boolean;
+  enableFrequencyCapping?: boolean;
+  maxFrequency?: number;
+  frequencyWindow?: number; // 시간 단위 (시간)
+}
+
+// A/B 테스트 설정
+export interface ABTestConfig {
+  enableABTesting?: boolean;
+  defaultVariant?: string;
+  variantSelection?: 'random' | 'hash' | 'user-agent';
+  persistVariant?: boolean;
+  variantStorageKey?: string;
+}
+
+// 스타일 설정
+export interface StyleConfig {
+  enableCustomCSS?: boolean;
+  theme?: 'light' | 'dark' | 'auto';
+  borderRadius?: number;
+  shadows?: boolean;
+  animations?: {
+    fadeIn?: boolean;
+    slideIn?: boolean;
+    duration?: number;
+    easing?: string;
+  };
+  responsive?: {
+    mobile?: Partial<CSSStyleDeclaration>;
+    tablet?: Partial<CSSStyleDeclaration>;
+    desktop?: Partial<CSSStyleDeclaration>;
+  };
+}
+
+// 통합 설정 (모든 설정 포함)
+export interface AdstageConfig extends SDKConfig {
+  logging?: LoggingConfig;
+  viewability?: ViewabilityConfig;
+  rendering?: RenderingConfig;
+  targeting?: TargetingConfig;
+  abTest?: ABTestConfig;
+  styling?: StyleConfig;
+  environment?: keyof EnvironmentConfig;
+}
+
+// 설정 검증 결과
+export interface ConfigValidationResult {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+  sanitizedConfig: AdstageConfig;
+}
+
+// 기본 설정 값들
+export const DEFAULT_CONFIG: Required<SDKConfig> = {
+  clientId: '',
+  baseUrl: 'https://api.adstage.io',
+  debug: false,
+  batchSize: 10,
+  retryCount: 3,
+  timeout: 10000,
+  
+  cache: {
+    enabled: true,
+    maxSize: 100,
+    ttl: 300000,
+  },
+  
+  viewability: {
+    threshold: 0.5,
+    minDuration: 1000,
+    scrollDepthTracking: true,
+    attentionTracking: true,
+  },
+};
+
+// 환경별 기본 설정
+export const ENVIRONMENT_DEFAULTS: EnvironmentConfig = {
+  production: {
+    debug: false,
+    cache: {
+      enabled: true,
+    },
+    timeout: 10000,
+  },
+  development: {
+    debug: true,
+    cache: {
+      enabled: false,
+    },
+    timeout: 30000,
+  },
+  test: {
+    debug: false,
+    cache: {
+      enabled: false,
+    },
+    timeout: 5000,
+  },
+};

package/src/types/events.ts

@@ -0,0 +1,60 @@
+// 이벤트 및 추적 관련 타입
+export interface SessionInfo {
+  sessionId: string;
+  userId?: string;
+  startTime: number;
+  lastActivity: number;
+  pageViews: number;
+  totalAdViews: number;
+  totalClicks: number;
+}
+
+// 오프라인 저장소
+export interface OfflineEventStore {
+  events: AdEvent[];
+  maxSize: number;
+  compressionEnabled: boolean;
+}
+
+// 성능 모니터링
+export interface PerformanceMonitor {
+  metrics: {
+    sdkLoadTime: number;
+    averageAdLoadTime: number;
+    memoryUsage: number;
+    errorRate: number;
+    cacheHitRate: number;
+  };
+  alerts: PerformanceAlert[];
+}
+
+export interface PerformanceAlert {
+  type: 'warning' | 'error' | 'critical';
+  message: string;
+  timestamp: number;
+  metric: string;
+  value: number;
+  threshold: number;
+}
+
+// 에러 타입
+export enum ErrorType {
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  API_ERROR = 'API_ERROR',
+  RENDER_ERROR = 'RENDER_ERROR',
+  CONFIG_ERROR = 'CONFIG_ERROR',
+  TRACKING_ERROR = 'TRACKING_ERROR',
+  VIEWABILITY_ERROR = 'VIEWABILITY_ERROR',
+  PERMISSION_ERROR = 'PERMISSION_ERROR',
+  TIMEOUT_ERROR = 'TIMEOUT_ERROR',
+}
+
+export interface SDKError extends Error {
+  type: ErrorType;
+  code: string;
+  context?: any;
+  timestamp: number;
+  retryable: boolean;
+}
+
+import type { AdEvent } from './advertisement';

package/src/types/index.ts

@@ -0,0 +1,6 @@
+// 타입 정의 통합 인덱스
+export * from './advertisement';
+export * from './api';
+export * from './config';
+export * from './events';
+

package/src/utils/dom-utils.ts

@@ -0,0 +1,237 @@
+/**
+ * SSR 안전한 DOM API 래퍼 클래스
+ * 서버사이드 렌더링 환경에서 DOM API 접근 시 오류를 방지합니다.
+ */
+export class DOMUtils {
+  /**
+   * 브라우저 환경 여부 체크
+   */
+  static isBrowser(): boolean {
+    return typeof window !== 'undefined' && typeof document !== 'undefined';
+  }
+
+  /**
+   * SSR 환경 여부 체크
+   */
+  static isSSR(): boolean {
+    return !this.isBrowser();
+  }
+
+  /**
+   * DOM 사용 가능 여부 체크
+   */
+  static canUseDOM(): boolean {
+    return this.isBrowser() && document.readyState !== undefined;
+  }
+
+  /**
+   * 안전한 getElementById
+   */
+  static safeGetElementById(id: string): HTMLElement | null {
+    if (!this.canUseDOM()) return null;
+    return document.getElementById(id);
+  }
+
+  /**
+   * 안전한 querySelector
+   */
+  static safeQuerySelector(selector: string): HTMLElement | null {
+    if (!this.canUseDOM()) return null;
+    return document.querySelector(selector);
+  }
+
+  /**
+   * 안전한 querySelectorAll
+   */
+  static safeQuerySelectorAll(selector: string): HTMLElement[] {
+    if (!this.canUseDOM()) return [];
+    return Array.from(document.querySelectorAll(selector)) as HTMLElement[];
+  }
+
+  /**
+   * 안전한 createElement
+   */
+  static safeCreateElement(tagName: string): HTMLElement | null {
+    if (!this.canUseDOM()) return null;
+    return document.createElement(tagName);
+  }
+
+  /**
+   * 안전한 addEventListener
+   */
+  static safeAddEventListener(
+    element: HTMLElement | null,
+    event: string,
+    handler: EventListener,
+    options?: boolean | AddEventListenerOptions
+  ): void {
+    if (!this.canUseDOM() || !element) return;
+    element.addEventListener(event, handler, options);
+  }
+
+  /**
+   * 안전한 removeEventListener
+   */
+  static safeRemoveEventListener(
+    element: HTMLElement | null,
+    event: string,
+    handler: EventListener,
+    options?: boolean | EventListenerOptions
+  ): void {
+    if (!this.canUseDOM() || !element) return;
+    element.removeEventListener(event, handler, options);
+  }
+
+  /**
+   * 안전한 window 속성 접근
+   */
+  static getWindowProperty<T>(property: keyof Window, defaultValue: T): T {
+    if (!this.isBrowser()) return defaultValue;
+    return (window[property] as T) ?? defaultValue;
+  }
+
+  /**
+   * 안전한 document 속성 접근
+   */
+  static getDocumentProperty<T>(property: keyof Document, defaultValue: T): T {
+    if (!this.canUseDOM()) return defaultValue;
+    return (document[property] as T) ?? defaultValue;
+  }
+
+  /**
+   * 안전한 window.open
+   */
+  static safeWindowOpen(url: string, target?: string, features?: string): Window | null {
+    if (!this.isBrowser()) return null;
+    return window.open(url, target, features);
+  }
+
+  /**
+   * 안전한 getComputedStyle
+   */
+  static safeGetComputedStyle(element: HTMLElement): CSSStyleDeclaration | null {
+    if (!this.isBrowser() || !element) return null;
+    return window.getComputedStyle(element);
+  }
+
+  /**
+   * DOM Ready 상태 체크
+   */
+  static isDOMReady(): boolean {
+    if (!this.canUseDOM()) return false;
+    return document.readyState !== 'loading';
+  }
+
+  /**
+   * DOM Ready 대기 (SSR 안전)
+   */
+  static waitForDOM(): Promise<void> {
+    return new Promise((resolve) => {
+      if (!this.canUseDOM()) {
+        resolve(); // SSR 환경에서는 즉시 resolve
+        return;
+      }
+
+      if (this.isDOMReady()) {
+        resolve();
+      } else {
+        this.safeAddEventListener(document as any, 'DOMContentLoaded', () => resolve());
+      }
+    });
+  }
+
+  /**
+   * 안전한 스타일 적용
+   */
+  static safeApplyStyles(element: HTMLElement | null, styles: Record<string, string>): void {
+    if (!this.canUseDOM() || !element) return;
+    
+    Object.entries(styles).forEach(([property, value]) => {
+      element.style.setProperty(property, value);
+    });
+  }
+
+  /**
+   * 안전한 클래스 추가
+   */
+  static safeAddClass(element: HTMLElement | null, className: string): void {
+    if (!this.canUseDOM() || !element) return;
+    element.classList.add(className);
+  }
+
+  /**
+   * 안전한 클래스 제거
+   */
+  static safeRemoveClass(element: HTMLElement | null, className: string): void {
+    if (!this.canUseDOM() || !element) return;
+    element.classList.remove(className);
+  }
+
+  /**
+   * 안전한 텍스트 콘텐츠 설정
+   */
+  static safeSetTextContent(element: HTMLElement | null, text: string): void {
+    if (!this.canUseDOM() || !element) return;
+    element.textContent = text;
+  }
+
+  /**
+   * 안전한 HTML 콘텐츠 설정
+   */
+  static safeSetInnerHTML(element: HTMLElement | null, html: string): void {
+    if (!this.canUseDOM() || !element) return;
+    element.innerHTML = html;
+  }
+
+  /**
+   * 안전한 자식 요소 추가
+   */
+  static safeAppendChild(parent: HTMLElement | null, child: HTMLElement | null): void {
+    if (!this.canUseDOM() || !parent || !child) return;
+    parent.appendChild(child);
+  }
+
+  /**
+   * 안전한 자식 요소 제거
+   */
+  static safeRemoveChild(parent: HTMLElement | null, child: HTMLElement | null): void {
+    if (!this.canUseDOM() || !parent || !child) return;
+    parent.removeChild(child);
+  }
+
+  /**
+   * 현재 페이지 정보 가져오기 (SSR 안전)
+   */
+  static getPageInfo() {
+    return {
+      url: this.getWindowProperty('location', { href: '' }).href,
+      title: this.getDocumentProperty('title', ''),
+      referrer: this.getDocumentProperty('referrer', ''),
+    };
+  }
+
+  /**
+   * 뷰포트 정보 가져오기 (SSR 안전)
+   */
+  static getViewportInfo() {
+    return {
+      width: this.getWindowProperty('innerWidth', 0),
+      height: this.getWindowProperty('innerHeight', 0),
+      pixelRatio: this.getWindowProperty('devicePixelRatio', 1),
+    };
+  }
+
+  /**
+   * 스크롤 정보 가져오기 (SSR 안전)
+   */
+  static getScrollInfo() {
+    const scrollTop = this.canUseDOM() 
+      ? (window.pageYOffset || document.documentElement.scrollTop)
+      : 0;
+    
+    return {
+      scrollTop,
+      scrollLeft: this.getWindowProperty('pageXOffset', 0),
+    };
+  }
+}

package/src/utils/sdk-utils.ts

@@ -0,0 +1,134 @@
+/**
+ * SDK 유틸리티 함수 모음
+ * - DOM 요소 속성 처리
+ * - 자동 슬롯 검색
+ * - 기타 헬퍼 함수들
+ */
+export class SDKUtils {
+  /**
+   * HTML 요소에서 속성값 가져오기 (data- 프리픽스 선택적)
+   */
+  static getElementAttribute(element: HTMLElement, attrName: string): string | undefined {
+    // 1. data- 프리픽스가 있는 경우 우선
+    const dataAttr = element.dataset[attrName];
+    if (dataAttr) return dataAttr;
+    
+    // 2. 직접 속성 확인
+    const directAttr = element.getAttribute(attrName);
+    if (directAttr) return directAttr;
+    
+    // 3. 케밥 케이스로 확인 (ad-type -> adType)
+    const kebabAttr = element.getAttribute(attrName.replace(/[A-Z]/g, '-$&').toLowerCase());
+    if (kebabAttr) return kebabAttr;
+    
+    return undefined;
+  }
+
+  /**
+   * DOM에서 자동 슬롯 요소 찾기 (SSR 안전)
+   */
+  static findAutoSlotElements(): HTMLElement[] {
+    if (typeof document === 'undefined') return [];
+    const elements = document.querySelectorAll('[data-adstage], [adstage]');
+    return Array.from(elements) as HTMLElement[];
+  }
+
+  /**
+   * 요소에서 슬롯 정보 추출
+   */
+  static extractSlotInfo(element: HTMLElement): {
+    slotId: string | null;
+    adType: string;
+    width: string | undefined;
+    height: string | undefined;
+    language: string | undefined;
+    deviceType: string | undefined;
+    country: string | undefined;
+    sliderEffect: string | undefined;
+  } {
+    // 슬롯 ID 가져오기
+    const slotId = SDKUtils.getElementAttribute(element, 'adstage');
+    
+    // 광고 타입 가져오기
+    const adType = SDKUtils.getElementAttribute(element, 'adType') || 
+                   SDKUtils.getElementAttribute(element, 'ad-type') || 
+                   'BANNER';
+    
+    // 크기 정보 가져오기 (다양한 형태 지원)
+    const width = SDKUtils.getElementAttribute(element, 'width');
+    const height = SDKUtils.getElementAttribute(element, 'height');
+    
+    // 기타 옵션들
+    const language = SDKUtils.getElementAttribute(element, 'language');
+    const deviceType = SDKUtils.getElementAttribute(element, 'deviceType') ||
+                      SDKUtils.getElementAttribute(element, 'device-type');
+    const country = SDKUtils.getElementAttribute(element, 'country');
+    const sliderEffect = SDKUtils.getElementAttribute(element, 'sliderEffect') ||
+                        SDKUtils.getElementAttribute(element, 'slider-effect');
+
+    return {
+      slotId: slotId || null,
+      adType,
+      width,
+      height,
+      language,
+      deviceType,
+      country,
+      sliderEffect,
+    };
+  }
+
+  /**
+   * AdType enum 값으로 변환
+   */
+  static parseAdType(adTypeStr: string, AdType: any): any {
+    return AdType[adTypeStr as keyof typeof AdType] || AdType.BANNER;
+  }
+
+  /**
+   * 브라우저 환경 체크
+   */
+  static isBrowser(): boolean {
+    return typeof window !== 'undefined';
+  }
+
+  /**
+   * SSR 환경 체크  
+   */
+  static isSSR(): boolean {
+    return typeof window === 'undefined';
+  }
+
+  /**
+   * DOM 사용 가능 체크
+   */
+  static canUseDOM(): boolean {
+    return !this.isSSR() && typeof document !== 'undefined';
+  }
+
+  /**
+   * DOM 로드 완료 체크 (SSR 안전)
+   */
+  static isDOMReady(): boolean {
+    if (!this.canUseDOM()) return false;
+    return document.readyState !== 'loading';
+  }
+
+  /**
+   * DOM 로드 완료 대기 (SSR 안전)
+   */
+  static waitForDOM(): Promise<void> {
+    return new Promise((resolve) => {
+      if (!this.canUseDOM()) {
+        resolve(); // SSR 환경에서는 즉시 resolve
+        return;
+      }
+
+      if (SDKUtils.isDOMReady()) {
+        resolve();
+      } else {
+        document.addEventListener('DOMContentLoaded', () => resolve());
+      }
+    });
+  }
+}