> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# Media Buy Lifecycle

> AdCP のメディアバイライフサイクル — create_media_buy、update_media_buy、get_media_buys タスクを使って、セラーをまたいでキャンペーンを作成、更新、モニタリング、最適化します。

メディアバイは、AdCP における広告キャンペーンの完全なライフサイクルを表します。AdCP:Buy プロトコルは、最初のキャンペーン作成から継続的な最適化と更新まで、複数の広告プラットフォームにまたがってメディアバイを管理する統一されたインターフェースを提供します。

## 概要

AdCP のメディアバイ管理は、次のための統一されたインターフェースを提供します:

* 発見されたプロダクトとパッケージからの**キャンペーン作成**
* すべてのキャンペーン状態を通じた**ライフサイクル管理**
* 継続的な最適化のための**予算とターゲティングの更新**
* 一貫した操作による**クロスプラットフォームのオーケストレーション**
* 人間参加型のサポートを伴う**非同期オペレーション**

## メディアバイのライフサイクルフェーズ

### 1. 作成フェーズ

[`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) を使って、発見されたプロダクトをアクティブな広告キャンペーンに変換します:

* **パッケージ設定**: プロダクトをフォーマット、ターゲティング、予算と組み合わせる
* **キャンペーンのセットアップ**: タイミング、全体予算、ブランドコンテキストを定義する
* **検証と承認**: 任意の人による承認を伴う自動チェック
* **プラットフォームへのデプロイ**: 広告プラットフォームにまたがるキャンペーン作成

このフェーズには次が含まれる場合があります:

* `active` ステータスでの即時作成（即時有効化）
* バイヤーがトップレベルの `paused: true` を渡し、有効化の前提条件がそれ以外は満たされている場合の、`paused` ステータスでの保留作成
* `pending_creatives` ステータス（クリエイティブの割り当て待ち）または `pending_start` ステータス（配信準備完了、フライト日待ち）での遅延作成
* `pending_manual` タスクステータスによる人間の承認ワークフロー（[非同期オペレーション](#非同期オペレーションと人間参加型)を参照）
* `pending_permission` タスクステータスによる権限要件（[非同期オペレーション](#非同期オペレーションと人間参加型)を参照）

<Note>
  `pending_manual` と `pending_permission` は、人間参加型のキューに由来する**タスクレベル**のステータスです——これらは*操作*が承認を必要とするかどうかを記述するものであり、メディアバイのライフサイクル状態ではありません。メディアバイ自体は、操作が完了すると `pending_creatives`、`pending_start`、`active`、または `paused` に入ります。
</Note>

**プラットフォームのマッピング:**

* **Google Ad Manager**: LineItem を持つ Order を作成
* **Kevel**: Flight を持つ Campaign を作成
* **Triton Digital**: Flight を持つ Campaign を作成

### 2. クリエイティブ供給フェーズ

作成されると、メディアバイは、セラーが表明している経路を通じてクリエイティブアセットを必要とします: ライブラリを持つセラーには [`sync_creatives`](/docs/creative/task-reference/sync_creatives)、インライン専用のセラーには [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) と [`update_media_buy`](/docs/media-buy/task-reference/update_media_buy) のインライン `packages[].creatives` です。

* **プラットフォーム固有のフォーマットサポート**（動画、音声、ディスプレイ、カスタム）
* クリエイティブのコンプライアンスのための**検証とポリシーレビュー**
* ターゲット配信のための**特定パッケージへの割り当て**

### 3. 有効化・配信フェーズ

アクティブなキャンペーンをモニタリングし管理します:

* **ステータストラッキング**: キャンペーンが `pending_creatives` から `pending_start`、そして `active` へ遷移する、または配信を保留して作成された場合は `paused` へ
* **クリエイティブの割り当て**: クリエイティブライブラリからアセットを添付
* **配信モニタリング**: [`get_media_buy_delivery`](/docs/media-buy/task-reference/get_media_buy_delivery) でペーシングとパフォーマンス指標を追跡
* **問題の解決**: 承認の遅延やプラットフォームの問題に対応

### 4. 最適化とレポートフェーズ

AdCP の包括的なレポートツールを使った、継続的なパフォーマンスモニタリングとデータ駆動のキャンペーン最適化。

主な活動には次が含まれます:

* リアルタイムおよび履歴分析による**パフォーマンスモニタリング**
* 予算の再配分とターゲティングの絞り込みによる**キャンペーン最適化**
* 一貫した分析のために同じターゲティング次元を使う**次元別レポート**
* パフォーマンスフィードバックループを通じた**AI 主導のインサイト**

最適化戦略、パフォーマンスモニタリング、標準メトリクス、ベストプラクティスの完全な詳細については、\*\*[最適化とレポート](/docs/media-buy/media-buys/optimization-reporting)\*\*を参照してください。

## キーコンセプト

### メディアバイの構造

メディアバイには次が含まれます:

* **キャンペーンメタデータ**（バイヤー参照、ブランド、タイミング）
* 通貨とペーシング設定を持つ**全体予算**
* 異なるターゲティング/クリエイティブの組み合わせを表す**複数のパッケージ**
* 作成、承認、実行の各フェーズを通じた**ステータストラッキング**

### パッケージの種類

三つの異なる種類が、ライフサイクルの異なる段階でパッケージを表します:

| 種類               | スキーマ                                             | 使用場所                       | 目的                                    |
| ---------------- | ------------------------------------------------ | -------------------------- | ------------------------------------- |
| `PackageRequest` | `media-buy/package-request.json`                 | `create_media_buy` リクエスト   | パッケージを作成するためにバイヤーが送るもの                |
| `Package`        | `core/package.json`                              | `create_media_buy` 成功レスポンス | 作成後にセラーが返すもの（確定した状態）                  |
| `PackageStatus`  | `media-buy/get-media-buys-response.json` 内にインライン | `get_media_buys` レスポンス     | 配信/レポートのビュー——クリエイティブ承認と任意のスナップショットを含む |

`create_media_buy` を実装するときは `PackageRequest` を送ります。レスポンスは `Package` オブジェクトを返します。`get_media_buys` を呼んでステータスや配信を確認するとき、レスポンスには配信固有のフィールドを持つ `PackageStatus` アイテムが含まれます。

### パッケージモデル

パッケージはメディアバイの構成要素です:

* 発見結果からの**単一プロダクト**の選択 - プロダクトを買うときは、プロダクト全体を買います（プロパティターゲティングを使う場合を除く）
* このパッケージ向けに提供される**クリエイティブフォーマット**
* ジオ制限、フリークエンシーキャップ、プロパティターゲティングを含む絞り込みのための**ターゲティングオーバーレイ**
* 全体のメディアバイ予算の一部としての**予算配分**
* プロダクトの利用可能な価格モデルからの**価格オプション**の選択
* 予算配信のための**ペーシング戦略**（even、asap、または front\_loaded）
* オークションベースの価格モデルのための**入札価格**（該当する場合）
* パッケージごとの任意の `start_time` と `end_time` を伴う**フライトスケジューリング**
* 保証付きバイのための\*\*[アカウンタビリティ条件](/docs/media-buy/advanced-topics/accountability)\*\* — `performance_standards`、`measurement_terms`、`cancellation_policy`

### フライトスケジューリング

パッケージは、メディアバイ内で独立したフライト日を持てます。これにより、同じプロダクトが異なる日付ウィンドウと予算で複数のパッケージとして現れる、週次（または任意のケイデンスの）フライトパターンが可能になります。

* **継承**: パッケージで `start_time` または `end_time` が省略された場合、パッケージはメディアバイの日付を継承します。各フィールドは独立して継承されます——パッケージはメディアバイの `end_time` を継承しつつ `start_time` を指定する、またはその逆も可能です。
* **検証**: パッケージの日付は親メディアバイの日付範囲内に収まらなければなりません。セラーは `start_time` が `end_time` と等しいか、それ以降であるパッケージを拒否すべきです（SHOULD）。
* **重複するフライト**: 同じプロダクトの複数のパッケージは、重複する日付範囲を持つことができます。各パッケージは独立した予算を維持します。
* **形式**: 素の ISO 8601 の日時——パッケージは `"asap"` をサポートしません

**週次フライトの例:**

3月1〜31日に配信されるディスプレイキャンペーンを、リフト計測のためのダーク期間を挟んで週次の \$2,000 フライトに分割したもの（省略形——完全なリクエストの形は [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) を参照）:

```json theme={null}
{
  "start_time": "2026-03-01T00:00:00Z",
  "end_time": "2026-03-31T23:59:59Z",
  "packages": [
    {
      "product_id": "prod_premium_display",
      "pricing_option_id": "cpm_usd_fixed",
      "budget": 2000,
      "start_time": "2026-03-01T00:00:00Z",
      "end_time": "2026-03-07T23:59:59Z"
    },
    {
      "product_id": "prod_premium_display",
      "pricing_option_id": "cpm_usd_fixed",
      "budget": 2000,
      "start_time": "2026-03-08T00:00:00Z",
      "end_time": "2026-03-14T23:59:59Z"
    },
    {
      "product_id": "prod_premium_display",
      "pricing_option_id": "cpm_usd_fixed",
      "budget": 2000,
      "start_time": "2026-03-22T00:00:00Z",
      "end_time": "2026-03-28T23:59:59Z"
    }
  ]
}
```

第 3 週は意図的に省略されています——リフト計測のためのダーク期間です。各フライトは独自の予算を持つため、ペーシングと支出は週ごとに制御されます。キャンペーン途中で調整するには、他のフライトに影響を与えずに個別のパッケージ予算を更新します。

### クリエイティブの割り当てとプレースメントルーティング

プロダクトが複数のバイヤーがターゲティング可能なプレースメントを定義する場合、バイヤーはプロダクトをパッケージとして購入しつつ、それらのプレースメントに異なるクリエイティブを割り当てられます。クリエイティブのプレースメント参照は、パッケージのインベントリ内でクリエイティブをルーティングします。パッケージが購入するインベントリを狭めることはありません。

**主なポイント:**

* **パッケージはプロダクトを買う** - プロダクトレベルの `placements[].mode` が、どのパブリッシャースコープのプレースメントがバイヤーにターゲティング可能かを示します
* **プレースメントのアイデンティティはパブリッシャースコープ** - パブリッシャー参照のプレースメントは、パブリッシャーの `adagents.json` に対して `{publisher_domain, placement_id}` として解決されます
* **インラインプレースメントも引き続き許可** - 公開のパブリッシャープレースメント宣言がない場合、セールスエージェントは `name`、フォーマット、公開のバイヤー向け詳細を持つインラインプレースメントを定義できます。その `placement_id` は、名前付きのパブリッシャー名前空間で、または単一パブリッシャーのレガシー文脈で `publisher_domain` が省略される場合はセラーエージェント自身のパブリッシャー名前空間で解釈されます
* パッケージのインベントリスコープは、選択したプロダクト、プロダクトの絞り込み、またはセラーがサポートするパッケージターゲティングサーフェスに由来します。`creative_assignments[].placement_refs` は、すでにスコープ内にあるプレースメントの間でクリエイティブをルーティングするだけです
* `placement_refs` も `placement_ids` も持たないクリエイティブは、パッケージ内のすべてのバイヤーがターゲティング可能なプレースメントで配信されます
* `placement_refs` とレガシーの `placement_ids` の両方が存在する場合、`placement_refs` が優先され、セラーは `placement_ids` を無視します
* `mode: "included"` のプレースメントはプロダクトの公開構成の一部であり、`creative_assignments[].placement_refs` で参照できません
* マルチパブリッシャープロダクトには `placement_refs` を使います。`placement_ids` は、プレースメント名前空間が曖昧でない場合にのみ、レガシーの略記として残ります
* パブリッシャーは、`adagents.json` の `authorized_agents[].placement_ids` またはガバナンス下の `placement_tags` を使って、特定のプレースメントについてエージェントを認可できます。セラーは販売を認可されたパブリッシャー参照のプレースメントのみを返すべきです

**ワークフロー例:**

1. **プロダクトがターゲティング可能なプレースメントを返す:**

```json theme={null}
{
  "product_id": "network_premium",
  "placements": [
    {
      "kind": "publisher_ref",
      "publisher_domain": "daily-pulse.example",
      "placement_id": "homepage_banner",
      "name": "Homepage Banner",
      "mode": "targetable",
      "format_ids": [{"agent_url": "...", "id": "display_728x90"}]
    },
    {
      "kind": "publisher_ref",
      "publisher_domain": "metro-report.example",
      "placement_id": "homepage_banner",
      "name": "Homepage Banner",
      "mode": "targetable",
      "format_ids": [{"agent_url": "...", "id": "display_728x90"}]
    },
    {
      "kind": "seller_inline",
      "publisher_domain": "daily-pulse.example",
      "placement_id": "article_sidebar",
      "name": "Article Sidebar",
      "mode": "targetable",
      "format_ids": [{"agent_url": "...", "id": "display_300x250"}]
    },
    {
      "kind": "seller_inline",
      "publisher_domain": "daily-pulse.example",
      "placement_id": "sponsorship_lockup",
      "name": "Sponsorship lockup",
      "mode": "included"
    }
  ]
}
```

最初の二つのプレースメントはどちらも `placement_id: "homepage_banner"` を使いますが、それぞれが異なる `publisher_domain` でスコープされているため別個です。三つ目のプレースメントはカタログ参照を持たないためインラインです。このプロダクトが複数のパブリッシャー名前空間にまたがるため、それでも `publisher_domain` を持ちます。

2. **バイヤーがパッケージを作成（プロダクト全体を買う）し、各プレースメントに異なるクリエイティブを割り当てる:**

```json theme={null}
{
  "product_id": "network_premium",
  "creative_assignments": [
    {
      "creative_id": "creative_daily_pulse",
      "placement_refs": [
        {
          "publisher_domain": "daily-pulse.example",
          "placement_id": "homepage_banner"
        }
      ]
    },
    {
      "creative_id": "creative_metro_report",
      "placement_refs": [
        {
          "publisher_domain": "metro-report.example",
          "placement_id": "homepage_banner"
        }
      ]
    }
  ]
}
```

3. **または、一つのクリエイティブをすべてのターゲティング可能なプレースメントに割り当てる（placement\_refs と placement\_ids を省略）:**

```json theme={null}
{
  "product_id": "network_premium",
  "creative_assignments": [
    {
      "creative_id": "creative_universal"
    }
  ]
}
```

`placement_refs` とレガシーの `placement_ids` の両方を省略すると、そのクリエイティブはパッケージ内のすべてのバイヤーがターゲティング可能なプレースメントで配信されます。

**ユースケース:**

* **フォーマット固有のプレースメント**: ホームページは 728x90、サイドバーは 300x250
* **A/B テスト**: 異なるプレースメントで異なるクリエイティブをテスト
* **ジオターゲティング**: 異なる DOOH スクリーンのロケーションに異なるクリエイティブ
* **デイパーティング**: 朝と夜のプレースメントに異なるクリエイティブ

完全なプレースメントのドキュメントについては、[メディアプロダクト - プレースメント](/docs/media-buy/product-discovery/media-products.mdx#プレースメント)を参照してください。

### プロパティターゲティング

`property_targeting_allowed: true` のプロダクトについて、バイヤーは `targeting_overlay` の `property_list` を使って、どのプロパティをターゲットするかを指定できます:

```json theme={null}
{
  "product_id": "flexible_news_network",
  "targeting_overlay": {
    "property_list": {
      "agent_url": "https://governance.example.com",
      "list_id": "pl_brand_safe_2024"
    }
  },
  "budget": 50000
}
```

**主なポイント:**

* `property_targeting_allowed: true` のプロダクトについてのみ有効
* パッケージは、プロダクトの `publisher_properties` と `property_list` の交差で配信されます
* 省略した場合、パッケージはプロダクトのすべてのプロパティで配信されます
* `property_targeting_allowed: false` のプロダクトに対して提供された場合、セラーはバリデーションエラーを返すべきです（SHOULD）

プロダクトがどのようにターゲティングの柔軟性を宣言するかについての詳細は、[メディアプロダクト - プロパティターゲティング](/docs/media-buy/product-discovery/media-products#プロパティターゲティング)を参照してください。

### ライフサイクル状態

メディアバイは、明示的な遷移ルールを持つ定義された状態を進みます:

```
create_media_buy ──┬──▶ pending_creatives ──▶ pending_start ──▶ active
                   ├──▶ active ──(pause)──▶ paused
                   └──▶ paused (when created with paused: true)

paused ──(resume)──▶ active
active ─────────────▶ completed (terminal)
paused ─────────────▶ completed (terminal)

pending_creatives ──▶ rejected (terminal)  — seller rejects during setup
pending_start ──────▶ rejected (terminal)  — seller rejects during setup

Any non-terminal ──── update(canceled: true) ──▶ canceled (terminal)
```

* **`pending_creatives`**: 承認済みだがクリエイティブが未割り当て——**バイヤー側のアクションが必要**（ライブラリを持つセラーには `sync_creatives`、インライン専用のセラーにはインラインの `packages[].creatives` を使用）。パブリッシャー側やガバナンス側の承認キューではありません: セラーはすでにバイを受理しており、欠けているのはバイヤーのクリエイティブ送信だけです。
* **`pending_start`**: 配信準備完了、フライト日待ち

`pending_X` の命名規約は、次に必要となるライフサイクルフェーズを名付けるものであり、セラー/オペレーターの承認を待つ状態では**ありません**——`pending_creatives` は「クリエイティブが次のフェーズ」を、`pending_start` は「フライト日の開始が次のフェーズ」を意味します。どちらもセラー受理後の状態です。

* **`active`**: 実行中でインプレッションを配信している
* **`paused`**: バイヤーまたはセラーによって一時的に停止された。有効化の前提条件をそれ以外は満たす場合、トップレベルの `paused: true` でバイを直接 `paused` として作成することもできます。クリエイティブの欠如や将来のフライト日のようなセットアップのブロッカーは、解消されるまで依然として `pending_creatives` または `pending_start` として表面化し、その後、作成時の保留が `paused` として可視になります。
* **`completed`**: 終了——フライトが終了、ゴールが達成、または予算が消化された
* **`rejected`**: セラーによって断られた（終端）
* **`canceled`**: 自然な完了の前に終了した。バイヤーとセラーのどちらが起点かを判断するには `cancellation.canceled_by` を確認します。

<Note>
  **表示の折りたたみ。** `pending_creatives` と `pending_start` は、下流のゲーティング——条件付き UI、タスクルーティング、レディネスチェック——をサポートするために細粒度です。バイヤーアプリケーションは、エンドユーザーに対して両方を単一の `pending` ラベルとして描画してもかまいませんが（MAY）、区別に依存するロジックが機能し続けるよう、ワイヤー上（API レスポンス、ウェブフック、永続化されたレコード、ログ）では生のステータス値を保持しなければなりません（MUST）。生の列挙を信頼できる情報源として扱い、そこから表示ラベルを導出してください。可能な限り、UI のアフォーダンスをステータス値から直接ではなく `valid_actions` から駆動してください。
</Note>

**クリエイティブへの影響**: メディアバイが `rejected`、`canceled`、または `completed` に到達すると、そのクリエイティブの割り当ては解放されますが、クリエイティブ自体は変更されません。割り当てられていたクリエイティブは既存のレビューステータスのままライブラリに残り、他のメディアバイへの割り当てに利用できます。[クリエイティブの状態と割り当ての状態](/docs/creative/creative-libraries#creative-state-and-assignment-state-are-separate)を参照してください。

**オーダーの確定**: コミットされた `create_media_buy` レスポンスはオーダーの確定を構成します。レスポンスには、セラーのコミットのタイムスタンプを持つ `confirmed_at` が含まれます。遅延/手動承認のフローでは、セラーがコミットするまで `confirmed_at: null` を公開することがあります。一度値が入ると、そのタイムスタンプは後続のライフサイクルの変更を通じて安定したままです。[リビジョンと確定のセマンティクス](/docs/media-buy/specification#revision-and-confirmation-semantics)を参照してください。

**終端状態**: `completed`、`rejected`、`canceled` は終端です——そこから外への遷移はありません。セラーは終端状態のメディアバイへの更新をエラーコード `INVALID_STATE` で拒否しなければなりません（MUST）。

**作成時の保留。** `create_media_buy` のトップレベルの `paused: true` は、セットアップのブロッカーが存在する場合の潜在的な配信保留です。バイヤーは依然として最初にブロッカーの状態（`pending_creatives` または `pending_start`）を見ます。それが次に必要なフェーズだからです。クリエイティブが揃いフライトが開始できるようになると、そのバイは `active` ではなく `paused` に入ります。バイヤーは `update_media_buy` と `paused: false` でブロッカーの解消前に保留を解除できます。可視ステータスはブロッカーが解消するまで `pending_creatives` または `pending_start` のままで、その後 `active` へ進みます。

**セラーの実装要件——ステータスを永続化し、日付から再計算しない**: `status` は明示的なフィールドとして保存され、プロトコルイベントによってのみ変更されなければなりません（MUST）。フライト日の計算は `paused`、`canceled`、`rejected` を表現できません——それらは時計ではなく明示的なコマンドによって駆動されます。リクエスト時に `start_time`/`end_time` から `status` を再計算するセラーは、これらの状態を黙って落とし、そのメディアバイを読むすべてのバイヤーの `valid_actions` を壊します。正しいアプローチは: 日付の比較が `create_media_buy` 時に初期ステータス（`pending_creatives`、`pending_start`、`active`、または `paused`）を設定し、その後は状態機械がそのフィールドを所有する、というものです。

**有効なアクションの発見**: `get_media_buys` レスポンスには、各メディアバイの `valid_actions`——現在の状態でバイヤーが実行できるアクションのリスト——が含まれます。エージェントは状態機械をハードコードする代わりにこれを使うべきです（SHOULD）:

```json theme={null}
{
  "media_buys": [{
    "media_buy_id": "mb_12345",
    "status": "active",
    "revision": 3,
    "valid_actions": ["pause", "cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"],
    "packages": [...]
  }]
}
```

**リビジョントラッキング**: 各メディアバイは、状態を変更するあらゆる変更のたびに増加する `revision` 番号を持ちます。楽観的並行性制御のために `update_media_buy` で `revision` を渡します——最後に読んでからリビジョンが変わっていれば、セラーは `CONFLICT` で拒否します。セラーはこのチェックを書き込みとアトミックに強制しなければなりません。アプリケーションレベルの read/compare/write のロジックは、並行する更新と競合する可能性があります。

## コアオペレーション

### メディアバイの作成

作成プロセスは次を扱います:

* 発見されたプロダクトがまだ利用可能であることを保証する**プロダクトの検証**
* パッケージをまたいでクリエイティブ要件を確認する**フォーマット互換性**
* 複数のパッケージにまたがって支出を配分する**予算の分配**
* 複数のアドサーバーにまたがってキャンペーンを作成する**プラットフォームの調整**

### メディアバイの更新

各パッケージの操作の種類は構造的に明示的です——リクエストのどこに現れるかで決まります:

| 操作        | リクエストフィールド                        | 例                        |
| --------- | --------------------------------- | ------------------------ |
| **新規**    | `new_packages[]`                  | フライト途中でラインアイテムを追加        |
| **変更**    | `packages[]`                      | 予算、ターゲティング、日付、クリエイティブを調整 |
| **キャンセル** | `canceled: true` を伴う `packages[]` | ラインアイテムをキャンセル（取り消し不可）    |

キャンペーンレベルの変更には次が含まれます:

* 支出の増減のための**予算調整**
* オーディエンスパラメータを絞り込む**ターゲティングの更新**
* キャンペーンのタイミングを延長または短縮する**スケジュールの変更**
* キャンペーンレベルの配信制御のための**一時停止/再開**

### メディアバイのキャンセル

[`update_media_buy`](/docs/media-buy/task-reference/update_media_buy) と `canceled: true` を使って、メディアバイまたは個別のパッケージをキャンセルします:

```json theme={null}
{
  "media_buy_id": "mb_12345",
  "canceled": true,
  "cancellation_reason": "Campaign strategy changed"
}
```

アクティブなメディアバイ内の単一のパッケージをキャンセルする:

```json theme={null}
{
  "media_buy_id": "mb_12345",
  "packages": [
    {
      "package_id": "pkg_67890",
      "canceled": true,
      "cancellation_reason": "Underperforming — reallocating budget"
    }
  ]
}
```

* キャンセルは**取り消し不可**です——キャンセルされたメディアバイとパッケージは再有効化できません
* セラーはキャンセルをエラーコード `NOT_CANCELLABLE` で拒否してもかまいません（MAY）（例: 契約上の義務、印刷生産中のオーダー）
* キャンセルされたパッケージは、同じメディアバイ内の他のパッケージに影響を与えません。すべてのパッケージがキャンセルされた場合、`add_packages` をサポートするセラーは、バイヤーが `update_media_buy` の `new_packages` を通じて新しいパッケージを追加することを許可します。そうでない場合、バイヤーはメディアバイを明示的にキャンセルすべきです（SHOULD）。
* セラーはメディアバイまたはパッケージをキャンセルしてもかまいません（MAY）（例: ポリシー違反、インベントリの引き上げ）。セラー起点のキャンセルは `cancellation.canceled_by: "seller"` を設定し、オーケストレーターへのウェブフック通知をトリガーしなければなりません（MUST）。

### パッケージのライフサイクル

パッケージはメディアバイと同じ一時停止/キャンセルのパターンに従い、加えてクリエイティブ期限の強制があります:

* **`paused`**: 一時的に停止——`paused: false` で再開可能
* **`canceled`**: 恒久的に停止——取り消し不可
* **`creative_deadline`**: クリエイティブのアップロードや変更のためのパッケージごとの期限。この期限の後、クリエイティブの変更は `CREATIVE_REJECTED` で拒否されます。

パッケージに `creative_deadline` が不在の場合、メディアバイの `creative_deadline` が適用されます。これはチャネル混在のオーダーで重要です——同じメディアバイ内で、印刷パッケージがデジタルパッケージより早い素材期限を持つことがあります。

### ステータス管理

キャンペーンの状態遷移:

* 保留中のキャンペーンを開始する**有効化リクエスト**
* キャンペーン制御のための**一時停止/再開の操作**
* バイヤー起点の終了のための**キャンセル**
* 成功したキャンペーンのクローズのための**完了処理**
* 失敗した操作のための**エラーリカバリ**

## レスポンスタイム

メディアバイの操作は、予測可能なタイミングを持つ統一されたステータスシステムを使います:

* **[`create_media_buy`](/docs/media-buy/task-reference/create_media_buy)**: 即時から数日
  * `completed`: 即座に作成される単純なキャンペーン
  * `working`: 120 秒以内の処理（検証、セットアップ）
  * `submitted`: 数時間から数日を要する複雑なキャンペーン（人による承認）

* **[`update_media_buy`](/docs/media-buy/task-reference/update_media_buy)**: 即時から数日
  * `completed`: 即座に適用される予算変更
  * `working`: 120 秒以内のターゲティング更新
  * `submitted`: 承認を要するパッケージ変更（数時間から数日）

* **[`get_media_buy_delivery`](/docs/media-buy/task-reference/get_media_buy_delivery)**: 約60秒（データ集計）

* **パフォーマンス分析**: 約1秒（キャッシュされたメトリクス）

**ステータスの意味:**

* **`completed`**: 操作が完了、結果を即座に処理
* **`working`**: 処理中、120 秒以内の完了を期待
* **`submitted`**: 長時間実行の操作、ウェブフックを提供するか `tasks/get` でポーリング

## ベストプラクティス

### キャンペーンプランニング

* プロダクトディスカバリーのブリーフで定義した**明確な目標から始める**
* 異なるオーディエンス/クリエイティブの組み合わせを中心に**パッケージ構造をプランニングする**
* プロダクトの価格ガイダンスに基づいて**現実的な予算を設定する**
* パブリッシャーのワークフローで**承認の時間を確保する**

### 継続的な管理

* ターゲットに対する配信を保証するために**日次のペーシングをモニタリングする**
* 最適化の機会のために**週次でパフォーマンスをレビューする**
* 配信を乱さないために**ターゲティングを段階的に更新する**
* オーディエンスの疲労を防ぐために**クリエイティブを定期的に刷新する**

### 予算管理

* 最初は**保守的に配分し**、その後パフォーマンスに基づいて増やす
* 高パフォーマンスのパッケージのために**予算を確保する**
* オーディエンスの可用性と価格の**季節性を見越す**
* 異なるターゲティングアプローチにまたがって**支出効率をモニタリングする**
* **予算管理**: 予算が更新されると、システムは CPM に基づいてインプレッションを自動的に再計算します

### 技術的実装

* **一時停止/再開の戦略**: メンテナンスにはキャンペーンレベルの制御を、最適化にはパッケージレベルを使う
* **パフォーマンスモニタリング**: 定期的なステータスチェックと配信レポートがキャンペーンを軌道に乗せ続けます
* **非同期設計**: 長時間実行の操作を適切に扱うようにオーケストレーターを設計する
* **タスクトラッキング**: 保留中のタスク ID のために永続的なストレージを維持する
* **ウェブフック統合**: リアルタイムの更新のためにウェブフックを実装する
* **ユーザーへの伝達**: 保留状態をエンドユーザーに明確に伝える

## エラーハンドリング

保留状態とエラー状態、レスポンスパターン、リカバリ戦略を含む包括的なエラーハンドリングのガイダンスについては、[エラーハンドリング](/docs/building/by-layer/L3/error-handling)を参照してください。

メディアバイ固有のエラーコードは、各タスク仕様と[エラーハンドリングリファレンス](/docs/building/by-layer/L3/error-handling)に記載されています。

## 非同期オペレーションと人間参加型

AdCP:Buy プロトコルは、コア原則として非同期オペレーションのために設計されています。オーケストレーターは保留状態を適切に扱わなければなりません（MUST）。

### 人間参加型（HITL）オペレーション

多くのパブリッシャーは、自動化された操作に手動承認を要求します。プロトコルは HITL タスクキューを通じてこれをサポートします:

1. **操作リクエスト**: オーケストレーターが任意の変更タスクを呼ぶ
2. **保留レスポンス**: サーバーがタスク ID とともに `pending_manual` ステータスを返す
3. **タスクのモニタリング**: オーケストレーターがポーリングするか、ウェブフックを受け取る
4. **人によるレビュー**: パブリッシャーがレビューして承認/拒否する
5. **完了**: 承認時に元の操作が実行される

### HITL タスクの状態

```
pending → assigned → in_progress → completed/failed
                  ↓
              escalated
```

### オーケストレーターの要件

オーケストレーターは次を満たさなければなりません（MUST）:

1. `pending_manual` と `pending_permission` を通常の状態として扱う
2. 保留中の操作を追跡するためにタスク ID を保存する
3. 指数バックオフを伴うリトライロジックを実装する
4. 操作の最終的な拒否を適切に扱う
5. リアルタイムの更新のためにウェブフックコールバックをサポートする（推奨）

## 標準メトリクス

すべてのプラットフォームはこれらのコアメトリクスをサポートしなければなりません:

* **impressions**: 広告閲覧回数
* **spend**: 通貨で使われた金額
* **clicks**: クリック数（該当する場合）
* **ctr**: クリック率（clicks/impressions）

任意の標準メトリクス:

* **conversions**: ポストクリック/ビューのコンバージョン
* **viewability**: ビューアブルインプレッションの割合
* **completion\_rate**: 動画/音声の完了率
* **engagement\_rate**: プラットフォーム固有のエンゲージメントメトリクス

## プラットフォーム固有の考慮事項

異なるプラットフォームは、さまざまなレポートと最適化の機能を提供します:

### Google Ad Manager

* Order は複数の LineItem を含められます
* LineItem はパッケージと 1:1 でマップします
* 高度なターゲティングとフリークエンシーキャップ
* クリエイティブ承認プロセスが必要
* **レポート**: 包括的な次元別レポート、リアルタイムおよび履歴データ、高度なビューアビリティメトリクス

### Kevel

* Campaign は Flight を含みます
* Flight はパッケージと 1:1 でマップします
* リアルタイム判断エンジン
* カスタムクリエイティブテンプレートをサポート
* **レポート**: リアルタイムレポート API、カスタムメトリクスのサポート、柔軟な集計オプション

### Triton Digital

* 音声広告に最適化
* Campaign は異なるデイパートのための Flight を含みます
* 強力なステーション/ストリームのターゲティング機能
* 音声のみのクリエイティブサポート
* **レポート**: 音声固有のメトリクス（完了率、スキップ率）、ステーションレベルのパフォーマンスデータ、デイパート分析

## 高度な分析

### クロスキャンペーン分析

* 複数のキャンペーンにまたがる**ポートフォリオのパフォーマンス**
* **オーディエンスの重複**とフリークエンシー管理
* キャンペーン横断の**予算配分**の最適化

### 予測インサイト

* 履歴データに基づく**パフォーマンス予測**
* AI 分析からの**最適化の推奨**
* 先を見越した調整のための**トレンド予測**

## 統合パターン

### 発見からメディアバイまで

プロダクトディスカバリーからキャンペーン作成までのシームレスなフロー:

1. [`get_products`](/docs/media-buy/task-reference/get_products) を使ってインベントリを見つける
2. キャンペーン目標に合致するプロダクトを選ぶ
3. 適切なターゲティングとフォーマットでパッケージを設定する
4. [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) でメディアバイを作成する

### クリエイティブ統合

クリエイティブ管理との連携:

1. 選択したプロダクトからフォーマット要件を理解する
2. [クリエイティブ管理](/docs/media-buy/creatives/)を使ってアセットを準備する
3. キャンペーン作成中または更新を通じてクリエイティブを割り当てる
4. クリエイティブのパフォーマンスをモニタリングし、必要に応じて刷新する

### パフォーマンス最適化

包括的な分析を活用したデータ駆動のキャンペーン改善:

1. [`get_media_buy_delivery`](/docs/media-buy/task-reference/get_media_buy_delivery) で**配信を追跡する**
   * リアルタイムの配信メトリクスとペーシング分析をモニタリングする
   * 最適化の機会のためにパッケージレベルのパフォーマンス内訳を得る
   * 異なるターゲティングアプローチにまたがってパフォーマンスを追跡する

2. パッケージとターゲティングにまたがって**パフォーマンスを分析する**
   * 詳細なインサイトのために次元別レポートを使う
   * AI 主導の最適化のためにパフォーマンスインデックススコアをモニタリングする
   * 高パフォーマンスと低パフォーマンスのセグメントを特定する

3. [`update_media_buy`](/docs/media-buy/task-reference/update_media_buy) で**キャンペーンを更新する**
   * 高パフォーマンスと低パフォーマンスのパッケージ間で予算を再配分する
   * パフォーマンスデータに基づいてターゲティングを調整する
   * 低パフォーマンスのパッケージを一時停止し、成功したものをスケールする

4. パフォーマンスデータとビジネス成果に基づいて**反復する**
   * パフォーマンスデータを最適化アルゴリズムにフィードバックする
   * ターゲティングとクリエイティブの割り当てを継続的に絞り込む
   * 成功した戦略を類似のキャンペーンにまたがってスケールする

#### 最適化のベストプラクティス

1. **頻繁にレポートする**: 定期的なレポートが最適化の機会を高めます
2. **ペーシングを追跡する**: 過少/過剰配信を避けるためにターゲットに対する配信をモニタリングする
3. **パターンを分析する**: 次元にまたがるパフォーマンスのトレンドを探す
4. **レイテンシを考慮する**: 一部のメトリクスはアトリビューションの遅延を持つことがあります
5. **メトリクスを正規化する**: パフォーマンス比較のために一貫したベースラインを使う

## 関連ドキュメント

* **[プロダクトディスカバリー](/docs/media-buy/product-discovery/)** - メディアバイのためのインベントリの発見
* **[タスクリファレンス](/docs/media-buy/task-reference/)** - 完全な API ドキュメント
* **[クリエイティブ](/docs/media-buy/creatives/)** - クリエイティブアセットの管理
* **[オーケストレーター設計ガイド](/docs/building/operating/orchestrator-design)** - 実装のベストプラクティス