메인 콘텐츠로 건너뛰기
Adrop Web SDK 1.2.3 이상에서 사용할 수 있습니다.

​
한 줄 요약

대부분의 광고 자리는 이 패턴 하나로 끝납니다. 
<!-- 모바일 친화적인 320×100 배너 자리 -->
<div
  data-adrop-unit="YOUR_UNIT_ID"
  data-adrop-backfill-mode="fixed"
  style="width: 100%; aspect-ratio: 320 / 100;"
></div>
이 한 패턴이 다음을 모두 해결합니다.
  • 반응형 폭 — 디바이스 폭에 맞춰 자리가 자동으로 늘어남
  • 잠긴 높이 — aspect-ratio가 폭에서 높이를 계산하므로 CLS 없음
  • 예측 가능한 렌더링 — fixed 모드가 백필 광고를 컨테이너에 꽉 맞춰 그림
핵심은 두 가지입니다. backfillMode: fixed + 등록 사이즈(320/100, 300/250, 728/90 등)와 일치하는 inline aspect-ratio.
선행 조건: 이 코드가 작동하려면 페이지 어딘가에서 Adrop.observe({ appId: 'YOUR_APP_ID' })가 먼저 호출돼 있어야 합니다. 개발 중에는 YOUR_UNIT_ID 자리에 PUBLIC_TEST_UNIT_ID_320_100을 넣어 테스트 광고를 바로 확인할 수 있습니다. SDK 설치와 초기화는 배너 광고 또는 CDN 가이드를 참고하세요.

​
어떤 모드를 쓸지

모드동작이런 경우에
fixed백필 광고를 컨테이너에 꽉 맞춰 그림(width:100%; height:100%). 매체에서 자리 크기를 정의 — 반응형 폭이 필요하면 aspect-ratio로, 픽셀 단위 자리는 height로.자리 크기/비율을 알고 있고 광고를 그 자리에 정확히 맞추고 싶을 때. 대부분의 배너 슬롯에 권장.
responsive (기본)백필 네트워크가 컨테이너 폭에 가장 맞는 사이즈를 자동으로 선택. 컨테이너에 크기 의도가 없으면 SDK가 안전한 min-height를 자동 예약.사이즈를 미리 고정하고 싶지 않을 때. 네트워크가 가장 넓은 인벤토리에서 고를 수 있음.
두 모드 모두, 컨테이너에 inline 크기 의도(aspect-ratio, height, min-height, max-height)가 있으면 CLS가 발생하지 않습니다. 차이는 높이를 매체사가 정하느냐, 네트워크가 정하느냐입니다.
fixed 모드는 컨테이너 높이를 그대로 따릅니다. 컨테이너에 aspect-ratio 또는 height가 정의되지 않으면 광고 높이가 0이 되어 보이지 않습니다 — fixed는 반드시 높이 의도와 함께 사용하세요.

​
컨테이너 패턴

자리에 맞는 패턴 하나를 고르세요. 세 패턴 모두 직광고와 백필 광고 양쪽을 지원합니다.

​
패턴 A. 반응형 폭 + 비율 고정 (권장)

자리가 가용한 가로 폭을 채우고, aspect-ratio가 등록 사이즈로부터 높이를 결정합니다. 모바일 우선 레이아웃과 콘텐츠 피드에 가장 적합합니다. 
<!-- 320 × 100 모바일 배너 비율 -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; aspect-ratio: 320 / 100;"></div>

<!-- 300 × 250 미디엄 렉탱글 비율 -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; aspect-ratio: 300 / 250;"></div>

<!-- 728 × 90 리더보드 비율 -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; aspect-ratio: 728 / 90;"></div>
aspect-ratio는 유닛 등록 사이즈의 비율과 똑같이 맞춰 주세요. 컨테이너 높이는 width × (ratio.h / ratio.w)로 계산되고, fixed 모드가 그 박스를 정확히 채우도록 SDK에 지시합니다.
폭 제한(max-width)이 필요하다면 매체사 디자인(콘텐츠 영역 폭, 사이드바 폭 등) 기준으로 정하세요. 광고 등록 사이즈를 픽셀 캡으로 박으면 큰 화면에서 광고가 일부러 작아져 노출 수익이 줄어듭니다. 화면이 등록 사이즈보다 넓어도 비율만 유지되면 백필 광고는 그대로 채워집니다.

​
패턴 B. 픽셀 고정 높이 (정렬이 중요한 자리)

다른 콘텐츠와 픽셀 단위로 정확히 맞춰야 하는 자리(도킹된 헤더, 사이드바, 스티키 푸터 등)에 사용합니다. 
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; height: 100px;"></div>

​
패턴 C. SDK 자동 예약 (사이즈 미지정)

크기를 미리 고정하고 싶지 않을 때 사용합니다. SDK가 컨테이너 폭에 맞춰 안전한 min-height를 자동으로 예약해 CLS를 줄이고, 백필 네트워크가 가장 잘 맞는 인벤토리를 선택합니다. 
<div data-adrop-unit="YOUR_UNIT_ID"
     style="width: 100%;"></div>
기본 동작입니다. data-adrop-backfill-mode 속성을 별도로 지정할 필요가 없습니다.

​
모드 지정 방법

좁은 범위가 우선합니다. 
request 옵션 > HTML 속성 > 전역 설정 > 기본값('responsive')
슬롯별 (선언적) 
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; aspect-ratio: 320 / 100;"></div>
슬롯별 (프로그래매틱) 
await Adrop.instance().renderAd(container, {
  unit: 'YOUR_UNIT_ID',
  backfillMode: 'fixed',
})
매체 전역 기본값 
Adrop.observe({
  appId: 'YOUR_APP_ID',
  backfillMode: 'fixed',
})

​
크기 의도는 반드시 inline으로

SDK는 다음 4가지 inline 속성만 크기 의도로 인식합니다.
  • height
  • min-height
  • max-height
  • aspect-ratio
이 중 하나라도 inline에 있으면 SDK가 매체사 레이아웃을 그대로 유지하고 자동 예약을 건너뜁니다.
width, padding, margin, 색상, 보더, 그림자, transition 등 나머지 모든 스타일은 CSS class나 Tailwind를 자유롭게 사용할 수 있습니다. 위 4가지 크기 의도만 inline에 두면 됩니다.

​
권장

<!-- aspect-ratio만 inline, 나머지는 class로 -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     class="w-full max-w-[640px] rounded-xl bg-gray-100 shadow-sm"
     style="aspect-ratio: 300 / 250;"></div>

<!-- height만 inline, 나머지는 class로 -->
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     class="w-full bg-gray-50 rounded border"
     style="height: 90px;"></div>

​
비권장

<!-- Tailwind 등 CSS class로만 크기 의도를 박는 경우 -->
<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full aspect-[300/250] rounded-xl"></div>

<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full h-[100px]"></div>

<!-- styled-components / CSS module로만 크기 의도를 지정 -->
<StyledAdSlot data-adrop-unit="YOUR_UNIT_ID" />
SDK는 CSS class로 박힌 크기를 감지하지 못합니다. responsive 모드의 자동 예약이 class 기반 높이와 동시에 적용되면서 컨테이너가 의도보다 늘어날 수 있습니다.
수정 방법 (택 1)
  1. 크기 의도만 inline으로 옮기기 (권장) 
    <div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full rounded-xl"
     style="aspect-ratio: 300 / 250;"></div>
  2. fixed로 옵트인해서 자동 예약 끄기 
    <div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     class="w-full aspect-[300/250]"></div>

​
CLS와 자동 예약

CLS란? 페이지 로딩 중 광고가 늦게 들어와 본문이 밀려나는 현상(Cumulative Layout Shift)입니다. 사용자가 누르려던 버튼이 갑자기 자리를 옮겨 오클릭을 유발하고, 검색 랭킹과 광고 수익에도 영향을 줍니다. responsive 모드의 처리 방식: 컨테이너에 inline 크기 의도가 없으면 SDK가 컨테이너 폭에 맞춰 안전한 min-height를 자동으로 예약합니다.
  • 실제 광고가 예약값보다 크면 컨테이너가 자연스럽게 확장됩니다 (점프 폭만 줄어듦)
  • 실제 광고가 예약값보다 작으면 빈 공간이 남습니다 (점프 없음)
  • max-height가 아닌 min-height만 박히므로 overflow 위험이 없습니다
inline으로 height나 aspect-ratio 의도를 표현하면 SDK는 자동 예약을 건너뛰어 매체사 레이아웃을 그대로 유지합니다.

​
자동 새로고침

백필 광고가 한 번 성공적으로 로드되면 SDK가 새로고침을 자동으로 관리합니다 — 매체사가 별도로 설정하거나 호출할 필요가 없습니다.
  • 가시성 조건: 컨테이너가 화면에 50% 이상 보이고 페이지 탭이 활성 상태일 때만 새로고침이 카운트됨
  • 횟수 제한: 슬롯별로 정해진 최대 횟수에 도달하면 멈춤
  • 자동 정리: 컨테이너가 DOM에서 제거되면 새로고침 등록이 자동으로 해제됨
매 새로고침 성공 시 format: 'backfill'을 가진 AD_RECEIVED 이벤트가 발생합니다.

​
백필도 안 나올 때

직광고와 백필 광고 모두 불러올 수 없는 경우 SDK가 AD_BACKFILL_NO_FILL 이벤트를 발생시킵니다. 이 이벤트를 처리해 광고 영역을 숨기거나 대체 콘텐츠를 보여주세요. 
Adrop.instance().on(Adrop.Events.AD_BACKFILL_NO_FILL, (unit) => {
  // 광고 영역 숨기기 또는 대체 콘텐츠 표시
})
전체 이벤트 사이클은 배너 광고 가이드를 참고하세요.

​
1.2.3 업그레이드 영향

컨테이너 상태변화
inline height / aspect-ratio 있음영향 없음 (기존 동작 그대로)
크기 의도 없음자동 예약으로 빈 공간 점프 감소. 광고 동작은 동일
크기 의도가 CSS class / Tailwind로만 박힘조치 필요 — 자동 예약이 함께 적용되어 컨테이너가 의도보다 늘어날 수 있습니다. 업그레이드 전 비권장 섹션을 확인해 inline으로 옮기거나 fixed로 옵트인하세요.
기본 모드가 responsive이므로 코드 변경 없이 업그레이드해도 대부분 안전합니다. 1.2.3 이전 레이아웃으로 동결하려면 전역 또는 슬롯별 fixed 옵트인 한 줄로 복원할 수 있습니다.

​
관련 가이드

배너 광고 (React)

React에서 배너 광고 구현

배너 광고 (CDN)

CDN 방식 배너 광고 구현

레퍼런스

BackfillMode 타입 정의