Skip to main content
選択したパッケージからメディアバイを作成するか、プロポーザルを実行します。必要に応じたバリデーションや承認、キャンペーン作成を処理します。 2 つのモードをサポート:
  • Manual Mode: packages 配列で明示的にラインアイテムを指定
  • Proposal Mode: proposal_idtotal_budget を指定し、get_products のプロポーザルを実行
Response Time: 即時〜日単位(completed、120 秒未満の working、数時間〜数日の submitted Request Schema: /schemas/v3/media-buy/create-media-buy-request.json Response Schema: /schemas/v3/media-buy/create-media-buy-response.json

クイックスタート

2 つのパッケージでシンプルなメディアバイを作成:

リクエストパラメーター

* Either packages OR (proposal_id + total_budget) must be provided. プロポーザルを実行する場合、返されたプロポーザルの proposal_status によって create_media_buy が有効かどうかが決まります。committed のプロポーザルは expires_at 前に実行でき、draft のプロポーザルは事前に action: "finalize" を指定した get_products の refine 呼び出しが必要です。Finalize は確定条件へのセラーのコミットであり、バイヤーの受諾ではありません。この create_media_buy 呼び出しが受諾/実行のステップです。

TotalBudget オブジェクト

Package オブジェクト

レスポンス

成功レスポンス

confirmed_at はセラーのコミット時刻であり、配信ステータスのタイムスタンプではありません。購入が後で一時停止、再開、配信開始、完了、またはパフォーマンス報告しても更新しないでください。コミット済みの同期作成は即座にこれを刻印します。バイヤーに media_buy_id を返さない場合は submitted レスポンス分岐を使います。セラーは代わりに、暫定購入について media_buy_idpackagesconfirmed_at: null を伴う同期成功を返してもよい(MAY)。そのような購入は get_media_buys で取得可能でなければならず(MUST)、コミット時に confirmed_at を正確に一度だけ設定して遷移しなければなりません(MUST)。confirmed_at: null の暫定購入は active であってはならず(MUST NOT)、packages[].committed_metrics を含んではなりません(MUST NOT)。

確定パッケージのレポート契約

レスポンス内の各パッケージは committed_metrics を運びうる(MAY)——このパッケージについてセラーが配信レポートで埋めることに合意した拘束的なレポート契約です。このフィールドは、標準メトリクス(閉じた available-metric.json 列挙由来)とベンダー定義メトリクス(BrandRef に紐付く)の両方を運ぶ統一配列で、各エントリは明示的な scope 判別子でタグ付けされ、committed_at でタイムスタンプされます: confirmed_atnull の場合、セラーは packages[].committed_metrics を省略しなければなりません(MUST)。confirmed_at を設定する最初のレスポンスは初期の committed-metrics セットを含んでもよく(MAY)、各エントリの committed_atconfirmed_at と等しくなければなりません(MUST)。
契約の仕組み:
  • Day-1 のエントリcommitted_at = confirmed_at を共有します。セラーは、プロダクトの reporting_capabilities から配信する準備があるものに基づいて、create_media_buy レスポンスで day-1 セットを刻印します。
  • フライト中の追加update_media_buy を通じて追記されます——それぞれ独自の committed_at タイムスタンプを持つ追記専用です。これにより、セラーは購入をキャンセルして再発行することなく、「Adelaide のアテンションは30日目以降から契約の一部です」と正直に言えます。
  • 既存のエントリは不変です。 セラーは、既存エントリを変更または削除しようとする update_media_buy リクエストを validation_error(推奨コード: IMMUTABLE_FIELD)で拒否しなければなりません(MUST)。新しいエントリは追記できます。
  • 標準メトリクスの qualifier。 一部のメトリクスは複数の非互換な計測パスを持ち、曖昧さの解消が必要です:
    • viewability_standardmetric_idviewable_impressionsviewable_ratemeasurable_impressions のいずれかで、セラーが特定のビューアビリティ標準にコミットする場合(MRC と GroupM は実質的に異なる閾値——viewability-standard 列挙を参照)、エントリは qualifier.viewability_standard を持たなければなりません(MUST)。missing_metrics でも対称: MRC ビューアビリティを期待するバイヤーは、GroupM のみの配信レポートを MRC コミットの欠如としてフラグします。
    • completion_sourcemetric_idcompletion_rate で、セラーが特定のソース(プレーヤー/広告サーバー自身の完了イベント vs. performance_standard.vendor に紐付く第三者計測ベンダー)にコミットする場合、エントリは qualifier.completion_sourceseller_attested または vendor_attested)を持たなければなりません(MUST)。二つのパスは、特に SSAI 環境で実質的に異なるレートを生みうる。missing_metrics でも対称。
    • attribution_methodologymetric_id が成果メトリクス(conversionsconversion_valueroascost_per_acquisitionincremental_sales_liftbrand_liftfoot_trafficconversion_liftbrand_search_liftunits_soldnew_to_brand_ratenew_to_brand_unitsleads)で、セラーが特定のアトリビューション手法にコミットする場合、エントリは qualifier.attribution_methodology(リテールメディアのクローズドループには deterministic_purchase、その他のパスには probabilisticpanel_basedmodeled)を持つべきです(SHOULD)。異なる手法の下の二つの成果行は交換不可。missing_metrics でも対称。
    • attribution_windowmetric_id が成果メトリクスで、セラーが特定のルックバックウィンドウにコミットする場合、エントリは構造化された期間として qualifier.attribution_window{ interval: 14, unit: "days" })を持つべきです(SHOULD)。異なるウィンドウの二つの成果行は、バイヤーが誤って期間をまたいで集計しないよう、別々の行として報告されます。
    qualifier がなければ契約は曖昧になり、照合は配信レポートがたまたま運ぶものにフォールバックします。qualifier の語彙は閉じています(additionalProperties: false)。新しいキーは後続のマイナーで明示的に出荷されます。
  • 照合: get_media_buy_deliverymissing_metrics は、committed_metricscommitted_at < reporting_period.end のエントリにフィルタし、レポートで埋められていないものをフラグします。フライト中にコミットされたメトリクスは、そのコミットタイムスタンプ以降のみ監査されます。qualifier は逐語的に一致します——コミット済みの {viewable_rate, mrc} は、viewability.standard: groupm を運ぶ配信された viewable_rate では満たされません。
  • v1 では任意。 パッケージごとのスナップショットインフラを持たないセラーは段階的に採用できます。欠如は適合ですが、既知の監査ギャップを伴います: スナップショットがなければ、missing_metrics はレポート時のプロダクトのライブ available_metrics に対して照合され、作成時にコミットされた内容を反映しないことがあります。committed_metrics を省略するセラーはこのリスクを受け入れます。バイヤーは欠如を「クリーンな配信」ではなく「監査グレードの契約なし」として扱うべきです(SHOULD)。次のメジャーで必須になる見込み。

エラーレスポンス

Submitted レスポンス

購入を同期的に確定できない場合に返されます——例: IO 署名を待つ保証付き購入、ガバナンスレビューのキュー入り、バッチ処理など。完了アーティファクト(tasks/get またはプッシュ通知 Webhook で配信)が media_buy_idpackages を運びます。 プロポーザル固有の受諾 Webhook はありません。人間の承認、IO 署名、または非同期処理を要するプロポーザル実行は、この同じ submitted タスクエンベロープと標準のタスク/Webhook 完了パスを使います。 Note: レスポンスはこれら三つの形状で相互排他です。まず status でディスパッチします: "submitted" → 非同期エンベロープ、それ以外は成功フィールドにアクセスする前に errors を確認します。

Submitted と同期 Success をいつ返すか(規範的)

submitted と同期成功の選択は呼び出しごとで、プロダクトごとの属性と各特定の作成に対するセラーのポリシーに駆動されます——一律のセラーごとのルールではありません。営業保証のセラーは、同じセッション内で一部の create_media_buy 呼び出しに同期成功を、他に submitted を正当に返しうる。適合的な SDK skill は、入力に関わらずすべての create_media_buy について submitted を返すようエージェントに指示してはなりません(MUST NOT)。一律に submitted を返すセラーは、sales-guaranteed コンプライアンスストーリーボードの非 IO 承認パスで失敗します。 セラーは次の場合に submitted を返さなければなりません(MUST):
  • リクエストが delivery_type: "guaranteed" のプロダクトを一つ以上参照し、かつセラーが requires_io_approval 機能を宣言する場合——人間の承認ハンドシェイクはレスポンス内で完了できません。完了アーティファクトは IO 署名の完了後に tasks/get または Webhook で配信されます。
  • リクエストが同期的に完了できないセラー側のガバナンスレビューをトリガーする場合(例: 規制業種向けの手動ブランドセーフティレビュー)。
  • リクエストが、セラーがレスポンスタイムアウト内に消化できないバッチ処理キューに入る場合。
セラーは次の場合に同期成功を返さなければなりません(MUST):
  • 参照されるすべてのプロダクトが delivery_type: "non_guaranteed" の場合。購入はインラインで作成・確認され、media_buy_idpackages が即座に発行されます。これはセラーの専門領域に関わらず適用されます——非保証プロダクトを提供する営業保証のセラーは同期成功を返します。
  • リクエストが保証プロダクトを参照し、セラーが requires_io_approval を宣言しない場合(まれ。通常はセラーが承認を事前クリアしているリテール SKU や見積レートの保証フロー)。
  • 購入が、バイヤーに即座に観測可能な既知の非終端状態(pending_creatives / pending_start / active / paused)に入る場合。
コンプライアンスグレーダーは、別々のストーリーボードシナリオを通じて同じセラーに対して両パスを観測します: create_buy_submitted シナリオは requires_io_approval を持つ保証プロダクトをシードし、四つの共有シナリオ(measurement_terms_rejectedpending_creatives_to_startinventory_list_targetinginvalid_transitions)は非保証プロダクトをシードして同期の media_buy_id 返却を期待します。同期期待のシナリオで submitted を返すセラーはコンプライアンスに失敗します——フィクスチャパターンは sales-guaranteed 専門領域 を参照(オープンブリーフの get_products 呼び出しが同期作成パスに解決されるよう、非保証プロダクトが最初にリストされます)。 このルールは、#3822 で追跡される skill ↔ storyboard の矛盾を解決します: 「すべての create_media_buy にタスクエンベロープを返す」ようエージェントに指示する SDK skill は非適合です。正しい skill は、プロダクトごとの delivery_type とセラーの requires_io_approval 機能でディスパッチするようエージェントに指示します。

主なシナリオ

ターゲティング付きキャンペーン

地理制限やフリークエンシーキャップを追加:

コンバージョン最適化付きキャンペーン

コンバージョン最適化配信のために per_ad_spend ターゲットを設定します。プロダクトが conversion_tracking.supported_targets でサポートを宣言しており、sync_event_sources 経由でイベントソースが設定済みである必要があります:

カタログ連動パッケージ

カタログ連動パッケージは、カタログ全体のアイテムに対して単一の予算枠を割り当てます。アイテムごとにパッケージを個別作成する代わりに、プラットフォームがパフォーマンスに基づいてカタログ全アイテムへの配信を最適化します。これは Google Performance Max や Meta Dynamic Product Ads などのカタログベースのキャンペーンタイプに相当する AdCP の機能です。 パッケージにカタログ連動を設定するには catalogs フィールドを含めます。各カタログはそれぞれ異なるタイプ(例:プロダクトカタログ 1 件、ストアカタログ 1 件)を持つ必要があります。参照するカタログは sync_catalogs 経由で事前に同期されている必要があります。 同期済みジョブカタログを使ったジョブキャンペーン:
test=false
プロダクトカタログとストア集客圏ターゲティングを使ったリテールメディア:
test=false
プラットフォームはパフォーマンスに基づいてカタログアイテム間で予算を配分します。アイテムごとのレポートには、by_catalog_item ブレークダウンを返す get_media_buy_delivery を使用します。カタログ連動パッケージのクリエイティブバリアントは、広告としてレンダリングされた個別のカタログアイテムを表します。 明示的なシグナルターゲティング付きパッケージ: バイヤーがセラー提供のシグナルを特定のパッケージに適用したい場合は targeting_overlay.signal_targeting_groups を使います。選択したプロダクトは signal_targeting_allowed: true を設定し、シグナルを適格にしなければなりません——インラインの signal_targeting_options(存在する場合)、インラインオプションを省略するホールセールプロダクトには get_signals、そして signal_targeting_rules を通じて。常にグループ化された式の形状を使います: トップレベルの operator: "all" と、include グループには operator: "any"、除外グループには operator: "none" を使う子グループ。単純な include のみのターゲティングには一つの any グループを送ります。バイナリシグナルでは、include と除外の両グループで value: true を送ります。除外は value: false ではなく親の none グループで表現します。シグナルは signal_ref で参照します: プロダクトローカルのシグナルオプションには scope: "product"、データプロバイダーが公開する adagents.json の signals[] で定義されたシグナルには data_provider_domain を伴う scope: "data_provider"、ソースネイティブなシグナルには signal_source_url を伴う scope: "signal_source"。これは、sync_audiences を通じて登録されたファーストパーティオーディエンスのみを参照する audience_include / audience_exclude とは別物です。signal_agent_segment_id は、選択したプロダクトオプションまたは get_signals の結果が、セラーが要求する別個の実行ハンドルとしてそれを公開した場合にのみ送ります。 クリエイティブがビルド時の signal_conditionbuild_creativesignal_conditions ファンアウト由来、#5240)を運ぶ場合、シグナルターゲティングが非互換なパッケージへの割り当て——例: 晴れのクリエイティブを雨ターゲットのパッケージへ——は SIGNAL_TARGETING_INCOMPATIBLE で拒否されます。互換性は、ここで使われる同じ共有 signal_ref アイデンティティで照合されます。規範的なトラフィッキング互換性契約はシグナル仕様を参照してください。
test=false
include と除外を組み合わせた例:
test=false

クリエイティブをインライン指定したキャンペーン

キャンペーン作成と同時にクリエイティブをアップロードします:

レポート用 Webhook を設定したキャンペーン

自動レポート通知を受け取ります。

プロポーザルの実行

get_products のプロポーザルを、パッケージを手作業で組まずに実行します。
プロポーザルを実行する際:
  • パブリッシャーが total_budget を使って配分割合を実額に変換
  • 配分に基づきパッケージが自動生成
  • それ以外のフィールド(brand、start_time、end_time など)は Manual モードと同じ
会話的なリファインを含む完全なフローは Proposals を参照。

相関のための Context

context フィールドは、セラーがレスポンスと Webhook でそのまま返す不透明なオブジェクトです。別個のルックアップテーブルを維持することなく、セラーが割り当てた ID を自分の内部システムにマッピングするために使います。 Context は二つのレベルで機能します:
  • メディアバイレベルcreate_media_buy レスポンスでエコーされる
  • パッケージレベル — 各パッケージのレスポンス、Webhook、読み取り面でエコーされ、package_id を内部ラインアイテムにマッピングするのに有用。明示的なパッケージリクエストでは、セラーは product_id もエコーしなければなりません(MUST)。
混在したセラー集団を対象とする場合、product_id をエコーしないかもしれない古いセラーのためのレガシーセーフなフォールバックとして、context.buyer_ref のようなパッケージ context を含めます。 内部のキャンペーン ID・ラインアイテム ID へのマッピング:
test=false
セラーのレスポンスは、セラーが割り当てた ID と並べて context を返します:
test=false
セラーは context データをパースしたり、それに基づいて動作したりしてはなりません——これは純粋にバイヤーの内部利用のために存在します。

エラーハンドリング

よくあるエラーと解決策: Example error response:

Key Concepts

フォーマット指定

各パッケージは、使用するフォーマットを format_ids[](レガシーの名前付きフォーマットパス——構造化された {agent_url, id} 参照)、format_option_refs[](3.1 以降のフォーマットオプションパス——プロダクトの format_options[] への参照)、または直接の正準セレクター(format_kind と任意の params)で指定すべきです(SHOULD)。すべてのフォーマットセレクターを省略すると、プロダクトがサポートするすべてのフォーマットがデフォルトになります。指定することで、システムは次を行えます:
  • アドサーバーにプレースホルダークリエイティブを公開する
  • 必要なクリエイティブアセットを正確にピン留めする
  • プロダクトが要求フォーマットをサポートするか検証する
  • 不足しているアセットを追跡する
セレクターの優先順位は決定的です: format_option_refs[] が存在すればそれが勝ち、なければ format_ids[] が存在すればそれが勝ち、なければ直接の format_kind/params が使われ、それもなければパッケージはすべてのプロダクトフォーマットにデフォルトします。バイヤーのコードベースが Product.format_options[] を読み、プロダクトが選択可能な format_option_id 値を公開する場合は format_option_refs[] を使います。レガシーフォーマットのみのセラーやライブラリと統合する場合は format_ids[] を使います。直接の format_kind は、バイヤーがプロダクトローカルの参照なしで対象プロダクト宣言を満たすのに十分な正準パラメータを持つ場合にのみ使います。format_option_refs[]format_ids[] の二重出力は許可され、混在したセラー集団を対象とするバイヤー SDK には推奨されます——上記の format_ids 行を参照。 3.1 以降のフォーマットオプションの例(パブリッシャースコープの Product.format_options[] エントリに対してバイヤーが作成する場合):
test=false
詳細は下記の フォーマットワークフロー を参照。

ブランド参照

brand フィールドはポリシー準拠とビジネス目的のために広告主を識別します。
ブランドの完全なアイデンティティデータ(色、フォント、プロダクトカタログ)は実行時に brand.json から解決されます。brand.json を参照。

価格と通貨

各パッケージは pricing_option_id を指定し、以下を決定します:
  • 通貨(USD、EUR など)
  • 価格モデル(CPM、CPCV、CPP など)
  • レートと固定/オークションの区別
セラーがサポートする場合、パッケージごとに異なる通貨を使用できます。Pricing Models 参照。

ターゲティングオーバーレイ

使用は最小限に — ターゲティングの大部分はブリーフに含め、プロダクト選択で処理されるべきです。 オーバーレイは以下に限定して使用します:
  • 地理的制限(RCT テスト、規制対応)
  • フリークエンシーキャップ
  • AXE セグメントの包含/除外(レガシー——新規統合は TMP を使用)
詳細は Targeting を参照。

フォーマットワークフロー

フォーマット指定が重要な理由

メディアバイ作成時にフォーマットを指定すると次が可能になります:
  1. プレースホルダー作成 - パブリッシャーが正しい仕様でアドサーバーにプレースホルダーを用意
  2. 検証 - 要求フォーマットをプロダクトがサポートするかシステムが検証
  3. 期待値の明確化 - 双方が必要なものを正確に把握
  4. 進捗トラッキング - 不足アセットと必須アセットを可視化
  5. 技術セットアップ - クリエイティブ到着前にアドサーバーを設定

完全なワークフロー

フォーマット検証

パブリッシャーが必ず検証する事項:
  • すべてのフォーマットがプロダクトでサポートされています
  • フォーマット仕様が list_creative_formats の出力と一致
  • 期限内にクリエイティブ要件を満たせる
無効なレガシー名前付きフォーマットの例:
無効な 3.1 以降のフォーマットオプションの例:

フライト日程バリデーション

新規メディアバイでは、トップレベルの start_time"asap" か、過去でない日時のいずれかでなければなりません(MUST)。過去の具体的な start_timeINVALID_REQUEST エラーを返さなければなりません(MUST)。 パッケージに start_time または end_time を指定した場合、セラーは以下を検証すべきだ:
  • 両日程がメディアバイの日付範囲内に収まっています
  • start_timeend_time より前です
範囲外または逆転した日程は INVALID_REQUEST エラーを返すべきだ:

非同期オペレーション

このタスクは即時完了する場合も、複雑さや承認要件によっては日数を要する場合もあります。レスポンスの status フィールドで結果と次のアクションを確認してください。 Note: 完全なステータス一覧は Task Lifecycle を参照。

即時成功 (completed)

タスクが同期的に完了しました。非同期処理は不要です。Request:
test=false
Response:
トップレベルの status はエンベロープのタスクステータス(TaskStatus)です——同期成功では completed。ボディレベルの media_buy_status は購入のライフサイクル状態(pending_creativespending_startactivepaused)を運びます。3.0 形式のレスポンスはこの二つの列挙を同じルートキーで衝突させていました。3.1 ではこれらは別々のフィールドです。セラーは、3.0 バイヤーとの後方互換のため 3.1 非推奨期間中に非推奨のトップレベル status: MediaBuyStatus を出し続けてもよい(MAY)が、3.1 バイヤーは media_buy_status を優先しなければなりません(MUST)。下記の メディアバイステータスフィールド(3.1 移行) を参照。

長時間処理 (submitted)

タスクが手動承認キューに入っています。更新を受け取るため Webhook を設定します。Request with webhook:
test=false
Initial response:
Webhook POST when approved:

Error (failed)

Response:
非同期処理の完全なパターンは Async Operations を参照。

使用上の注意

  • 総予算は各パッケージの個別の budget 値に基づいて配分されます
  • クリエイティブアセットはキャンペーン有効化のためにデッドライン前にアップロードしなければなりません
  • インプレッション時のターゲティング(オーディエンス、フリークエンシー、適合性)は TMP が処理します
  • workingsubmitted などの保留状態は正常であり、エラーではありません
  • オーケストレーターは保留状態を通常のワークフローの一部として処理しなければなりません
  • インラインクリエイティブ: creatives 配列はパッケージのクリエイティブをインラインで作成または提供します。セラーが creative.has_creative_library: true を宣言する場合、インラインクリエイティブはライブラリに入ります。既存のライブラリクリエイティブを更新するには sync_creatives を、割り当てるには creative_assignments を使用。セラーがクリエイティブライブラリなしで inline_creative_management: true を宣言する場合、create_media_buyupdate_media_buypackages[].creatives を使い、sync_creatives は呼びません。
  • インラインクリエイティブのライフサイクル: ライブラリ対応のインラインクリエイティブは、sync_creatives のアップロードと同じライフサイクルでライブラリに入ります。インライン専用のセラーはクリエイティブをパッケージスコープに保ち、後の creative_id による再利用を宣言しないことがあります。クリエイティブレビューは購入の結果とは独立しています。セラーは、購入がアクティベートされなかったというだけでレビューをスキップしてはなりません(MUST NOT)。未割り当てのライブラリクリエイティブの保持は 3.0 ではセラー定義です。パッケージ上のインラインクリエイティブを参照。

Content Standards

メディアバイがコンテンツ標準を含む場合(get_products レスポンスの governance.content_standards フィールド、またはメディアバイリクエスト経由)、バイヤーは配信中のブランド適合性の強制を要求しています。
コンテンツ標準は、検証エージェント(例: IAS、DoubleVerify)で create_content_standards を呼び出すことで作成されます。標準は、セラーのローカル評価モデルが検証エージェントの解釈と整合するよう、本番で使う前に各セラーとキャリブレーションされなければなりません(MUST)。完全なセットアップワークフロー(create → calibrate → activate → validate)はコンテンツ標準の概要を参照してください。

ポリシー準拠

ブランドとプロダクトは作成時に検証されます。ポリシー違反はエラーを返します:
パブリッシャーは以下を確認すべきだ:
  • ブランド/プロダクトが選択したパッケージと整合しています
  • クリエイティブが宣言したブランド/プロダクトと一致しています
  • キャンペーンがすべての広告ポリシーに準拠しています

次のステップ

メディアバイ作成後:
  1. クリエイティブの提供: ライブラリ対応のセラーには sync_creatives を、インライン専用のセラーには update_media_buypackages[].creatives を使用
  2. ステータスの監視: get_media_buy_delivery を使用
  3. 最適化: provide_performance_feedback を使用
  4. 更新: update_media_buy でキャンペーンを変更

メディアバイステータスフィールド(3.1 移行)

3.1 は、3.0 が同じルートキーで衝突させていた二つの列挙を分割します——すべてのレスポンスの先頭にあるエンベロープの status(TaskStatus)と、購入のライフサイクル状態を並べて運ぶボディの media_buy_status(MediaBuyStatus、3.1 の新機能)。レガシーのトップレベル status: MediaBuyStatus 形式は 3.1 で deprecated: true となり、3.2 で削除されます(#4906)。get_media_buysget_media_buy_deliverycore/media-buy.json のネストされた status は 4.0 で続きます(#4905)。 3.1 バイヤーは、存在する場合 media_buy_status を優先しなければなりません(MUST)。3.1 コンプライアンスストーリーボードは path: "media_buy_status" をアサートします——レガシーの status のみを出す 3.1 セラーはスキーマ上有効ですが認定に失敗します。ストーリーボードが拘束的な適合性チェックです。 完全な移行: 移行 › media_buy_status

関連ドキュメント