@adstage/web-sdk 1.1.0

package/src/managers/slider-manager.ts

@@ -0,0 +1,405 @@
+import { AdType, AdEventType } from '../types/advertisement';
+import type { AdSlot, Advertisement } from '../types/advertisement';
+import { AdRendererFactory } from '../renderers';
+
+/**
+ * 슬라이더 관리 클래스
+ * - 다중 광고 슬라이더 생성 및 관리
+ * - 무한 루프 슬라이더 지원
+ * - 터치 제스처 및 자동 슬라이드 기능
+ */
+export class SliderManager {
+  /**
+   * 슬라이더 컨테이너 생성
+   */
+  static createSliderContainer(
+    slot: AdSlot,
+    advertisements: Advertisement[],
+    options: any,
+    trackEventCallback: (adId: string, slotId: string, eventType: AdEventType) => void
+  ): HTMLElement {
+    const sliderWrapper = document.createElement('div');
+    sliderWrapper.className = 'adstage-slider-wrapper';
+    
+    // 사용자 지정 크기가 있으면 적용, 없으면 콘텐츠 크기에 맞춤
+    const containerStyles: Record<string, string> = {
+      position: 'relative',
+      overflow: 'hidden',
+    };
+    
+    // 사용자가 크기를 지정한 경우
+    if (slot.width && slot.width !== 0) {
+      let width: string;
+      if (typeof slot.width === 'string') {
+        // 문자열인 경우 px 단위가 있는지 확인
+        width = slot.width.includes('px') || slot.width.includes('%') ? slot.width : `${slot.width}px`;
+      } else {
+        // 숫자인 경우 px 단위 추가
+        width = `${slot.width}px`;
+      }
+      containerStyles.width = width;
+      containerStyles.display = 'inline-block'; // 지정된 크기에 맞춤 (좌측 정렬)
+    } else {
+      // 컨텐츠 크기에 맞춤
+      containerStyles.display = 'inline-block';
+    }
+    
+    if (slot.height && slot.height !== 0) {
+      const height = typeof slot.height === 'string' ? slot.height : `${slot.height}px`;
+      containerStyles.height = height;
+    }
+    
+    // 스타일 적용
+    Object.entries(containerStyles).forEach(([key, value]) => {
+      sliderWrapper.style.setProperty(key, value);
+    });
+    
+    // 크기 측정 (width나 height가 설정되지 않은 경우)
+    const needsWidthMeasurement = !slot.width || slot.width === 0;
+    const needsHeightMeasurement = !slot.height || slot.height === 0;
+    
+    if (needsWidthMeasurement || needsHeightMeasurement) {
+      const measureContainer = document.createElement('div');
+      measureContainer.style.cssText = `
+        position: absolute;
+        visibility: hidden;
+        white-space: nowrap;
+        top: -9999px;
+        left: -9999px;
+      `;
+      
+      // width가 설정되어 있으면 측정 컨테이너에도 적용
+      if (!needsWidthMeasurement && slot.width) {
+        let width: string;
+        if (typeof slot.width === 'string') {
+          width = slot.width.includes('px') || slot.width.includes('%') ? slot.width : `${slot.width}px`;
+        } else {
+          width = `${slot.width}px`;
+        }
+        measureContainer.style.width = width;
+        measureContainer.style.whiteSpace = 'normal'; // width가 있으면 줄바꿈 허용
+      }
+      
+      document.body.appendChild(measureContainer);
+      
+      let maxWidth = 0;
+      let maxHeight = 0;
+      
+      // 모든 광고의 크기를 측정하여 최대 크기 찾기
+      advertisements.forEach(ad => {
+        const measureAdElement = AdRendererFactory.render(
+          ad,
+          slot,
+          trackEventCallback
+        );
+        measureContainer.appendChild(measureAdElement);
+        
+        const rect = measureAdElement.getBoundingClientRect();
+        if (rect.width > maxWidth) maxWidth = rect.width;
+        if (rect.height > maxHeight) maxHeight = rect.height;
+        
+        // 측정 후 요소 제거
+        measureContainer.removeChild(measureAdElement);
+      });
+      
+      // 측정된 최대 크기로 래퍼 크기 설정
+      if (needsWidthMeasurement && maxWidth > 0) {
+        sliderWrapper.style.width = `${maxWidth}px`;
+        containerStyles.width = `${maxWidth}px`;
+      }
+      
+      if (needsHeightMeasurement && maxHeight > 0) {
+        sliderWrapper.style.height = `${maxHeight}px`;
+        containerStyles.height = `${maxHeight}px`;
+      }
+      
+      // 측정 컨테이너 제거
+      document.body.removeChild(measureContainer);
+    }
+    // 무한 루프를 위해 첫 번째 슬라이드를 마지막에 복사
+    const extendedAds = [...advertisements, advertisements[0]];
+
+    // 슬라이드 컨테이너
+    const slideContainer = document.createElement('div');
+    slideContainer.className = 'adstage-slide-container';
+    
+    // 슬라이드 컨테이너 스타일 - 항상 기본 설정 적용
+    const slideContainerStyles: Record<string, string> = {
+      display: 'flex',
+      transition: 'transform 0.4s ease-out',
+      width: `${extendedAds.length * 100}%`,
+    };
+    
+    if (slot.height && slot.height !== 0) {
+      slideContainerStyles.height = '100%';
+    }
+    
+    Object.entries(slideContainerStyles).forEach(([key, value]) => {
+      slideContainer.style.setProperty(key, value);
+    });
+
+    // 각 광고를 슬라이드로 생성 (복사된 첫 번째 포함)
+    extendedAds.forEach((ad, index) => {
+      const slideElement = document.createElement('div');
+      slideElement.className = 'adstage-slide';
+      
+      // 슬라이드 스타일 설정 - 항상 균등 분할
+      const slideStyles: Record<string, string> = {
+        width: `${100 / extendedAds.length}%`,
+        'flex-shrink': '0',
+        display: 'flex',
+        'align-items': 'center',
+        'justify-content': 'center'
+      };
+      
+      if (slot.height && slot.height !== 0) {
+        slideStyles.height = '100%';
+      }
+      
+      Object.entries(slideStyles).forEach(([key, value]) => {
+        slideElement.style.setProperty(key, value);
+      });
+
+      // 광고 렌더링
+      const adElement = AdRendererFactory.render(
+        ad,
+        slot,
+        trackEventCallback
+      );
+      
+      slideElement.appendChild(adElement);
+      slideContainer.appendChild(slideElement);
+    });
+
+    // 텍스트 광고인지 확인 (모든 광고가 텍스트 타입인 경우)
+    const isAllTextAds = advertisements.every(ad => ad.adType === AdType.TEXT);
+    
+    // 무채색 도트 인디케이터 생성 (원본 광고 수만큼) - 텍스트 광고가 아닐 때만
+    const dotContainer = isAllTextAds ? null : SliderManager.createMinimalDotIndicator(advertisements.length);
+    
+    // 슬라이더 상태 관리
+    let currentSlide = 0;
+    const totalSlides = advertisements.length;
+    const autoSlideInterval = (options?.autoSlideInterval || 3) * 1000; // 기본 3초
+
+    // 슬라이드 이동 함수 (무한 루프 지원)
+    const moveToSlide = (index: number, instant = false) => {
+      currentSlide = index;
+      
+      // 애니메이션 임시 비활성화 (무한 루프용)
+      if (instant) {
+        slideContainer.style.transition = 'none';
+      } else {
+        slideContainer.style.transition = 'transform 0.4s ease-out';
+      }
+      
+      // 항상 퍼센트 기반으로 이동
+      slideContainer.style.transform = `translateX(-${(100 / extendedAds.length) * currentSlide}%)`;
+      
+      // 도트 업데이트 (무채색 스타일) - 실제 광고 인덱스 기준, 텍스트 광고가 아닐 때만
+      const actualIndex = currentSlide === totalSlides ? 0 : currentSlide;
+      if (dotContainer) {
+        const dots = dotContainer.querySelectorAll('.adstage-dot');
+        dots.forEach((dot: Element, i: number) => {
+          const dotElement = dot as HTMLElement;
+          if (i === actualIndex) {
+            dotElement.classList.add('active');
+            dotElement.style.background = '#666666';
+            dotElement.style.borderColor = '#666666';
+            dotElement.style.opacity = '1';
+          } else {
+            dotElement.classList.remove('active');
+            dotElement.style.background = 'transparent';
+            dotElement.style.borderColor = '#cccccc';
+            dotElement.style.opacity = '0.7';
+          }
+        });
+      }
+
+      // 현재 슬라이드의 광고에 대해 노출 이벤트 추적
+      if (actualIndex > 0) { // 첫 번째는 이미 loadSlot에서 추적됨
+        trackEventCallback(advertisements[actualIndex]._id, slot.id, AdEventType.IMPRESSION);
+      }
+    };
+
+    // 무한 루프 처리 함수
+    const handleInfiniteLoop = () => {
+      if (currentSlide === totalSlides) {
+        // 복사된 첫 번째 슬라이드에 도달하면 즉시 원본 첫 번째로 이동
+        setTimeout(() => {
+          moveToSlide(0, true); // 애니메이션 없이 즉시 이동
+        }, 400); // transition 시간과 맞춤
+      }
+    };
+
+    // 도트 클릭 이벤트 (텍스트 광고가 아닐 때만)
+    if (dotContainer) {
+      const dots = dotContainer.querySelectorAll('.adstage-dot');
+      dots.forEach((dot: Element, index: number) => {
+        dot.addEventListener('click', () => moveToSlide(index));
+      });
+    }
+
+    // 자동 슬라이드 (한 방향으로만 무한 진행)
+    let autoSlideTimer = setInterval(() => {
+      const nextIndex = currentSlide + 1;
+      moveToSlide(nextIndex);
+      handleInfiniteLoop();
+    }, autoSlideInterval);
+
+    // 마우스 호버 시 자동 슬라이드 일시정지
+    sliderWrapper.addEventListener('mouseenter', () => {
+      clearInterval(autoSlideTimer);
+    });
+
+    sliderWrapper.addEventListener('mouseleave', () => {
+      autoSlideTimer = setInterval(() => {
+        const nextIndex = currentSlide + 1;
+        moveToSlide(nextIndex);
+        handleInfiniteLoop();
+      }, autoSlideInterval);
+    });
+
+    // 터치 제스처 지원 수정 (무한 루프 지원)
+    SliderManager.addTouchSupport(slideContainer, moveToSlide, () => currentSlide, totalSlides, handleInfiniteLoop);
+
+    // 요소들 조립 (화살표 제거, 도트는 텍스트 광고가 아닐 때만 추가)
+    sliderWrapper.appendChild(slideContainer);
+    if (dotContainer) {
+      sliderWrapper.appendChild(dotContainer);
+    }
+
+    // 첫 번째 도트 활성화
+    moveToSlide(0);
+
+    // 사용자가 크기를 지정하지 않은 경우, 첫 번째 슬라이드 크기에 맞춰 래퍼 크기 동적 조정
+    if (!slot.width || slot.width === 0) {
+      // DOM 렌더링 후 크기 측정
+      setTimeout(() => {
+        const firstSlide = slideContainer.children[0] as HTMLElement;
+        if (firstSlide) {
+          const firstAdElement = firstSlide.children[0] as HTMLElement;
+          if (firstAdElement) {
+            const rect = firstAdElement.getBoundingClientRect();
+            sliderWrapper.style.width = `${rect.width}px`;
+            if (!slot.height || slot.height === 0) {
+              sliderWrapper.style.height = `${rect.height}px`;
+            }
+            
+            // 크기 조정 후 overflow hidden 재적용
+            sliderWrapper.style.overflow = 'hidden';
+          }
+        }
+      }, 10);
+    }
+
+    return sliderWrapper;
+  }
+
+  /**
+   * 무채색 미니멀 도트 인디케이터 생성
+   */
+  private static createMinimalDotIndicator(count: number): HTMLElement {
+    const dotContainer = document.createElement('div');
+    dotContainer.className = 'adstage-dots';
+    dotContainer.style.cssText = `
+      position: absolute;
+      bottom: 15px;
+      left: 50%;
+      transform: translateX(-50%);
+      display: flex;
+      gap: 12px;
+      z-index: 3;
+      padding: 8px 16px;
+      border-radius: 20px;
+      background: rgba(255, 255, 255, 0.1);
+      backdrop-filter: blur(10px);
+    `;
+
+    for (let i = 0; i < count; i++) {
+      const dot = document.createElement('button');
+      dot.className = 'adstage-dot';
+      dot.style.cssText = `
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        border: 1px solid #cccccc;
+        background: transparent;
+        cursor: pointer;
+        transition: all 0.3s ease;
+        outline: none;
+        opacity: 0.7;
+        padding: 0;
+        margin: 0;
+        flex-shrink: 0;
+      `;
+      
+      // 호버 효과
+      dot.addEventListener('mouseenter', () => {
+        if (!dot.classList.contains('active')) {
+          dot.style.borderColor = '#999999';
+          dot.style.opacity = '0.9';
+        }
+      });
+
+      dot.addEventListener('mouseleave', () => {
+        if (!dot.classList.contains('active')) {
+          dot.style.borderColor = '#cccccc';
+          dot.style.opacity = '0.7';
+        }
+      });
+
+      dotContainer.appendChild(dot);
+    }
+
+    return dotContainer;
+  }
+
+  /**
+   * 터치 제스처 지원 추가
+   */
+  private static addTouchSupport(
+    container: HTMLElement, 
+    moveToSlide: (index: number, instant?: boolean) => void, 
+    getCurrentSlide: () => number,
+    totalSlides: number,
+    handleInfiniteLoop?: () => void
+  ): void {
+    let startX = 0;
+    let isDragging = false;
+
+    container.addEventListener('touchstart', (e) => {
+      startX = e.touches[0].clientX;
+      isDragging = true;
+    });
+
+    container.addEventListener('touchmove', (e) => {
+      if (!isDragging) return;
+      e.preventDefault();
+    });
+
+    container.addEventListener('touchend', (e) => {
+      if (!isDragging) return;
+      isDragging = false;
+
+      const endX = e.changedTouches[0].clientX;
+      const diff = startX - endX;
+
+      if (Math.abs(diff) > 50) { // 50px 이상 스와이프 시
+        const currentSlide = getCurrentSlide();
+        if (diff > 0) {
+          // 왼쪽으로 스와이프 (다음 슬라이드)
+          const nextIndex = currentSlide + 1;
+          moveToSlide(nextIndex);
+          if (handleInfiniteLoop) {
+            handleInfiniteLoop();
+          }
+        } else {
+          // 오른쪽으로 스와이프 (이전 슬라이드)
+          const prevIndex = currentSlide > 0 ? currentSlide - 1 : totalSlides - 1;
+          moveToSlide(prevIndex);
+        }
+      }
+    });
+  }
+}

package/src/react/components/AdErrorBoundary.tsx

@@ -0,0 +1,75 @@
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+
+interface AdErrorBoundaryProps {
+  children: ReactNode;
+  fallback?: ReactNode;
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+
+interface AdErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+/**
+ * 광고 컴포넌트에서 발생하는 오류를 포착하는 Error Boundary
+ * 광고 로딩 실패 시 fallback UI를 표시하고 앱 전체가 크래시되는 것을 방지
+ */
+export class AdErrorBoundary extends Component<AdErrorBoundaryProps, AdErrorBoundaryState> {
+  constructor(props: AdErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): AdErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('AdStage Error Boundary caught an error:', error, errorInfo);
+    
+    // 사용자 정의 에러 핸들러 호출
+    if (this.props.onError) {
+      this.props.onError(error, errorInfo);
+    }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      // 사용자 정의 fallback이 있으면 사용, 없으면 기본 fallback 표시
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      return (
+        <div
+          style={{
+            padding: '20px',
+            textAlign: 'center',
+            backgroundColor: '#fee',
+            border: '1px solid #fcc',
+            borderRadius: '4px',
+            color: '#c00',
+          }}
+        >
+          <h3>광고 로딩 오류</h3>
+          <p>광고를 불러오는 중 문제가 발생했습니다.</p>
+          <button
+            onClick={() => this.setState({ hasError: false, error: null })}
+            style={{
+              padding: '8px 16px',
+              backgroundColor: '#fff',
+              border: '1px solid #ccc',
+              borderRadius: '4px',
+              cursor: 'pointer',
+            }}
+          >
+            다시 시도
+          </button>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}

package/src/react/components/AdSlot.tsx

@@ -0,0 +1,144 @@
+import React, { useEffect, useRef, useMemo } from 'react';
+import { AdType } from '../../types/advertisement';
+import { useAdStage } from '../hooks/useAdStage';
+
+interface AdSlotProps {
+  slotId: string;
+  adType: AdType;
+  width?: string | number;
+  height?: string | number;
+  className?: string;
+  style?: React.CSSProperties;
+  autoSlideInterval?: number;
+  sliderEffect?: 'slide' | 'fade';
+  language?: string;
+  deviceType?: string;
+  country?: string;
+}
+
+/**
+ * 범용 광고 슬롯 컴포넌트
+ * 모든 광고 타입을 지원하며 SSR 환경에서도 안전하게 동작
+ */
+export const AdSlot: React.FC<AdSlotProps> = ({
+  slotId,
+  adType,
+  width,
+  height,
+  className,
+  style,
+  autoSlideInterval = 3,
+  sliderEffect = 'slide',
+  language,
+  deviceType,
+  country,
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const { sdk, isLoading, error } = useAdStage();
+
+  const containerId = useMemo(() => `adstage-${slotId}`, [slotId]);
+
+  useEffect(() => {
+    if (!sdk || !containerRef.current || isLoading || error) {
+      return;
+    }
+
+    // 컨테이너에 ID 설정
+    containerRef.current.id = containerId;
+
+    // 광고 슬롯 생성
+    const createSlot = async () => {
+      try {
+        await sdk.createSlot(slotId, containerId, adType, {
+          width,
+          height,
+          language,
+          deviceType,
+          country,
+          autoSlideInterval,
+          sliderEffect,
+        });
+      } catch (err) {
+        console.error(`Failed to create ad slot ${slotId}:`, err);
+      }
+    };
+
+    createSlot();
+
+    // 클린업 함수
+    return () => {
+      // SDK에 removeSlot 메서드가 없으므로 DOM 정리만 수행
+      if (containerRef.current) {
+        containerRef.current.innerHTML = '';
+      }
+    };
+  }, [
+    sdk,
+    slotId,
+    containerId,
+    adType,
+    width,
+    height,
+    language,
+    deviceType,
+    country,
+    autoSlideInterval,
+    sliderEffect,
+    isLoading,
+    error,
+  ]);
+
+  const containerStyle: React.CSSProperties = {
+    width: typeof width === 'number' ? `${width}px` : width,
+    height: typeof height === 'number' ? `${height}px` : height,
+    ...style,
+  };
+
+  // 로딩 상태 표시
+  if (isLoading) {
+    return (
+      <div
+        className={className}
+        style={{
+          ...containerStyle,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          backgroundColor: '#f5f5f5',
+          border: '1px dashed #ccc',
+          color: '#999',
+        }}
+      >
+        Loading Ad...
+      </div>
+    );
+  }
+
+  // 에러 상태 표시
+  if (error) {
+    return (
+      <div
+        className={className}
+        style={{
+          ...containerStyle,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          backgroundColor: '#fee',
+          border: '1px solid #fcc',
+          color: '#c00',
+        }}
+      >
+        Ad Load Error
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className={className}
+      style={containerStyle}
+    />
+  );
+};

package/src/react/components/BannerAd.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { AdType } from '../../types/advertisement';
+import { AdSlot } from './AdSlot';
+
+interface BannerAdProps {
+  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이 BANNER로 고정됨
+ */
+export const BannerAd: React.FC<BannerAdProps> = (props) => {
+  return <AdSlot {...props} adType={AdType.BANNER} />;
+};

package/src/react/components/InterstitialAd.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { AdType } from '../../types/advertisement';
+import { AdSlot } from './AdSlot';
+
+interface InterstitialAdProps {
+  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이 INTERSTITIAL로 고정됨
+ */
+export const InterstitialAd: React.FC<InterstitialAdProps> = (props) => {
+  return <AdSlot {...props} adType={AdType.INTERSTITIAL} />;
+};

package/src/react/components/NativeAd.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { AdType } from '../../types/advertisement';
+import { AdSlot } from './AdSlot';
+
+interface NativeAdProps {
+  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이 NATIVE로 고정됨
+ */
+export const NativeAd: React.FC<NativeAdProps> = (props) => {
+  return <AdSlot {...props} adType={AdType.NATIVE} />;
+};