메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.adrop.io/llms.txt

Use this file to discover all available pages before exploring further.

Adrop Web SDK 1.2.3 이상에서 사용할 수 있습니다.

​
요약

  • 기본 모드는 responsive입니다. 대부분의 매체는 그대로 사용하시면 됩니다.
  • 광고 자리가 카드/그리드 디자인에 고정 높이로 박혀 있어야만 하는 경우에만 fixed를 적용하세요.
  • 컨테이너의 height / aspect-ratio 같은 크기 의도는 inline style로 명시하는 것을 권장합니다. (CSS class / Tailwind 단독은 비권장)

​
모드 비교

모드동작권장 케이스
responsive (기본)컨테이너 폭에 맞춰 광고 크기가 자동 선택됩니다. 컨테이너에 크기 의도가 없으면 SDK가 적절한 min-height를 자동으로 예약해 콘텐츠 점프(CLS)를 방지합니다.광고 자리가 동적 높이를 허용하는 일반 슬롯. 수익과 UX 모두 최적.
fixed컨테이너의 height에 광고를 맞춥니다 (width:100%; height:100%). 폭에 따른 자동 크기 선택이 적용되지 않습니다.광고 자리의 높이가 카드/그리드 디자인에 의해 고정되어 있어 responsive 모드에서 레이아웃이 깨지는 슬롯.

​
CLS가 무엇인가요?

페이지 로딩 중 광고가 늦게 들어오면서 본문이 밀려나는 현상(Cumulative Layout Shift)입니다. 사용자가 클릭하려던 버튼이 갑자기 자리를 옮겨 오클릭을 유발하고, 검색 랭킹과 광고 수익에도 영향을 줍니다. responsive 모드는 광고가 들어오기 전에 자리를 미리 예약하여 이 점프를 줄입니다.

​
어떤 모드를 선택해야 하나요?

기본값 responsive를 그대로 두는 것을 권장합니다. 다음 케이스에 한해 fixed로 옵트인하세요.
  • 광고 영역 높이가 카드/그리드 디자인에 픽셀 단위로 고정되어 있어 responsive 모드에서 변형되면 안 되는 경우
  • 헤더/사이드바처럼 다른 콘텐츠와 픽셀 단위 정렬이 필요한 슬롯
단순한 콘텐츠 점프(빈 공간이 광고로 채워지는 것)만 거슬리는 경우라면 모드를 바꾸지 말고 아래의 컨테이너 작성 권장 패턴을 따라주세요. SDK 자동 예약이 알아서 해결합니다.

​
모드 지정 방법

좁은 범위가 우선합니다. 우선순위는 다음과 같습니다. 
request 옵션 > HTML 속성 > 전역 설정 > 기본값('responsive')

​
1. 슬롯별, 프로그래매틱 (renderAd)

await Adrop.instance().renderAd(container, {
  unit: 'YOUR_UNIT_ID',
  backfillMode: 'fixed',
})

​
2. 슬롯별, HTML 속성 (선언적)

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

​
3. 매체사 전체 기본값

Adrop.observe({
  appId: 'YOUR_APP_ID',
  backfillMode: 'fixed',
})
지정하지 않으면 'responsive'가 적용됩니다.

​
컨테이너 작성 권장 패턴

광고 영역의 height / aspect-ratio 같은 크기 의도는 반드시 inline style로 명시해 주세요. inline 의도가 있으면 SDK가 자동 예약을 건너뛰어 매체사의 디자인을 그대로 유지합니다. SDK가 인식하는 inline 의도는 다음 4가지입니다.
  • height
  • min-height
  • max-height
  • aspect-ratio
width / padding / margin / 색상 / 보더 / 그림자 / transition 등 나머지 모든 스타일은 CSS class나 Tailwind를 자유롭게 사용해도 됩니다. 위 4가지 크기 의도만 inline으로 두면 됩니다.

​
권장 패턴

<!-- 동적 비율 슬롯: aspect-ratio만 inline, 나머지 자유 -->
<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full max-w-[640px] rounded-xl bg-gray-100 shadow-sm"
     style="aspect-ratio: 300 / 250;"></div>

<!-- 고정 높이 슬롯: height만 inline -->
<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full bg-gray-50 rounded border"
     style="height: 90px;"></div>

<!-- 자동 예약에 맡김: 크기 의도 없이 -->
<div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full max-w-[728px]"></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로만 height / aspect-ratio 지정 -->
<StyledAdSlot data-adrop-unit="YOUR_UNIT_ID" />
SDK는 inline 의도만 인식하므로 class만으로 박힌 크기는 감지하지 못합니다. 자동 예약이 함께 적용되면서 컨테이너 의도와 충돌하여 레이아웃이 의도와 다르게 표시될 수 있습니다.
수정 방법 (택 1):
  1. 크기 의도만 inline으로 옮기기 (권장) 
    <div data-adrop-unit="YOUR_UNIT_ID"
     class="w-full rounded-xl"
     style="aspect-ratio: 300 / 250;"></div>
  2. 자동 예약 비활성화 
    <div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     class="w-full aspect-[300/250]"></div>

​
자동 예약 동작 (responsive 모드)

responsive 모드에서 SDK는 컨테이너 폭에 맞춰 안전한 최소 높이를 자동으로 예약합니다.
  • 실제 광고가 예약값보다 크면 컨테이너가 자연스럽게 확장됩니다 (점프 폭이 줄어들 뿐)
  • 실제 광고가 예약값보다 작으면 빈 공간이 남습니다 (점프는 발생하지 않음)
  • max-height가 아니라 min-height만 박히므로 overflow 위험은 없습니다
매체사가 inline으로 height 또는 aspect-ratio 의도를 표현한 경우 SDK는 자동 예약을 건너뜁니다.

​
1.2.3으로 업그레이드 시 영향

컨테이너 상태변화
inline height / aspect-ratio 있음영향 없음 (기존 동작 그대로)
크기 의도 없음자동 예약으로 빈 공간 점프가 줄어듦. 광고 동작은 동일
CSS class / Tailwind로만 크기 의도 박힘자동 예약이 함께 적용되어 컨테이너 높이가 늘어날 수 있음 → 위 비권장 패턴 참고 후 수정
기본 동작이 responsive이므로 코드 변경 없이 받으셔도 대부분 안전합니다. 디자인을 1.2.1 시점 동작으로 동결하려면 전역 또는 슬롯별 fixed 옵트인 한 줄로 복원 가능합니다.

​
관련 가이드

배너 광고 (React)

React에서 배너 광고 구현

배너 광고 (CDN)

CDN 방식 배너 광고 구현

레퍼런스

BackfillMode 타입 정의