@adstage/web-sdk 1.3.2 → 1.3.4

package/dist/index.cjs.js

@@ -257,6 +257,72 @@ class DOMUtils {
             scrollLeft: this.getWindowProperty('pageXOffset', 0),
         };
     }
+    /**
+     * DOM 요소가 나타날 때까지 기다리기 (사용자 친화적 API)
+     */
+    static async waitForElement(id, options = {}) {
+        const { timeout = 3000, retryInterval = 100, debug = false } = options;
+        if (!this.canUseDOM()) {
+            throw new Error('DOM을 사용할 수 없는 환경입니다.');
+        }
+        // 즉시 찾을 수 있으면 바로 반환
+        const immediateElement = document.getElementById(id);
+        if (immediateElement) {
+            if (debug) {
+                console.log(`✅ 컨테이너 즉시 발견: ${id}`);
+            }
+            return immediateElement;
+        }
+        if (debug) {
+            console.log(`⏳ 컨테이너 대기 시작: ${id} (최대 ${timeout}ms)`);
+        }
+        return new Promise((resolve, reject) => {
+            let attempts = 0;
+            const maxAttempts = Math.ceil(timeout / retryInterval);
+            const checkElement = () => {
+                attempts++;
+                const element = document.getElementById(id);
+                if (element) {
+                    if (debug) {
+                        console.log(`✅ 컨테이너 발견: ${id} (${attempts}번째 시도, ${attempts * retryInterval}ms 경과)`);
+                    }
+                    resolve(element);
+                    return;
+                }
+                if (attempts >= maxAttempts) {
+                    const errorMessage = `❌ 컨테이너를 찾을 수 없습니다: "${id}"
+          
+다음을 확인해보세요:
+1. HTML에 id="${id}" 요소가 있는지 확인
+2. React/Vue 등에서 컴포넌트가 렌더링된 후 SDK 호출
+3. 철자가 정확한지 확인
+4. 중복된 ID가 없는지 확인
+
+대기 시간: ${timeout}ms (${attempts}번 시도)`;
+                    if (debug) {
+                        console.error(errorMessage);
+                    }
+                    reject(new Error(errorMessage));
+                    return;
+                }
+                if (debug && attempts % 10 === 0) {
+                    console.log(`⏳ 컨테이너 대기 중: ${id} (${attempts}/${maxAttempts})`);
+                }
+                // Exponential backoff: 처음엔 빠르게, 나중엔 느리게
+                const nextInterval = Math.min(retryInterval * Math.pow(1.2, attempts), 500);
+                setTimeout(checkElement, nextInterval);
+            };
+            // 첫 번째 체크는 즉시 실행
+            setTimeout(checkElement, retryInterval);
+        });
+    }
+    /**
+     * 여러 DOM 요소를 동시에 기다리기
+     */
+    static async waitForElements(ids, options = {}) {
+        const promises = ids.map(id => this.waitForElement(id, options));
+        return Promise.all(promises);
+    }
 }
 
 /**
@@ -1814,31 +1880,49 @@ class AdStageSDK {
      * 광고 슬롯 생성 및 로드
      */
     async createSlot(id, containerId, adType = exports.AdType.BANNER, options) {
-        const container = DOMUtils.safeGetElementById(containerId);
-        if (!container) {
-            if (DOMUtils.canUseDOM()) {
-                console.error(`Container with ID "${containerId}" not found`);
+        try {
+            // 💡 사용자 친화적 개선: 컨테이너가 나타날 때까지 자동으로 기다림
+            if (this.config.debug) {
+                console.log(`🔍 컨테이너 검색 시작: ${containerId}`);
+            }
+            const container = await DOMUtils.waitForElement(containerId, {
+                timeout: 5000, // 최대 5초 대기
+                retryInterval: 50, // 50ms마다 체크 (부드러운 사용자 경험)
+                debug: this.config.debug
+            });
+            if (this.config.debug) {
+                console.log(`✅ 컨테이너 확인됨: ${containerId}`, container);
+            }
+            const slot = {
+                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) => this.renderSlot(slot, ad),
+                refresh: () => this.refreshSlot(slot.id),
+                destroy: () => this.destroySlot(slot.id),
+            };
+            this.slots.set(id, slot);
+            await this.loadSlot(slot, options);
+        }
+        catch (error) {
+            // 친절한 에러 메시지로 사용자 가이드
+            if (error instanceof Error && error.message.includes('컨테이너를 찾을 수 없습니다')) {
+                console.error(error.message);
+                throw error;
+            }
+            else {
+                console.error(`❌ 광고 슬롯 생성 실패 (${id}):`, error);
+                throw new Error(`광고 슬롯 생성에 실패했습니다: ${error}`);
             }
-            return;
         }
-        const slot = {
-            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) => this.renderSlot(slot, ad),
-            refresh: () => this.refreshSlot(slot.id),
-            destroy: () => this.destroySlot(slot.id),
-        };
-        this.slots.set(id, slot);
-        await this.loadSlot(slot, options);
     }
     /**
      * 광고 슬롯 로드
@@ -1852,38 +1936,73 @@ class AdStageSDK {
                 ...(options?.deviceType && { deviceType: options.deviceType }),
                 ...(options?.country && { country: options.country }),
             });
-            const response = await fetch(`${this.baseUrl}/advertisements/list?${queryParams}`, {
+            const requestUrl = `${this.baseUrl}/advertisements/list?${queryParams}`;
+            if (this.config.debug) {
+                console.log(`🌐 광고 API 요청 시작:`, {
+                    url: requestUrl,
+                    apiKey: this.config.apiKey.substring(0, 10) + '...',
+                    slot: slot.id
+                });
+            }
+            const response = await fetch(requestUrl, {
                 headers: {
                     'x-api-key': this.config.apiKey,
                     'Content-Type': 'application/json',
                 },
             });
+            if (this.config.debug) {
+                console.log(`📡 API 응답 상태:`, {
+                    status: response.status,
+                    statusText: response.statusText,
+                    ok: response.ok
+                });
+            }
             if (!response.ok) {
                 throw new Error(`HTTP error! status: ${response.status}`);
             }
             const data = await response.json();
+            if (this.config.debug) {
+                console.log(`📊 API 응답 데이터:`, {
+                    data,
+                    advertisementsCount: data.advertisements ? data.advertisements.length : 0
+                });
+            }
             const advertisements = data.advertisements || [];
             if (advertisements.length > 0) {
+                if (this.config.debug) {
+                    console.log(`✅ ${advertisements.length}개 광고 발견:`, advertisements);
+                }
                 // 여러 광고가 있을 경우 슬라이드로 렌더링
                 this.renderSlotWithSlider(slot, advertisements, options);
                 // 첫 번째 광고에 대해서만 노출 이벤트 추적
                 await this.eventTracker.trackEvent(advertisements[0]._id, slot.id, exports.AdEventType.IMPRESSION);
             }
             else {
-                console.warn(`No advertisements available for slot ${slot.id}`);
+                console.warn(`⚠️ 슬롯 ${slot.id}에 사용 가능한 광고가 없습니다. API 응답:`, data);
             }
         }
         catch (error) {
-            console.error(`Failed to load slot ${slot.id}:`, error);
+            console.error(`❌ 슬롯 ${slot.id} 로드 실패:`, error);
         }
     }
     /**
      * 광고 슬롯 렌더링 (슬라이더 포함)
      */
     renderSlotWithSlider(slot, advertisements, options) {
+        // 💡 한 번 더 안전하게 컨테이너 확인
         const container = DOMUtils.safeGetElementById(slot.containerId);
-        if (!container)
+        if (!container) {
+            console.error(`❌ 렌더링 시점에 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
             return;
+        }
+        if (this.config.debug) {
+            console.log(`🎨 광고 렌더링 시작:`, {
+                slotId: slot.id,
+                containerId: slot.containerId,
+                advertisementCount: advertisements.length,
+                container: container
+            });
+        }
         if (advertisements.length === 1) {
             // 광고가 하나뿐이면 기본 렌더링
             this.renderSlot(slot, advertisements[0]);
@@ -1907,7 +2026,11 @@ class AdStageSDK {
         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);
+            console.log(`✅ ${advertisements.length}개 광고를 ${sliderType}로 렌더링 완료:`, {
+                slotId: slot.id,
+                container: container,
+                sliderContainer: sliderContainer
+            });
         }
     }
     /**
@@ -1915,15 +2038,36 @@ class AdStageSDK {
      */
     renderSlot(slot, ad) {
         const container = DOMUtils.safeGetElementById(slot.containerId);
-        if (!container)
+        if (!container) {
+            console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
             return;
+        }
+        if (this.config.debug) {
+            console.log(`🎨 단일 광고 렌더링 시작:`, {
+                slotId: slot.id,
+                containerId: slot.containerId,
+                ad: ad,
+                container: container
+            });
+        }
         // 팩토리를 사용해서 적절한 렌더러로 광고 생성
         const adElement = AdRendererFactory.render(ad, slot, (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType));
+        if (this.config.debug) {
+            console.log(`🔧 광고 요소 생성됨:`, {
+                adElement: adElement,
+                tagName: adElement.tagName,
+                innerHTML: adElement.innerHTML.substring(0, 200) + '...'
+            });
+        }
         container.innerHTML = '';
         container.appendChild(adElement);
         slot.isLoaded = true;
         if (this.config.debug) {
-            console.log(`Rendered ad for slot ${slot.id}:`, ad);
+            console.log(`✅ 단일 광고 렌더링 완료:`, {
+                slotId: slot.id,
+                ad: ad,
+                containerContent: container.innerHTML.substring(0, 200) + '...'
+            });
         }
     }
     /**

package/dist/index.esm.js

@@ -253,6 +253,72 @@ class DOMUtils {
             scrollLeft: this.getWindowProperty('pageXOffset', 0),
         };
     }
+    /**
+     * DOM 요소가 나타날 때까지 기다리기 (사용자 친화적 API)
+     */
+    static async waitForElement(id, options = {}) {
+        const { timeout = 3000, retryInterval = 100, debug = false } = options;
+        if (!this.canUseDOM()) {
+            throw new Error('DOM을 사용할 수 없는 환경입니다.');
+        }
+        // 즉시 찾을 수 있으면 바로 반환
+        const immediateElement = document.getElementById(id);
+        if (immediateElement) {
+            if (debug) {
+                console.log(`✅ 컨테이너 즉시 발견: ${id}`);
+            }
+            return immediateElement;
+        }
+        if (debug) {
+            console.log(`⏳ 컨테이너 대기 시작: ${id} (최대 ${timeout}ms)`);
+        }
+        return new Promise((resolve, reject) => {
+            let attempts = 0;
+            const maxAttempts = Math.ceil(timeout / retryInterval);
+            const checkElement = () => {
+                attempts++;
+                const element = document.getElementById(id);
+                if (element) {
+                    if (debug) {
+                        console.log(`✅ 컨테이너 발견: ${id} (${attempts}번째 시도, ${attempts * retryInterval}ms 경과)`);
+                    }
+                    resolve(element);
+                    return;
+                }
+                if (attempts >= maxAttempts) {
+                    const errorMessage = `❌ 컨테이너를 찾을 수 없습니다: "${id}"
+          
+다음을 확인해보세요:
+1. HTML에 id="${id}" 요소가 있는지 확인
+2. React/Vue 등에서 컴포넌트가 렌더링된 후 SDK 호출
+3. 철자가 정확한지 확인
+4. 중복된 ID가 없는지 확인
+
+대기 시간: ${timeout}ms (${attempts}번 시도)`;
+                    if (debug) {
+                        console.error(errorMessage);
+                    }
+                    reject(new Error(errorMessage));
+                    return;
+                }
+                if (debug && attempts % 10 === 0) {
+                    console.log(`⏳ 컨테이너 대기 중: ${id} (${attempts}/${maxAttempts})`);
+                }
+                // Exponential backoff: 처음엔 빠르게, 나중엔 느리게
+                const nextInterval = Math.min(retryInterval * Math.pow(1.2, attempts), 500);
+                setTimeout(checkElement, nextInterval);
+            };
+            // 첫 번째 체크는 즉시 실행
+            setTimeout(checkElement, retryInterval);
+        });
+    }
+    /**
+     * 여러 DOM 요소를 동시에 기다리기
+     */
+    static async waitForElements(ids, options = {}) {
+        const promises = ids.map(id => this.waitForElement(id, options));
+        return Promise.all(promises);
+    }
 }
 
 /**
@@ -1810,31 +1876,49 @@ class AdStageSDK {
      * 광고 슬롯 생성 및 로드
      */
     async createSlot(id, containerId, adType = AdType.BANNER, options) {
-        const container = DOMUtils.safeGetElementById(containerId);
-        if (!container) {
-            if (DOMUtils.canUseDOM()) {
-                console.error(`Container with ID "${containerId}" not found`);
+        try {
+            // 💡 사용자 친화적 개선: 컨테이너가 나타날 때까지 자동으로 기다림
+            if (this.config.debug) {
+                console.log(`🔍 컨테이너 검색 시작: ${containerId}`);
+            }
+            const container = await DOMUtils.waitForElement(containerId, {
+                timeout: 5000, // 최대 5초 대기
+                retryInterval: 50, // 50ms마다 체크 (부드러운 사용자 경험)
+                debug: this.config.debug
+            });
+            if (this.config.debug) {
+                console.log(`✅ 컨테이너 확인됨: ${containerId}`, container);
+            }
+            const slot = {
+                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) => this.renderSlot(slot, ad),
+                refresh: () => this.refreshSlot(slot.id),
+                destroy: () => this.destroySlot(slot.id),
+            };
+            this.slots.set(id, slot);
+            await this.loadSlot(slot, options);
+        }
+        catch (error) {
+            // 친절한 에러 메시지로 사용자 가이드
+            if (error instanceof Error && error.message.includes('컨테이너를 찾을 수 없습니다')) {
+                console.error(error.message);
+                throw error;
+            }
+            else {
+                console.error(`❌ 광고 슬롯 생성 실패 (${id}):`, error);
+                throw new Error(`광고 슬롯 생성에 실패했습니다: ${error}`);
             }
-            return;
         }
-        const slot = {
-            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) => this.renderSlot(slot, ad),
-            refresh: () => this.refreshSlot(slot.id),
-            destroy: () => this.destroySlot(slot.id),
-        };
-        this.slots.set(id, slot);
-        await this.loadSlot(slot, options);
     }
     /**
      * 광고 슬롯 로드
@@ -1848,38 +1932,73 @@ class AdStageSDK {
                 ...(options?.deviceType && { deviceType: options.deviceType }),
                 ...(options?.country && { country: options.country }),
             });
-            const response = await fetch(`${this.baseUrl}/advertisements/list?${queryParams}`, {
+            const requestUrl = `${this.baseUrl}/advertisements/list?${queryParams}`;
+            if (this.config.debug) {
+                console.log(`🌐 광고 API 요청 시작:`, {
+                    url: requestUrl,
+                    apiKey: this.config.apiKey.substring(0, 10) + '...',
+                    slot: slot.id
+                });
+            }
+            const response = await fetch(requestUrl, {
                 headers: {
                     'x-api-key': this.config.apiKey,
                     'Content-Type': 'application/json',
                 },
             });
+            if (this.config.debug) {
+                console.log(`📡 API 응답 상태:`, {
+                    status: response.status,
+                    statusText: response.statusText,
+                    ok: response.ok
+                });
+            }
             if (!response.ok) {
                 throw new Error(`HTTP error! status: ${response.status}`);
             }
             const data = await response.json();
+            if (this.config.debug) {
+                console.log(`📊 API 응답 데이터:`, {
+                    data,
+                    advertisementsCount: data.advertisements ? data.advertisements.length : 0
+                });
+            }
             const advertisements = data.advertisements || [];
             if (advertisements.length > 0) {
+                if (this.config.debug) {
+                    console.log(`✅ ${advertisements.length}개 광고 발견:`, advertisements);
+                }
                 // 여러 광고가 있을 경우 슬라이드로 렌더링
                 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}`);
+                console.warn(`⚠️ 슬롯 ${slot.id}에 사용 가능한 광고가 없습니다. API 응답:`, data);
             }
         }
         catch (error) {
-            console.error(`Failed to load slot ${slot.id}:`, error);
+            console.error(`❌ 슬롯 ${slot.id} 로드 실패:`, error);
         }
     }
     /**
      * 광고 슬롯 렌더링 (슬라이더 포함)
      */
     renderSlotWithSlider(slot, advertisements, options) {
+        // 💡 한 번 더 안전하게 컨테이너 확인
         const container = DOMUtils.safeGetElementById(slot.containerId);
-        if (!container)
+        if (!container) {
+            console.error(`❌ 렌더링 시점에 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
             return;
+        }
+        if (this.config.debug) {
+            console.log(`🎨 광고 렌더링 시작:`, {
+                slotId: slot.id,
+                containerId: slot.containerId,
+                advertisementCount: advertisements.length,
+                container: container
+            });
+        }
         if (advertisements.length === 1) {
             // 광고가 하나뿐이면 기본 렌더링
             this.renderSlot(slot, advertisements[0]);
@@ -1903,7 +2022,11 @@ class AdStageSDK {
         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);
+            console.log(`✅ ${advertisements.length}개 광고를 ${sliderType}로 렌더링 완료:`, {
+                slotId: slot.id,
+                container: container,
+                sliderContainer: sliderContainer
+            });
         }
     }
     /**
@@ -1911,15 +2034,36 @@ class AdStageSDK {
      */
     renderSlot(slot, ad) {
         const container = DOMUtils.safeGetElementById(slot.containerId);
-        if (!container)
+        if (!container) {
+            console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
             return;
+        }
+        if (this.config.debug) {
+            console.log(`🎨 단일 광고 렌더링 시작:`, {
+                slotId: slot.id,
+                containerId: slot.containerId,
+                ad: ad,
+                container: container
+            });
+        }
         // 팩토리를 사용해서 적절한 렌더러로 광고 생성
         const adElement = AdRendererFactory.render(ad, slot, (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType));
+        if (this.config.debug) {
+            console.log(`🔧 광고 요소 생성됨:`, {
+                adElement: adElement,
+                tagName: adElement.tagName,
+                innerHTML: adElement.innerHTML.substring(0, 200) + '...'
+            });
+        }
         container.innerHTML = '';
         container.appendChild(adElement);
         slot.isLoaded = true;
         if (this.config.debug) {
-            console.log(`Rendered ad for slot ${slot.id}:`, ad);
+            console.log(`✅ 단일 광고 렌더링 완료:`, {
+                slotId: slot.id,
+                ad: ad,
+                containerContent: container.innerHTML.substring(0, 200) + '...'
+            });
         }
     }
     /**

package/dist/index.standalone.js

@@ -253,6 +253,72 @@ class DOMUtils {
             scrollLeft: this.getWindowProperty('pageXOffset', 0),
         };
     }
+    /**
+     * DOM 요소가 나타날 때까지 기다리기 (사용자 친화적 API)
+     */
+    static async waitForElement(id, options = {}) {
+        const { timeout = 3000, retryInterval = 100, debug = false } = options;
+        if (!this.canUseDOM()) {
+            throw new Error('DOM을 사용할 수 없는 환경입니다.');
+        }
+        // 즉시 찾을 수 있으면 바로 반환
+        const immediateElement = document.getElementById(id);
+        if (immediateElement) {
+            if (debug) {
+                console.log(`✅ 컨테이너 즉시 발견: ${id}`);
+            }
+            return immediateElement;
+        }
+        if (debug) {
+            console.log(`⏳ 컨테이너 대기 시작: ${id} (최대 ${timeout}ms)`);
+        }
+        return new Promise((resolve, reject) => {
+            let attempts = 0;
+            const maxAttempts = Math.ceil(timeout / retryInterval);
+            const checkElement = () => {
+                attempts++;
+                const element = document.getElementById(id);
+                if (element) {
+                    if (debug) {
+                        console.log(`✅ 컨테이너 발견: ${id} (${attempts}번째 시도, ${attempts * retryInterval}ms 경과)`);
+                    }
+                    resolve(element);
+                    return;
+                }
+                if (attempts >= maxAttempts) {
+                    const errorMessage = `❌ 컨테이너를 찾을 수 없습니다: "${id}"
+          
+다음을 확인해보세요:
+1. HTML에 id="${id}" 요소가 있는지 확인
+2. React/Vue 등에서 컴포넌트가 렌더링된 후 SDK 호출
+3. 철자가 정확한지 확인
+4. 중복된 ID가 없는지 확인
+
+대기 시간: ${timeout}ms (${attempts}번 시도)`;
+                    if (debug) {
+                        console.error(errorMessage);
+                    }
+                    reject(new Error(errorMessage));
+                    return;
+                }
+                if (debug && attempts % 10 === 0) {
+                    console.log(`⏳ 컨테이너 대기 중: ${id} (${attempts}/${maxAttempts})`);
+                }
+                // Exponential backoff: 처음엔 빠르게, 나중엔 느리게
+                const nextInterval = Math.min(retryInterval * Math.pow(1.2, attempts), 500);
+                setTimeout(checkElement, nextInterval);
+            };
+            // 첫 번째 체크는 즉시 실행
+            setTimeout(checkElement, retryInterval);
+        });
+    }
+    /**
+     * 여러 DOM 요소를 동시에 기다리기
+     */
+    static async waitForElements(ids, options = {}) {
+        const promises = ids.map(id => this.waitForElement(id, options));
+        return Promise.all(promises);
+    }
 }
 
 /**
@@ -1810,31 +1876,49 @@ class AdStageSDK {
      * 광고 슬롯 생성 및 로드
      */
     async createSlot(id, containerId, adType = AdType.BANNER, options) {
-        const container = DOMUtils.safeGetElementById(containerId);
-        if (!container) {
-            if (DOMUtils.canUseDOM()) {
-                console.error(`Container with ID "${containerId}" not found`);
+        try {
+            // 💡 사용자 친화적 개선: 컨테이너가 나타날 때까지 자동으로 기다림
+            if (this.config.debug) {
+                console.log(`🔍 컨테이너 검색 시작: ${containerId}`);
+            }
+            const container = await DOMUtils.waitForElement(containerId, {
+                timeout: 5000, // 최대 5초 대기
+                retryInterval: 50, // 50ms마다 체크 (부드러운 사용자 경험)
+                debug: this.config.debug
+            });
+            if (this.config.debug) {
+                console.log(`✅ 컨테이너 확인됨: ${containerId}`, container);
+            }
+            const slot = {
+                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) => this.renderSlot(slot, ad),
+                refresh: () => this.refreshSlot(slot.id),
+                destroy: () => this.destroySlot(slot.id),
+            };
+            this.slots.set(id, slot);
+            await this.loadSlot(slot, options);
+        }
+        catch (error) {
+            // 친절한 에러 메시지로 사용자 가이드
+            if (error instanceof Error && error.message.includes('컨테이너를 찾을 수 없습니다')) {
+                console.error(error.message);
+                throw error;
+            }
+            else {
+                console.error(`❌ 광고 슬롯 생성 실패 (${id}):`, error);
+                throw new Error(`광고 슬롯 생성에 실패했습니다: ${error}`);
             }
-            return;
         }
-        const slot = {
-            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) => this.renderSlot(slot, ad),
-            refresh: () => this.refreshSlot(slot.id),
-            destroy: () => this.destroySlot(slot.id),
-        };
-        this.slots.set(id, slot);
-        await this.loadSlot(slot, options);
     }
     /**
      * 광고 슬롯 로드
@@ -1848,38 +1932,73 @@ class AdStageSDK {
                 ...(options?.deviceType && { deviceType: options.deviceType }),
                 ...(options?.country && { country: options.country }),
             });
-            const response = await fetch(`${this.baseUrl}/advertisements/list?${queryParams}`, {
+            const requestUrl = `${this.baseUrl}/advertisements/list?${queryParams}`;
+            if (this.config.debug) {
+                console.log(`🌐 광고 API 요청 시작:`, {
+                    url: requestUrl,
+                    apiKey: this.config.apiKey.substring(0, 10) + '...',
+                    slot: slot.id
+                });
+            }
+            const response = await fetch(requestUrl, {
                 headers: {
                     'x-api-key': this.config.apiKey,
                     'Content-Type': 'application/json',
                 },
             });
+            if (this.config.debug) {
+                console.log(`📡 API 응답 상태:`, {
+                    status: response.status,
+                    statusText: response.statusText,
+                    ok: response.ok
+                });
+            }
             if (!response.ok) {
                 throw new Error(`HTTP error! status: ${response.status}`);
             }
             const data = await response.json();
+            if (this.config.debug) {
+                console.log(`📊 API 응답 데이터:`, {
+                    data,
+                    advertisementsCount: data.advertisements ? data.advertisements.length : 0
+                });
+            }
             const advertisements = data.advertisements || [];
             if (advertisements.length > 0) {
+                if (this.config.debug) {
+                    console.log(`✅ ${advertisements.length}개 광고 발견:`, advertisements);
+                }
                 // 여러 광고가 있을 경우 슬라이드로 렌더링
                 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}`);
+                console.warn(`⚠️ 슬롯 ${slot.id}에 사용 가능한 광고가 없습니다. API 응답:`, data);
             }
         }
         catch (error) {
-            console.error(`Failed to load slot ${slot.id}:`, error);
+            console.error(`❌ 슬롯 ${slot.id} 로드 실패:`, error);
         }
     }
     /**
      * 광고 슬롯 렌더링 (슬라이더 포함)
      */
     renderSlotWithSlider(slot, advertisements, options) {
+        // 💡 한 번 더 안전하게 컨테이너 확인
         const container = DOMUtils.safeGetElementById(slot.containerId);
-        if (!container)
+        if (!container) {
+            console.error(`❌ 렌더링 시점에 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
             return;
+        }
+        if (this.config.debug) {
+            console.log(`🎨 광고 렌더링 시작:`, {
+                slotId: slot.id,
+                containerId: slot.containerId,
+                advertisementCount: advertisements.length,
+                container: container
+            });
+        }
         if (advertisements.length === 1) {
             // 광고가 하나뿐이면 기본 렌더링
             this.renderSlot(slot, advertisements[0]);
@@ -1903,7 +2022,11 @@ class AdStageSDK {
         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);
+            console.log(`✅ ${advertisements.length}개 광고를 ${sliderType}로 렌더링 완료:`, {
+                slotId: slot.id,
+                container: container,
+                sliderContainer: sliderContainer
+            });
         }
     }
     /**
@@ -1911,15 +2034,36 @@ class AdStageSDK {
      */
     renderSlot(slot, ad) {
         const container = DOMUtils.safeGetElementById(slot.containerId);
-        if (!container)
+        if (!container) {
+            console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
             return;
+        }
+        if (this.config.debug) {
+            console.log(`🎨 단일 광고 렌더링 시작:`, {
+                slotId: slot.id,
+                containerId: slot.containerId,
+                ad: ad,
+                container: container
+            });
+        }
         // 팩토리를 사용해서 적절한 렌더러로 광고 생성
         const adElement = AdRendererFactory.render(ad, slot, (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType));
+        if (this.config.debug) {
+            console.log(`🔧 광고 요소 생성됨:`, {
+                adElement: adElement,
+                tagName: adElement.tagName,
+                innerHTML: adElement.innerHTML.substring(0, 200) + '...'
+            });
+        }
         container.innerHTML = '';
         container.appendChild(adElement);
         slot.isLoaded = true;
         if (this.config.debug) {
-            console.log(`Rendered ad for slot ${slot.id}:`, ad);
+            console.log(`✅ 단일 광고 렌더링 완료:`, {
+                slotId: slot.id,
+                ad: ad,
+                containerContent: container.innerHTML.substring(0, 200) + '...'
+            });
         }
     }
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adstage/web-sdk",
-  "version": "1.3.2",
-  "description": "AdStage Web SDK for displaying advertisements",
+  "version": "1.3.4",
+  "description": "AdStage Web SDK for displaying advertisements with auto DOM-ready detection",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/src/index.ts

@@ -85,33 +85,51 @@ export class AdStageSDK {
       sliderEffect?: 'slide' | 'fade'; // 슬라이더 효과 선택 (기본값: slide)
     }
   ): Promise<void> {
-    const container = DOMUtils.safeGetElementById(containerId);
-    if (!container) {
-      if (DOMUtils.canUseDOM()) {
-        console.error(`Container with ID "${containerId}" not found`);
+    try {
+      // 💡 사용자 친화적 개선: 컨테이너가 나타날 때까지 자동으로 기다림
+      if (this.config.debug) {
+        console.log(`🔍 컨테이너 검색 시작: ${containerId}`);
       }
-      return;
-    }
+      
+      const container = await DOMUtils.waitForElement(containerId, {
+        timeout: 5000,      // 최대 5초 대기
+        retryInterval: 50,  // 50ms마다 체크 (부드러운 사용자 경험)
+        debug: this.config.debug
+      });
 
-    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),
-    };
+      if (this.config.debug) {
+        console.log(`✅ 컨테이너 확인됨: ${containerId}`, container);
+      }
 
-    this.slots.set(id, slot);
-    await this.loadSlot(slot, options);
+      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);
+    } catch (error) {
+      // 친절한 에러 메시지로 사용자 가이드
+      if (error instanceof Error && error.message.includes('컨테이너를 찾을 수 없습니다')) {
+        console.error(error.message);
+        throw error;
+      } else {
+        console.error(`❌ 광고 슬롯 생성 실패 (${id}):`, error);
+        throw new Error(`광고 슬롯 생성에 실패했습니다: ${error}`);
+      }
+    }
   }
 
   /**
@@ -127,34 +145,61 @@ export class AdStageSDK {
         ...(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',
-          },
-        }
-      );
+      const requestUrl = `${this.baseUrl}/advertisements/list?${queryParams}`;
+      
+      if (this.config.debug) {
+        console.log(`🌐 광고 API 요청 시작:`, {
+          url: requestUrl,
+          apiKey: this.config.apiKey.substring(0, 10) + '...',
+          slot: slot.id
+        });
+      }
+
+      const response = await fetch(requestUrl, {
+        headers: {
+          'x-api-key': this.config.apiKey,
+          'Content-Type': 'application/json',
+        },
+      });
+
+      if (this.config.debug) {
+        console.log(`📡 API 응답 상태:`, {
+          status: response.status,
+          statusText: response.statusText,
+          ok: response.ok
+        });
+      }
 
       if (!response.ok) {
         throw new Error(`HTTP error! status: ${response.status}`);
       }
 
       const data = await response.json();
+      
+      if (this.config.debug) {
+        console.log(`📊 API 응답 데이터:`, {
+          data,
+          advertisementsCount: data.advertisements ? data.advertisements.length : 0
+        });
+      }
+      
       const advertisements = data.advertisements || [];
 
       if (advertisements.length > 0) {
+        if (this.config.debug) {
+          console.log(`✅ ${advertisements.length}개 광고 발견:`, advertisements);
+        }
+        
         // 여러 광고가 있을 경우 슬라이드로 렌더링
         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}`);
+        console.warn(`⚠️ 슬롯 ${slot.id}에 사용 가능한 광고가 없습니다. API 응답:`, data);
       }
     } catch (error) {
-      console.error(`Failed to load slot ${slot.id}:`, error);
+      console.error(`❌ 슬롯 ${slot.id} 로드 실패:`, error);
     }
   }
 
@@ -162,8 +207,21 @@ export class AdStageSDK {
    * 광고 슬롯 렌더링 (슬라이더 포함)
    */
   private renderSlotWithSlider(slot: AdSlot, advertisements: Advertisement[], options?: any): void {
+    // 💡 한 번 더 안전하게 컨테이너 확인
     const container = DOMUtils.safeGetElementById(slot.containerId);
-    if (!container) return;
+    if (!container) {
+      console.error(`❌ 렌더링 시점에 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
+      return;
+    }
+
+    if (this.config.debug) {
+      console.log(`🎨 광고 렌더링 시작:`, {
+        slotId: slot.id,
+        containerId: slot.containerId,
+        advertisementCount: advertisements.length,
+        container: container
+      });
+    }
 
     if (advertisements.length === 1) {
       // 광고가 하나뿐이면 기본 렌더링
@@ -202,7 +260,11 @@ export class AdStageSDK {
 
     if (this.config.debug) {
       const sliderType = useFadeEffect ? 'fade slider' : 'slider';
-      console.log(`Rendered ${advertisements.length} ads with ${sliderType} for slot ${slot.id}:`, advertisements);
+      console.log(`✅ ${advertisements.length}개 광고를 ${sliderType}로 렌더링 완료:`, {
+        slotId: slot.id,
+        container: container,
+        sliderContainer: sliderContainer
+      });
     }
   }
 
@@ -211,7 +273,19 @@ export class AdStageSDK {
    */
   private renderSlot(slot: AdSlot, ad: Advertisement): void {
     const container = DOMUtils.safeGetElementById(slot.containerId);
-    if (!container) return;
+    if (!container) {
+      console.error(`❌ 컨테이너를 찾을 수 없습니다: ${slot.containerId}`);
+      return;
+    }
+
+    if (this.config.debug) {
+      console.log(`🎨 단일 광고 렌더링 시작:`, {
+        slotId: slot.id,
+        containerId: slot.containerId,
+        ad: ad,
+        container: container
+      });
+    }
 
     // 팩토리를 사용해서 적절한 렌더러로 광고 생성
     const adElement = AdRendererFactory.render(
@@ -220,12 +294,24 @@ export class AdStageSDK {
       (adId, slotId, eventType) => this.eventTracker.trackEvent(adId, slotId, eventType)
     );
 
+    if (this.config.debug) {
+      console.log(`🔧 광고 요소 생성됨:`, {
+        adElement: adElement,
+        tagName: adElement.tagName,
+        innerHTML: adElement.innerHTML.substring(0, 200) + '...'
+      });
+    }
+
     container.innerHTML = '';
     container.appendChild(adElement);
     slot.isLoaded = true;
 
     if (this.config.debug) {
-      console.log(`Rendered ad for slot ${slot.id}:`, ad);
+      console.log(`✅ 단일 광고 렌더링 완료:`, {
+        slotId: slot.id,
+        ad: ad,
+        containerContent: container.innerHTML.substring(0, 200) + '...'
+      });
     }
   }
 

package/src/utils/dom-utils.ts

@@ -234,4 +234,97 @@ export class DOMUtils {
       scrollLeft: this.getWindowProperty('pageXOffset', 0),
     };
   }
+
+  /**
+   * DOM 요소가 나타날 때까지 기다리기 (사용자 친화적 API)
+   */
+  static async waitForElement(
+    id: string, 
+    options: {
+      timeout?: number;        // 최대 대기 시간 (ms), 기본값: 3000
+      retryInterval?: number;  // 재시도 간격 (ms), 기본값: 100  
+      debug?: boolean;         // 디버그 로그 출력 여부
+    } = {}
+  ): Promise<HTMLElement> {
+    const { timeout = 3000, retryInterval = 100, debug = false } = options;
+    
+    if (!this.canUseDOM()) {
+      throw new Error('DOM을 사용할 수 없는 환경입니다.');
+    }
+
+    // 즉시 찾을 수 있으면 바로 반환
+    const immediateElement = document.getElementById(id);
+    if (immediateElement) {
+      if (debug) {
+        console.log(`✅ 컨테이너 즉시 발견: ${id}`);
+      }
+      return immediateElement;
+    }
+
+    if (debug) {
+      console.log(`⏳ 컨테이너 대기 시작: ${id} (최대 ${timeout}ms)`);
+    }
+
+    return new Promise((resolve, reject) => {
+      let attempts = 0;
+      const maxAttempts = Math.ceil(timeout / retryInterval);
+      
+      const checkElement = () => {
+        attempts++;
+        const element = document.getElementById(id);
+        
+        if (element) {
+          if (debug) {
+            console.log(`✅ 컨테이너 발견: ${id} (${attempts}번째 시도, ${attempts * retryInterval}ms 경과)`);
+          }
+          resolve(element);
+          return;
+        }
+        
+        if (attempts >= maxAttempts) {
+          const errorMessage = `❌ 컨테이너를 찾을 수 없습니다: "${id}"
+          
+다음을 확인해보세요:
+1. HTML에 id="${id}" 요소가 있는지 확인
+2. React/Vue 등에서 컴포넌트가 렌더링된 후 SDK 호출
+3. 철자가 정확한지 확인
+4. 중복된 ID가 없는지 확인
+
+대기 시간: ${timeout}ms (${attempts}번 시도)`;
+          
+          if (debug) {
+            console.error(errorMessage);
+          }
+          reject(new Error(errorMessage));
+          return;
+        }
+        
+        if (debug && attempts % 10 === 0) {
+          console.log(`⏳ 컨테이너 대기 중: ${id} (${attempts}/${maxAttempts})`);
+        }
+        
+        // Exponential backoff: 처음엔 빠르게, 나중엔 느리게
+        const nextInterval = Math.min(retryInterval * Math.pow(1.2, attempts), 500);
+        setTimeout(checkElement, nextInterval);
+      };
+      
+      // 첫 번째 체크는 즉시 실행
+      setTimeout(checkElement, retryInterval);
+    });
+  }
+
+  /**
+   * 여러 DOM 요소를 동시에 기다리기
+   */
+  static async waitForElements(
+    ids: string[], 
+    options: {
+      timeout?: number;
+      retryInterval?: number;
+      debug?: boolean;
+    } = {}
+  ): Promise<HTMLElement[]> {
+    const promises = ids.map(id => this.waitForElement(id, options));
+    return Promise.all(promises);
+  }
 }