> ## 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.

# 백필 렌더링 모드

> 올바른 컨테이너 패턴으로 백필 광고를 예측 가능하게 렌더링하는 방법을 안내합니다.

<Info>
  Adrop Web SDK **1.2.3** 이상에서 사용할 수 있습니다.
</Info>

## 한 줄 요약

대부분의 광고 자리는 이 패턴 하나로 끝납니다.

```html theme={null}
<!-- 모바일 친화적인 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`**.

<Note>
  **선행 조건**: 이 코드가 작동하려면 페이지 어딘가에서 `Adrop.observe({ appId: 'YOUR_APP_ID' })`가 먼저 호출돼 있어야 합니다. 개발 중에는 `YOUR_UNIT_ID` 자리에 `PUBLIC_TEST_UNIT_ID_320_100`을 넣어 테스트 광고를 바로 확인할 수 있습니다. SDK 설치와 초기화는 [배너 광고](/ko/sdk/web/banner) 또는 [CDN](/ko/sdk/web/cdn) 가이드를 참고하세요.
</Note>

***

## 어떤 모드를 쓸지

| 모드                | 동작                                                                                                                  | 이런 경우에                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `fixed`           | 백필 광고를 컨테이너에 꽉 맞춰 그림(`width:100%; height:100%`). 매체에서 자리 크기를 정의 — 반응형 폭이 필요하면 `aspect-ratio`로, 픽셀 단위 자리는 `height`로. | 자리 크기/비율을 알고 있고 광고를 그 자리에 정확히 맞추고 싶을 때. **대부분의 배너 슬롯에 권장.** |
| `responsive` (기본) | 백필 네트워크가 컨테이너 폭에 가장 맞는 사이즈를 자동으로 선택. 컨테이너에 크기 의도가 없으면 SDK가 안전한 `min-height`를 자동 예약.                                 | 사이즈를 미리 고정하고 싶지 않을 때. 네트워크가 가장 넓은 인벤토리에서 고를 수 있음.           |

<Note>
  두 모드 모두, 컨테이너에 inline 크기 의도(`aspect-ratio`, `height`, `min-height`, `max-height`)가 있으면 CLS가 발생하지 않습니다. 차이는 높이를 매체사가 정하느냐, 네트워크가 정하느냐입니다.
</Note>

<Warning>
  `fixed` 모드는 컨테이너 높이를 그대로 따릅니다. 컨테이너에 `aspect-ratio` 또는 `height`가 정의되지 않으면 광고 높이가 0이 되어 보이지 않습니다 — `fixed`는 반드시 높이 의도와 함께 사용하세요.
</Warning>

***

## 컨테이너 패턴

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

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

자리가 가용한 가로 폭을 채우고, `aspect-ratio`가 등록 사이즈로부터 높이를 결정합니다. 모바일 우선 레이아웃과 콘텐츠 피드에 가장 적합합니다.

```html theme={null}
<!-- 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에 지시합니다.

<Note>
  폭 제한(`max-width`)이 필요하다면 **매체사 디자인(콘텐츠 영역 폭, 사이드바 폭 등)** 기준으로 정하세요. 광고 등록 사이즈를 픽셀 캡으로 박으면 큰 화면에서 광고가 일부러 작아져 노출 수익이 줄어듭니다. 화면이 등록 사이즈보다 넓어도 비율만 유지되면 백필 광고는 그대로 채워집니다.
</Note>

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

다른 콘텐츠와 픽셀 단위로 정확히 맞춰야 하는 자리(도킹된 헤더, 사이드바, 스티키 푸터 등)에 사용합니다.

```html theme={null}
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; height: 100px;"></div>
```

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

크기를 미리 고정하고 싶지 않을 때 사용합니다. SDK가 컨테이너 폭에 맞춰 안전한 `min-height`를 자동으로 예약해 CLS를 줄이고, 백필 네트워크가 가장 잘 맞는 인벤토리를 선택합니다.

```html theme={null}
<div data-adrop-unit="YOUR_UNIT_ID"
     style="width: 100%;"></div>
```

기본 동작입니다. `data-adrop-backfill-mode` 속성을 별도로 지정할 필요가 없습니다.

***

## 모드 지정 방법

좁은 범위가 우선합니다.

```
request 옵션 > HTML 속성 > 전역 설정 > 기본값('responsive')
```

**슬롯별 (선언적)**

```html theme={null}
<div data-adrop-unit="YOUR_UNIT_ID"
     data-adrop-backfill-mode="fixed"
     style="width: 100%; aspect-ratio: 320 / 100;"></div>
```

**슬롯별 (프로그래매틱)**

```js theme={null}
await Adrop.instance().renderAd(container, {
  unit: 'YOUR_UNIT_ID',
  backfillMode: 'fixed',
})
```

**매체 전역 기본값**

```js theme={null}
Adrop.observe({
  appId: 'YOUR_APP_ID',
  backfillMode: 'fixed',
})
```

***

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

SDK는 다음 4가지 **inline** 속성만 크기 의도로 인식합니다.

* `height`
* `min-height`
* `max-height`
* `aspect-ratio`

이 중 하나라도 inline에 있으면 SDK가 매체사 레이아웃을 그대로 유지하고 자동 예약을 건너뜁니다.

<Note>
  width, padding, margin, 색상, 보더, 그림자, transition 등 **나머지 모든 스타일은 CSS class나 Tailwind를 자유롭게 사용**할 수 있습니다. 위 4가지 크기 의도만 inline에 두면 됩니다.
</Note>

### 권장

```html theme={null}
<!-- 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>
```

### 비권장

```html theme={null}
<!-- 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" />
```

<Warning>
  SDK는 CSS class로 박힌 크기를 감지하지 못합니다. `responsive` 모드의 자동 예약이 class 기반 높이와 동시에 적용되면서 컨테이너가 의도보다 늘어날 수 있습니다.
</Warning>

**수정 방법 (택 1)**

1. **크기 의도만 inline으로 옮기기 (권장)**

   ```html theme={null}
   <div data-adrop-unit="YOUR_UNIT_ID"
        class="w-full rounded-xl"
        style="aspect-ratio: 300 / 250;"></div>
   ```

2. **`fixed`로 옵트인해서 자동 예약 끄기**

   ```html theme={null}
   <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` 이벤트를 발생시킵니다. 이 이벤트를 처리해 광고 영역을 숨기거나 대체 콘텐츠를 보여주세요.

```js theme={null}
Adrop.instance().on(Adrop.Events.AD_BACKFILL_NO_FILL, (unit) => {
  // 광고 영역 숨기기 또는 대체 콘텐츠 표시
})
```

전체 이벤트 사이클은 [배너 광고](/ko/sdk/web/banner) 가이드를 참고하세요.

***

## 1.2.3 업그레이드 영향

| 컨테이너 상태                                 | 변화                                                                                                           |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **inline** `height` / `aspect-ratio` 있음 | 영향 없음 (기존 동작 그대로)                                                                                            |
| 크기 의도 **없음**                            | 자동 예약으로 빈 공간 점프 감소. 광고 동작은 동일                                                                                |
| 크기 의도가 **CSS class / Tailwind로만** 박힘    | **조치 필요** — 자동 예약이 함께 적용되어 컨테이너가 의도보다 늘어날 수 있습니다. 업그레이드 전 [비권장](#비권장) 섹션을 확인해 inline으로 옮기거나 `fixed`로 옵트인하세요. |

기본 모드가 `responsive`이므로 코드 변경 없이 업그레이드해도 대부분 안전합니다. 1.2.3 이전 레이아웃으로 동결하려면 전역 또는 슬롯별 `fixed` 옵트인 한 줄로 복원할 수 있습니다.

***

## 관련 가이드

<CardGroup cols={2}>
  <Card title="배너 광고 (React)" href="/ko/sdk/web/banner">
    React에서 배너 광고 구현
  </Card>

  <Card title="배너 광고 (CDN)" href="/ko/sdk/web/cdn-banner">
    CDN 방식 배너 광고 구현
  </Card>

  <Card title="레퍼런스" href="/ko/sdk/web/reference">
    BackfillMode 타입 정의
  </Card>
</CardGroup>