@adstage/web-sdk 2.5.2 → 2.6.0

package/src/modules/config/{ConfigModule.ts → config-module.ts}

@@ -21,10 +21,6 @@ export class ConfigModule implements BaseModule {
       timeout: 30000,
       debug: false,
       modules: ['ads', 'events', 'config'],
-      validateOnInit: false,
-      fallbackMode: true,
-      offlineMode: false,
-      productionMode: false,
       ...config
     };
     
@@ -39,7 +35,7 @@ export class ConfigModule implements BaseModule {
       console.log('✅ Config module initialized (sync mode)', {
         modules: this._config.modules,
         endpoint: endpoints.getBaseUrl(),
-        mode: config.productionMode ? 'production' : 'development'
+        mode: 'development'
       });
     }
   }

package/src/react/{AdStageProvider.tsx → ad-stage-provider.tsx}

@@ -4,7 +4,7 @@
  */
 
 import React, { createContext, useContext, useEffect, useState, ReactNode } from 'react';
-import AdStage from '../core/AdStage';
+import AdStage from '../core/adstage';
 import { AdStageConfig } from '../types/config';
 
 interface AdStageContextType {

package/src/react/index.ts

@@ -3,9 +3,9 @@
  * React 애플리케이션을 위한 컴포넌트와 훅들
  */
 
-export { AdStageProvider, useAdStageContext, useAdStageInstance } from './AdStageProvider';
+export { AdStageProvider, useAdStageContext, useAdStageInstance } from './ad-stage-provider';
 
 // 타입들도 재export
 export type { AdStageConfig, ModuleName, BaseModule } from '../types/config';
-export type { AdOptions } from '../modules/ads/AdsModule';
+export type { AdOptions } from '../modules/ads/ads-module';
 export type { AdType, AdEventType, Advertisement, AdSlot } from '../types/advertisement';

package/src/types/config.ts

@@ -24,17 +24,8 @@ export interface AdStageConfig {
   /** 요청 타임아웃 (ms) */
   timeout?: number;
   
-  /** 초기화시 API 키 검증 여부 (기본값: false) */
-  validateOnInit?: boolean;
-  
-  /** 네트워크 오류시 fallback 모드 사용 (기본값: true) */
-  fallbackMode?: boolean;
-  
-  /** 오프라인 모드 (기본값: false) */
-  offlineMode?: boolean;
-  
-  /** 프로덕션 모드 (엄격한 검증, 기본값: false) */
-  productionMode?: boolean;
+  /** 플레이스홀더 스타일 모드 (기본값: 'subtle') */
+  placeholderMode?: 'invisible' | 'transparent' | 'subtle' | 'minimal' | 'debug' | 'legacy';
 }
 
 /**
@@ -70,176 +61,3 @@ export interface OrganizationInfo {
   slug: string;
   settings: Record<string, any>;
 }
-
-// 메인 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://beta-api.adstage.app', // 현재 개발 단계에서는 베타 URL 사용
-  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/utils/ad-click-handler.ts

@@ -0,0 +1,155 @@
+import { AdEventType } from '../types/advertisement';
+import type { AdSlot, Advertisement } from '../types/advertisement';
+
+/**
+ * 광고 클릭 이벤트 핸들러 유틸리티
+ * 모든 광고 타입에서 일관된 클릭 이벤트 처리를 위한 공통 컴포넌트
+ */
+export class AdClickHandler {
+  /**
+   * 광고 요소에 클릭 이벤트를 추가하는 공통 함수
+   * @param element - 클릭 이벤트를 추가할 DOM 요소
+   * @param advertisement - 광고 데이터
+   * @param slot - 광고 슬롯 정보
+   * @param trackEventCallback - 이벤트 추적 콜백 함수
+   * @param debug - 디버그 모드
+   * @param adTypeLabel - 광고 타입 라벨 (로그용, 선택사항)
+   */
+  static addClickEvent(
+    element: HTMLElement,
+    advertisement: Advertisement,
+    slot: AdSlot,
+    trackEventCallback: (adId: string, slotId: string, eventType: AdEventType) => void,
+    debug: boolean = false,
+    adTypeLabel?: string
+  ): void {
+    // linkUrl이 없으면 클릭 이벤트 추가하지 않음
+    if (!advertisement.linkUrl) {
+      return;
+    }
+
+    // 커서 스타일 설정
+    element.style.cursor = 'pointer';
+
+    // 클릭 이벤트 리스너 추가
+    element.addEventListener('click', (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+
+      // 이벤트 추적
+      if (trackEventCallback) {
+        trackEventCallback(advertisement._id, slot.id, AdEventType.CLICK);
+      }
+
+      // 링크 이동
+      window.open(advertisement.linkUrl!, '_blank');
+
+      // 디버그 로그
+      if (debug) {
+        const typeLabel = adTypeLabel || String(slot.adType).toLowerCase();
+        console.log(`🔗 ${typeLabel} ad clicked: ${advertisement._id} -> ${advertisement.linkUrl}`);
+      }
+    });
+  }
+
+  /**
+   * 렌더러에서 사용할 수 있는 간편한 클릭 이벤트 추가 함수
+   * BaseAdRenderer를 상속받은 클래스에서 사용
+   * @param element - 클릭 이벤트를 추가할 DOM 요소
+   * @param advertisement - 광고 데이터
+   * @param slot - 광고 슬롯 정보
+   * @param createEventTrackingCallback - 이벤트 추적 콜백 생성 함수
+   * @param debug - 디버그 모드
+   * @param adTypeLabel - 광고 타입 라벨 (로그용, 선택사항)
+   */
+  static addClickEventForRenderer(
+    element: HTMLElement,
+    advertisement: Advertisement,
+    slot: AdSlot,
+    createEventTrackingCallback: () => (adId: string, slotId: string, eventType: AdEventType) => void,
+    debug: boolean = false,
+    adTypeLabel?: string
+  ): void {
+    // linkUrl이 없으면 클릭 이벤트 추가하지 않음
+    if (!advertisement.linkUrl) {
+      return;
+    }
+
+    // 커서 스타일 설정
+    element.style.cursor = 'pointer';
+
+    // 클릭 이벤트 리스너 추가
+    element.addEventListener('click', (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+
+      // 이벤트 추적 콜백 생성
+      const trackEventCallback = createEventTrackingCallback();
+      trackEventCallback(advertisement._id, slot.id, AdEventType.CLICK);
+
+      // 링크 이동
+      window.open(advertisement.linkUrl!, '_blank');
+
+      // 디버그 로그
+      if (debug) {
+        const typeLabel = adTypeLabel || String(slot.adType).toLowerCase();
+        console.log(`🔗 ${typeLabel} ad clicked: ${advertisement._id} -> ${advertisement.linkUrl}`);
+      }
+    });
+  }
+
+  /**
+   * 슬라이더/매니저에서 사용할 수 있는 클릭 이벤트 추가 함수
+   * 이미 trackEventCallback이 준비된 상황에서 사용
+   * @param element - 클릭 이벤트를 추가할 DOM 요소
+   * @param advertisement - 광고 데이터
+   * @param slot - 광고 슬롯 정보
+   * @param trackEventCallback - 준비된 이벤트 추적 콜백
+   * @param debug - 디버그 모드
+   * @param adTypeLabel - 광고 타입 라벨 (로그용, 선택사항)
+   */
+  static addClickEventForSlider(
+    element: HTMLElement,
+    advertisement: Advertisement,
+    slot: AdSlot,
+    trackEventCallback: (adId: string, slotId: string, eventType: AdEventType) => void,
+    debug: boolean = false,
+    adTypeLabel?: string
+  ): void {
+    this.addClickEvent(element, advertisement, slot, trackEventCallback, debug, adTypeLabel);
+  }
+
+  /**
+   * 클릭 가능한 광고인지 확인하는 헬퍼 함수
+   * @param advertisement - 광고 데이터
+   * @returns linkUrl이 있으면 true, 없으면 false
+   */
+  static isClickable(advertisement: Advertisement): boolean {
+    return Boolean(advertisement.linkUrl);
+  }
+
+  /**
+   * 여러 요소에 대해 일괄적으로 클릭 이벤트를 추가하는 함수
+   * @param elements - 클릭 이벤트를 추가할 DOM 요소들
+   * @param advertisements - 광고 데이터 배열 (elements와 같은 순서)
+   * @param slot - 광고 슬롯 정보
+   * @param trackEventCallback - 이벤트 추적 콜백
+   * @param debug - 디버그 모드
+   * @param adTypeLabel - 광고 타입 라벨 (로그용, 선택사항)
+   */
+  static addClickEventsBatch(
+    elements: HTMLElement[],
+    advertisements: Advertisement[],
+    slot: AdSlot,
+    trackEventCallback: (adId: string, slotId: string, eventType: AdEventType) => void,
+    debug: boolean = false,
+    adTypeLabel?: string
+  ): void {
+    elements.forEach((element, index) => {
+      const advertisement = advertisements[index];
+      if (advertisement) {
+        this.addClickEvent(element, advertisement, slot, trackEventCallback, debug, adTypeLabel);
+      }
+    });
+  }
+}

package/src/utils/text-ad-utils.ts

@@ -0,0 +1,37 @@
+/**
+ * 텍스트 광고 공통 유틸리티 함수들
+ */
+export class TextAdUtils {
+  /**
+   * 텍스트 광고의 기본 스타일을 생성
+   * @param isSimple 간단한 스타일 여부
+   * @returns CSS 스타일 문자열
+   */
+  static createTextAdStyles(isSimple: boolean = false): string {
+   const baseStyles = `
+      font-family: 'Arial', sans-serif;
+      text-decoration: none;
+      display: block;
+      text-align: left;
+      transition: color 0.3s ease;
+      width: 100%;
+      box-sizing: border-box;
+      overflow: visible;
+      padding-right: 2px;
+      padding-left: 2px;
+      white-space: nowrap;
+    `;
+ 
+    return baseStyles;
+  }
+
+  /**
+   * 텍스트 광고의 콘텐츠를 설정 (textContent 우선, 없으면 title)
+   * @param element 설정할 HTML 요소
+   * @param adData 광고 데이터
+   */
+  static setTextAdContent(element: HTMLElement, adData: any): void {
+    const content = adData.textContent || adData.title || '';
+    element.textContent = content;
+  }
+}

package/src/dummy/ads_dummy.json

@@ -1,84 +0,0 @@
-[
-    {
-        "_id": "68870e36bdfa1e6e54d108a5",
-        "title": "stageUp 입점 신청 - 수수료 할인 광고",
-        "description": "",
-        "adType": "BANNER",
-        "orgId": "c1cd5bb0-2f45-4e49-8e86-7ba653d3477c",
-        "textContent": "",
-        "imageUrl": "https://cmvn255e11092.edge.naverncp.com/d82ceba0-ce99-48e0-9a19-6a6c8792af31.png",
-        "videoUrl": "",
-        "linkUrl": "/partnership",
-        "startDate": "2025-07-28T00:00:00.000Z",
-        "endDate": "2025-12-31T00:00:00.000Z",
-        "status": "ACTIVE",
-        "order": 0,
-        "language": "ko",
-        "countries": [
-            "KR",
-            "US",
-            "JP",
-            "CN",
-            "DE",
-            "FR",
-            "GB",
-            "IT",
-            "ES",
-            "RU",
-            "ID",
-            "VN",
-            "TH",
-            "MY",
-            "SG",
-            "PH",
-            "IN",
-            "BR",
-            "CA",
-            "AU"
-        ],
-        "deviceType": "DESKTOP",
-        "createdAt": "2025-07-28T05:44:22.999Z",
-        "updatedAt": "2025-07-28T05:45:12.589Z"
-    },
-    {
-        "_id": "68870edbbdfa1e6e54d10901",
-        "title": "Join stageUp Today! - 간편한 통합 절차",
-        "description": "",
-        "adType": "BANNER",
-        "orgId": "c1cd5bb0-2f45-4e49-8e86-7ba653d3477c",
-        "textContent": "",
-        "imageUrl": "https://cmvn255e11092.edge.naverncp.com/550849fd-9c25-4e15-bd0f-a3efd7cff617.webp",
-        "videoUrl": "",
-        "linkUrl": "https://www.stageup.store/",
-        "startDate": "2025-07-28T00:00:00.000Z",
-        "endDate": "2025-12-31T00:00:00.000Z",
-        "status": "ACTIVE",
-        "order": 1,
-        "language": "ko",
-        "countries": [
-            "KR",
-            "US",
-            "JP",
-            "CN",
-            "DE",
-            "FR",
-            "GB",
-            "IT",
-            "ES",
-            "RU",
-            "ID",
-            "VN",
-            "TH",
-            "MY",
-            "SG",
-            "PH",
-            "IN",
-            "BR",
-            "CA",
-            "AU"
-        ],
-        "deviceType": "DESKTOP",
-        "createdAt": "2025-07-28T05:47:07.685Z",
-        "updatedAt": "2025-07-28T05:47:07.685Z"
-    }
-]