@adstage/web-sdk 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+declare enum AdType {
+    BANNER = "BANNER",
+    POPUP = "POPUP",
+    INTERSTITIAL = "INTERSTITIAL",
+    NATIVE = "NATIVE",
+    VIDEO = "VIDEO",
+    TEXT = "TEXT"
+}
+declare enum Platform {
+    WEB = "WEB",
+    MOBILE = "MOBILE"
+}
+declare 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"
+}
+declare enum DeviceType {
+    DESKTOP = "DESKTOP",
+    MOBILE = "MOBILE",
+    TABLET = "TABLET"
+}
+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;
+}
+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>;
+}
+/**
+ * 가시성 메트릭스
+ */
+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;
+    };
+}
+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;
+}
+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>;
+}
+interface AdSlot {
+    id: string;
+    containerId: string;
+    adType: AdType;
+    width: number | string;
+    height: number | string;
+    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;
+}
+
+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로 고정됨
+ */
+declare const BannerAd: React.FC<BannerAdProps>;
+
+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로 고정됨
+ */
+declare const TextAd: React.FC<TextAdProps>;
+
+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로 고정됨
+ */
+declare const NativeAd: React.FC<NativeAdProps>;
+
+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로 고정됨
+ */
+declare const VideoAd: React.FC<VideoAdProps>;
+
+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로 고정됨
+ */
+declare const InterstitialAd: React.FC<InterstitialAdProps>;
+
+interface AdErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface AdErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * 광고 컴포넌트에서 발생하는 오류를 포착하는 Error Boundary
+ * 광고 로딩 실패 시 fallback UI를 표시하고 앱 전체가 크래시되는 것을 방지
+ */
+declare class AdErrorBoundary extends Component<AdErrorBoundaryProps, AdErrorBoundaryState> {
+    constructor(props: AdErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): AdErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+interface AdStageSDKInstance {
+    createSlot: (...args: any[]) => Promise<void>;
+    removeSlot?: (slotId: string) => void;
+}
+interface AdStageContextValue {
+    sdk: AdStageSDKInstance | null;
+    isLoading: boolean;
+    error: string | null;
+    isInitialized: boolean;
+}
+interface AdStageProviderProps {
+    config: AdStageConfig;
+    children: ReactNode;
+    autoInit?: boolean;
+}
+declare const AdStageProvider: React.FC<AdStageProviderProps>;
+
+/**
+ * AdStage SDK 인스턴스에 접근하기 위한 Hook
+ * AdStageProvider 내부에서만 사용 가능
+ */
+declare const useAdStage: () => AdStageContextValue;
+
+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
+ * 컴포넌트에서 직접 슬롯을 제어하고 싶을 때 사용
+ */
+declare const useAdSlot: (options: UseAdSlotOptions) => UseAdSlotReturn;
+
+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
+ * 커스텀 이벤트 추적이 필요할 때 사용
+ */
+declare const useAdTracking: () => UseAdTrackingReturn;
+
+/**
+ * AdStage SDK 설정
+ */
+interface AdStageConfig {
+    apiKey: string;
+    debug?: boolean;
+}
+/**
+ * AdStage SDK 메인 클래스
+ * - 간단한 API Key 기반 초기화
+ * - 광고 슬롯 자동 관리
+ * - 이벤트 자동 추적
+ */
+declare class AdStageSDK {
+    private static instance;
+    private config;
+    private baseUrl;
+    private slots;
+    private initialized;
+    private eventTracker;
+    constructor(config: AdStageConfig);
+    /**
+     * SDK 초기화 및 인스턴스 반환
+     */
+    static init(config: AdStageConfig): AdStageSDK;
+    /**
+     * SDK 인스턴스 반환 (이미 초기화된 경우)
+     */
+    static getInstance(): AdStageSDK;
+    /**
+     * 광고 슬롯 생성 및 로드
+     */
+    createSlot(id: string, containerId: string, adType?: AdType, options?: {
+        width?: number | string;
+        height?: number | string;
+        language?: string;
+        deviceType?: string;
+        country?: string;
+        autoSlideInterval?: number;
+        sliderEffect?: 'slide' | 'fade';
+    }): Promise<void>;
+    /**
+     * 광고 슬롯 로드
+     */
+    private loadSlot;
+    /**
+     * 광고 슬롯 렌더링 (슬라이더 포함)
+     */
+    private renderSlotWithSlider;
+    /**
+     * 광고 슬롯 렌더링 (단일 광고용)
+     */
+    private renderSlot;
+    /**
+     * 광고 슬롯 새로고침
+     */
+    refreshSlot(slotId: string): Promise<void>;
+    /**
+     * 광고 슬롯 제거
+     */
+    destroySlot(slotId: string): void;
+    /**
+     * 자동 슬롯 검색 및 로드 (분리된 SDKUtils 사용)
+     */
+    autoLoadSlots(): Promise<void>;
+    /**
+     * SDK 정리
+     */
+    destroy(): void;
+    /**
+     * 디바이스 ID 가져오기
+     */
+    getDeviceId(): string;
+    /**
+     * 세션 ID 가져오기
+     */
+    getSessionId(): string;
+    /**
+     * 현재 로드된 슬롯 수 가져오기
+     */
+    getLoadedSlotCount(): number;
+    /**
+     * 모든 슬롯 정보 가져오기
+     */
+    getAllSlots(): Map<string, AdSlot>;
+}
+
+export { AdErrorBoundary, AdEventType, AdSlot, AdStageConfig, AdStageProvider, AdStageSDK, AdType, Advertisement, BannerAd, InterstitialAd, NativeAd, TextAd, VideoAd, AdStageSDK as default, useAdSlot, useAdStage, useAdTracking };