배너 광고

배너 광고는 이미지 기반의 광고로, 웹사이트에서 가장 일반적으로 사용되는 광고 형태입니다. AdStage SDK는 배너 광고의 자동 크기 조정, 슬라이드 기능, 백그라운드 로딩을 지원합니다.

🎯 기본 사용법

단순한 배너 광고

// HTML에 컨테이너  useEffect(() => {
// SDK 초기화 (한 번만)
AdStage.init({
    apiKey: process.env.NEXT_PUBLIC_ADSTAGE_API_KEY
});
 
// 배너 광고 생성
if (containerRef.current) {…} id="banner-container"></div>
 
// 기본 배너 광고 생성
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250
});

클릭 이벤트 처리

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  onClick: (adData) => {
    console.log('배너 광고 클릭됨:', adData);
    // 사용자 정의 로직 추가 가능
  }
});

⚙️ 설정 옵션

기본 옵션

옵션	타입	기본값	설명
`width`	`string \| number`	`'100%'`	배너 너비 (px 또는 %)
`height`	`number`	`250`	배너 높이 (px)
`onClick`	`function`	`undefined`	클릭 시 실행될 콜백 함수

고급 옵션

옵션	타입	기본값	설명
`autoSlide`	`boolean`	`false`	여러 광고 시 자동 슬라이드
`slideInterval`	`number`	`5000`	슬라이드 간격 (밀리초)
`adId`	`string`	`undefined`	특정 광고 ID 지정

필터링 옵션

옵션	타입	기본값	설명
`language`	`'ko' \| 'en' \| 'ja' \| 'zh'`	`undefined`	언어별 필터링
`deviceType`	`'MOBILE' \| 'DESKTOP'`	`undefined`	디바이스별 필터링
`country`	`'KR' \| 'US' \| 'JP' \| 'CN' \| 'DE'`	`undefined`	국가별 필터링

💡 실제 구현 예제

가장 간단한 CDN 방식으로 HTML에서 바로 사용할 수 있습니다.

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>배너 광고 예제</title>
</head>
<body>
  <h1>내 웹사이트</h1>
  
  <!-- 배너 광고 컨테이너 -->
  <div id="banner-container" style="width: 100%; height: 250px; border: 1px solid #ddd;">
    로딩 중...
  </div>
 
  <!-- AdStage SDK 로드 -->
  <script src="https://unpkg.com/@adstage/web-sdk/dist/index.umd.js"></script>
  <script>
    // SDK 초기화
    AdStage.init({
      apiKey: 'your-api-key'
    });
 
    // 배너 광고 생성
    AdStage.ads.banner('banner-container', {
      width: '100%',
      height: 250
    });
  </script>
</body>
</html>

🚀 고급 기능

자동 슬라이드

여러 배너 광고가 있을 때 자동으로 슬라이드하는 기능입니다.

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  autoSlide: true,        // 자동 슬라이드 활성화
  slideInterval: 3000     // 3초마다 슬라이드
});

반응형 배너

화면 크기에 따라 배너 크기를 조정하는 방법입니다.

// 미디어 쿼리를 활용한 반응형 구현
const getResponsiveHeight = () => {
  if (window.innerWidth <= 768) {
    return 100;  // 모바일: 높이 100px
  } else if (window.innerWidth <= 1024) {
    return 200;  // 태블릿: 높이 200px
  } else {
    return 250;  // 데스크톱: 높이 250px
  }
};
 
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: getResponsiveHeight(),
  deviceType: window.innerWidth <= 768 ? 'MOBILE' : 'DESKTOP'
});
 
// 윈도우 리사이즈 시 재생성
window.addEventListener('resize', () => {
  // 기존 광고 제거 후 새로 생성
  AdStage.ads.destroy(slotId);
  slotId = AdStage.ads.banner('banner-container', {
    width: '100%',
    height: getResponsiveHeight(),
    deviceType: window.innerWidth <= 768 ? 'MOBILE' : 'DESKTOP'
  });
});

특정 광고 ID 지정

특정한 배너 광고만 표시하고 싶을 때 사용합니다.

AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 250,
  adId: 'banner-ad-123'  // 특정 광고 ID
});

🔧 최적화 팁

1. 동적 크기 조정 활용

SDK가 자동으로 이미지 크기에 맞춰 컨테이너를 최적화합니다.

// 이미지 크기에 맞춰 자동 조정
AdStage.ads.banner('banner-container', {
  width: '100%',
  height: 'auto'  // 이미지 비율에 맞춰 자동 조정
});

2. 백그라운드 로딩

광고는 백그라운드에서 로드되므로 즉시 슬롯 ID를 받을 수 있습니다.

// 즉시 슬롯 ID 반환
const slotId = AdStage.ads.banner('banner-container');
console.log('슬롯 생성됨:', slotId);  // 즉시 실행
 
// 실제 광고는 비동기로 로드됨

3. 자동 정리 활용

DOM에서 컨테이너가 제거되면 광고도 자동으로 정리됩니다.

const slotId = AdStage.ads.banner('banner-container');
 
// DOM에서 컨테이너 제거 시 자동 정리됨
document.getElementById('banner-container').remove();
// 수동으로 destroy() 호출할 필요 없음

🎨 스타일링

CSS 클래스 활용

SDK가 자동으로 추가하는 CSS 클래스를 활용하여 스타일링할 수 있습니다.

/* 광고 컨테이너 기본 스타일 */
.adstage-ad {
  position: relative;
  overflow: hidden;
  border-radius: 8px;
}
 
/* 로딩 상태 */
.adstage-loading {
  opacity: 0.7;
  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
  background-size: 200% 100%;
  animation: loading 1.5s infinite;
}
 
@keyframes loading {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}
 
/* 로딩 완료 */
.adstage-loaded {
  opacity: 1;
  transition: opacity 0.3s ease;
}
 
/* 오류 상태 */
.adstage-error {
  border: 1px solid #ff6b6b;
  background-color: #ffe0e0;
}

슬롯 상태 확인

// 모든 슬롯 확인
const allSlots = AdStage.ads.getAllSlots();
console.log('전체 광고 슬롯:', allSlots);
 
// 특정 슬롯 확인
const slot = AdStage.ads.getSlotById(slotId);
console.log('슬롯 정보:', slot);

배너 광고

목차