@adstage/web-sdk 1.1.0

package/src/react/components/TextAd.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { AdType } from '../../types/advertisement';
+import { AdSlot } from './AdSlot';
+
+interface TextAdProps {
+  slotId: string;
+  width?: string | number;
+  height?: string | number;
+  className?: string;
+  style?: React.CSSProperties;
+  autoSlideInterval?: number;
+  sliderEffect?: 'slide' | 'fade';
+  language?: string;
+  deviceType?: string;
+  country?: string;
+}
+
+/**
+ * 텍스트 광고 전용 컴포넌트
+ * AdSlot의 래퍼로 adType이 TEXT로 고정됨
+ */
+export const TextAd: React.FC<TextAdProps> = (props) => {
+  return <AdSlot {...props} adType={AdType.TEXT} />;
+};

package/src/react/components/VideoAd.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { AdType } from '../../types/advertisement';
+import { AdSlot } from './AdSlot';
+
+interface VideoAdProps {
+  slotId: string;
+  width?: string | number;
+  height?: string | number;
+  className?: string;
+  style?: React.CSSProperties;
+  autoSlideInterval?: number;
+  sliderEffect?: 'slide' | 'fade';
+  language?: string;
+  deviceType?: string;
+  country?: string;
+}
+
+/**
+ * 비디오 광고 전용 컴포넌트
+ * AdSlot의 래퍼로 adType이 VIDEO로 고정됨
+ */
+export const VideoAd: React.FC<VideoAdProps> = (props) => {
+  return <AdSlot {...props} adType={AdType.VIDEO} />;
+};

package/src/react/components/index.ts

@@ -0,0 +1,8 @@
+// React 컴포넌트들
+export { AdSlot } from './AdSlot';
+export { BannerAd } from './BannerAd';
+export { TextAd } from './TextAd';
+export { NativeAd } from './NativeAd';
+export { VideoAd } from './VideoAd';
+export { InterstitialAd } from './InterstitialAd';
+export { AdErrorBoundary } from './AdErrorBoundary';

package/src/react/hooks/index.ts

@@ -0,0 +1,4 @@
+// React Hook들
+export { useAdStage } from './useAdStage';
+export { useAdSlot } from './useAdSlot';
+export { useAdTracking } from './useAdTracking';

package/src/react/hooks/useAdSlot.ts

@@ -0,0 +1,83 @@
+import { useEffect, useState } from 'react';
+import { AdType } from '../../types/advertisement';
+import { useAdStage } from './useAdStage';
+
+interface UseAdSlotOptions {
+  slotId: string;
+  containerId: string;
+  adType: AdType;
+  width?: string | number;
+  height?: string | number;
+  language?: string;
+  deviceType?: string;
+  country?: string;
+  autoSlideInterval?: number;
+  sliderEffect?: 'slide' | 'fade';
+}
+
+interface UseAdSlotReturn {
+  isLoading: boolean;
+  error: string | null;
+  isCreated: boolean;
+  createSlot: () => Promise<void>;
+  resetSlot: () => void;
+}
+
+/**
+ * 광고 슬롯 생성 및 관리를 위한 Hook
+ * 컴포넌트에서 직접 슬롯을 제어하고 싶을 때 사용
+ */
+export const useAdSlot = (options: UseAdSlotOptions): UseAdSlotReturn => {
+  const { sdk } = useAdStage();
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [isCreated, setIsCreated] = useState(false);
+
+  const createSlot = async () => {
+    if (!sdk) {
+      setError('SDK not initialized');
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      await sdk.createSlot(options.slotId, options.containerId, options.adType, {
+        width: options.width,
+        height: options.height,
+        language: options.language,
+        deviceType: options.deviceType,
+        country: options.country,
+        autoSlideInterval: options.autoSlideInterval,
+        sliderEffect: options.sliderEffect,
+      });
+      setIsCreated(true);
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : '슬롯 생성 중 오류가 발생했습니다.';
+      setError(errorMessage);
+      setIsCreated(false);
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  const resetSlot = () => {
+    setIsLoading(false);
+    setError(null);
+    setIsCreated(false);
+  };
+
+  // SDK가 변경되면 상태 초기화
+  useEffect(() => {
+    resetSlot();
+  }, [sdk]);
+
+  return {
+    isLoading,
+    error,
+    isCreated,
+    createSlot,
+    resetSlot,
+  };
+};

package/src/react/hooks/useAdStage.ts

@@ -0,0 +1,14 @@
+import { useContext } from 'react';
+import { AdStageContext, type AdStageContextValue } from '../providers/AdStageProvider';
+
+/**
+ * AdStage SDK 인스턴스에 접근하기 위한 Hook
+ * AdStageProvider 내부에서만 사용 가능
+ */
+export const useAdStage = (): AdStageContextValue => {
+  const context = useContext(AdStageContext);
+  if (!context) {
+    throw new Error('useAdStage must be used within an AdStageProvider');
+  }
+  return context;
+};

package/src/react/hooks/useAdTracking.ts

@@ -0,0 +1,61 @@
+import { useCallback } from 'react';
+import { AdEventType } from '../../types/advertisement';
+import { useAdStage } from './useAdStage';
+
+interface UseAdTrackingReturn {
+  trackEvent: (adId: string, slotId: string, eventType: AdEventType) => void;
+  trackClick: (adId: string, slotId: string) => void;
+  trackImpression: (adId: string, slotId: string) => void;
+  trackView: (adId: string, slotId: string) => void;
+  trackClose: (adId: string, slotId: string) => void;
+}
+
+/**
+ * 광고 이벤트 추적을 위한 Hook
+ * 커스텀 이벤트 추적이 필요할 때 사용
+ */
+export const useAdTracking = (): UseAdTrackingReturn => {
+  const { sdk } = useAdStage();
+
+  const trackEvent = useCallback((adId: string, slotId: string, eventType: AdEventType) => {
+    if (!sdk) {
+      console.warn('SDK not initialized - cannot track event');
+      return;
+    }
+
+    try {
+      // SDK의 eventTracker에 직접 접근할 수 없으므로 
+      // 여기서는 console.log로 대체하거나 SDK에 public 메서드가 있다면 사용
+      console.log('Ad Event Tracked:', { adId, slotId, eventType });
+      
+      // 실제 구현에서는 SDK에 trackEvent 메서드가 있다면 사용
+      // sdk.trackEvent(adId, slotId, eventType);
+    } catch (err) {
+      console.error('Failed to track event:', err);
+    }
+  }, [sdk]);
+
+  const trackClick = useCallback((adId: string, slotId: string) => {
+    trackEvent(adId, slotId, AdEventType.CLICK);
+  }, [trackEvent]);
+
+  const trackImpression = useCallback((adId: string, slotId: string) => {
+    trackEvent(adId, slotId, AdEventType.IMPRESSION);
+  }, [trackEvent]);
+
+  const trackView = useCallback((adId: string, slotId: string) => {
+    trackEvent(adId, slotId, AdEventType.VIEWABLE);
+  }, [trackEvent]);
+
+  const trackClose = useCallback((adId: string, slotId: string) => {
+    trackEvent(adId, slotId, AdEventType.COMPLETED);
+  }, [trackEvent]);
+
+  return {
+    trackEvent,
+    trackClick,
+    trackImpression,
+    trackView,
+    trackClose,
+  };
+};

package/src/react/index.ts

@@ -0,0 +1,4 @@
+// React 관련 모든 exports
+export * from './components';
+export * from './hooks';
+export * from './providers';

package/src/react/providers/AdStageProvider.tsx

@@ -0,0 +1,86 @@
+import React, { createContext, useContext, useEffect, useState, ReactNode } from 'react';
+
+// 타입만 import해서 circular dependency 방지
+import type { AdStageConfig } from '../../index';
+
+// AdStageSDK 클래스 타입 정의 (런타임에는 dynamic import 사용)
+interface AdStageSDKClass {
+  init(config: AdStageConfig): AdStageSDKInstance;
+}
+
+interface AdStageSDKInstance {
+  createSlot: (...args: any[]) => Promise<void>;
+  removeSlot?: (slotId: string) => void;
+}
+
+export interface AdStageContextValue {
+  sdk: AdStageSDKInstance | null;
+  isLoading: boolean;
+  error: string | null;
+  isInitialized: boolean;
+}
+
+const AdStageContext = createContext<AdStageContextValue>({
+  sdk: null,
+  isLoading: true,
+  error: null,
+  isInitialized: false,
+});
+
+export { AdStageContext };
+
+interface AdStageProviderProps {
+  config: AdStageConfig;
+  children: ReactNode;
+  autoInit?: boolean;
+}
+
+export const AdStageProvider: React.FC<AdStageProviderProps> = ({
+  config,
+  children,
+  autoInit = true,
+}) => {
+  const [sdk, setSdk] = useState<AdStageSDKInstance | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [isInitialized, setIsInitialized] = useState(false);
+
+  useEffect(() => {
+    const initializeSDK = async () => {
+      try {
+        setIsLoading(true);
+        setError(null);
+
+        // Dynamic import를 사용해서 circular dependency 방지
+        const { AdStageSDK } = await import('../../index');
+
+        // SDK 인스턴스 생성
+        const sdkInstance = AdStageSDK.init(config);
+        
+        setSdk(sdkInstance);
+        setIsInitialized(true);
+        setIsLoading(false);
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : 'SDK 초기화 중 오류가 발생했습니다.';
+        setError(errorMessage);
+        setIsLoading(false);
+        console.error('AdStage SDK initialization failed:', err);
+      }
+    };
+
+    initializeSDK();
+  }, [config.apiKey, config.debug, autoInit]);
+
+  const value: AdStageContextValue = {
+    sdk,
+    isLoading,
+    error,
+    isInitialized,
+  };
+
+  return (
+    <AdStageContext.Provider value={value}>
+      {children}
+    </AdStageContext.Provider>
+  );
+};

package/src/react/providers/index.ts

@@ -0,0 +1,2 @@
+// React Provider
+export { AdStageProvider } from './AdStageProvider';

package/src/renderers/banner-renderer.ts

@@ -0,0 +1,35 @@
+import type { Advertisement, AdSlot } from '../types/advertisement';
+import { BaseAdRenderer } from './base-renderer';
+import { DOMUtils } from '../utils/dom-utils';
+
+/**
+ * 배너 광고 렌더러 - 이미지만 표시
+ */
+export class BannerAdRenderer extends BaseAdRenderer {
+  render(ad: Advertisement, slot: AdSlot): HTMLElement {
+    const adElement = DOMUtils.safeCreateElement('div');
+    if (!adElement) {
+      // SSR 환경에서는 기본 div 반환
+      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/base-renderer.ts

@@ -0,0 +1,207 @@
+import type { Advertisement, AdSlot, AdEventType } from '../types/advertisement';
+import { DOMUtils } from '../utils/dom-utils';
+
+/**
+ * 광고 렌더러 인터페이스
+ */
+export interface AdRenderer {
+  render(ad: Advertisement, slot: AdSlot): HTMLElement;
+}
+
+/**
+ * 이벤트 추적 콜백 타입
+ */
+export type EventTracker = (adId: string, slotId: string, eventType: AdEventType) => void;
+
+/**
+ * 기본 광고 렌더러 추상 클래스
+ */
+export abstract class BaseAdRenderer implements AdRenderer {
+  protected trackEvent?: EventTracker;
+
+  constructor(trackEvent?: EventTracker) {
+    this.trackEvent = trackEvent;
+  }
+
+  /**
+   * 광고 렌더링 (각 구현체에서 오버라이드)
+   */
+  abstract render(ad: Advertisement, slot: AdSlot): HTMLElement;
+
+  /**
+   * 공통 클릭 이벤트 핸들러 (SSR 안전)
+   */
+  protected addClickHandler(element: HTMLElement, ad: Advertisement, slot: AdSlot): void {
+    DOMUtils.safeAddEventListener(element, 'click', () => {
+      this.trackEvent?.(ad._id, slot.id, 'CLICK' as AdEventType);
+      if (ad.linkUrl) {
+        DOMUtils.safeWindowOpen(ad.linkUrl, '_blank');
+      }
+    });
+  }
+
+  /**
+   * 공통 스타일 적용 유틸리티 (SSR 안전)
+   */
+  protected applyStyles(element: HTMLElement, styles: Record<string, string>): void {
+    DOMUtils.safeApplyStyles(element, styles);
+  }
+
+  /**
+   * 크기 값 파싱 유틸리티 (px, %, number 지원)
+   */
+  protected parseSizeValue(value: number | string | undefined): string | undefined {
+    if (!value) return undefined;
+    
+    if (typeof value === 'number') {
+      return value > 0 ? `${value}px` : undefined;
+    }
+    
+    if (typeof value === 'string') {
+      const trimmed = value.trim();
+      if (!trimmed) return undefined;
+      
+      // 퍼센트 값 처리
+      if (trimmed.endsWith('%')) {
+        const percent = parseFloat(trimmed);
+        return !isNaN(percent) && percent > 0 ? trimmed : undefined;
+      }
+      
+      // px 값 처리 (px 단위 포함/미포함 모두 지원)
+      const numValue = trimmed.endsWith('px') 
+        ? parseFloat(trimmed.slice(0, -2))
+        : parseFloat(trimmed);
+        
+      return !isNaN(numValue) && numValue > 0 ? `${numValue}px` : undefined;
+    }
+    
+    return undefined;
+  }
+
+  /**
+   * 기본 컨테이너 스타일 (사용자 지정 크기만 적용)
+   */
+  protected getBaseContainerStyles(slot: AdSlot): Record<string, string> {
+    const styles: Record<string, string> = {
+      cursor: 'pointer',
+      position: 'relative',
+      overflow: 'hidden',
+    };
+    
+    // 사용자가 지정한 크기가 있을 때만 적용
+    const parsedWidth = this.parseSizeValue(slot.width);
+    const parsedHeight = this.parseSizeValue(slot.height);
+    
+    if (parsedWidth) {
+      styles.width = parsedWidth;
+    }
+    if (parsedHeight) {
+      styles.height = parsedHeight;
+    }
+    
+    return styles;
+  }
+
+  /**
+   * 이미지 스타일 (고유 사이즈 유지, 사용자 지정 크기 우선)
+   */
+  protected getImageStyles(slot?: AdSlot): Record<string, string> {
+    const styles: Record<string, string> = {
+      display: 'block',
+      'max-width': '100%',
+      height: 'auto',
+    };
+    
+    // 사용자가 컨테이너 크기를 지정한 경우에만 크기 제한
+    const parsedWidth = this.parseSizeValue(slot?.width);
+    const parsedHeight = this.parseSizeValue(slot?.height);
+    
+    if (parsedWidth && parsedHeight) {
+      styles.width = '100%';
+      styles.height = '100%';
+      styles['object-fit'] = 'cover';
+    }
+    
+    return styles;
+  }
+
+  /**
+   * 기본 폰트 스타일
+   */
+  protected getBaseFontStyles(): Record<string, string> {
+    return {
+      'font-family': 'Arial, sans-serif',
+      'line-height': '1.4',
+      'word-break': 'keep-all',
+    };
+  }
+
+  /**
+   * 이미지 요소 생성 (SSR 안전)
+   */
+  protected createImageElement(imageUrl: string, alt: string = '', slot?: AdSlot): HTMLImageElement | null {
+    const img = DOMUtils.safeCreateElement('img') as HTMLImageElement;
+    if (!img) return null;
+    
+    img.src = imageUrl;
+    img.alt = alt;
+    this.applyStyles(img, this.getImageStyles(slot));
+    return img;
+  }
+
+  /**
+   * 텍스트 요소 생성 (SSR 안전)
+   */
+  protected createTextElement(
+    text: string,
+    tag: keyof HTMLElementTagNameMap = 'div',
+    additionalStyles: Record<string, string> = {}
+  ): HTMLElement | null {
+    const element = DOMUtils.safeCreateElement(tag);
+    if (!element) return null;
+    
+    DOMUtils.safeSetTextContent(element, text);
+    this.applyStyles(element, {
+      ...this.getBaseFontStyles(),
+      ...additionalStyles,
+    });
+    return element;
+  }
+
+  /**
+   * 플레이스홀더 요소 생성
+   */
+  protected createPlaceholder(slot: AdSlot, text: string = '광고'): HTMLElement {
+    let placeholder = DOMUtils.safeCreateElement('div');
+    
+    // SSR 환경에서 DOM을 사용할 수 없는 경우, 런타임에 생성되도록 함
+    if (!placeholder) {
+      // SSR에서는 빈 div를 반환하되, 브라우저에서는 제대로 작동하도록 함
+      if (typeof document !== 'undefined') {
+        placeholder = document.createElement('div');
+      } else {
+        // SSR 환경에서는 더미 객체 반환 (타입 단언 사용)
+        placeholder = {} as HTMLElement;
+      }
+    }
+    
+    // DOM이 사용 가능한 경우에만 스타일 적용
+    if (DOMUtils.canUseDOM() && placeholder) {
+      this.applyStyles(placeholder, {
+        ...this.getBaseContainerStyles(slot),
+        background: '#f8f9fa',
+        display: 'flex',
+        'align-items': 'center',
+        'justify-content': 'center',
+        color: '#6c757d',
+        ...this.getBaseFontStyles(),
+        // 플레이스홀더는 최소 크기 보장
+        'min-width': '100px',
+        'min-height': '100px',
+      });
+      DOMUtils.safeSetTextContent(placeholder, text);
+    }
+    
+    return placeholder;
+  }
+}

package/src/renderers/index.ts

@@ -0,0 +1,71 @@
+import { AdType } from '../types/advertisement';
+import type { Advertisement, AdSlot } from '../types/advertisement';
+import type { AdRenderer, EventTracker } from './base-renderer';
+import { BannerAdRenderer } from './banner-renderer';
+import { TextAdRenderer } from './text-renderer';
+import { NativeAdRenderer } from './native-renderer';
+import { VideoAdRenderer } from './video-renderer';
+import { InterstitialAdRenderer } from './interstitial-renderer';
+
+/**
+ * 광고 렌더러 팩토리
+ * - 광고 타입에 따라 적절한 렌더러 인스턴스를 반환
+ */
+export class AdRendererFactory {
+  private static renderers = new Map<AdType, new (trackEvent?: EventTracker) => AdRenderer>();
+
+  static {
+    // 렌더러 등록
+    this.renderers.set(AdType.BANNER, BannerAdRenderer);
+    this.renderers.set(AdType.TEXT, TextAdRenderer);
+    this.renderers.set(AdType.NATIVE, NativeAdRenderer);
+    this.renderers.set(AdType.VIDEO, VideoAdRenderer);
+    this.renderers.set(AdType.INTERSTITIAL, InterstitialAdRenderer);
+    this.renderers.set(AdType.POPUP, InterstitialAdRenderer); // POPUP은 INTERSTITIAL과 동일
+  }
+
+  /**
+   * 광고 타입에 맞는 렌더러 생성
+   */
+  static createRenderer(adType: AdType, trackEvent?: EventTracker): AdRenderer {
+    const RendererClass = this.renderers.get(adType);
+    
+    if (!RendererClass) {
+      console.warn(`No renderer found for ad type: ${adType}, falling back to Banner renderer`);
+      return new BannerAdRenderer(trackEvent);
+    }
+
+    return new RendererClass(trackEvent);
+  }
+
+  /**
+   * 광고 렌더링 (편의 메서드)
+   */
+  static render(ad: Advertisement, slot: AdSlot, trackEvent?: EventTracker): HTMLElement {
+    const renderer = this.createRenderer(slot.adType, trackEvent);
+    return renderer.render(ad, slot);
+  }
+
+  /**
+   * 사용 가능한 렌더러 타입 목록
+   */
+  static getSupportedAdTypes(): AdType[] {
+    return Array.from(this.renderers.keys());
+  }
+
+  /**
+   * 커스텀 렌더러 등록
+   */
+  static registerRenderer(adType: AdType, RendererClass: new (trackEvent?: EventTracker) => AdRenderer): void {
+    this.renderers.set(adType, RendererClass);
+  }
+}
+
+// 개별 렌더러들 export
+export { BannerAdRenderer } from './banner-renderer';
+export { TextAdRenderer } from './text-renderer';
+export { NativeAdRenderer } from './native-renderer';
+export { VideoAdRenderer } from './video-renderer';
+export { InterstitialAdRenderer } from './interstitial-renderer';
+export { BaseAdRenderer } from './base-renderer';
+export type { AdRenderer, EventTracker } from './base-renderer';