@adstage/web-sdk 1.1.0

package/src/renderers/interstitial-renderer.ts

@@ -0,0 +1,70 @@
+import type { Advertisement, AdSlot, AdEventType } from '../types/advertisement';
+import { DOMUtils } from '../utils/dom-utils';
+import { BaseAdRenderer } from './base-renderer';
+
+/**
+ * 전면/팝업 광고 렌더러 - 핵심 콘텐츠만 표시
+ */
+export class InterstitialAdRenderer extends BaseAdRenderer {
+  render(ad: Advertisement, slot: AdSlot): HTMLElement {
+    let adElement = DOMUtils.safeCreateElement('div');
+    
+    if (!adElement) {
+      return this.createPlaceholder(slot, '전면 광고');
+    }
+    
+    // 컨테이너 스타일 적용 (불필요한 스타일 제거)
+    this.applyStyles(adElement, {
+      ...this.getBaseContainerStyles(slot),
+      display: 'flex',
+      'flex-direction': 'column',
+    });
+
+    // 우선순위: 1. 이미지, 2. 비디오, 3. 텍스트
+    if (ad.imageUrl) {
+      const img = this.createImageElement(ad.imageUrl, '', slot);
+      if (img) {
+        adElement.appendChild(img);
+      }
+    } else if (ad.videoUrl) {
+      // 이미지가 없고 비디오가 있는 경우
+      const video = this.createVideoElement(ad.videoUrl, ad, slot);
+      if (video) {
+        adElement.appendChild(video);
+      }
+    } else {
+      // 모든 콘텐츠가 없는 경우
+      return this.createPlaceholder(slot, '전면 광고');
+    }
+
+    // 클릭 이벤트 추가
+    this.addClickHandler(adElement, ad, slot);
+
+    return adElement;
+  }
+
+  /**
+   * 비디오 요소 생성
+   */
+  private createVideoElement(videoUrl: string, ad: Advertisement, slot: AdSlot): HTMLVideoElement | null {
+    const video = DOMUtils.safeCreateElement('video') as HTMLVideoElement;
+    if (!video) return null;
+    
+    video.src = videoUrl;
+    video.controls = true;
+    
+    // 비디오도 이미지와 같은 스타일 적용
+    this.applyStyles(video, this.getImageStyles(slot));
+    
+    // 비디오 이벤트 추적
+    video.addEventListener('play', () => {
+      this.trackEvent?.(ad._id, slot.id, 'VIDEO_START' as AdEventType);
+    });
+    
+    video.addEventListener('ended', () => {
+      this.trackEvent?.(ad._id, slot.id, 'VIDEO_COMPLETE' as AdEventType);
+    });
+    
+    return video;
+  }
+}

package/src/renderers/native-renderer.ts

@@ -0,0 +1,35 @@
+import type { Advertisement, AdSlot } from '../types/advertisement';
+import { DOMUtils } from '../utils/dom-utils';
+import { BaseAdRenderer } from './base-renderer';
+
+/**
+ * 네이티브 광고 렌더러 - 이미지 + textContent 표시
+ */
+export class NativeAdRenderer extends BaseAdRenderer {
+  render(ad: Advertisement, slot: AdSlot): HTMLElement {
+    const adElement = DOMUtils.safeCreateElement('div');
+    if (!adElement) {
+      return document.createElement('div');
+    }
+    
+    // 컨테이너 스타일 적용 (불필요한 스타일 제거)
+    this.applyStyles(adElement, this.getBaseContainerStyles(slot));
+
+    // 네이티브 광고는 이미지만 표시
+    if (!ad.imageUrl) {
+      // 이미지가 없는 경우 플레이스홀더 반환
+      const placeholder = this.createPlaceholder(slot, '네이티브 광고');
+      return placeholder || adElement;
+    }
+
+    // 이미지 생성 (고유 사이즈 또는 사용자 지정 크기)
+    const img = this.createImageElement(ad.imageUrl, '', slot);
+    if (img) {
+      DOMUtils.safeAppendChild(adElement, img);
+      // 클릭 이벤트 추가
+      this.addClickHandler(adElement, ad, slot);
+    }
+
+    return adElement;
+  }
+}

package/src/renderers/text-renderer.ts

@@ -0,0 +1,94 @@
+import type { Advertisement, AdSlot } from '../types/advertisement';
+import { BaseAdRenderer } from './base-renderer';
+import { DOMUtils } from '../utils/dom-utils';
+
+/**
+ * 텍스트 광고 렌더러 - textContent만 표시
+ */
+export class TextAdRenderer extends BaseAdRenderer {
+  render(ad: Advertisement, slot: AdSlot): HTMLElement {
+    let adElement = DOMUtils.safeCreateElement('div');
+    
+    if (!adElement) {
+      return this.createPlaceholder(slot, '텍스트 광고');
+    }
+    
+    // 기본 컨테이너 스타일
+    const containerStyles: Record<string, string> = {
+      ...this.getBaseContainerStyles(slot),
+      padding: '20px',
+      background: 'transparent',
+      display: 'flex',
+      'align-items': 'center',
+      'justify-content': 'center',
+      // text-align은 사용자가 설정할 수 있도록 기본값에서 제외
+      ...this.getBaseFontStyles(),
+    };
+    
+    // 사용자가 크기를 지정하지 않은 경우 컨텐츠에 맞춤
+    if (!slot.width || slot.width === 0) {
+      containerStyles.display = 'inline-flex';
+      containerStyles['white-space'] = 'nowrap';
+      containerStyles['justify-content'] = 'flex-start'; // 좌측 정렬로 변경
+    }
+    
+    // height만 자동인 경우 줄바꿈 허용
+    if ((slot.width && slot.width !== 0) && (!slot.height || slot.height === 0)) {
+      containerStyles['white-space'] = 'normal';
+      containerStyles['min-height'] = 'auto';
+      containerStyles['justify-content'] = 'flex-start'; // 좌측 정렬로 변경
+    }
+    
+    this.applyStyles(adElement, containerStyles);
+
+    // 텍스트 광고는 textContent만 표시
+    if (!ad.textContent) {
+      // 텍스트가 없는 경우 플레이스홀더 반환
+      return this.createPlaceholder(slot, '텍스트 광고');
+    }
+
+    // 텍스트 콘텐츠 생성
+    const textContent = this.createTextElement(
+      ad.textContent,
+      'div',
+      {
+        'font-size': '16px',
+        'font-weight': '500',
+        color: '#212529',
+        width: '100%', // 전체 너비 사용하여 텍스트 정렬이 적용되도록 함
+      }
+    );
+
+    if (textContent) {
+      adElement.appendChild(textContent);
+    }
+
+    // 사용자가 text-align을 지정했는지 확인하고 레이아웃 조정
+    setTimeout(() => {
+      if (!adElement || typeof window === 'undefined') return;
+      
+      const computedStyle = window.getComputedStyle(adElement);
+      const textAlign = computedStyle.textAlign;
+      
+      // 사용자가 text-align을 설정했고, width가 없는 경우
+      if (textAlign && textAlign !== 'start' && textAlign !== 'left' && (!slot.width || slot.width === 0)) {
+        // 블록 레벨로 변경하여 text-align이 제대로 작동하도록 함
+        adElement.style.display = 'block';
+        adElement.style.whiteSpace = 'normal';
+        
+        // 최소 너비 설정 (텍스트가 한 줄일 때를 위해)
+        if (textContent) {
+          const textRect = textContent.getBoundingClientRect();
+          if (textRect.width > 0) {
+            adElement.style.minWidth = `${textRect.width}px`;
+          }
+        }
+      }
+    }, 0);
+
+    // 클릭 이벤트 추가
+    this.addClickHandler(adElement, ad, slot);
+
+    return adElement;
+  }
+}

package/src/renderers/video-renderer.ts

@@ -0,0 +1,63 @@
+import type { Advertisement, AdSlot, AdEventType } from '../types/advertisement';
+import { DOMUtils } from '../utils/dom-utils';
+import { BaseAdRenderer } from './base-renderer';
+
+/**
+ * 비디오 광고 렌더러 - 비디오 또는 이미지 표시
+ */
+export class VideoAdRenderer extends BaseAdRenderer {
+  render(ad: Advertisement, slot: AdSlot): HTMLElement {
+    let adElement = DOMUtils.safeCreateElement('div');
+    
+    if (!adElement) {
+      return this.createPlaceholder(slot, '비디오 광고');
+    }
+    
+    // 컨테이너 스타일 적용 (불필요한 스타일 제거)
+    this.applyStyles(adElement, {
+      ...this.getBaseContainerStyles(slot),
+      background: '#000',
+    });
+
+    // 비디오 광고는 비디오만 표시
+    if (!ad.videoUrl) {
+      // 비디오가 없는 경우 플레이스홀더 반환
+      return this.createPlaceholder(slot, '비디오 광고');
+    }
+
+    const video = this.createVideoElement(ad.videoUrl, ad, slot);
+    if (video) {
+      adElement.appendChild(video);
+    }
+
+    // 클릭 이벤트 추가
+    this.addClickHandler(adElement, ad, slot);
+
+    return adElement;
+  }
+
+  /**
+   * 비디오 요소 생성
+   */
+  private createVideoElement(videoUrl: string, ad: Advertisement, slot: AdSlot): HTMLVideoElement | null {
+    const video = DOMUtils.safeCreateElement('video') as HTMLVideoElement;
+    if (!video) return null;
+    
+    video.src = videoUrl;
+    video.controls = true;
+    
+    // 비디오도 이미지와 같은 스타일 적용
+    this.applyStyles(video, this.getImageStyles(slot));
+    
+    // 비디오 이벤트 추적
+    video.addEventListener('play', () => {
+      this.trackEvent?.(ad._id, slot.id, 'VIDEO_START' as AdEventType);
+    });
+    
+    video.addEventListener('ended', () => {
+      this.trackEvent?.(ad._id, slot.id, 'VIDEO_COMPLETE' as AdEventType);
+    });
+    
+    return video;
+  }
+}

package/src/types/advertisement.ts

@@ -0,0 +1,197 @@
+// 광고 타입 정의
+export enum AdType {
+  BANNER = 'BANNER',
+  POPUP = 'POPUP',
+  INTERSTITIAL = 'INTERSTITIAL',
+  NATIVE = 'NATIVE',
+  VIDEO = 'VIDEO',
+  TEXT = 'TEXT',
+}
+
+// 플랫폼 정의
+export enum Platform {
+  WEB = 'WEB',
+  MOBILE = 'MOBILE',
+}
+
+// 광고 이벤트 타입
+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',
+}
+
+// 디바이스 타입
+export enum DeviceType {
+  DESKTOP = 'DESKTOP',
+  MOBILE = 'MOBILE',
+  TABLET = 'TABLET',
+}
+
+// 광고 데이터 인터페이스
+export interface Advertisement {
+  _id: string;
+  title: string;
+  description?: string;
+  adType: AdType;
+  orgId: string;
+  textContent?: string;
+  imageUrl?: string;
+  videoUrl?: string;
+  linkUrl: string;
+  startDate: Date | string;
+  endDate: Date | string;
+  status: 'ACTIVE' | 'INACTIVE' | 'PENDING';
+  order: number;
+  language: string;
+  countries: string[];
+  deviceType: DeviceType;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+}
+
+// 광고 슬롯 설정
+export interface AdSlotConfig {
+  type: AdType;
+  placement?: string;
+  width?: number;
+  height?: number;
+  autoRefresh?: number; // 초 단위
+  fallback?: string;
+  targeting?: Record<string, any>;
+  lazyLoad?: boolean;
+  responsive?: boolean;
+  className?: string;
+  style?: Partial<CSSStyleDeclaration>;
+}
+
+// 뷰어빌리티 메트릭
+/**
+ * 가시성 메트릭스
+ */
+export interface ViewabilityMetrics {
+  isViewable: boolean;
+  visibilityRatio: number;
+  duration: number;
+  impressions: number;
+  attentionTime: number;
+  scrollDepth: number;
+  completionRate: number;
+  firstView: number;
+  timestamps: {
+    firstView: number;
+    lastView: number;
+    totalViewTime: number;
+  };
+}
+
+/**
+ * 가시성 설정
+ */
+export interface ViewabilityConfiguration {
+  threshold: number;
+  minDuration: number;
+  scrollDepthTracking: boolean;
+  attentionTracking: boolean;
+}
+
+// 디바이스 정보
+export interface DeviceInfo {
+  deviceId: string;
+  platform: Platform;
+  osVersion?: string;
+  deviceModel?: string;
+  appVersion?: string;
+  sdkVersion: string;
+  viewport: {
+    width: number;
+    height: number;
+  };
+  screen: {
+    width: number;
+    height: number;
+  };
+  userAgent: string;
+  language: string;
+  timezone: string;
+  connectionType?: string;
+}
+
+// 광고 이벤트
+export interface AdEvent {
+  id: string;
+  type: AdEventType;
+  adId: string;
+  slotId: string;
+  timestamp: number;
+  deviceInfo: DeviceInfo;
+  contextInfo: {
+    pageUrl: string;
+    pageTitle: string;
+    referrer: string;
+    sessionId: string;
+    userId?: string;
+  };
+  adInfo: {
+    type: AdType;
+    placement: string;
+    creative: string;
+    campaign?: string;
+    targeting?: Record<string, any>;
+  };
+  viewabilityMetrics?: ViewabilityMetrics;
+  performanceMetrics?: {
+    pageLoadTime?: number;
+    adLoadTime?: number;
+    renderTime?: number;
+  };
+  abTestVariant?: string;
+  metadata?: Record<string, any>;
+}
+
+// 광고 슬롯 인스턴스
+export interface AdSlot {
+  id: string;
+  containerId: string;
+  adType: AdType;
+  width: number | string;  // 숫자(px) 또는 문자열(%, px 등) 지원
+  height: number | string; // 숫자(px) 또는 문자열(%, px 등) 지원
+  isLoaded: boolean;
+  isVisible: boolean;
+  refreshRate: number;
+  lazyLoad: boolean;
+  targeting: Record<string, any>;
+  element?: HTMLElement;
+  config?: AdSlotConfig;
+  advertisement?: Advertisement;
+  isViewable?: boolean;
+  impressionSent?: boolean;
+  loadTime?: number;
+  renderTime?: number;
+  events?: AdEvent[];
+  
+  // 메서드
+  load(): Promise<Advertisement | null>;
+  render(ad: Advertisement): void;
+  refresh(): Promise<void>;
+  destroy(): void;
+}
+
+// 광고 성과 지표
+export interface AdAnalytics {
+  impressions: 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

@@ -0,0 +1,173 @@
+// API 응답 타입 정의
+
+// 기본 API 응답
+export interface ApiResponse<T = any> {
+  success: boolean;
+  message?: string;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+    details?: any;
+  };
+}
+
+// 광고 목록 응답
+export interface AdvertisementsResponse {
+  advertisements: Advertisement[];
+  total: number;
+  hasMore?: boolean;
+}
+
+// 광고 요청 파라미터
+export interface AdRequest {
+  adType?: AdType;
+  language?: string;
+  deviceType?: DeviceType;
+  country?: string;
+  placement?: string;
+  limit?: number;
+  targeting?: Record<string, any>;
+}
+
+// 배치 광고 요청
+export interface BatchAdRequest {
+  requests: AdRequest[];
+  sessionId: string;
+  userId?: string;
+  contextInfo?: {
+    pageUrl: string;
+    referrer: string;
+    userAgent: string;
+  };
+}
+
+// 이벤트 추적 요청
+export interface TrackEventRequest {
+  adType: AdType;
+  platform: Platform;
+  deviceId: string;
+  pageUrl: string;
+  slotId: string;
+  sessionId: string;
+  viewabilityMetrics?: Partial<ViewabilityMetrics>;
+  performanceMetrics?: {
+    pageLoadTime?: number;
+    adLoadTime?: number;
+    renderTime?: number;
+  };
+  metadata?: Record<string, any>;
+}
+
+// 이벤트 추적 응답
+export interface TrackEventResponse {
+  success: boolean;
+  timestamp: Date | string;
+  message?: string;
+}
+
+// 광고 분석 요청
+export interface AnalyticsRequest {
+  advertisementId?: string;
+  startDate?: string;
+  endDate?: string;
+  groupBy?: 'day' | 'hour' | 'country' | 'deviceType';
+}
+
+// 광고 분석 응답
+export interface AnalyticsResponse {
+  impressions: number;
+  clicks: number;
+  hovers: number;
+  viewableImpressions: number;
+  errors: number;
+  ctr: number;
+  viewabilityRate: number;
+  breakdown?: Record<string, AdAnalytics>;
+}
+
+// 광고 추천 요청
+export interface RecommendationRequest {
+  adType?: AdType;
+  placement?: string;
+  targeting?: Record<string, any>;
+  limit?: number;
+  excludeIds?: string[];
+}
+
+// 광고 추천 응답
+export interface RecommendationResponse {
+  ads: Advertisement[];
+  context: {
+    totalAvailable: number;
+    recommendationScore: number;
+    targetingApplied: string[];
+  };
+}
+
+// API 클라이언트 설정
+export interface ApiClientConfig {
+  baseURL: string;
+  apiKey: string;
+  orgId: string;
+  timeout?: number;
+  retryCount?: number;
+  enableCache?: boolean;
+  cacheTTL?: number;
+  enableBatching?: boolean;
+  batchSize?: number;
+  batchInterval?: number;
+}
+
+// 캐시 엔트리
+export interface CacheEntry<T = any> {
+  data: T;
+  timestamp: number;
+  ttl: number;
+  hits: number;
+}
+
+// 배치 요청 큐
+export interface BatchRequest {
+  id: string;
+  request: AdRequest;
+  resolve: (value: Advertisement[]) => void;
+  reject: (error: Error) => void;
+  timestamp: number;
+}
+
+// 재시도 정책
+export interface RetryPolicy {
+  maxAttempts: number;
+  backoff: 'linear' | 'exponential';
+  delay: number;
+  maxDelay?: number;
+}
+
+// 네트워크 상태
+export interface NetworkInfo {
+  effectiveType: '2g' | '3g' | '4g' | 'slow-2g' | undefined;
+  downlink: number;
+  rtt: number;
+  saveData: boolean;
+}
+
+// 성능 메트릭
+export interface PerformanceMetrics {
+  requestDuration: number;
+  cacheHitRate: number;
+  errorRate: number;
+  averageResponseSize: number;
+  totalRequests: number;
+  totalErrors: number;
+}
+
+import type {
+    AdAnalytics,
+    AdType,
+    Advertisement,
+    DeviceType,
+    Platform,
+    ViewabilityMetrics
+} from './advertisement';
+