StageUp
웹 SDK광고

광고 시스템 개요

AdStage Web SDK는 웹 애플리케이션에서 3가지 타입의 광고를 지원합니다.

🎯 지원하는 광고 타입

배너 광고 (Banner Ads)

이미지 기반의 광고로, 가장 일반적인 형태입니다.

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

특징: 이미지 기반, 자동 크기 조정, 슬라이드 지원

텍스트 광고 (Text Ads)

텍스트 기반의 네이티브 광고로, 콘텐츠와 자연스럽게 통합됩니다.

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

특징: 높이 자동 조정, 줄 수 제한, 네이티브 스타일

비디오 광고 (Video Ads)

동영상 기반의 광고로, 높은 참여도를 제공합니다.

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

특징: HTML5 비디오, 자동재생/음소거, 모바일 최적화

🔄 기본 사용 흐름

  1. SDK 초기화 - AdStage.init()로 설정
  2. 컨테이너 준비 - HTML에 광고 표시 영역 생성
  3. 광고 요청 - ads.banner(), ads.text(), ads.video() 호출
  4. 자동 렌더링 - 백그라운드에서 광고 로드 및 표시
  5. 이벤트 추적 - 노출/클릭 자동 수집

📚 다음 단계

각 광고 타입별 상세 사용법을 확인해보세요:

🎯 지원하는 광고 타입

배너 광고 (Banner Ads)

이미지 기반의 배너 광고로, 가장 일반적인 형태의 웹 광고입니다.

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

주요 특징:

  • 동적 크기 조정 (이미지 크기 기반으로 자동 최적화)
  • 백그라운드 로딩으로 빠른 응답
  • 자동 슬라이드 지원 (여러 광고 시)

텍스트 광고 (Text Ads)

텍스트 기반의 네이티브 광고로, 콘텐츠와 자연스럽게 어우러집니다.

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

주요 특징:

  • 콘텐츠 높이에 자동 맞춤 (height: 'auto')
  • 사이트 디자인과 자연스러운 통합
  • 최대 줄 수 제한 가능

비디오 광고 (Video Ads)

동영상 기반의 광고로, 높은 참여도를 제공합니다.

// 기본 비디오 광고 (기본값: 자동재생, 음소거, 컨트롤 숨김)
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);
  }
});

주요 특징:

  • 단일 비디오 최적화 (maxAds: 1)
  • HTML5 비디오 플레이어
  • 모바일 인라인 재생 지원 (playsinline: true)
  • 반복 재생 기본 활성화 (loop: true)

🔄 광고 표시 프로세스

graph TD
    A[SDK 초기화] --> B[광고 컨테이너 탐지]
    B --> C[광고 요청]
    C --> D[광고 응답 수신]
    D --> E[광고 렌더링]
    E --> F[노출 이벤트 전송]
    F --> G[사용자 상호작용 추적]
  1. 초기화: AdStage.init()로 SDK 설정
  2. 컨테이너 준비: HTML에 광고가 표시될 요소 생성
  3. 광고 요청: 서버에 광고 콘텐츠 요청
  4. 렌더링: 받은 광고를 지정된 컨테이너에 표시
  5. 추적: 노출 및 클릭 이벤트 자동 추적

⚙️ 설정 옵션

공통 옵션

모든 광고 타입에서 사용할 수 있는 옵션들:

옵션타입기본값설명
onClickfunctionundefined광고 클릭 시 콜백 함수
adIdstringundefined특정 광고 ID 지정
language'ko' | 'en' | 'ja' | 'zh'undefined언어 필터
deviceType'MOBILE' | 'DESKTOP'undefined디바이스 타입 필터
country'KR' | 'US' | 'JP' | 'CN' | 'DE'undefined국가 필터

배너 광고 전용 옵션

옵션타입기본값설명
widthstring | number'100%'광고 너비
heightnumber250광고 높이 (배너는 기본 250px)
autoSlidebooleanfalse여러 광고 시 자동 슬라이드
slideIntervalnumber5000슬라이드 간격 (ms)

텍스트 광고 전용 옵션

옵션타입기본값설명
maxLinesnumber3최대 줄 수
stylestring'default'스타일 테마

참고: 텍스트 광고는 콘텐츠에 따라 높이가 자동 조정됩니다 (height: 'auto').

비디오 광고 전용 옵션

옵션타입기본값설명
widthnumber640비디오 너비
heightnumber360비디오 높이
autoplaybooleantrue자동 재생
mutedbooleantrue음소거
loopbooleantrue반복 재생
controlsbooleanfalse컨트롤 표시
playsinlinebooleantrue인라인 재생 (모바일)
hideControlsbooleanfalse모든 컨트롤 숨기기
customControlsobjectundefined세부 컨트롤 설정

비디오 커스텀 컨트롤 옵션

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

예시: 고급 설정

// 특정 광고 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
  }
});

📊 성능 최적화

백그라운드 로딩

SDK는 자동으로 백그라운드에서 광고를 로드합니다:

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

자동 정리 (Auto Cleanup)

DOM에서 제거된 광고 컨테이너는 자동으로 정리됩니다:

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

재시도 로직

컨테이너를 찾지 못할 경우 자동 재시도:

// 컨테이너가 아직 존재하지 않아도 점진적으로 재시도
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);

🎨 스타일링 가이드

CSS 클래스

SDK가 자동으로 추가하는 CSS 클래스들:

/* 광고 컨테이너 */
.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;
}

반응형 디자인

다양한 화면 크기에 맞는 광고 설정:

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

실제 사용 예제

SDK는 JavaScript, React, Next.js 환경에서 사용할 수 있습니다. 실제 예제를 통해 구현 방법을 알아보세요.

JavaScript (UMD 방식)

HTML 파일에서 UMD 버전을 직접 로드하여 사용하는 방법입니다.

<!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',
      baseUrl: '',
      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 (기본 방식)

React에서 직접 SDK를 사용하는 방법입니다.

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 방식)

Next.js에서 AdStageProvider를 사용하는 권장 방법입니다.

1. _app.js에서 Provider 설정

// 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. 페이지에서 useAdStageInstance 훅 사용

// 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>
  );
}

이전 페이지

웹 SDK 개요 및 설치

다음 페이지

배너 광고

목차

🎯 지원하는 광고 타입배너 광고 (Banner Ads)텍스트 광고 (Text Ads)비디오 광고 (Video Ads)🔄 기본 사용 흐름📚 다음 단계🎯 지원하는 광고 타입배너 광고 (Banner Ads)텍스트 광고 (Text Ads)비디오 광고 (Video Ads)🔄 광고 표시 프로세스⚙️ 설정 옵션공통 옵션배너 광고 전용 옵션텍스트 광고 전용 옵션비디오 광고 전용 옵션비디오 커스텀 컨트롤 옵션예시: 고급 설정📊 성능 최적화백그라운드 로딩자동 정리 (Auto Cleanup)재시도 로직🎨 스타일링 가이드CSS 클래스반응형 디자인실제 사용 예제JavaScript (UMD 방식)React (기본 방식)Next.js (Provider 방식)1. _app.js에서 Provider 설정2. 페이지에서 useAdStageInstance 훅 사용