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

## 概要

ほとんどの広告枠はこのパターン 1 つで完結します。

```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` モードがバックフィル広告をコンテナにぴったりフィット

キーは 2 つだけ。**`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 のインストールと初期化は[バナー広告](/ja/sdk/web/banner)または [CDN](/ja/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>

***

## コンテナパターン

枠に合うパターンを 1 つ選んでください。3 つともダイレクト広告とバックフィル広告の両方に対応します。

### パターン 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`

このうち 1 つでも 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. **サイズ意図のみを 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) => {
  // 広告枠を非表示にする、または代替コンテンツを表示
})
```

完全なイベントライフサイクルは[バナー広告](/ja/sdk/web/banner)ガイドを参照してください。

***

## 1.2.3 へのアップグレードの影響

| コンテナの状態                                 | 変化                                                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **inline** `height` / `aspect-ratio` あり | 影響なし（既存動作のまま）                                                                                           |
| サイズ意図 **なし**                            | 自動予約により空白のジャンプが軽減。広告動作は同一                                                                               |
| サイズ意図が **CSS class / Tailwind のみで** 固定  | **要対応** — 自動予約が同時に適用され、コンテナが意図より広がる可能性があります。アップグレード前に[非推奨](#非推奨)を参照して inline に移すか、`fixed` にオプトインしてください。 |

デフォルトモードが `responsive` のため、コード変更なしでアップグレードしてもほとんどの場合安全です。1.2.3 以前のレイアウトに固定したい場合は、グローバルまたはスロット単位の `fixed` オプトインを 1 行追加するだけで復元できます。

***

## 関連ガイド

<CardGroup cols={2}>
  <Card title="バナー広告 (React)" href="/ja/sdk/web/banner">
    React でバナー広告を実装
  </Card>

  <Card title="バナー広告 (CDN)" href="/ja/sdk/web/cdn-banner">
    CDN 方式でバナー広告を実装
  </Card>

  <Card title="リファレンス" href="/ja/sdk/web/reference">
    BackfillMode タイプ定義
  </Card>
</CardGroup>