Common Features

This document gathers the "common concepts" that were repeated across the individual ad type documents into one place to make maintenance easier, so that the ad type documents can focus on the features unique to each type.

🧱 Basic Structure & Common Call Pattern

// 1) SDK 초기화 (앱 전역 1회)
AdStage.init({
  apiKey: 'your-api-key',
  debug: process.env.NODE_ENV === 'development'
});
 
// 2) 컨테이너 DOM 준비 후 호출 (id 또는 Element 모두 허용)
AdStage.ads.banner('banner-container', { /* 옵션 */ });
// AdStage.ads.text(element, { /* 옵션 */ });
// AdStage.ads.video('video-wrapper', { /* 옵션 */ });
 
// 3) 필요 시 수동 제거 (대부분 필요 없음: 자동 정리 지원)
AdStage.ads.destroy(slotId);

Common Pattern for React / Next.js Provider

import { AdStageProvider, useAdStageInstance } from '@adstage/web-sdk';
 
// layout / root
<AdStageProvider config={{ apiKey: process.env.NEXT_PUBLIC_ADSTAGE_API_KEY, debug: true }}>
  {children}
</AdStageProvider>
 
// 개별 컴포넌트
function BannerSlot() {
  const adstage = useAdStageInstance();
  const ref = useRef(null);
  useEffect(() => {
    if (!adstage || !ref.current) return;
    const id = adstage.ads.banner(ref.current, { width: '100%', height: 250 });
    return () => adstage.ads.destroy(id);
  }, [adstage]);
  return <div ref={ref} style={{ height: 250 }} />;
}

⚙️ Common Options Summary

Option	Type	Description	Applies To
`onClick`	`function(adData)`	Callback when the ad is clicked	All types
`adId`	`string`	Force a specific ad	All types
`language`	`'ko' \| 'en' \| 'ja' \| 'zh'`	Language filter	All types
`deviceType`	`'MOBILE' \| 'DESKTOP'`	Device filter	All types
`country`	Country code (ISO2)	Country filter	All types

For options unique to each ad type, refer to the respective document (banner/text/video).

🔄 Lifecycle & Internal Behavior

graph TD
  A[init 호출] --> B[slot 함수 호출]
  B --> C[컨테이너 탐색/재시도]
  C --> D[서버 광고 요청]
  D --> E[비동기 로딩]
  E --> F[렌더링]
  F --> G[노출 추적]
  G --> H[클릭/상호작용 추적]

Key Characteristics

Immediate-return type: slotId is returned immediately before the server responds ⇒ no UI blocking
Handling of deferred containers: even if the container is not yet in the DOM, it will retry for a certain time and render once it is attached
Automatic cleanup based on MutationObserver: destroy() runs automatically when the DOM is removed
Multi-ad safe: when the same container is called repeatedly, only the latest call is valid (implementation policy)

🧪 Slot Management API

// 모든 슬롯 정보
const all = AdStage.ads.getAllSlots();
 
// 특정 슬롯 조회
const slot = AdStage.ads.getSlotById(slotId);
 
// 수동 제거 (필요한 경우)
AdStage.ads.destroy(slotId);

Slot object (actual fields):

interface AdSlot {
  id: string;                 // 슬롯 ID (slotId)
  containerId: string;        // 컨테이너 DOM id
  adType: 'BANNER' | 'TEXT' | 'VIDEO' | 'NATIVE' | 'INTERSTITIAL' | 'POPUP';
  width: number | string;     // 숫자(px) 또는 문자열('100%' 등)
  height: number | string;    // 숫자(px) 또는 문자열('auto' 등)
  isLoaded: boolean;          // 광고 로드 완료 여부
  isVisible: boolean;         // 노출 상태
  refreshRate: number;        // 자동 새로고침 주기(초)
  lazyLoad: boolean;          // 지연 로딩 여부
  targeting: Record<string, any>;
 
  // 슬롯 메서드
  load(): Promise<Advertisement | null>;
  render(ad: Advertisement): void;
  refresh(): Promise<void>;
  destroy(): void;
}

🚀 Common Performance & Optimization Strategies

Strategy	Description	Notes
Background loading	No blocking of initial render thanks to async loading	`slotId` is usable immediately
Deferred container support	Automatically handles cases where the DOM is inserted later	Simplifies initialization code
Automatic cleanup	Prevents memory/event leaks	Useful during SPA transitions
Minimal DOM manipulation	Updates only the DOM inside the container	Minimizes impact on parent layout
Size optimization per type	Banner/video specify size, text uses automatic height	Reduces CLS

Common Template for Responsive Pattern

function selectDeviceType() {
  return window.innerWidth <= 768 ? 'MOBILE' : 'DESKTOP';
}
 
const base = { language: 'ko', deviceType: selectDeviceType() };
const id = AdStage.ads.banner('rwd-banner', { width: '100%', height: 250, ...base });
 
window.addEventListener('resize', () => {
  AdStage.ads.destroy(id);
  const next = AdStage.ads.banner('rwd-banner', { width: '100%', height: 250, deviceType: selectDeviceType() });
});

📦 Summary of Recommended React / Next.js Patterns

Pattern	Description	When to Use
Global initialization via Provider	Configure the SDK only once	App/RootLayout
Hook (useAdStageInstance)	Safe SDK access	CSR component
cleanup in useEffect	Guarantees `destroy`	Clarifies slot lifetime
Skeleton style	Customize the `.adstage-loading` state	Improves UX

🎨 Common CSS Classes

.adstage-ad, .adstage-text-ad, .adstage-video-ad { position: relative; overflow: hidden; }
.adstage-loading { opacity: .6; transition: opacity .15s; }
.adstage-loaded { opacity: 1; }
.adstage-error { outline: 1px solid #f87171; }

For additional styles per type, refer to the individual documents.

🛠 Debugging & Monitoring

Enabling Debug Mode

AdStage.init({ apiKey: 'your-api-key', debug: true });

Click Hook (onClick callback)

The SDK does not emit DOM CustomEvents such as adstage:ad:loaded / adstage:ad:error. If you need an ad interaction hook, pass an onClick callback when creating the slot.

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  onClick: (adData) => {
    console.log('광고 클릭됨:', adData);
    // 추가 추적/라우팅 로직
  }
});

Checking Load Status

You can check whether loading has completed by polling the slot's isLoaded field (if you turn on debug mode, load/failure is printed to the console).

const slotId = AdStage.ads.banner('banner-container', { width: '100%', height: 250 });
 
const timer = setInterval(() => {
  const slot = AdStage.ads.getSlotById(slotId);
  if (slot?.isLoaded) {
    console.log('로드 완료:', slot);
    clearInterval(timer);
  }
}, 200);

State Diagnostic Utility

function dumpAdStage() {
  const slots = AdStage.ads.getAllSlots();
  console.table(slots.map(s => ({
    id: s.id,
    containerId: s.containerId,
    adType: s.adType,
    isLoaded: s.isLoaded
  })));
}

🔐 Safety & Best Practices

Topic	Recommendation
API Key	It can be publicly exposed, but use a key with minimal permissions
Event tracking	When adding tracking in onClick, sending asynchronously before routing is recommended
Error handling	Diagnose load failures using debug mode console logs and the slot's `isLoaded` state
Retry policy	The deferred container insertion case is handled internally → avoid overusing additional setTimeout

❓FAQ (Common)

Q. Do I have to call destroy()?
A. In most cases, no. DOM removal detection is performed automatically. However, if you reuse the same container immediately for a different purpose, a manual destroy() is recommended.

Q. The ad isn't showing, but the slotId is returned.
A. It may still be loading asynchronously, or it may have been filtered out by a filter (adId / language / deviceType / country). Enable debug mode and check the event log.

Q. With SSR (Next.js), is it rendered on the server side?
A. No. Ad rendering is performed only on the client side. Call it inside a use client component.

Q. What happens with consecutive calls at the same location?
A. Per the implementation policy, the existing slot is removed and the state is maintained based on the last call.

Common Features

Table of Contents