배너 광고 - Ad Control Help Center

구현 방법

배너 광고는 HTML 속성만으로 간단하게 구현할 수 있습니다. 별도의 함수 호출 없이 광고 지면이 렌더링될 때 자동으로 광고가 요청됩니다.

개발 환경에서는 테스트 유닛 ID를 사용하세요: PUBLIC_TEST_UNIT_ID_320_100

Data Attributes 방식

data-adrop-unit 속성만 추가하면 SDK가 자동으로 광고를 로드합니다.

<div
  data-adrop-unit="YOUR_UNIT_ID"
  data-adrop-context-id="YOUR_CONTEXT_ID"
  data-adrop-theme="light"
  data-adrop-custom-click="true">
</div>

Data Attributes

data-adrop-unit

string

필수

애드컨트롤 콘솔에서 생성한 유닛 ID

data-adrop-context-id

string

문맥 타겟팅용 Context ID

data-adrop-theme

string

기본값:"light"

테마 설정 (light 또는 dark) - 다크모드 설정 참고

data-adrop-custom-click

boolean

기본값:false

커스텀 클릭 처리 활성화 - true로 설정하면 SDK가 자동으로 목적지 URL로 이동하지 않고, adClicked 이벤트만 발생시킵니다. 개발자가 클릭 동작을 직접 구현할 수 있습니다.

data-adrop-backfill-mode

string

기본값:"responsive"

백필 광고 렌더링 모드 (responsive 또는 fixed). 자세한 내용은 백필 렌더링 모드 가이드를 참고하세요. (SDK 1.2.3+)

data-adrop-ad-id

string

광고 식별자 — 내 기기에서 보기 기능으로 등록한 테스트 기기에서 소재를 미리 확인할 때 필수입니다. 운영 환경에 하드코딩하지 마세요.

광고 재요청

광고 지면 DOM을 새로 생성하여 기존 DOM을 교체하면 광고가 다시 요청됩니다.

const container = document.getElementById('ad-wrapper');
const newAd = document.createElement('div');
newAd.setAttribute('data-adrop-unit', 'YOUR_UNIT_ID');
Adrop.instance().clear(container);
container.appendChild(newAd);

renderAd 방식

광고 로드 타이밍을 직접 제어하고 싶을 때 사용합니다.

<div id="ad-container"></div>

<script>
  const container = document.getElementById('ad-container');
  const adrop = Adrop.instance();

  adrop.renderAd(container, {
    unit: 'YOUR_UNIT_ID',
    contextId: 'YOUR_CONTEXT_ID',
    theme: 'light',
    useCustomClick: true  // 커스텀 클릭 처리 활성화
  });
</script>

renderAd 옵션

unit

string

필수

애드컨트롤 콘솔에서 생성한 유닛 ID

uid

string

사용자 식별자 (SDK 설정 값을 개별 지면에서 오버라이드할 때 사용)

contextId

string

문맥 타겟팅용 Context ID

theme

string

기본값:"light"

테마 설정 (light 또는 dark) - 다크모드 설정 참고

useCustomClick

boolean

기본값:false

backfillMode

'responsive' | 'fixed'

기본값:"responsive"

백필 광고 렌더링 모드. 자세한 내용은 백필 렌더링 모드 가이드를 참고하세요. (SDK 1.2.3+)

adId

string

광고 식별자 — 내 기기에서 보기 기능으로 등록한 테스트 기기에서 소재를 미리 확인할 때 필수입니다. 운영 환경에 하드코딩하지 마세요.

광고 재요청

renderAd()를 다시 호출하면 광고가 재요청됩니다.

const container = document.getElementById('ad-container');
Adrop.instance().renderAd(container, {
  unit: 'YOUR_UNIT_ID'
});

광고 제거

clear()를 호출하여 컨테이너에서 광고를 제거할 수 있습니다.

const container = document.getElementById('ad-container');
Adrop.instance().clear(container);

광고 크기

권장: 반응형 폭 + 유닛 등록 사이즈와 일치하는 aspect-ratio. 자리가 디바이스 폭에 맞춰 늘어나고 높이는 비율로 잠겨 CLS가 발생하지 않습니다.

<div
  data-adrop-unit="YOUR_UNIT_ID"
  data-adrop-backfill-mode="fixed"
  style="width: 100%; aspect-ratio: 320 / 100;">
</div>

픽셀 단위 정렬이 필요한 경우 고정 픽셀 크기도 지원합니다.

<div
  data-adrop-unit="YOUR_UNIT_ID"
  style="width: 320px; height: 100px;">
</div>

구분	크기 설정	정렬
직광고	반응형 지원, 높이 필수	가로/세로 가운데
백필 광고	컨테이너 폭에 맞춰 자동 매칭 (`responsive`) 또는 컨테이너 높이에 맞춤 (`fixed`)	가로 가운데

백필 광고의 컨테이너 크기 작성 패턴과 렌더링 모드 선택 기준은 백필 렌더링 모드 가이드를 참고하세요.

이벤트 처리

광고 상태 변화를 감지하여 적절한 UI 처리를 할 수 있습니다.

<script>
  const adrop = Adrop.instance();

  // 광고 수신 성공
  function handleReceived(unit, adData) {
    console.log('광고 수신:', unit);
  }

  // 송출 가능한 직광고 없음
  function handleNoFill(unit) {
    console.warn('광고 없음:', unit);
  }

  // 요청 실패
  function handleFailed(unit) {
    console.error('광고 실패:', unit);
  }

  // 노출
  function handleImpression(unit, adData) {
    console.log('광고 노출:', unit);
  }

  // 클릭
  function handleClicked(unit, adData) {
    console.log('광고 클릭:', unit);
  }

  // 백필 광고 없음
  function handleBackfillNoFill(unit) {
    console.warn('백필 광고 없음:', unit);
  }

  // 동영상 재생 시작
  function handleVideoStart(unit, adData) {
    console.log('동영상 시작:', unit);
  }

  // 동영상 재생 완료
  function handleVideoEnd(unit, adData) {
    console.log('동영상 완료:', unit);
  }

  // 특정 유닛만 필터링
  const filter = { unit: 'YOUR_UNIT_ID' };

  adrop.on(Adrop.Events.AD_RECEIVED, handleReceived, filter);
  adrop.on(Adrop.Events.AD_NO_FILL, handleNoFill, filter);
  adrop.on(Adrop.Events.AD_FAILED, handleFailed, filter);
  adrop.on(Adrop.Events.AD_IMPRESSION, handleImpression, filter);
  adrop.on(Adrop.Events.AD_CLICKED, handleClicked, filter);
  adrop.on(Adrop.Events.AD_BACKFILL_NO_FILL, handleBackfillNoFill, filter);
  adrop.on(Adrop.Events.AD_VIDEO_START, handleVideoStart, filter);
  adrop.on(Adrop.Events.AD_VIDEO_END, handleVideoEnd, filter);
</script>

지원 이벤트

이벤트	상수	설명
광고 수신	`AD_RECEIVED`	광고 요청 성공
광고 없음	`AD_NO_FILL`	송출 가능한 직광고 없음
요청 실패	`AD_FAILED`	광고 요청 실패
노출	`AD_IMPRESSION`	광고 노출 기록됨
클릭	`AD_CLICKED`	사용자가 광고 클릭
백필 없음	`AD_BACKFILL_NO_FILL`	백필 광고 없음
동영상 시작	`AD_VIDEO_START`	동영상 광고 재생 시작
동영상 완료	`AD_VIDEO_END`	동영상 광고 재생 완료

이벤트 리스너 해제

더 이상 필요하지 않은 이벤트 리스너는 off()로 해제하세요.

adrop.off(Adrop.Events.AD_RECEIVED, handleReceived);

AdData

이벤트 핸들러에서 전달받는 광고 데이터입니다. 자세한 필드 정보는 레퍼런스 > AdData를 참고하세요.

커스텀 클릭 처리

useCustomClick이 활성화되면 SDK가 자동으로 목적지 URL로 이동하지 않습니다. 대신 클릭 이벤트를 처리하여 사용자 정의 동작을 구현할 수 있습니다.

<script>
  const adrop = Adrop.instance();
  
  // 커스텀 동작으로 광고 클릭 처리
  function handleCustomClick(unit, adData) {
    console.log('광고 클릭:', unit);
    console.log('목적지 URL:', adData.destinationURL);
    
    // 커스텀 클릭 동작 구현
    // 예시: 확인 대화상자 표시, 분석 추적 등
    const userConfirmed = confirm('광고주 페이지를 방문하시겠습니까?');
    if (userConfirmed && adData.destinationURL) {
      window.open(adData.destinationURL, '_blank');
    }
  }
  
  // 클릭 핸들러 등록
  adrop.on(Adrop.Events.AD_CLICKED, handleCustomClick);
  
  // 커스텀 클릭 활성화하여 광고 렌더링
  const container = document.getElementById('ad-container');
  adrop.renderAd(container, {
    unit: 'YOUR_UNIT_ID',
    useCustomClick: true
  });
</script>

커스텀 클릭 처리가 활성화되면 사용자가 광고를 클릭할 때 어떤 일이 일어날지 완전히 제어할 수 있습니다. destinationURL은 adClicked 이벤트 데이터에 포함되어 제공됩니다.

전체 예제

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>배너 광고 예제</title>
</head>
<body>
  <header>
    <!-- 헤더 배너 광고 -->
    <div
      data-adrop-unit="HEADER_BANNER_UNIT_ID"
      style="width: 100%; height: 80px;">
    </div>
  </header>

  <main>
    <h1>콘텐츠</h1>
  </main>

  <footer>
    <!-- 푸터 배너 광고 -->
    <div
      data-adrop-unit="FOOTER_BANNER_UNIT_ID"
      data-adrop-theme="dark"
      style="width: 320px; height: 100px;">
    </div>
  </footer>

  <script src="https://cdn.jsdelivr.net/npm/@adrop/ads-web-sdk@latest/dist/adrop-ads.min.js"></script>
  <script>
    const adrop = Adrop.observe({
      appId: 'YOUR_APP_ID',
      debug: true
    });

    adrop.on(Adrop.Events.AD_CLICKED, function(unit, adData) {
      console.log('광고 클릭:', unit);
    });
  </script>
</body>
</html>

​구현 방법

​Data Attributes 방식

​Data Attributes

​광고 재요청

​renderAd 방식

​renderAd 옵션

​광고 재요청

​광고 제거

​광고 크기

​이벤트 처리

​지원 이벤트

​이벤트 리스너 해제

​AdData

​커스텀 클릭 처리

​전체 예제

구현 방법

Data Attributes 방식

Data Attributes

광고 재요청

renderAd 방식

renderAd 옵션

광고 재요청

광고 제거

광고 크기

이벤트 처리

지원 이벤트

이벤트 리스너 해제

AdData

커스텀 클릭 처리

전체 예제