Advertising System Overview

The AdStage Web SDK supports three types of ads in web applications.

🎯 Supported Ad Types

Image-based ads, the most common format.

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250
});

Features: Image-based, automatic resizing, slide support

Text Ads

Text-based native ads that integrate naturally with your content.

AdStage.ads.text('text-container');

Features: Automatic height adjustment, line count limit, native styling

Video Ads

Video-based ads that deliver high engagement.

AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: true,
  muted: true
});

Features: HTML5 video, autoplay/mute, mobile optimization

🔄 Basic Usage Flow

Initialize the SDK - Configure with AdStage.init()
Prepare a container - Create an ad display area in your HTML
Request an ad - Call ads.banner(), ads.text(), or ads.video()
Automatic rendering - Ads load and display in the background
Event tracking - Impressions/clicks are collected automatically

📚 Next Steps

Check out the detailed usage guide for each ad type:

Common Features: Common options and features for all ad types
Banner Ads: Detailed banner ad settings and advanced features
Text Ads: How to customize text ads
Video Ads: Video ad control and optimization

🎯 Supported Ad Types

Image-based banner ads, the most common form of web advertising.

// 기본 배너 광고
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250
});
 
// 클릭 이벤트 처리 및 고급 옵션
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  onClick: (adData) => {
    console.log('배너 광고 클릭:', adData);
  }
});

Key features:

Dynamic resizing (automatically optimized based on image size)
Fast response with background loading
Automatic slide support (for multiple ads)

Text Ads

Text-based native ads that blend naturally with your content.

// 기본 텍스트 광고
AdStage.ads.text('text-container', {
  maxLines: 3
});
 
// 클릭 이벤트 처리
AdStage.ads.text('text-container', {
  maxLines: 3,
  onClick: (adData) => {
    console.log('텍스트 광고 클릭:', adData);
  }
});

Key features:

Automatically fits to content height (height: 'auto')
Natural integration with your site design
Maximum line count limit available

Video Ads

Video-based ads that deliver high engagement.

// 기본 비디오 광고 (기본값: 자동재생, 음소거, 컨트롤 숨김)
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: true,  // 기본값: true
  muted: true,     // 기본값: true
  controls: false  // 기본값: false
});
 
// 사용자 제어 가능한 비디오 광고
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: false,
  muted: false,
  controls: true,
  onClick: (adData) => {
    console.log('비디오 광고 클릭:', adData);
  }
});

Key features:

Optimized for a single video (maxAds: 1)
HTML5 video player
Mobile inline playback support (playsinline: true)
Loop playback enabled by default (loop: true)

🔄 Ad Display Process

graph TD
    A[SDK 초기화] --> B[광고 컨테이너 탐지]
    B --> C[광고 요청]
    C --> D[광고 응답 수신]
    D --> E[광고 렌더링]
    E --> F[노출 이벤트 전송]
    F --> G[사용자 상호작용 추적]

Initialization: Configure the SDK with AdStage.init()
Container preparation: Create the element where the ad will be displayed in your HTML
Ad request: Request ad content from the server
Rendering: Display the received ad in the specified container
Tracking: Automatically track impression and click events

⚙️ Configuration Options

Common Options

Options available for all ad types:

Option	Type	Default	Description
`onClick`	`function`	`undefined`	Callback function on ad click
`adId`	`string`	`undefined`	Specify a particular ad ID
`language`	`'ko' \| 'en' \| 'ja' \| 'zh'`	`undefined`	Language filter
`deviceType`	`'MOBILE' \| 'DESKTOP'`	`undefined`	Device type filter
`country`	`'KR' \| 'US' \| 'JP' \| 'CN' \| 'DE'`	`undefined`	Country filter

Option	Type	Default	Description
`width`	`string \| number`	`'100%'`	Ad width
`height`	`number`	250	Ad height (banner defaults to 250px)
`autoSlide`	`boolean`	`false`	Automatic slide for multiple ads
`slideInterval`	`number`	`5000`	Slide interval (ms)

Text Ad-Specific Options

Option	Type	Default	Description
`maxLines`	`number`	`3`	Maximum number of lines
`style`	`string`	`'default'`	Style theme

Note: The height of text ads is automatically adjusted based on content (height: 'auto').

Video Ad-Specific Options

Option	Type	Default	Description
`width`	`number`	`640`	Video width
`height`	`number`	`360`	Video height
`autoplay`	`boolean`	`true`	Autoplay
`muted`	`boolean`	`true`	Mute
`loop`	`boolean`	`true`	Loop playback
`controls`	`boolean`	`false`	Show controls
`playsinline`	`boolean`	`true`	Inline playback (mobile)
`hideControls`	`boolean`	`false`	Hide all controls
`customControls`	`object`	`undefined`	Detailed control settings

Video Custom Control Options

customControls: {
  hidePlayButton: boolean,      // 재생 버튼 숨기기
  hideProgressBar: boolean,     // 진행바 숨기기  
  hideCurrentTime: boolean,     // 현재 시간 숨기기
  hideRemainingTime: boolean,   // 남은 시간 숨기기
  hideVolumeSlider: boolean,    // 볼륨 슬라이더 숨기기
  hideMuteButton: boolean,      // 음소거 버튼 숨기기
  hideFullscreenButton: boolean // 전체화면 버튼 숨기기
}

Example: Advanced Configuration

// 특정 광고 ID로 배너 광고 표시
AdStage.ads.banner('my-banner', {
  width: '100%',
  height: 250,
  adId: 'specific-ad-123',
  language: 'ko',
  deviceType: 'DESKTOP',
  onClick: (adData) => {
    console.log('광고 클릭:', adData);
    // 사용자 정의 추적 로직
  }
});
 
// 커스텀 컨트롤이 있는 비디오 광고
AdStage.ads.video('video-container', {
  width: 640,
  height: 360,
  autoplay: false,
  muted: false,
  controls: true,
  customControls: {
    hideFullscreenButton: true,
    hideVolumeSlider: false,
    hideProgressBar: false
  }
});

📊 Performance Optimization

Background Loading

The SDK automatically loads ads in the background:

// 슬롯 ID는 즉시 반환, 광고는 백그라운드에서 로드
const slotId = AdStage.ads.banner('banner-ad');
console.log('슬롯 생성됨:', slotId); // 즉시 실행
 
// 실제 광고는 비동기로 로드되어 렌더링됨

Auto Cleanup

Ad containers removed from the DOM are cleaned up automatically:

// MutationObserver를 통한 자동 감지 및 정리
// 개발자가 수동으로 destroy()를 호출할 필요 없음
const slotId = AdStage.ads.banner('banner-ad');
 
// DOM에서 컨테이너가 제거되면 자동으로 슬롯도 정리됨
document.getElementById('banner-ad').remove();

Retry Logic

Automatically retries when the container is not found:

// 컨테이너가 아직 존재하지 않아도 점진적으로 재시도
const slotId = AdStage.ads.banner('not-yet-exists', {
  width: '100%',
  height: 250
});
 
// 나중에 DOM에 컨테이너가 추가되면 자동으로 광고 표시
setTimeout(() => {
  const div = document.createElement('div');
  div.id = 'not-yet-exists';
  document.body.appendChild(div);
}, 1000);

🎨 Styling Guide

CSS Classes

CSS classes the SDK adds automatically:

/* 광고 컨테이너 */
.adstage-ad {
  position: relative;
  overflow: hidden;
}
 
/* 로딩 상태 */
.adstage-loading {
  opacity: 0.7;
}
 
/* 로딩 완료 */
.adstage-loaded {
  opacity: 1;
  transition: opacity 0.3s ease;
}
 
/* 오류 상태 */
.adstage-error {
  border: 1px solid #ff0000;
}

Responsive Design

Ad settings tailored to various screen sizes:

AdStage.ads.banner('responsive-banner', {
  width: '100%',
  height: window.innerWidth > 768 ? 250 : 100
});

Real-World Usage Examples

The SDK can be used in JavaScript, React, and Next.js environments. Learn how to implement it through real-world examples.

JavaScript (UMD Approach)

How to load and use the UMD build directly in an HTML file.

<!DOCTYPE html>
<html>
<head>
  <title>AdStage SDK Example</title>
</head>
<body>
  <!-- 광고 컨테이너 -->
  <div id="banner-ad">배너 광고가 로드 중입니다...</div>
  <div id="text-ad">텍스트 광고가 로드 중입니다...</div>
  <div id="video-ad">비디오 광고가 로드 중입니다...</div>
 
  <!-- SDK 로드 -->
  <script src="https://unpkg.com/@adstage/web-sdk/dist/index.umd.js"></script>
  
  <script>
    // SDK 초기화
    AdStage.init({
      apiKey: 'your-api-key',
      debug: true
    });
    
    // 광고 생성
    const bannerSlotId = AdStage.ads.banner('banner-ad', {
      width: '100%',
      height: 250,
      onClick: (adData) => console.log('배너 클릭:', adData)
    });
    
    const textSlotId = AdStage.ads.text('text-ad', {
      maxLines: 3,
      onClick: (adData) => console.log('텍스트 클릭:', adData)
    });
    
    const videoSlotId = AdStage.ads.video('video-ad', {
      width: 640,
      height: 360,
      autoplay: true,
      muted: true,
      controls: false,
      onClick: (adData) => console.log('비디오 클릭:', adData)
    });
  </script>
</body>
</html>

React (Basic Approach)

How to use the SDK directly in React.

import React, { useEffect, useRef } from 'react';
import { AdStage } from '@adstage/web-sdk';
 
function AdComponent() {
  const bannerRef = useRef(null);
  const textRef = useRef(null);
  const videoRef = useRef(null);
  const slotIdsRef = useRef({});
 
  useEffect(() => {
    // SDK 초기화
    AdStage.init({
      apiKey: 'your-api-key',
      debug: true
    });
 
    // 광고 생성
    if (bannerRef.current) {
      slotIdsRef.current.banner = AdStage.ads.banner(bannerRef.current, {
        width: '100%',
        height: 250,
        onClick: (adData) => console.log('배너 클릭:', adData)
      });
    }
 
    if (textRef.current) {
      slotIdsRef.current.text = AdStage.ads.text(textRef.current, {
        maxLines: 3,
        onClick: (adData) => console.log('텍스트 클릭:', adData)
      });
    }
 
    if (videoRef.current) {
      slotIdsRef.current.video = AdStage.ads.video(videoRef.current, {
        width: 640,
        height: 360,
        autoplay: true,
        muted: true,
        controls: false,
        onClick: (adData) => console.log('비디오 클릭:', adData)
      });
    }
 
    // 정리 함수
    return () => {
      Object.values(slotIdsRef.current).forEach(slotId => {
        if (slotId) AdStage.ads.destroy(slotId);
      });
    };
  }, []);
 
  return (
    <div>
      <h1>AdStage SDK - React 예제</h1>
      
      <div style={{ margin: '20px 0' }}>
        <h2>Banner Advertisement</h2>
        <div 
          ref={bannerRef}
          style={{ 
            minHeight: '100px',
            border: '2px dashed #ccc',
            borderRadius: '4px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          배너 광고가 로드 중입니다...
        </div>
      </div>
 
      <div style={{ margin: '20px 0' }}>
        <h2>Text Advertisement</h2>
        <div ref={textRef}>
          텍스트 광고가 로드 중입니다...
        </div>
      </div>
 
      <div style={{ margin: '20px 0' }}>
        <h2>Video Advertisement</h2>
        <div ref={videoRef}>
          비디오 광고가 로드 중입니다...
        </div>
      </div>
    </div>
  );
}
 
export default AdComponent;

Next.js (Provider Approach)

The recommended approach using AdStageProvider in Next.js.

1. Set up the Provider in _app.js

// pages/_app.js
import { AdStageProvider } from '@adstage/web-sdk';
 
export default function App({ Component, pageProps }) {
  return (
    <AdStageProvider
      config={{
        apiKey: 'your-api-key',
        debug: true
      }}
    >
      <Component {...pageProps} />
    </AdStageProvider>
  );
}

2. Use the useAdStageInstance hook in a page

// pages/index.js
import { useEffect, useRef } from 'react';
import { useAdStageInstance } from '@adstage/web-sdk';
 
export default function Home() {
  const adstage = useAdStageInstance();
  
  const bannerRef = useRef(null);
  const textRef = useRef(null);
  const videoRef = useRef(null);
  const slotIdsRef = useRef({});
 
  useEffect(() => {
    if (adstage) {
      loadAds();
    }
    
    return () => {
      // 컴포넌트 언마운트 시 정리
      Object.values(slotIdsRef.current).forEach(slotId => {
        if (slotId) adstage?.ads?.destroy(slotId);
      });
    };
  }, [adstage]);
 
  const loadAds = () => {
    // 배너 광고
    if (bannerRef.current) {
      slotIdsRef.current.banner = adstage.ads.banner(bannerRef.current, {
        width: '100%',
        height: 250,
        onClick: (adData) => console.log('배너 클릭:', adData)
      });
    }
    
    // 텍스트 광고
    if (textRef.current) {
      slotIdsRef.current.text = adstage.ads.text(textRef.current, {
        maxLines: 3,
        onClick: (adData) => console.log('텍스트 클릭:', adData)
      });
    }
    
    // 비디오 광고
    if (videoRef.current) {
      slotIdsRef.current.video = adstage.ads.video(videoRef.current, {
        width: 640,
        height: 360,
        autoplay: true,
        muted: true,
        controls: false,
        onClick: (adData) => console.log('비디오 클릭:', adData)
      });
    }
  };
 
  return (
    <div style={{ fontFamily: 'Arial, sans-serif', margin: '20px' }}>
      <h1>AdStage SDK - Next.js 광고 예제</h1>
      
      {/* 배너 광고 */}
      <div style={{ margin: '40px 0', padding: '20px', border: '1px solid #ddd' }}>
        <h2>Banner Advertisement</h2>
        <div 
          ref={bannerRef}
          style={{ 
            minHeight: '100px',
            border: '2px dashed #ccc',
            borderRadius: '4px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          배너 광고가 로드 중입니다...
        </div>
      </div>
      
      {/* 텍스트 광고 */}
      <div style={{ margin: '40px 0', padding: '20px', border: '1px solid #ddd' }}>
        <h2>Text Advertisement</h2>
        <div 
          ref={textRef}
          style={{ 
            backgroundColor: 'rgba(34, 197, 94, 0.1)',
            borderRadius: '12px',
            border: '1px solid rgba(34, 197, 94, 0.2)',
            padding: '16px',
            minHeight: '80px'
          }}
        >
          텍스트 광고가 로드 중입니다...
        </div>
      </div>
      
      {/* 비디오 광고 */}
      <div style={{ margin: '40px 0', padding: '20px', border: '1px solid #ddd' }}>
        <h2>Video Advertisement</h2>
        <div 
          ref={videoRef}
          style={{ 
            minHeight: '100px',
            border: '2px dashed #ccc',
            borderRadius: '4px',
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center'
          }}
        >
          비디오 광고가 로드 중입니다...
        </div>
      </div>
    </div>
  );
}

Advertising System Overview

🎯 Supported Ad Types

Banner Ads

Text Ads

Video Ads

🔄 Basic Usage Flow

📚 Next Steps

🎯 Supported Ad Types

Banner Ads

Text Ads

Video Ads

🔄 Ad Display Process

⚙️ Configuration Options

Common Options

Banner Ad-Specific Options

Text Ad-Specific Options

Video Ad-Specific Options

Video Custom Control Options

Example: Advanced Configuration

📊 Performance Optimization

Background Loading

Auto Cleanup

Retry Logic

🎨 Styling Guide

CSS Classes

Responsive Design

Real-World Usage Examples

JavaScript (UMD Approach)

React (Basic Approach)

Next.js (Provider Approach)

1. Set up the Provider in _app.js

2. Use the useAdStageInstance hook in a page

Table of Contents