@adstage/web-sdk 2.4.4 → 2.4.6

package/dist/index.cjs.js

@@ -47,11 +47,15 @@ class ViewableEventTracker {
     static isDuplicateViewable(adId, slotId, debug = false) {
         const key = `${adId}_${slotId}`;
         const now = Date.now();
+        // 디버그 모드에 따른 쿨다운 시간 결정
+        const cooldownTime = debug ?
+            ViewableEventTracker.VIEWABLE_COOLDOWN_DEBUG :
+            ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION;
         // 메모리 기반 중복 확인 (새로고침 시 초기화됨)
         const lastViewable = ViewableEventTracker.viewableTracker.get(key);
-        if (lastViewable && (now - lastViewable) < ViewableEventTracker.VIEWABLE_COOLDOWN) {
+        if (lastViewable && (now - lastViewable) < cooldownTime) {
             if (debug) {
-                console.log(`Duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - lastViewable)) / 1000)}s remaining`);
+                console.log(`Duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((cooldownTime - (now - lastViewable)) / 1000)}s remaining (${debug ? 'debug' : 'production'} mode)`);
             }
             return true;
         }
@@ -60,9 +64,9 @@ class ViewableEventTracker {
         const sessionViewable = sessionStorage.getItem(sessionKey);
         if (sessionViewable) {
             const sessionTime = parseInt(sessionViewable, 10);
-            if (!isNaN(sessionTime) && (now - sessionTime) < ViewableEventTracker.VIEWABLE_COOLDOWN) {
+            if (!isNaN(sessionTime) && (now - sessionTime) < cooldownTime) {
                 if (debug) {
-                    console.log(`Session-based duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - sessionTime)) / 1000)}s remaining`);
+                    console.log(`Session-based duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((cooldownTime - (now - sessionTime)) / 1000)}s remaining (${debug ? 'debug' : 'production'} mode)`);
                 }
                 // 메모리에도 기록하여 이후 요청 최적화
                 ViewableEventTracker.viewableTracker.set(key, sessionTime);
@@ -74,6 +78,9 @@ class ViewableEventTracker {
         sessionStorage.setItem(sessionKey, now.toString());
         // 오래된 세션 스토리지 데이터 정리 (선택적)
         ViewableEventTracker.cleanupOldViewables();
+        if (debug) {
+            console.log(`✅ New viewable recorded for ad ${adId} in slot ${slotId} (${debug ? 'debug' : 'production'} mode)`);
+        }
         return false;
     }
     /**
@@ -81,7 +88,8 @@ class ViewableEventTracker {
      */
     static cleanupOldViewables() {
         const now = Date.now();
-        const cleanupThreshold = ViewableEventTracker.VIEWABLE_COOLDOWN * 2; // 쿨다운의 2배 시간이 지난 데이터 정리
+        // 프로덕션 쿨다운의 2배 시간이 지난 데이터 정리
+        const cleanupThreshold = ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION * 2;
         // 세션 스토리지 정리
         for (let i = 0; i < sessionStorage.length; i++) {
             const key = sessionStorage.key(i);
@@ -104,14 +112,33 @@ class ViewableEventTracker {
         }
     }
     /**
-     * 모든 추적 데이터 정리
+     * 모든 추적 데이터 정리 (디버그용)
      */
     static clear() {
         ViewableEventTracker.viewableTracker.clear();
+        // 세션 스토리지에서도 adstage_viewable_ 키들 제거
+        const keysToRemove = [];
+        for (let i = 0; i < sessionStorage.length; i++) {
+            const key = sessionStorage.key(i);
+            if (key && key.startsWith('adstage_viewable_')) {
+                keysToRemove.push(key);
+            }
+        }
+        keysToRemove.forEach(key => sessionStorage.removeItem(key));
+    }
+    /**
+     * 특정 광고의 viewable 추적 초기화 (디버그용)
+     */
+    static clearAdViewable(adId, slotId) {
+        const key = `${adId}_${slotId}`;
+        ViewableEventTracker.viewableTracker.delete(key);
+        const sessionKey = `adstage_viewable_${key}`;
+        sessionStorage.removeItem(sessionKey);
     }
 }
 ViewableEventTracker.viewableTracker = new Map();
-ViewableEventTracker.VIEWABLE_COOLDOWN = 300000; // 5분 쿨다운
+ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION = 300000; // 5분 쿨다운 (프로덕션)
+ViewableEventTracker.VIEWABLE_COOLDOWN_DEBUG = 30000; // 30초 쿨다운 (디버그)
 
 /**
  * SSR 안전한 DOM API 래퍼 클래스
@@ -607,13 +634,32 @@ class AdvertisementEventTracker {
                     riskLevel: additionalData.riskLevel,
                 }),
             };
-            await fetch(`${this.baseUrl}/advertisements/events/${adId}/${eventType}`, {
+            const url = `${this.baseUrl}/advertisements/events/${adId}/${eventType}`;
+            const headers = ApiHeaders.createForEvents(this.apiKey, eventData);
+            if (this.debug) {
+                console.log(`🚀 Sending advertisement event: ${eventType} for ad ${adId}`, {
+                    url,
+                    headers,
+                    eventData
+                });
+            }
+            const response = await fetch(url, {
                 method: 'POST',
-                headers: ApiHeaders.createForEvents(this.apiKey, eventData),
+                headers,
                 body: JSON.stringify(eventData),
             });
             if (this.debug) {
-                console.log(`Tracked advertisement event: ${eventType} for ad ${adId}`, eventData);
+                console.log(`📡 API Response Status: ${response.status} ${response.statusText}`, {
+                    url,
+                    ok: response.ok
+                });
+            }
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`API request failed: ${response.status} ${response.statusText} - ${errorText}`);
+            }
+            if (this.debug) {
+                console.log(`✅ Successfully tracked advertisement event: ${eventType} for ad ${adId}`);
             }
         }
         catch (error) {
@@ -948,6 +994,7 @@ const API_PATHS = {
     /** 광고 관련 */
     advertisements: {
         list: '/advertisements/list',
+        detail: '/advertisements',
         events: '/advertisements/events'
     },
     /** 이벤트 관련 */
@@ -966,6 +1013,7 @@ class EndpointBuilder {
          */
         this.advertisements = {
             list: () => `${this.baseUrl}${API_PATHS.advertisements.list}`,
+            detail: (adId) => `${this.baseUrl}${API_PATHS.advertisements.detail}/${adId}`,
             events: (adId, eventType) => `${this.baseUrl}${API_PATHS.advertisements.events}/${adId}/${eventType}`
         };
         /**
@@ -1206,7 +1254,7 @@ class TextAdRenderer extends BaseAdRenderer {
         // 기본 컨테이너 스타일
         const containerStyles = {
             ...this.getBaseContainerStyles(slot),
-            padding: '20px',
+            padding: '4px',
             background: 'transparent',
             display: 'flex',
             'align-items': 'center',
@@ -1234,7 +1282,7 @@ class TextAdRenderer extends BaseAdRenderer {
         }
         // 텍스트 콘텐츠 생성
         const textContent = this.createTextElement(ad.textContent, 'div', {
-            'font-size': '16px',
+            'font-size': '14px',
             'font-weight': '500',
             color: '#212529',
             width: '100%', // 전체 너비 사용하여 텍스트 정렬이 적용되도록 함
@@ -2285,8 +2333,6 @@ class AdRenderer {
             case AdType.TEXT: {
                 const textDiv = document.createElement('div');
                 textDiv.innerHTML = `
-          <h3>${ad.title}</h3>
-          ${ad.description ? `<p>${ad.description}</p>` : ''}
           ${ad.textContent ? `<div>${ad.textContent}</div>` : ''}
         `;
                 adElement.appendChild(textDiv);
@@ -2412,7 +2458,7 @@ class AdRenderer {
             case AdType.BANNER:
                 return '250px'; // 일반 배너
             case AdType.TEXT:
-                return '120px'; // 텍스트는 좀 더 작게
+                return '60px'; // 텍스트는 좀 더 작게
             case AdType.VIDEO:
                 return '360px'; // 비디오는 16:9 비율 고려
             case AdType.NATIVE:
@@ -2682,6 +2728,8 @@ class AdsModule {
             autoSlide: options?.autoSlide || false,
             slideInterval: options?.slideInterval || 5000,
             onClick: options?.onClick,
+            // 특정 광고 ID
+            adId: options?.adId,
             // 필터링 옵션들 전달
             language: options?.language,
             deviceType: options?.deviceType,
@@ -2698,6 +2746,8 @@ class AdsModule {
             maxLines: options?.maxLines || 3,
             style: options?.style || 'default',
             onClick: options?.onClick,
+            // 특정 광고 ID
+            adId: options?.adId,
             // 필터링 옵션들 전달
             language: options?.language,
             deviceType: options?.deviceType,
@@ -2897,8 +2947,8 @@ class AdsModule {
         // 기본 fraud 검사
         const fraudDetector = new BasicFraudDetector();
         // viewability 추적
-        const tracker = new ViewabilityTracker(element, slot.adType, (metrics) => {
-            this.handleViewableEvent(ad, slot, metrics, fraudDetector);
+        const tracker = new ViewabilityTracker(element, slot.adType, async (metrics) => {
+            await this.handleViewableEvent(ad, slot, metrics, fraudDetector);
         });
         // 정리를 위해 저장
         slot.viewabilityTracker = tracker;
@@ -2952,7 +3002,27 @@ class AdsModule {
         if (!this._config?.apiKey) {
             throw new Error('API key not configured');
         }
-        // GET 요청용 query parameters 구성
+        // 특정 광고 ID가 지정된 경우, 해당 광고만 요청
+        if (options.adId) {
+            const url = `${endpoints.advertisements.detail(options.adId)}`;
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: ApiHeaders.create(this._config.apiKey)
+            });
+            if (!response.ok) {
+                if (response.status === 404) {
+                    console.warn(`🚫 Advertisement not found with ID: ${options.adId}`);
+                    return [];
+                }
+                throw new Error(`Failed to fetch ad data: ${response.status}`);
+            }
+            const advertisement = await response.json();
+            if (this._config?.debug) {
+                console.log(`📊 Fetched specific ad with ID: ${options.adId}`, advertisement);
+            }
+            return [advertisement];
+        }
+        // 일반적인 광고 목록 요청
         const params = new URLSearchParams();
         params.append('adType', type);
         // 백엔드 API에서 실제 지원하는 필터링 옵션들만 추가

package/dist/index.d.ts

@@ -220,6 +220,7 @@ interface AdOptions {
     autoplay?: boolean;
     muted?: boolean;
     onClick?: (adData: any) => void;
+    adId?: string;
     language?: 'ko' | 'en' | 'ja' | 'zh';
     deviceType?: 'MOBILE' | 'DESKTOP';
     country?: 'KR' | 'US' | 'JP' | 'CN' | 'DE';

package/dist/index.esm.js

@@ -45,11 +45,15 @@ class ViewableEventTracker {
     static isDuplicateViewable(adId, slotId, debug = false) {
         const key = `${adId}_${slotId}`;
         const now = Date.now();
+        // 디버그 모드에 따른 쿨다운 시간 결정
+        const cooldownTime = debug ?
+            ViewableEventTracker.VIEWABLE_COOLDOWN_DEBUG :
+            ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION;
         // 메모리 기반 중복 확인 (새로고침 시 초기화됨)
         const lastViewable = ViewableEventTracker.viewableTracker.get(key);
-        if (lastViewable && (now - lastViewable) < ViewableEventTracker.VIEWABLE_COOLDOWN) {
+        if (lastViewable && (now - lastViewable) < cooldownTime) {
             if (debug) {
-                console.log(`Duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - lastViewable)) / 1000)}s remaining`);
+                console.log(`Duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((cooldownTime - (now - lastViewable)) / 1000)}s remaining (${debug ? 'debug' : 'production'} mode)`);
             }
             return true;
         }
@@ -58,9 +62,9 @@ class ViewableEventTracker {
         const sessionViewable = sessionStorage.getItem(sessionKey);
         if (sessionViewable) {
             const sessionTime = parseInt(sessionViewable, 10);
-            if (!isNaN(sessionTime) && (now - sessionTime) < ViewableEventTracker.VIEWABLE_COOLDOWN) {
+            if (!isNaN(sessionTime) && (now - sessionTime) < cooldownTime) {
                 if (debug) {
-                    console.log(`Session-based duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - sessionTime)) / 1000)}s remaining`);
+                    console.log(`Session-based duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((cooldownTime - (now - sessionTime)) / 1000)}s remaining (${debug ? 'debug' : 'production'} mode)`);
                 }
                 // 메모리에도 기록하여 이후 요청 최적화
                 ViewableEventTracker.viewableTracker.set(key, sessionTime);
@@ -72,6 +76,9 @@ class ViewableEventTracker {
         sessionStorage.setItem(sessionKey, now.toString());
         // 오래된 세션 스토리지 데이터 정리 (선택적)
         ViewableEventTracker.cleanupOldViewables();
+        if (debug) {
+            console.log(`✅ New viewable recorded for ad ${adId} in slot ${slotId} (${debug ? 'debug' : 'production'} mode)`);
+        }
         return false;
     }
     /**
@@ -79,7 +86,8 @@ class ViewableEventTracker {
      */
     static cleanupOldViewables() {
         const now = Date.now();
-        const cleanupThreshold = ViewableEventTracker.VIEWABLE_COOLDOWN * 2; // 쿨다운의 2배 시간이 지난 데이터 정리
+        // 프로덕션 쿨다운의 2배 시간이 지난 데이터 정리
+        const cleanupThreshold = ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION * 2;
         // 세션 스토리지 정리
         for (let i = 0; i < sessionStorage.length; i++) {
             const key = sessionStorage.key(i);
@@ -102,14 +110,33 @@ class ViewableEventTracker {
         }
     }
     /**
-     * 모든 추적 데이터 정리
+     * 모든 추적 데이터 정리 (디버그용)
      */
     static clear() {
         ViewableEventTracker.viewableTracker.clear();
+        // 세션 스토리지에서도 adstage_viewable_ 키들 제거
+        const keysToRemove = [];
+        for (let i = 0; i < sessionStorage.length; i++) {
+            const key = sessionStorage.key(i);
+            if (key && key.startsWith('adstage_viewable_')) {
+                keysToRemove.push(key);
+            }
+        }
+        keysToRemove.forEach(key => sessionStorage.removeItem(key));
+    }
+    /**
+     * 특정 광고의 viewable 추적 초기화 (디버그용)
+     */
+    static clearAdViewable(adId, slotId) {
+        const key = `${adId}_${slotId}`;
+        ViewableEventTracker.viewableTracker.delete(key);
+        const sessionKey = `adstage_viewable_${key}`;
+        sessionStorage.removeItem(sessionKey);
     }
 }
 ViewableEventTracker.viewableTracker = new Map();
-ViewableEventTracker.VIEWABLE_COOLDOWN = 300000; // 5분 쿨다운
+ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION = 300000; // 5분 쿨다운 (프로덕션)
+ViewableEventTracker.VIEWABLE_COOLDOWN_DEBUG = 30000; // 30초 쿨다운 (디버그)
 
 /**
  * SSR 안전한 DOM API 래퍼 클래스
@@ -605,13 +632,32 @@ class AdvertisementEventTracker {
                     riskLevel: additionalData.riskLevel,
                 }),
             };
-            await fetch(`${this.baseUrl}/advertisements/events/${adId}/${eventType}`, {
+            const url = `${this.baseUrl}/advertisements/events/${adId}/${eventType}`;
+            const headers = ApiHeaders.createForEvents(this.apiKey, eventData);
+            if (this.debug) {
+                console.log(`🚀 Sending advertisement event: ${eventType} for ad ${adId}`, {
+                    url,
+                    headers,
+                    eventData
+                });
+            }
+            const response = await fetch(url, {
                 method: 'POST',
-                headers: ApiHeaders.createForEvents(this.apiKey, eventData),
+                headers,
                 body: JSON.stringify(eventData),
             });
             if (this.debug) {
-                console.log(`Tracked advertisement event: ${eventType} for ad ${adId}`, eventData);
+                console.log(`📡 API Response Status: ${response.status} ${response.statusText}`, {
+                    url,
+                    ok: response.ok
+                });
+            }
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`API request failed: ${response.status} ${response.statusText} - ${errorText}`);
+            }
+            if (this.debug) {
+                console.log(`✅ Successfully tracked advertisement event: ${eventType} for ad ${adId}`);
             }
         }
         catch (error) {
@@ -946,6 +992,7 @@ const API_PATHS = {
     /** 광고 관련 */
     advertisements: {
         list: '/advertisements/list',
+        detail: '/advertisements',
         events: '/advertisements/events'
     },
     /** 이벤트 관련 */
@@ -964,6 +1011,7 @@ class EndpointBuilder {
          */
         this.advertisements = {
             list: () => `${this.baseUrl}${API_PATHS.advertisements.list}`,
+            detail: (adId) => `${this.baseUrl}${API_PATHS.advertisements.detail}/${adId}`,
             events: (adId, eventType) => `${this.baseUrl}${API_PATHS.advertisements.events}/${adId}/${eventType}`
         };
         /**
@@ -1204,7 +1252,7 @@ class TextAdRenderer extends BaseAdRenderer {
         // 기본 컨테이너 스타일
         const containerStyles = {
             ...this.getBaseContainerStyles(slot),
-            padding: '20px',
+            padding: '4px',
             background: 'transparent',
             display: 'flex',
             'align-items': 'center',
@@ -1232,7 +1280,7 @@ class TextAdRenderer extends BaseAdRenderer {
         }
         // 텍스트 콘텐츠 생성
         const textContent = this.createTextElement(ad.textContent, 'div', {
-            'font-size': '16px',
+            'font-size': '14px',
             'font-weight': '500',
             color: '#212529',
             width: '100%', // 전체 너비 사용하여 텍스트 정렬이 적용되도록 함
@@ -2283,8 +2331,6 @@ class AdRenderer {
             case AdType.TEXT: {
                 const textDiv = document.createElement('div');
                 textDiv.innerHTML = `
-          <h3>${ad.title}</h3>
-          ${ad.description ? `<p>${ad.description}</p>` : ''}
           ${ad.textContent ? `<div>${ad.textContent}</div>` : ''}
         `;
                 adElement.appendChild(textDiv);
@@ -2410,7 +2456,7 @@ class AdRenderer {
             case AdType.BANNER:
                 return '250px'; // 일반 배너
             case AdType.TEXT:
-                return '120px'; // 텍스트는 좀 더 작게
+                return '60px'; // 텍스트는 좀 더 작게
             case AdType.VIDEO:
                 return '360px'; // 비디오는 16:9 비율 고려
             case AdType.NATIVE:
@@ -2680,6 +2726,8 @@ class AdsModule {
             autoSlide: options?.autoSlide || false,
             slideInterval: options?.slideInterval || 5000,
             onClick: options?.onClick,
+            // 특정 광고 ID
+            adId: options?.adId,
             // 필터링 옵션들 전달
             language: options?.language,
             deviceType: options?.deviceType,
@@ -2696,6 +2744,8 @@ class AdsModule {
             maxLines: options?.maxLines || 3,
             style: options?.style || 'default',
             onClick: options?.onClick,
+            // 특정 광고 ID
+            adId: options?.adId,
             // 필터링 옵션들 전달
             language: options?.language,
             deviceType: options?.deviceType,
@@ -2895,8 +2945,8 @@ class AdsModule {
         // 기본 fraud 검사
         const fraudDetector = new BasicFraudDetector();
         // viewability 추적
-        const tracker = new ViewabilityTracker(element, slot.adType, (metrics) => {
-            this.handleViewableEvent(ad, slot, metrics, fraudDetector);
+        const tracker = new ViewabilityTracker(element, slot.adType, async (metrics) => {
+            await this.handleViewableEvent(ad, slot, metrics, fraudDetector);
         });
         // 정리를 위해 저장
         slot.viewabilityTracker = tracker;
@@ -2950,7 +3000,27 @@ class AdsModule {
         if (!this._config?.apiKey) {
             throw new Error('API key not configured');
         }
-        // GET 요청용 query parameters 구성
+        // 특정 광고 ID가 지정된 경우, 해당 광고만 요청
+        if (options.adId) {
+            const url = `${endpoints.advertisements.detail(options.adId)}`;
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: ApiHeaders.create(this._config.apiKey)
+            });
+            if (!response.ok) {
+                if (response.status === 404) {
+                    console.warn(`🚫 Advertisement not found with ID: ${options.adId}`);
+                    return [];
+                }
+                throw new Error(`Failed to fetch ad data: ${response.status}`);
+            }
+            const advertisement = await response.json();
+            if (this._config?.debug) {
+                console.log(`📊 Fetched specific ad with ID: ${options.adId}`, advertisement);
+            }
+            return [advertisement];
+        }
+        // 일반적인 광고 목록 요청
         const params = new URLSearchParams();
         params.append('adType', type);
         // 백엔드 API에서 실제 지원하는 필터링 옵션들만 추가

package/dist/index.standalone.js

@@ -42,11 +42,15 @@ class ViewableEventTracker {
     static isDuplicateViewable(adId, slotId, debug = false) {
         const key = `${adId}_${slotId}`;
         const now = Date.now();
+        // 디버그 모드에 따른 쿨다운 시간 결정
+        const cooldownTime = debug ?
+            ViewableEventTracker.VIEWABLE_COOLDOWN_DEBUG :
+            ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION;
         // 메모리 기반 중복 확인 (새로고침 시 초기화됨)
         const lastViewable = ViewableEventTracker.viewableTracker.get(key);
-        if (lastViewable && (now - lastViewable) < ViewableEventTracker.VIEWABLE_COOLDOWN) {
+        if (lastViewable && (now - lastViewable) < cooldownTime) {
             if (debug) {
-                console.log(`Duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - lastViewable)) / 1000)}s remaining`);
+                console.log(`Duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((cooldownTime - (now - lastViewable)) / 1000)}s remaining (${debug ? 'debug' : 'production'} mode)`);
             }
             return true;
         }
@@ -55,9 +59,9 @@ class ViewableEventTracker {
         const sessionViewable = sessionStorage.getItem(sessionKey);
         if (sessionViewable) {
             const sessionTime = parseInt(sessionViewable, 10);
-            if (!isNaN(sessionTime) && (now - sessionTime) < ViewableEventTracker.VIEWABLE_COOLDOWN) {
+            if (!isNaN(sessionTime) && (now - sessionTime) < cooldownTime) {
                 if (debug) {
-                    console.log(`Session-based duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - sessionTime)) / 1000)}s remaining`);
+                    console.log(`Session-based duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((cooldownTime - (now - sessionTime)) / 1000)}s remaining (${debug ? 'debug' : 'production'} mode)`);
                 }
                 // 메모리에도 기록하여 이후 요청 최적화
                 ViewableEventTracker.viewableTracker.set(key, sessionTime);
@@ -69,6 +73,9 @@ class ViewableEventTracker {
         sessionStorage.setItem(sessionKey, now.toString());
         // 오래된 세션 스토리지 데이터 정리 (선택적)
         ViewableEventTracker.cleanupOldViewables();
+        if (debug) {
+            console.log(`✅ New viewable recorded for ad ${adId} in slot ${slotId} (${debug ? 'debug' : 'production'} mode)`);
+        }
         return false;
     }
     /**
@@ -76,7 +83,8 @@ class ViewableEventTracker {
      */
     static cleanupOldViewables() {
         const now = Date.now();
-        const cleanupThreshold = ViewableEventTracker.VIEWABLE_COOLDOWN * 2; // 쿨다운의 2배 시간이 지난 데이터 정리
+        // 프로덕션 쿨다운의 2배 시간이 지난 데이터 정리
+        const cleanupThreshold = ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION * 2;
         // 세션 스토리지 정리
         for (let i = 0; i < sessionStorage.length; i++) {
             const key = sessionStorage.key(i);
@@ -99,14 +107,33 @@ class ViewableEventTracker {
         }
     }
     /**
-     * 모든 추적 데이터 정리
+     * 모든 추적 데이터 정리 (디버그용)
      */
     static clear() {
         ViewableEventTracker.viewableTracker.clear();
+        // 세션 스토리지에서도 adstage_viewable_ 키들 제거
+        const keysToRemove = [];
+        for (let i = 0; i < sessionStorage.length; i++) {
+            const key = sessionStorage.key(i);
+            if (key && key.startsWith('adstage_viewable_')) {
+                keysToRemove.push(key);
+            }
+        }
+        keysToRemove.forEach(key => sessionStorage.removeItem(key));
+    }
+    /**
+     * 특정 광고의 viewable 추적 초기화 (디버그용)
+     */
+    static clearAdViewable(adId, slotId) {
+        const key = `${adId}_${slotId}`;
+        ViewableEventTracker.viewableTracker.delete(key);
+        const sessionKey = `adstage_viewable_${key}`;
+        sessionStorage.removeItem(sessionKey);
     }
 }
 ViewableEventTracker.viewableTracker = new Map();
-ViewableEventTracker.VIEWABLE_COOLDOWN = 300000; // 5분 쿨다운
+ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION = 300000; // 5분 쿨다운 (프로덕션)
+ViewableEventTracker.VIEWABLE_COOLDOWN_DEBUG = 30000; // 30초 쿨다운 (디버그)
 
 /**
  * SSR 안전한 DOM API 래퍼 클래스
@@ -602,13 +629,32 @@ class AdvertisementEventTracker {
                     riskLevel: additionalData.riskLevel,
                 }),
             };
-            await fetch(`${this.baseUrl}/advertisements/events/${adId}/${eventType}`, {
+            const url = `${this.baseUrl}/advertisements/events/${adId}/${eventType}`;
+            const headers = ApiHeaders.createForEvents(this.apiKey, eventData);
+            if (this.debug) {
+                console.log(`🚀 Sending advertisement event: ${eventType} for ad ${adId}`, {
+                    url,
+                    headers,
+                    eventData
+                });
+            }
+            const response = await fetch(url, {
                 method: 'POST',
-                headers: ApiHeaders.createForEvents(this.apiKey, eventData),
+                headers,
                 body: JSON.stringify(eventData),
             });
             if (this.debug) {
-                console.log(`Tracked advertisement event: ${eventType} for ad ${adId}`, eventData);
+                console.log(`📡 API Response Status: ${response.status} ${response.statusText}`, {
+                    url,
+                    ok: response.ok
+                });
+            }
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`API request failed: ${response.status} ${response.statusText} - ${errorText}`);
+            }
+            if (this.debug) {
+                console.log(`✅ Successfully tracked advertisement event: ${eventType} for ad ${adId}`);
             }
         }
         catch (error) {
@@ -943,6 +989,7 @@ const API_PATHS = {
     /** 광고 관련 */
     advertisements: {
         list: '/advertisements/list',
+        detail: '/advertisements',
         events: '/advertisements/events'
     },
     /** 이벤트 관련 */
@@ -961,6 +1008,7 @@ class EndpointBuilder {
          */
         this.advertisements = {
             list: () => `${this.baseUrl}${API_PATHS.advertisements.list}`,
+            detail: (adId) => `${this.baseUrl}${API_PATHS.advertisements.detail}/${adId}`,
             events: (adId, eventType) => `${this.baseUrl}${API_PATHS.advertisements.events}/${adId}/${eventType}`
         };
         /**
@@ -1201,7 +1249,7 @@ class TextAdRenderer extends BaseAdRenderer {
         // 기본 컨테이너 스타일
         const containerStyles = {
             ...this.getBaseContainerStyles(slot),
-            padding: '20px',
+            padding: '4px',
             background: 'transparent',
             display: 'flex',
             'align-items': 'center',
@@ -1229,7 +1277,7 @@ class TextAdRenderer extends BaseAdRenderer {
         }
         // 텍스트 콘텐츠 생성
         const textContent = this.createTextElement(ad.textContent, 'div', {
-            'font-size': '16px',
+            'font-size': '14px',
             'font-weight': '500',
             color: '#212529',
             width: '100%', // 전체 너비 사용하여 텍스트 정렬이 적용되도록 함
@@ -2280,8 +2328,6 @@ class AdRenderer {
             case AdType.TEXT: {
                 const textDiv = document.createElement('div');
                 textDiv.innerHTML = `
-          <h3>${ad.title}</h3>
-          ${ad.description ? `<p>${ad.description}</p>` : ''}
           ${ad.textContent ? `<div>${ad.textContent}</div>` : ''}
         `;
                 adElement.appendChild(textDiv);
@@ -2407,7 +2453,7 @@ class AdRenderer {
             case AdType.BANNER:
                 return '250px'; // 일반 배너
             case AdType.TEXT:
-                return '120px'; // 텍스트는 좀 더 작게
+                return '60px'; // 텍스트는 좀 더 작게
             case AdType.VIDEO:
                 return '360px'; // 비디오는 16:9 비율 고려
             case AdType.NATIVE:
@@ -2677,6 +2723,8 @@ class AdsModule {
             autoSlide: options?.autoSlide || false,
             slideInterval: options?.slideInterval || 5000,
             onClick: options?.onClick,
+            // 특정 광고 ID
+            adId: options?.adId,
             // 필터링 옵션들 전달
             language: options?.language,
             deviceType: options?.deviceType,
@@ -2693,6 +2741,8 @@ class AdsModule {
             maxLines: options?.maxLines || 3,
             style: options?.style || 'default',
             onClick: options?.onClick,
+            // 특정 광고 ID
+            adId: options?.adId,
             // 필터링 옵션들 전달
             language: options?.language,
             deviceType: options?.deviceType,
@@ -2892,8 +2942,8 @@ class AdsModule {
         // 기본 fraud 검사
         const fraudDetector = new BasicFraudDetector();
         // viewability 추적
-        const tracker = new ViewabilityTracker(element, slot.adType, (metrics) => {
-            this.handleViewableEvent(ad, slot, metrics, fraudDetector);
+        const tracker = new ViewabilityTracker(element, slot.adType, async (metrics) => {
+            await this.handleViewableEvent(ad, slot, metrics, fraudDetector);
         });
         // 정리를 위해 저장
         slot.viewabilityTracker = tracker;
@@ -2947,7 +2997,27 @@ class AdsModule {
         if (!this._config?.apiKey) {
             throw new Error('API key not configured');
         }
-        // GET 요청용 query parameters 구성
+        // 특정 광고 ID가 지정된 경우, 해당 광고만 요청
+        if (options.adId) {
+            const url = `${endpoints.advertisements.detail(options.adId)}`;
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: ApiHeaders.create(this._config.apiKey)
+            });
+            if (!response.ok) {
+                if (response.status === 404) {
+                    console.warn(`🚫 Advertisement not found with ID: ${options.adId}`);
+                    return [];
+                }
+                throw new Error(`Failed to fetch ad data: ${response.status}`);
+            }
+            const advertisement = await response.json();
+            if (this._config?.debug) {
+                console.log(`📊 Fetched specific ad with ID: ${options.adId}`, advertisement);
+            }
+            return [advertisement];
+        }
+        // 일반적인 광고 목록 요청
         const params = new URLSearchParams();
         params.append('adType', type);
         // 백엔드 API에서 실제 지원하는 필터링 옵션들만 추가

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "2.4.4",
+  "version": "2.4.6",
   "description": "AdStage Web SDK - Production-ready marketing platform SDK with React Provider support for seamless integration",
   "type": "module",
   "main": "dist/index.cjs.js",

package/src/constants/endpoints.ts

@@ -26,6 +26,7 @@ export const API_PATHS = {
   /** 광고 관련 */
   advertisements: {
     list: '/advertisements/list',
+    detail: '/advertisements',
     events: '/advertisements/events'
   },
   
@@ -67,6 +68,7 @@ export class EndpointBuilder {
    */
   advertisements = {
     list: () => `${this.baseUrl}${API_PATHS.advertisements.list}`,
+    detail: (adId: string) => `${this.baseUrl}${API_PATHS.advertisements.detail}/${adId}`,
     events: (adId: string, eventType: string) => 
       `${this.baseUrl}${API_PATHS.advertisements.events}/${adId}/${eventType}`
   };

package/src/managers/ads/advertisement-event-tracker.ts

@@ -107,17 +107,37 @@ export class AdvertisementEventTracker {
       };
 
 
-      await fetch(
-        `${this.baseUrl}/advertisements/events/${adId}/${eventType}`,
-        {
-          method: 'POST',
-          headers: ApiHeaders.createForEvents(this.apiKey, eventData),
-          body: JSON.stringify(eventData),
-        }
-      );
+      const url = `${this.baseUrl}/advertisements/events/${adId}/${eventType}`;
+      const headers = ApiHeaders.createForEvents(this.apiKey, eventData);
+      
+      if (this.debug) {
+        console.log(`🚀 Sending advertisement event: ${eventType} for ad ${adId}`, {
+          url,
+          headers,
+          eventData
+        });
+      }
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(eventData),
+      });
+
+      if (this.debug) {
+        console.log(`📡 API Response Status: ${response.status} ${response.statusText}`, {
+          url,
+          ok: response.ok
+        });
+      }
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`API request failed: ${response.status} ${response.statusText} - ${errorText}`);
+      }
 
       if (this.debug) {
-        console.log(`Tracked advertisement event: ${eventType} for ad ${adId}`, eventData);
+        console.log(`✅ Successfully tracked advertisement event: ${eventType} for ad ${adId}`);
       }
     } catch (error) {
       console.error('Failed to track advertisement event:', error);

package/src/managers/ads/viewable-event-tracker.ts

@@ -7,7 +7,8 @@
  */
 export class ViewableEventTracker {
   private static viewableTracker = new Map<string, number>();
-  private static readonly VIEWABLE_COOLDOWN = 300000; // 5분 쿨다운
+  private static readonly VIEWABLE_COOLDOWN_PRODUCTION = 300000; // 5분 쿨다운 (프로덕션)
+  private static readonly VIEWABLE_COOLDOWN_DEBUG = 30000; // 30초 쿨다운 (디버그)
 
   /**
    * 중복 viewable 이벤트 여부 확인
@@ -16,11 +17,16 @@ export class ViewableEventTracker {
     const key = `${adId}_${slotId}`;
     const now = Date.now();
     
+    // 디버그 모드에 따른 쿨다운 시간 결정
+    const cooldownTime = debug ? 
+      ViewableEventTracker.VIEWABLE_COOLDOWN_DEBUG : 
+      ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION;
+    
     // 메모리 기반 중복 확인 (새로고침 시 초기화됨)
     const lastViewable = ViewableEventTracker.viewableTracker.get(key);
-    if (lastViewable && (now - lastViewable) < ViewableEventTracker.VIEWABLE_COOLDOWN) {
+    if (lastViewable && (now - lastViewable) < cooldownTime) {
       if (debug) {
-        console.log(`Duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - lastViewable)) / 1000)}s remaining`);
+        console.log(`Duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((cooldownTime - (now - lastViewable)) / 1000)}s remaining (${debug ? 'debug' : 'production'} mode)`);
       }
       return true;
     }
@@ -30,9 +36,9 @@ export class ViewableEventTracker {
     const sessionViewable = sessionStorage.getItem(sessionKey);
     if (sessionViewable) {
       const sessionTime = parseInt(sessionViewable, 10);
-      if (!isNaN(sessionTime) && (now - sessionTime) < ViewableEventTracker.VIEWABLE_COOLDOWN) {
+      if (!isNaN(sessionTime) && (now - sessionTime) < cooldownTime) {
         if (debug) {
-          console.log(`Session-based duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((ViewableEventTracker.VIEWABLE_COOLDOWN - (now - sessionTime)) / 1000)}s remaining`);
+          console.log(`Session-based duplicate viewable blocked for ad ${adId} in slot ${slotId}. Cooldown: ${Math.round((cooldownTime - (now - sessionTime)) / 1000)}s remaining (${debug ? 'debug' : 'production'} mode)`);
         }
         // 메모리에도 기록하여 이후 요청 최적화
         ViewableEventTracker.viewableTracker.set(key, sessionTime);
@@ -47,6 +53,10 @@ export class ViewableEventTracker {
     // 오래된 세션 스토리지 데이터 정리 (선택적)
     ViewableEventTracker.cleanupOldViewables();
     
+    if (debug) {
+      console.log(`✅ New viewable recorded for ad ${adId} in slot ${slotId} (${debug ? 'debug' : 'production'} mode)`);
+    }
+    
     return false;
   }
 
@@ -55,7 +65,8 @@ export class ViewableEventTracker {
    */
   private static cleanupOldViewables(): void {
     const now = Date.now();
-    const cleanupThreshold = ViewableEventTracker.VIEWABLE_COOLDOWN * 2; // 쿨다운의 2배 시간이 지난 데이터 정리
+    // 프로덕션 쿨다운의 2배 시간이 지난 데이터 정리
+    const cleanupThreshold = ViewableEventTracker.VIEWABLE_COOLDOWN_PRODUCTION * 2;
     
     // 세션 스토리지 정리
     for (let i = 0; i < sessionStorage.length; i++) {
@@ -81,9 +92,28 @@ export class ViewableEventTracker {
   }
 
   /**
-   * 모든 추적 데이터 정리
+   * 모든 추적 데이터 정리 (디버그용)
    */
   static clear(): void {
     ViewableEventTracker.viewableTracker.clear();
+    // 세션 스토리지에서도 adstage_viewable_ 키들 제거
+    const keysToRemove: string[] = [];
+    for (let i = 0; i < sessionStorage.length; i++) {
+      const key = sessionStorage.key(i);
+      if (key && key.startsWith('adstage_viewable_')) {
+        keysToRemove.push(key);
+      }
+    }
+    keysToRemove.forEach(key => sessionStorage.removeItem(key));
+  }
+
+  /**
+   * 특정 광고의 viewable 추적 초기화 (디버그용)
+   */
+  static clearAdViewable(adId: string, slotId: string): void {
+    const key = `${adId}_${slotId}`;
+    ViewableEventTracker.viewableTracker.delete(key);
+    const sessionKey = `adstage_viewable_${key}`;
+    sessionStorage.removeItem(sessionKey);
   }
 }

package/src/modules/ads/AdRenderer.ts

@@ -345,8 +345,6 @@ export class AdRenderer {
       case AdType.TEXT: {
         const textDiv = document.createElement('div');
         textDiv.innerHTML = `
-          <h3>${ad.title}</h3>
-          ${ad.description ? `<p>${ad.description}</p>` : ''}
           ${ad.textContent ? `<div>${ad.textContent}</div>` : ''}
         `;
         adElement.appendChild(textDiv);
@@ -480,7 +478,7 @@ export class AdRenderer {
       case AdType.BANNER:
         return '250px'; // 일반 배너
       case AdType.TEXT:
-        return '120px'; // 텍스트는 좀 더 작게
+        return '60px'; // 텍스트는 좀 더 작게
       case AdType.VIDEO:
         return '360px'; // 비디오는 16:9 비율 고려
       case AdType.NATIVE:

package/src/modules/ads/AdsModule.ts

@@ -26,6 +26,8 @@ export interface AdOptions {
   autoplay?: boolean;
   muted?: boolean;
   onClick?: (adData: any) => void;
+  // 특정 광고 ID 지정
+  adId?: string;
   // 광고 필터링 옵션 (백엔드 API에서 실제 지원하는 것들만)
   language?: 'ko' | 'en' | 'ja' | 'zh';
   deviceType?: 'MOBILE' | 'DESKTOP';
@@ -91,6 +93,8 @@ export class AdsModule implements BaseModule {
       autoSlide: options?.autoSlide || false,
       slideInterval: options?.slideInterval || 5000,
       onClick: options?.onClick,
+      // 특정 광고 ID
+      adId: options?.adId,
       // 필터링 옵션들 전달
       language: options?.language,
       deviceType: options?.deviceType,
@@ -110,6 +114,8 @@ export class AdsModule implements BaseModule {
       maxLines: options?.maxLines || 3,
       style: options?.style || 'default',
       onClick: options?.onClick,
+      // 특정 광고 ID
+      adId: options?.adId,
       // 필터링 옵션들 전달
       language: options?.language,
       deviceType: options?.deviceType,
@@ -351,8 +357,8 @@ export class AdsModule implements BaseModule {
     const fraudDetector = new BasicFraudDetector();
     
     // viewability 추적
-    const tracker = new ViewabilityTracker(element, slot.adType, (metrics) => {
-      this.handleViewableEvent(ad, slot, metrics, fraudDetector);
+    const tracker = new ViewabilityTracker(element, slot.adType, async (metrics) => {
+      await this.handleViewableEvent(ad, slot, metrics, fraudDetector);
     });
     
     // 정리를 위해 저장
@@ -426,7 +432,33 @@ export class AdsModule implements BaseModule {
       throw new Error('API key not configured');
     }
 
-    // GET 요청용 query parameters 구성
+    // 특정 광고 ID가 지정된 경우, 해당 광고만 요청
+    if (options.adId) {
+      const url = `${endpoints.advertisements.detail(options.adId)}`;
+      
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: ApiHeaders.create(this._config.apiKey)
+      });
+
+      if (!response.ok) {
+        if (response.status === 404) {
+          console.warn(`🚫 Advertisement not found with ID: ${options.adId}`);
+          return [];
+        }
+        throw new Error(`Failed to fetch ad data: ${response.status}`);
+      }
+
+      const advertisement = await response.json();
+      
+      if (this._config?.debug) {
+        console.log(`📊 Fetched specific ad with ID: ${options.adId}`, advertisement);
+      }
+      
+      return [advertisement];
+    }
+
+    // 일반적인 광고 목록 요청
     const params = new URLSearchParams();
     params.append('adType', type);
     

package/src/renderers/text-renderer.ts

@@ -16,7 +16,7 @@ export class TextAdRenderer extends BaseAdRenderer {
     // 기본 컨테이너 스타일
     const containerStyles: Record<string, string> = {
       ...this.getBaseContainerStyles(slot),
-      padding: '20px',
+      padding: '4px',
       background: 'transparent',
       display: 'flex',
       'align-items': 'center',
@@ -52,7 +52,7 @@ export class TextAdRenderer extends BaseAdRenderer {
       ad.textContent,
       'div',
       {
-        'font-size': '16px',
+        'font-size': '14px',
         'font-weight': '500',
         color: '#212529',
         width: '100%', // 전체 너비 사용하여 텍스트 정렬이 적용되도록 함