@adstage/web-sdk 1.1.0

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@adstage/web-sdk",
+  "version": "1.1.0",
+  "description": "AdStage Web SDK for displaying advertisements",
+  "type": "module",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "examples",
+    "README.md",
+    "REACT_GUIDE.md",
+    "PUBLISH_GUIDE.md"
+  ],
+  "scripts": {
+    "build:types": "tsc --project tsconfig.types.json",
+    "build": "npm run build:types && rollup -c",
+    "build:watch": "rollup -c -w",
+    "dev": "rollup -c -w",
+    "clean": "rm -rf dist dist-types",
+    "prepublishOnly": "npm run clean && npm run build",
+    "lint": "tsc --noEmit",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "publish:npm": "npm publish --access public",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major"
+  },
+  "keywords": [
+    "adstage",
+    "advertisement",
+    "ads",
+    "banner",
+    "sdk",
+    "web",
+    "react",
+    "hooks",
+    "component",
+    "typescript",
+    "text",
+    "native",
+    "video",
+    "marketing",
+    "monetization"
+  ],
+  "author": "AdStage",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-node-resolve": "^15.1.0",
+    "@rollup/plugin-replace": "^6.0.2",
+    "@rollup/plugin-terser": "^0.4.3",
+    "@rollup/plugin-typescript": "^11.1.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "react": "^18.0.0",
+    "rollup": "^3.23.0",
+    "rollup-plugin-dts": "^5.3.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nbase-io/adstage.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/nbase-io/adstage/issues"
+  },
+  "homepage": "https://github.com/nbase-io/adstage#readme"
+}

package/src/global.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AdStage SDK 전역 타입 선언
+ * 
+ * 이 파일을 프로젝트에 포함하면 TypeScript에서 window.AdStageSDK를 인식할 수 있습니다.
+ * 
+ * 사용법:
+ * 1. 이 파일을 프로젝트의 types/ 폴더에 복사
+ * 2. tsconfig.json의 include에 추가
+ */
+
+import { AdStageSDK, AdStageConfig } from './index';
+
+declare global {
+  interface Window {
+    AdStageSDK: typeof AdStageSDK;
+    adstageConfig?: AdStageConfig;
+  }
+}
+
+export {};

package/src/index.ts

@@ -0,0 +1,350 @@
+import { AdType, AdEventType } from './types/advertisement';
+import type { AdSlot, Advertisement } from './types/advertisement';
+import { AdRendererFactory } from './renderers';
+import { SliderManager } from './managers/slider-manager';
+import { FadeSliderManager } from './managers/fade-slider-manager';
+import { ImpressionTracker } from './managers/impression-tracker';
+import { EventTracker } from './managers/event-tracker';
+import { DeviceInfoCollector } from './managers/device-info-collector';
+import { SDKUtils } from './utils/sdk-utils';
+import { DOMUtils } from './utils/dom-utils';
+
+/**
+ * AdStage SDK 설정
+ */
+export interface AdStageConfig {
+  apiKey: string;
+  debug?: boolean;
+}
+
+/**
+ * AdStage SDK 메인 클래스
+ * - 간단한 API Key 기반 초기화
+ * - 광고 슬롯 자동 관리
+ * - 이벤트 자동 추적
+ */
+export class AdStageSDK {
+  private static instance: AdStageSDK | null = null;
+  
+  private config: AdStageConfig;
+  private baseUrl = 'https://beta-api.adstage.app';
+  private slots = new Map<string, AdSlot>();
+  private initialized = false;
+  private eventTracker: EventTracker;
+  
+  constructor(config: AdStageConfig) {
+    this.config = {
+      debug: false,
+      ...config,
+    };
+    
+    this.eventTracker = new EventTracker(
+      this.baseUrl,
+      this.config.apiKey,
+      this.config.debug || false,
+      this.slots
+    );
+  }
+  
+  /**
+   * SDK 초기화 및 인스턴스 반환
+   */
+  static init(config: AdStageConfig): AdStageSDK {
+    if (!AdStageSDK.instance) {
+      AdStageSDK.instance = new AdStageSDK(config);
+    }
+    
+    return AdStageSDK.instance;
+  }
+  
+  /**
+   * SDK 인스턴스 반환 (이미 초기화된 경우)
+   */
+  static getInstance(): AdStageSDK {
+    if (!AdStageSDK.instance) {
+      throw new Error('AdStageSDK must be initialized first. Call AdStageSDK.init(config)');
+    }
+    
+    return AdStageSDK.instance;
+  }
+  
+  /**
+   * 광고 슬롯 생성 및 로드
+   */
+  async createSlot(
+    id: string,
+    containerId: string,
+    adType: AdType = AdType.BANNER,
+    options?: {
+      width?: number | string;  // 숫자(px) 또는 문자열(%, px 등) 지원
+      height?: number | string; // 숫자(px) 또는 문자열(%, px 등) 지원
+      language?: string;
+      deviceType?: string;
+      country?: string;
+      autoSlideInterval?: number; // 자동 슬라이드 간격 (초), 기본값: 3초
+      sliderEffect?: 'slide' | 'fade'; // 슬라이더 효과 선택 (기본값: slide)
+    }
+  ): Promise<void> {
+    const container = DOMUtils.safeGetElementById(containerId);
+    if (!container) {
+      if (DOMUtils.canUseDOM()) {
+        console.error(`Container with ID "${containerId}" not found`);
+      }
+      return;
+    }
+
+    const slot: AdSlot = {
+      id,
+      containerId,
+      adType,
+      width: options?.width || 0,  // 문자열도 지원
+      height: options?.height || 0, // 문자열도 지원
+      isLoaded: false,
+      isVisible: false,
+      refreshRate: 0,
+      lazyLoad: false,
+      targeting: {},
+      load: async () => { await this.loadSlot(slot, options); return null; },
+      render: (ad: Advertisement) => this.renderSlot(slot, ad),
+      refresh: () => this.refreshSlot(slot.id),
+      destroy: () => this.destroySlot(slot.id),
+    };
+
+    this.slots.set(id, slot);
+    await this.loadSlot(slot, options);
+  }
+
+  /**
+   * 광고 슬롯 로드
+   */
+  private async loadSlot(slot: AdSlot, options?: any): Promise<void> {
+    try {
+      const queryParams = new URLSearchParams({
+        adType: slot.adType,
+        status: 'ACTIVE', // ACTIVE 상태인 광고만 조회
+        ...(options?.language && { language: options.language }),
+        ...(options?.deviceType && { deviceType: options.deviceType }),
+        ...(options?.country && { country: options.country }),
+      });
+
+      const response = await fetch(
+        `${this.baseUrl}/advertisements/list?${queryParams}`,
+        {
+          headers: {
+            'x-api-key': this.config.apiKey,
+            'Content-Type': 'application/json',
+          },
+        }
+      );
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const data = await response.json();
+      const advertisements = data.advertisements || [];
+
+      if (advertisements.length > 0) {
+        // 여러 광고가 있을 경우 슬라이드로 렌더링
+        this.renderSlotWithSlider(slot, advertisements, options);
+        
+        // 첫 번째 광고에 대해서만 노출 이벤트 추적
+        await this.eventTracker.trackEvent(advertisements[0]._id, slot.id, AdEventType.IMPRESSION);
+      } else {
+        console.warn(`No advertisements available for slot ${slot.id}`);
+      }
+    } catch (error) {
+      console.error(`Failed to load slot ${slot.id}:`, error);
+    }
+  }
+
+  /**
+   * 광고 슬롯 렌더링 (슬라이더 포함)
+   */
+  private renderSlotWithSlider(slot: AdSlot, advertisements: Advertisement[], options?: any): void {
+    const container = DOMUtils.safeGetElementById(slot.containerId);
+    if (!container) return;
+
+    if (advertisements.length === 1) {
+      // 광고가 하나뿐이면 기본 렌더링
+      this.renderSlot(slot, advertisements[0]);
+      return;
+    }
+
+    // 슬라이더 효과 결정 (옵션으로 지정하거나 텍스트 광고인 경우 fade 기본값)
+    const isAllTextAds = advertisements.every(ad => ad.adType === AdType.TEXT);
+    const useFadeEffect = options?.sliderEffect === 'fade' || 
+                         (options?.sliderEffect !== 'slide' && isAllTextAds);
+    
+    let sliderContainer: HTMLElement;
+    
+    if (useFadeEffect) {
+      // 페이드 슬라이더 사용
+      sliderContainer = FadeSliderManager.createFadeSliderContainer(
+        slot, 
+        advertisements, 
+        options,
+        (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType)
+      );
+    } else {
+      // 기본 슬라이더 사용
+      sliderContainer = SliderManager.createSliderContainer(
+        slot, 
+        advertisements, 
+        options,
+        (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType)
+      );
+    }
+    
+    container.innerHTML = '';
+    container.appendChild(sliderContainer);
+    slot.isLoaded = true;
+
+    if (this.config.debug) {
+      const sliderType = useFadeEffect ? 'fade slider' : 'slider';
+      console.log(`Rendered ${advertisements.length} ads with ${sliderType} for slot ${slot.id}:`, advertisements);
+    }
+  }
+
+  /**
+   * 광고 슬롯 렌더링 (단일 광고용)
+   */
+  private renderSlot(slot: AdSlot, ad: Advertisement): void {
+    const container = DOMUtils.safeGetElementById(slot.containerId);
+    if (!container) return;
+
+    // 팩토리를 사용해서 적절한 렌더러로 광고 생성
+    const adElement = AdRendererFactory.render(
+      ad, 
+      slot, 
+      (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType)
+    );
+
+    container.innerHTML = '';
+    container.appendChild(adElement);
+    slot.isLoaded = true;
+
+    if (this.config.debug) {
+      console.log(`Rendered ad for slot ${slot.id}:`, ad);
+    }
+  }
+
+  /**
+   * 광고 슬롯 새로고침
+   */
+  async refreshSlot(slotId: string): Promise<void> {
+    const slot = this.slots.get(slotId);
+    if (slot) {
+      await this.loadSlot(slot);
+    }
+  }
+
+  /**
+   * 광고 슬롯 제거
+   */
+  destroySlot(slotId: string): void {
+    const slot = this.slots.get(slotId);
+    if (slot) {
+      const container = DOMUtils.safeGetElementById(slot.containerId);
+      if (container) {
+        DOMUtils.safeSetInnerHTML(container, '');
+      }
+      this.slots.delete(slotId);
+    }
+  }
+
+  /**
+   * 자동 슬롯 검색 및 로드 (분리된 SDKUtils 사용)
+   */
+  async autoLoadSlots(): Promise<void> {
+    const elements = SDKUtils.findAutoSlotElements();
+
+    for (const element of elements) {
+      const slotInfo = SDKUtils.extractSlotInfo(element);
+      
+      if (!slotInfo.slotId || this.slots.has(slotInfo.slotId)) continue;
+      
+      const adType = SDKUtils.parseAdType(slotInfo.adType, AdType);
+
+      await this.createSlot(slotInfo.slotId, element.id || slotInfo.slotId, adType, {
+        width: slotInfo.width,
+        height: slotInfo.height,
+        language: slotInfo.language,
+        deviceType: slotInfo.deviceType,
+        country: slotInfo.country,
+        sliderEffect: slotInfo.sliderEffect as 'slide' | 'fade' | undefined,
+      });
+    }
+  }
+
+  /**
+   * SDK 정리
+   */
+  destroy(): void {
+    this.slots.clear();
+    ImpressionTracker.clear(); // 노출 추적 데이터도 정리
+    this.initialized = false;
+    AdStageSDK.instance = null;
+  }
+
+  /**
+   * 디바이스 ID 가져오기
+   */
+  getDeviceId(): string {
+    return DeviceInfoCollector.generateDeviceId();
+  }
+
+  /**
+   * 세션 ID 가져오기
+   */
+  getSessionId(): string {
+    return DeviceInfoCollector.generateSessionId();
+  }
+
+  /**
+   * 현재 로드된 슬롯 수 가져오기
+   */
+  getLoadedSlotCount(): number {
+    return this.slots.size;
+  }
+
+  /**
+   * 모든 슬롯 정보 가져오기
+   */
+  getAllSlots(): Map<string, AdSlot> {
+    return new Map(this.slots);
+  }
+}
+
+async function autoInit() {
+  if (DOMUtils.isBrowser() && (window as any).adstageConfig) {
+    try {
+      const sdk = AdStageSDK.init((window as any).adstageConfig);
+      await sdk.autoLoadSlots();
+    } catch (error) {
+      console.error('Failed to auto-initialize AdStageSDK:', error);
+    }
+  }
+}
+
+// 브라우저 환경에서 자동 초기화
+if (DOMUtils.isBrowser()) {
+  // 타입 단언을 사용하여 window 객체에 할당
+  (window as any).AdStageSDK = AdStageSDK;
+  
+  // DOM 로드 후 자동 초기화
+  if (DOMUtils.isDOMReady()) {
+    autoInit();
+  } else {
+    DOMUtils.waitForDOM().then(autoInit);
+  }
+}
+
+export default AdStageSDK;
+
+// Core SDK exports
+export { AdType, AdEventType };
+export type { AdSlot, Advertisement };
+
+// React exports (통합)
+export * from './react';

package/src/managers/device-info-collector.ts

@@ -0,0 +1,127 @@
+import { DOMUtils } from '../utils/dom-utils';
+
+/**
+ * 디바이스 정보 수집 클래스
+ * - 브라우저 환경 정보 수집
+ * - 디바이스 ID 생성 및 관리
+ * - 세션 ID 생성 및 관리
+ */
+export class DeviceInfoCollector {
+  /**
+   * 디바이스 ID 생성 및 반환 (SSR 안전)
+   */
+  static generateDeviceId(): string {
+    if (!DOMUtils.isBrowser()) return 'ssr_device_' + Date.now();
+    
+    const stored = localStorage.getItem('adstage_device_id');
+    if (stored) return stored;
+    
+    const deviceId = 'device_' + Math.random().toString(36).substr(2, 9) + '_' + Date.now();
+    localStorage.setItem('adstage_device_id', deviceId);
+    return deviceId;
+  }
+
+  /**
+   * 세션 ID 생성 및 반환 (SSR 안전)
+   */
+  static generateSessionId(): string {
+    if (!DOMUtils.isBrowser()) return 'ssr_session_' + Date.now();
+    
+    const stored = sessionStorage.getItem('adstage_session_id');
+    if (stored) return stored;
+    
+    const sessionId = 'session_' + Math.random().toString(36).substr(2, 9) + '_' + Date.now();
+    sessionStorage.setItem('adstage_session_id', sessionId);
+    return sessionId;
+  }
+
+  /**
+   * 모바일 디바이스 여부 확인
+   */
+  static isMobile(): boolean {
+    return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+  }
+
+  /**
+   * 플랫폼 타입 반환 (서버 enum에 맞춤)
+   */
+  static getPlatform(): 'ios' | 'android' | 'web' | 'desktop' {
+    const userAgent = navigator.userAgent.toLowerCase();
+    
+    if (/iphone|ipad|ipod/.test(userAgent)) {
+      return 'ios';
+    }
+    
+    if (/android/.test(userAgent)) {
+      return 'android';
+    }
+    
+    if (DeviceInfoCollector.isMobile()) {
+      return 'web'; // 모바일 웹
+    }
+    
+    return 'desktop'; // 데스크톱 웹
+  }
+
+  /**
+   * 완전한 디바이스 정보 수집
+   */
+  static collectDeviceInfo(): {
+    deviceId: string;
+    sessionId: string;
+    osVersion: string;
+    deviceModel: string;
+    appVersion: string;
+    sdkVersion: string;
+    language: string;
+    country: string;
+    ipAddress: string;
+    userAgent: string;
+    timezone: string;
+    viewportWidth: number;
+    viewportHeight: number;
+    screenWidth: number;
+    screenHeight: number;
+    colorDepth: number;
+    pixelRatio: number;
+    connectionType: string;
+    platform: 'ios' | 'android' | 'web' | 'desktop';
+  } {
+    const viewportInfo = DOMUtils.getViewportInfo();
+    
+    return {
+      deviceId: DeviceInfoCollector.generateDeviceId(),
+      sessionId: DeviceInfoCollector.generateSessionId(),
+      osVersion: DOMUtils.isBrowser() ? navigator.platform : 'SSR',
+      deviceModel: DOMUtils.isBrowser() ? navigator.platform : 'SSR',
+      appVersion: '1.0.0',
+      sdkVersion: '1.0.0',
+      language: DOMUtils.isBrowser() ? (navigator.language || 'ko') : 'ko',
+      country: 'KR', // 기본값
+      ipAddress: '', // 서버에서 자동으로 설정됨
+      userAgent: DOMUtils.isBrowser() ? navigator.userAgent : 'SSR',
+      timezone: DOMUtils.isBrowser() ? Intl.DateTimeFormat().resolvedOptions().timeZone : 'UTC',
+      viewportWidth: viewportInfo.width,
+      viewportHeight: viewportInfo.height,
+      screenWidth: DOMUtils.isBrowser() ? screen.width : 0,
+      screenHeight: DOMUtils.isBrowser() ? screen.height : 0,
+      colorDepth: DOMUtils.isBrowser() ? screen.colorDepth : 24,
+      pixelRatio: viewportInfo.pixelRatio,
+      connectionType: DOMUtils.isBrowser() ? ((navigator as any).connection?.effectiveType || 'unknown') : 'unknown',
+      platform: DeviceInfoCollector.getPlatform(),
+    };
+  }
+
+  /**
+   * 슬롯 위치 정보 가져오기 (SSR 안전)
+   */
+  static getSlotPosition(containerId: string): string {
+    const element = DOMUtils.safeGetElementById(containerId);
+    if (!element) return 'unknown';
+    
+    const rect = element.getBoundingClientRect();
+    const scrollInfo = DOMUtils.getScrollInfo();
+    
+    return `x:${Math.round(rect.left)},y:${Math.round(rect.top + scrollInfo.scrollTop)}`;
+  }
+}

package/src/managers/event-tracker.ts

@@ -0,0 +1,131 @@
+import { AdEventType } from '../types/advertisement';
+import type { AdSlot } from '../types/advertisement';
+import { ImpressionTracker } from './impression-tracker';
+import { DeviceInfoCollector } from './device-info-collector';
+import { DOMUtils } from '../utils/dom-utils';
+
+/**
+ * 이벤트 추적 관리 클래스
+ * - 광고 이벤트 추적 및 전송
+ * - 중복 노출 방지 통합
+ * - 서버 API 통신
+ */
+export class EventTracker {
+  private baseUrl: string;
+  private apiKey: string;
+  private debug: boolean;
+  private slots: Map<string, AdSlot>;
+
+  constructor(baseUrl: string, apiKey: string, debug: boolean, slots: Map<string, AdSlot>) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.debug = debug;
+    this.slots = slots;
+  }
+
+  /**
+   * 이벤트 추적
+   */
+  async trackEvent(adId: string, slotId: string, eventType: AdEventType): Promise<void> {
+    try {
+      // 노출 이벤트의 경우 중복 확인
+      if (eventType === AdEventType.IMPRESSION) {
+        if (ImpressionTracker.isDuplicateImpression(adId, slotId, this.debug)) {
+          return; // 중복 노출이므로 추적하지 않음
+        }
+      }
+      
+      // 현재 슬롯 정보 가져오기
+      const slot = this.slots.get(slotId);
+      
+      // 디바이스 정보 수집
+      const deviceInfo = DeviceInfoCollector.collectDeviceInfo();
+
+      // 이벤트 데이터 구성 (MongoDB 스키마에 맞춤)
+      const eventData = {
+        // 서버에서 자동 설정: orgId, advertisementId, action
+        // 하지만 DTO 검증을 위해 임시값 제공
+        orgId: 'temp', // 서버에서 API 키로부터 덮어씀
+        advertisementId: adId, // 서버에서 URL 파라미터로부터 덮어씀
+        action: eventType, // 서버에서 URL 파라미터로부터 덮어씀
+        
+        // 필수 필드들
+        adType: slot?.adType || 'BANNER',
+        platform: deviceInfo.platform,
+        
+        // 디바이스 정보를 최상위로 플래튼
+        deviceId: deviceInfo.deviceId,
+        osVersion: deviceInfo.osVersion,
+        deviceModel: deviceInfo.deviceModel,
+        appVersion: deviceInfo.appVersion,
+        sdkVersion: deviceInfo.sdkVersion,
+        language: deviceInfo.language,
+        country: deviceInfo.country,
+        ipAddress: deviceInfo.ipAddress,
+        userAgent: deviceInfo.userAgent,
+        timezone: deviceInfo.timezone,
+        viewportWidth: deviceInfo.viewportWidth,
+        viewportHeight: deviceInfo.viewportHeight,
+        screenWidth: deviceInfo.screenWidth,
+        screenHeight: deviceInfo.screenHeight,
+        connectionType: deviceInfo.connectionType,
+        
+        // 페이지 및 슬롯 정보
+        pageUrl: DOMUtils.getPageInfo().url,
+        pageTitle: DOMUtils.getPageInfo().title,
+        referrer: DOMUtils.getPageInfo().referrer,
+        slotId,
+        slotPosition: DeviceInfoCollector.getSlotPosition(slot?.containerId || ''),
+        slotWidth: EventTracker.parseNumericValue(slot?.width),
+        slotHeight: EventTracker.parseNumericValue(slot?.height),
+        sessionId: deviceInfo.sessionId,
+        
+        // 성능 메트릭
+        pageLoadTime: performance.now(),
+        timestamp: new Date().toISOString(),
+        
+        // 추가 메타데이터
+        metadata: {
+          eventType,
+          sdkVersion: '1.0.0',
+          timestamp: Date.now(),
+        },
+      };
+
+      await fetch(
+        `${this.baseUrl}/advertisements/events/${adId}/${eventType}`,
+        {
+          method: 'POST',
+          headers: {
+            'x-api-key': this.apiKey,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify(eventData),
+        }
+      );
+
+      if (this.debug) {
+        console.log(`Tracked event: ${eventType} for ad ${adId}`, eventData);
+      }
+    } catch (error) {
+      console.error('Failed to track event:', error);
+    }
+  }
+
+  /**
+   * 크기 값을 숫자로 변환 (서버 API용)
+   */
+  private static parseNumericValue(value: number | string | undefined): number {
+    if (typeof value === 'number') {
+      return value;
+    }
+    
+    if (typeof value === 'string') {
+      // px 단위 제거하고 숫자만 추출
+      const numericValue = parseFloat(value.replace(/px$/, ''));
+      return isNaN(numericValue) ? 0 : numericValue;
+    }
+    
+    return 0; // 기본값
+  }
+}