AdCP — Optimization & Reporting

データドリブンな監視と最適化による継続的改善を実現します。AdCP はパフォーマンス追跡・配信分析・成果向上を支援する包括的なレポーティング/最適化機能を提供します。 AdCP のレポーティングはキャンペーン設定に用いる Targeting と整合しており、ライフサイクル全体で一貫した分析が可能です。ターゲットした内容と同じ粒度でレポートできます。パフォーマンスデータは AdCP の Accountability & Trust Framework に反映され、パブリッシャーは安定した配信でレピュテーションを築き、バイヤーはデータに基づいて配分判断ができます。

主な最適化タスク

デリバリーレポート

get_media_buy_delivery でインプレッション、消化額、クリック、コンバージョンなど全パッケージのパフォーマンスデータを取得します。あるいはメディアバイ作成時に Webhook ベースのレポーティング を設定し、定期的な自動通知を受け取ります。

キャンペーン更新

パフォーマンスインサイトに基づき、update_media_buy で設定・予算・構成を更新します。

最適化ワークフロー

一般的な最適化サイクル:

配信を監視: 目標に対するパフォーマンスを追跡
パフォーマンス分析: 最適化の機会を特定
調整を実施: 予算・ターゲティング・クリエイティブ割り当てを更新
変化を追跡: 最適化の影響をモニタリング
反復: 定期的な分析で継続的改善

メトリクスのライフサイクル

AdCP のすべての最適化メトリクス——セラーネイティブ（clicks、views、reach）、卒業済みのベンダー証明（viewability）、ベンダー定義（アテンション、ブランドリフト、排出量）のいずれであっても——は、同じ一連のサーフェスを流れます。バイヤーは次の三つの問いを順に立ててメトリクスを推論します:

できるか？ — プロダクトはこのメトリクスを最適化できるか？ （ディスカバリー）
やるか？ — このパッケージについて、最適化と報告をコミットするか？ （コミットメント）
やったか？ — 配信において値はいくつで、コミットメントを満たしたか？ （レポーティング）

各問いは特定のプロトコルサーフェスに対応します。同じ metric_id（ベンダー証明メトリクスでは (vendor, metric_id) タプル）がすべてのレイヤー——ディスカバリー、機能宣言、パッケージのコミットメント、配信——を流れるため、目標に対して配信を照合するバイヤーは変換表を必要としません。

標準メトリクスのフロー（例: `clicks`、`viewable_rate`）

Question	Surface	Field
プロダクトは報告できるか？	プロダクト機能	`reporting_capabilities.available_metrics`
プロダクトは最適化できるか？	プロダクト機能	`metric_optimization.supported_metrics`
セラーは報告にコミットするか？	パッケージ	`committed_metrics[]`（scope: `standard`）
バイヤーは最適化を望むか？	パッケージ	`optimization_goals[]`（kind: `metric`）
バイヤーはアカウンタビリティを望むか？	パッケージ	`performance_standards[]`
値はいくつだったか？	配信	標準スカラー（例: `clicks`、`viewability.viewable_rate`）
セラーはコミット済みメトリクスの提供に失敗したか？	配信	`missing_metrics[]`（scope: `standard`）

ベンダー証明メトリクスのフロー（例: Adelaide アテンション、Scope3 排出量、Kantar ブランドリフト）

同じライフサイクルで、単なる metric_id の代わりに (vendor, metric_id) タプルがあらゆる箇所に入ります:

Question	Surface	Field
ベンダーはこのメトリクスを定義しているか？	ベンダーの機能	`get_adcp_capabilities.measurement.metrics[]`
プロダクトはこのベンダーメトリクスを報告できるか？	プロダクト機能	`reporting_capabilities.vendor_metrics[]`
プロダクトはこのベンダーメトリクスを最適化できるか？	プロダクト機能	`vendor_metric_optimization.supported_metrics[]`
セラーは報告にコミットするか？	パッケージ	`committed_metrics[]`（scope: `vendor`）
バイヤーは最適化を望むか？	パッケージ	`optimization_goals[]`（kind: `vendor_metric`）
バイヤーはアカウンタビリティを望むか？	パッケージ	`performance_standards[]`（`vendor` フィールド付き）
値はいくつだったか？	配信	`vendor_metric_values[]`
セラーはコミット済みメトリクスの提供に失敗したか？	配信	`missing_metrics[]`（scope: `vendor`）

なぜ両方のフローが重要か

二つのフローは重複ではありません——標準化された計測とベンダー固有の計測の違いをエンコードしています。クリックはどのセラーでも同じ意味を持ちますが、アテンションはそうではありません。ベンダーの紐付けは、どのアテンションモデルが最適化・報告されているかについてバイヤーとセラーが合意したという、ワイヤーレベルの証拠です。あるメトリクスがどちらのフローを使うかを決める Tier 0 → Tier 1 の卒業ポリシーは measurement/taxonomy.mdx を参照してください。

レイヤー間で必要な整合性

三つのルールがレイヤーを接続し、孤立した目標を防ぎます:

最適化には機能が必要。 パッケージの optimization_goals[] エントリは、プロダクト機能と一致しなければなりません（MUST）——kind: "metric" には metric_optimization.supported_metrics、kind: "vendor_metric" には vendor_metric_optimization.supported_metrics。セラーは不一致を TERMS_REJECTED で拒否します。
最適化には報告のコミットメントが必要。 kind: "vendor_metric" の目標では、一致する (vendor, metric_id) がパッケージの committed_metrics[] にも現れなければなりません（MUST）。セラーが報告をコミットしていないメトリクスの最適化は検証不能です——バイヤーには目標を採点する手段がありません。セラーはコミットされていない vendor_metric 目標を TERMS_REJECTED で拒否します。（このルールは特にベンダーメトリクスについて規範的です。セラーネイティブな metric 目標では、セラーネイティブであること自体により通常は常に報告されるため、整合性は暗黙的です。）三つ目の前提条件——ディスカバリー、すなわち metric_id がベンダーの公開する measurement.metrics[] カタログに現れること——は、計測ベンダーの AdCP 適合の機能公開への対応が追いつくまで、このマイナーでは SHOULD であり、次のマイナーで MUST に強化されます。
パフォーマンスのアカウンタビリティは独立。 performance_standards[] は並行して存在します——バイヤーは、最適化目標も設定するかどうかに関わらず、セラーが報告をコミットする任意のメトリクスに閾値のコミットメントを追加してよい（MAY）。三つのサーフェス（目標 / コミットメント / 基準）は組み合わさります:
- 目標のみ — 「これに向けて押し進めて」、アカウンタビリティの下限なし
- 基準のみ — 「X 以上を負っている」、達成方法はセラーが決める
- 両方 — 最適化が舵を取り、基準が下支えする
優先度は序数で、値が小さいほど優先。 optimization_goals[] が明示的な priority 値を運ぶ場合、セラーは最小の priority 値を持つ目標を主目標として扱います——priority: 1 の目標がない場合でも（priority が 2 と 3 なら 2 が主）。priority が省略された場合、セラーは配列の位置を使ってよい。重複する priority 値は未定義です。

実例: Adelaide アテンションのエンドツーエンド

バイヤーが Adelaide の attention_score を閾値 70 で最適化したいとします。四つのサーフェスがどう並ぶかを示します: 1. プロダクト機能（get_products でディスカバリー）:

{
  "product_id": "premium_ctv_video",
  "vendor_metric_optimization": {
    "supported_metrics": [
      {
        "vendor": { "domain": "adelaidemetrics.com" },
        "metric_id": "attention_score",
        "supported_targets": ["cost_per", "threshold_rate"]
      }
    ]
  },
  "reporting_capabilities": {
    "vendor_metrics": [
      { "vendor": { "domain": "adelaidemetrics.com" }, "metric_id": "attention_score" }
    ]
  }
}

2. create_media_buy でのパッケージ提案 — バイヤーは報告のコミットと最適化目標の両方を設定します（報告整合性ルールにより両方必須）:

{
  "product_id": "premium_ctv_video",
  "committed_metrics": [
    {
      "scope": "vendor",
      "vendor": { "domain": "adelaidemetrics.com" },
      "metric_id": "attention_score"
    }
  ],
  "optimization_goals": [
    {
      "kind": "vendor_metric",
      "vendor": { "domain": "adelaidemetrics.com" },
      "metric_id": "attention_score",
      "target": { "kind": "threshold_rate", "value": 70 },
      "priority": 1
    }
  ]
}

バイヤーが契約上の下限を望む場合、performance_standard を上に重ねてもよい（MAY）——例: { "metric": "attention_score", "vendor": { "domain": "adelaidemetrics.com" }, "threshold": 65 }——が、これは目標とは独立です。 3. 配信（get_media_buy_delivery レスポンス）:

{
  "vendor_metric_values": [
    {
      "vendor": { "domain": "adelaidemetrics.com" },
      "metric_id": "attention_score",
      "value": 73.2,
      "measurable_impressions": 420000
    }
  ]
}

セラーの入札スタックはより高い Adelaide アテンションスコアへ舵を切りました。報告値 73.2 は閾値 70 を上回るため、目標は達成されています。measurable_impressions の分母（配信インプレッション 100 万のうち 420000 など）は Adelaide の計測のカバレッジ値です——ベンダー SDK が配信インプレッションの 100% で発火することはまれで、今日の CTV におけるアテンションベンダーのカバレッジは、アプリ SDK の有無に応じて通常 30〜60% です。報告値について推論する前に、必ず measurable_impressions / impressions からカバレッジを計算してください。 4. アカウンタビリティギャップの報告（コミットメントが満たされない場合、同じく get_media_buy_delivery レスポンス内）:

{
  "by_package": [{
    "package_id": "...",
    "missing_metrics": [
      {
        "scope": "vendor",
        "vendor": { "domain": "adelaidemetrics.com" },
        "metric_id": "attention_score"
      }
    ]
  }]
}

在庫における Adelaide のカバレッジがセラーの信頼閾値を下回り、この期間の vendor_metric_values を埋められなかった場合、同じ (vendor, metric_id) が missing_metrics に現れます——ライフサイクル全体で同じキーであるため、バイヤーの照合は行レベルの結合になります。

パフォーマンス監視

リアルタイム指標

配信中のキャンペーンを追跡します。

目標に対する インプレッション配信状況
予算に対する 消化ペース
CTR とエンゲージメント
事業成果に紐づく コンバージョン追跡

ヒストリカル分析

時間軸でパフォーマンス傾向を把握します。

主要指標の 日次/時間別の内訳
期間をまたいだ パフォーマンス比較
最適化機会を見つける トレンド識別

アラート/通知

重要なキャンペーンイベントを把握します。

ペース異常に対する 配信アラート
大きな変化に対する パフォーマンス通知
上限到達前の 予算警告

配信方法

パブリッシャーは Webhook 通知またはオフラインファイル配信でレポートデータをバイヤーへプッシュできます。これによりポーリングを不要にし、タイムリーなインサイトを提供します。 Webhook Push（リアルタイム） - バイヤーのエンドポイントへ HTTP POST

適合: 多くのバイヤー・セラー関係
レイテンシ: ほぼリアルタイム（秒〜分）
コスト: 標準的な Webhook 基盤

オフラインファイル配信（バッチ） - クラウドストレージバケットへのプッシュ

適合: 高ボリュームの大口バイヤー/セラー
レイテンシ: 定期バッチ（毎時/日次）
コスト: 大幅に低い（ $0.01-0.10/GB 対$ 0.50-2.00/100 万 Webhook）
フォーマット: JSON Lines, CSV, Parquet
ストレージ: S3, GCS, Azure Blob Storage

Webhook ベースのレポーティング

Webhook 設定

メディアバイ作成時に reporting_webhook パラメーターでレポート Webhook を設定します。

{
  "packages": [...],
  "reporting_webhook": {
    "url": "https://buyer.example.com/webhooks/reporting",
    "authentication": {
      "schemes": ["Bearer"],
      "credentials": "secret_token_min_32_chars"
    },
    "reporting_frequency": "daily"
  }
}

本番推奨: HMAC 署名付き

{
  "packages": [...],
  "reporting_webhook": {
    "url": "https://buyer.example.com/webhooks/reporting",
    "authentication": {
      "schemes": ["HMAC-SHA256"],
      "credentials": "shared_secret_min_32_chars"
    },
    "reporting_frequency": "daily"
  }
}

セキュリティ必須:

authentication 設定は必須（32 文字以上）
Bearer トークン: シンプルで開発向き（Authorization ヘッダー）
HMAC-SHA256: 本番推奨。リプレイ攻撃を防止（署名ヘッダー）
資格情報はオンボーディング時に帯域外で交換
実装詳細は Security を参照

サポートされる頻度

パブリッシャーはプロダクトの reporting_capabilities でサポートする頻度を宣言します。すべてをサポートする必要はなく、運用に適した頻度を選択します。

hourly: キャンペーン期間中、毎時間通知（任意。コスト/複雑性を考慮）
daily: 1 日 1 回通知（最も一般的、フェーズ1に推奨）
monthly: 月 1 回通知（タイムゾーンはパブリッシャー指定）

コスト考慮: 時間単位 Webhook は日次の 24 倍のトラフィックを発生。大規模なバイヤー/セラーではコスト効率のためオフラインレポートを好む場合があります。

提供可能な指標

指標の可否は 2 つのレベルで宣言します。

プロダクトレベル: reporting_capabilities.available_metrics でプラットフォームが提供できる指標を宣言
フォーマットレベル: クリエイティブフォーマットの reported_metrics でそのフォーマットが生成できる指標を宣言（Reported Metrics を参照）

バイヤーは両者の積集合を受け取ります。impressions と spend は積集合によらず常に提供されます。標準的な指標:

impressions: 広告表示（常に提供）
spend: 消化額（常に提供）
clicks: クリック数
ctr: クリック率
views: プラットフォーム定義の閾値での視聴数
completed_views: 動画/オーディオの完了数（最適化目標がカスタムの視聴尺を設定する場合は閾値ベースの完了数）
completion_rate: 完了率（completed_views / impressions）。該当しない場合（非動画の購入など）は null
conversions: クリック後/視聴後コンバージョン
conversion_value: 帰属コンバージョンの金銭的価値
roas: 広告費用対効果
cost_per_acquisition: コンバージョンあたりコスト
new_to_brand_rate: 初回購入者によるコンバージョンの割合
leads: リード獲得数
reach: ユニークリーチ（reach_unit と対）。計測ウィンドウは reach_window（cumulative / period / rolling）で宣言。reach_window が省略された場合ウィンドウは未指定であり、バイヤーは行をまたいでリーチを合計してはなりません（MUST NOT）。
reach_window: リーチ/フリークエンシーのウィンドウ意味論——kind（キャンペーン開始以降の cumulative、重複しないスナップショットの period、後方ウィンドウの rolling）と period: Duration（period と rolling で必須）を持つオブジェクト
frequency: reach_window にわたって計測された、リーチ単位あたりの平均フリークエンシー
grps: グロスレーティングポイント（CPP 課金向け）
engagements: 視聴を超える直接的な広告インタラクション（リアクション、タップ、オープン）
engagement_rate: プラットフォーム固有のエンゲージメント率
follows: 配信に帰属する新規フォロワー、ページのいいね、アーティスト/ポッドキャスト/チャンネルのフォロー、または無料のチャンネル/フィード購読。有料サブスクリプションは event_type: "subscribe" のコンバージョンイベントです。
saves: 配信に帰属する保存、ブックマーク、プレイリスト追加（プラットフォームによって名称が異なる——Pinterest の「repins」、TikTok の「video_saves」——すべてこの正準キーで報告）
profile_visits: ブランドのプラットフォーム内ページへの訪問
viewability: ビューアビリティデータ（measurable_impressions, viewable_impressions, viewable_rate, viewed_seconds, standard, vendor）。MRC 基準と GroupM 基準を区別。viewed_seconds は計測可能インプレッションあたりの平均インビュー時間で、viewed_seconds 最適化目標のレポート側の対応物であり、viewable_rate と同じ standard 閾値に従います。任意の vendor フィールドは BrandRef を運ぶため行が自己記述的になります——配信を単独で読むバイヤーエージェントは、package.committed_metrics や package.performance_standards へ結合し直すことなく数値を計測ベンダーに帰属できます。
quartile_data: 動画クォータイル完了データ（q1〜q4）。該当しない場合（非動画の購入など）は null
dooh_metrics: DOOH 固有指標（ループ再生数、スクリーン数、会場別内訳）
cost_per_click: クリックあたりコスト（spend / clicks）
cost_per_completed_view: 完了視聴あたりコスト（spend / completed_views）。動画/オーディオ在庫の CPCV 価格スカラー
cpm: 1000 インプレッションあたりコスト（(spend / impressions) × 1000）。CTV、ディスプレイ、モバイル/ウェブ動画、ネイティブ、オーディオ、DOOH をまたぐ普遍的な価格スカラー
downloads: オーディオ/ポッドキャストのダウンロード（IAB Podcast Measurement Technical Guidelines の手法）。views とは別
units_sold: 配信に帰属して販売された点数（リテールメディアのコマーススカラー。conversions とは別——1 トランザクションが複数の点数を含みうる。アトリビューションウィンドウは measurement_terms で宣言）
new_to_brand_units: new_to_brand_rate の点数版——初回購入者に販売された点数のカウント
plays: DOOH/放送在庫の生の再生回数（forecastable-metric.plays に対応）。dooh_metrics.loop_plays（スクリーンごとのローテーション）や impressions（乗算後のオーディエンス数）とは別

バイヤーは requested_metrics で必要な指標のみを要求し、ペイロードを抑えて KPI に集中できます。 completion_rate と quartile_data については、セラーはメトリクスが該当しないことを示すために null を返してよく（MAY。例: 非動画の購入）、クライアントはこの二つのフィールドについて null を有効な値として受け入れなければなりません（MUST）。他のすべてのメトリクスは省略によって「該当なし」を示します——セラーは null を送るのではなく省略します。

ベンダー定義メトリクス

標準の available_metrics 列挙は閉じたプロトコル語彙です。ベンダー定義メトリクス——独自のアテンションスコア、インプレッションあたり排出量、パネルベースのデモグラフィック、ブランドリフト調査、フライト中のアテンションパネル、カスタムのビューアビリティ亜種——は並行する構造化サーフェスに存在します:

宣言（reporting_capabilities.vendor_metrics）: 各エントリはベンダーのメトリクスカタログへのポインタ（{ vendor: BrandRef, metric_id }）です。セラーは「このベンダーのメトリクスをサポートする」と言うだけで、それ以外（カテゴリ、手法、標準との整合、人が読めるドキュメント）はベンダー側に存在します。識別子はベンダーで名前空間化されます——同じ metric_id が異なるベンダーの語彙で異なる意味を持ちうる。
ディスカバリーのアンカー: ベンダーの brand.json の agents[type='measurement'] が、計測エージェントの URL、機能プロファイル、手法、各メトリクスが実装する標準、メトリクスごとのドキュメントを見つける正準的な場所です。AdCP はそのメタデータをすべてのセラーのプロダクトごとの拡張に複製しません。バイヤーは必要なときにベンダーごとに一度だけ解決します（キャッシュ可能）。
フィルター（get_products の filters.required_vendor_metrics）: 各エントリは vendor および/または metric_id を指定します（少なくとも一方）。ベンダー横断のクエリ（例: 「サポートするベンダーの任意のアテンション計測」）はバイヤーエージェントの責任です: エージェントは brand.json レコードを通じてどのベンダーがカテゴリを提供するかを解決し、それらをフィルターエントリとして列挙します。他の required_* フィルターと同じ filter-not-fail の慣習。
レポーティング（各 by_package 配信行の vendor_metric_values）: 各値は { vendor, metric_id, value, unit?, measurable_impressions?, breakdown? } を運びます。measurable_impressions はカバレッジの分母です——ベンダー計測が配信インプレッションの 100% であることはまれです。このフィールドが存在する場合、バイヤーはカバレッジを measurable_impressions / impressions として計算します。存在しない場合、カバレッジは未指定です（率を計算したり、完全なカバレッジを仮定したりしないでください）。breakdown スロットは、単一のスカラーを超える構造化ペイロード（パネルのデモグラフィック、共視聴比率、増分の分解）をベンダーが置く場所です。これが唯一の逃げ道であり、値エンベロープの残りは閉じています。
昇格パス: 業界が公開された標準を通じてあるメトリクスに収束したとき、仕様はそれを閉じた available_metrics 列挙に追加し、ベンダー拡張は歴史的なエイリアスになります。昇格は、場当たり的なベンダー収束数ではなく、標準化団体の公開に基づきます。
アカウンタビリティのスコープ: セラーが package.committed_metrics にベンダーメトリクスを刻印する場合（scope: "vendor"）、標準メトリクスと同じ get_media_buy_delivery の missing_metrics 契約の対象になります。ベンダーメトリクスを確かに証明できないセラーは、それを committed_metrics に刻印すべきではありません（SHOULD NOT）。不在はメトリクスを助言的なままにし、照合は vendor_metric_values.measurable_impressions のカバレッジと、ベンダーの計測エージェントを通じた帯域外の検証にフォールバックします。助言的か説明責任を伴うかの区別は、メトリクスのスコープ間で非対称であるのではなく、契約レイヤーで明示的になりました。

パブリッシャーのコミットメント

レポート Webhook を設定した場合、パブリッシャーは以下を送信します。 (campaign_duration / reporting_frequency) + 1 回の通知

キャンペーン期間中、頻度ごとに 1 回
キャンペーン完了時に最終通知を 1 回
想定遅延時間を超える場合は "delayed" 通知を送信

Webhook ペイロード

レポート Webhook は完全な MCP Webhook エンベロープを送ります。配信レポート自体は get_media_buy_delivery と同じペイロード構造にメタデータを加えたものですが、result の下にネストされます。内側の配信オブジェクトをトップレベルの POST ボディとして送らないでください。

{
  "idempotency_key": "whk_20240205_example_000005",
  "operation_id": "delivery_report_mb001_2024_02_05",
  "task_id": "delivery_report_mb001_2024_02_05_000005",
  "task_type": "media_buy_delivery",
  "status": "completed",
  "timestamp": "2024-02-06T08:00:00Z",
  "message": "Scheduled media buy delivery report available",
  "result": {
    "notification_type": "scheduled",
    "sequence_number": 5,
    "next_expected_at": "2024-02-06T08:00:00Z",
    "reporting_period": {
      "start": "2024-02-05T00:00:00Z",
      "end": "2024-02-05T23:59:59Z"
    },
    "currency": "USD",
    "media_buy_deliveries": [
      {
        "media_buy_id": "mb_001",
        "status": "active",
        "totals": {
          "impressions": 125000,
          "spend": 5625.0,
          "clicks": 250,
          "ctr": 0.002
        },
        "by_package": []
      }
    ]
  }
}

内側の result オブジェクトは個別に表示・保存できますが、この形状はトップレベルの Webhook POST ボディとしては無効です:

{
  "notification_type": "scheduled",
  "sequence_number": 5,
  "reporting_period": {
    "start": "2024-02-05T00:00:00Z",
    "end": "2024-02-05T23:59:59Z"
  },
  "currency": "USD",
  "media_buy_deliveries": [
    {
      "media_buy_id": "mb_001",
      "status": "active",
      "totals": {
        "impressions": 125000,
        "spend": 5625.00,
        "clicks": 250,
        "ctr": 0.002
      },
      "by_package": [...]
    }
  ]
}

Fields:

notification_type: "scheduled"（定期）、"final"（完了）、"delayed"（データ未準備）
sequence_number: 連番（1 起算）
next_expected_at: 次回通知の ISO 8601 時刻（最終通知では省略）
media_buy_deliveries: メディアバイ配信データの配列（パブリッシャーが複数メディアバイをまとめて返す場合あり）

タイムゾーンの扱い

レポーティングはすべて UTC を使用しなければなりません。 DST の複雑性を排除し、照合を簡素化し、一貫した 24 時間単位を保証します。

{
  "reporting_capabilities": {
    "timezone": "UTC",
    "available_reporting_frequencies": ["daily"],
    "date_range_support": "date_range"
  }
}

レポート期間:

日次: 00:00:00Z 〜 23:59:59Z（常に 24 時間）
時次: 時刻 00 分 00 秒〜59 分 59 秒（常に 1 時間）
月次: 月初〜月末

Example webhook payload:

{
  "reporting_period": {
    "start": "2024-02-05T00:00:00Z",
    "end": "2024-02-05T23:59:59Z"
  }
}

遅延レポーティング

プロダクトの expected_delay_minutes 内にレポートデータが用意できない場合、パブリッシャーは notification_type: "delayed" で通知します。

{
  "notification_type": "delayed",
  "sequence_number": 3,
  "next_expected_at": "2024-02-06T10:00:00Z",
  "message": "Reporting data delayed due to upstream processing. Expected availability in 2 hours."
}

これにより、通知が欠落したと誤解されるのを防ぎます。

計測成熟ウィンドウ

課金グレードのデータが初日に最終値として届くのではなく段階的に生成されるチャネルでは、セラーはプロダクトに measurement_windows を宣言します。各ウィンドウは、独自の想定提供時期を持つ成熟ステージを表します。このパターンはチャネルをまたいで使われます:

Channel	Typical windows
放送 / 地上波 TV	`live`（当日）→ `c3`（約4日）→ `c7`（約15〜22日、保証の基準）
DOOH	`tentative`（当日）→ IVT/不正チェック後の `final`（約1日、保証の基準）
IVT フィルタリング付きデジタル	raw → `post_givt` → `post_sivt`（約2〜3日、保証の基準）
ポッドキャスト	`downloads_7d` → `downloads_30d`（保証の基準）

各ウィンドウの数値は前のものに優先します。通常、一つのウィンドウが is_guarantee_basis——双方が照合する数値——です。計測ベンダーの処理時間は各ウィンドウの expected_availability_days に取り込まれます（累積と処理の両方を含む）。放送では、初期ウィンドウのデータの遅延や疎さは、通常セラー側のメタデータの問題ではなく、計測ベンダーの精算の問題です。Nielsen、Comscore、VideoAmp、その他の指定ベンダーは、Live、C3、C7、Live+5、または市場レベルの結果を波状に公開しうる。その期間中、セラーは配信を暫定または計測ベンダーの確定待ちとしてラベル付けし、measurement_window を保持し、is_final、finalized_at、supersedes_window、および遅延/ウィンドウ更新の通知を使って何が変わったかを示すべきです。バイヤーは、部分的なアフィリエイトや局の可視性を表すためにクリエイティブレコードやプロダクトメタデータをフォークすべきではありません。代わりに、セラーの配信行を市場、プレースメント、デイパート、クリエイティブ、計測ウィンドウで集約してください。セラーは、最初に利用可能になるデータパイプラインを反映するようプロダクトに expected_delay_minutes を設定します。reporting_capabilities の measurement_windows 配列がウィンドウごとのタイムラインを提供します。計測ウィンドウを持つプロダクトの配信データには、各パッケージに三つのフィールドが含まれます:

is_final — セラーがこのレポート期間についてデータを確定とみなす場合 true。データが更新される（より広いウィンドウ、追加処理）場合は false。セラーが暫定と最終を区別しない場合は不在。
measurement_window — このデータがどのウィンドウを表すか（例: "c3"）。プロダクトの measurement_windows の window_id を参照します。ウィンドウ成熟のない標準的なデジタルレポーティングでは不在。
supersedes_window — このレポートがどの以前のウィンドウを置き換えるか（例: C3 データが届いたときの "live"）。ある期間の最初のレポートでは不在。

セラーが同じ期間についてより広いウィンドウで更新データを送る場合、notification_type: "window_update" を使います。これは adjusted（同じウィンドウ内の訂正）とは別です。 計測ウィンドウのライフサイクル例 — 3月1日に放映される放送スポット: 3月2日 — Live データが到着（notification_type: scheduled）:

{
  "notification_type": "scheduled",
  "media_buy_deliveries": [{
    "media_buy_id": "mb_nova_q4",
    "by_package": [{
      "package_id": "primetime_30s",
      "impressions": 980000,
      "spend": 24500,
      "is_final": false,
      "measurement_window": "live"
    }]
  }]
}

3月5日 — C3 データが live に優先（notification_type: window_update）:

{
  "notification_type": "window_update",
  "media_buy_deliveries": [{
    "media_buy_id": "mb_nova_q4",
    "by_package": [{
      "package_id": "primetime_30s",
      "impressions": 1050000,
      "spend": 26250,
      "is_final": false,
      "measurement_window": "c3",
      "supersedes_window": "live"
    }]
  }]
}

3月16日 — C7 データが到着、この期間について最終（notification_type: window_update）:

{
  "notification_type": "window_update",
  "media_buy_deliveries": [{
    "media_buy_id": "mb_nova_q4",
    "by_package": [{
      "package_id": "primetime_30s",
      "impressions": 1120000,
      "spend": 28000,
      "is_final": true,
      "measurement_window": "c7",
      "supersedes_window": "c3"
    }]
  }]
}

バイヤーは window_update が届くたびに保存データを置き換えます。is_final: true のとき、それが保証に対して照合すべき数値です。同じライフサイクルの形状が、DOOH（tentative → final）、IVT フィルタリング付きデジタル（post_givt → post_sivt）、ポッドキャスト（downloads_7d → downloads_30d）、その他データが段階的に成熟するあらゆるチャネルに適用されます——異なるのはウィンドウ ID とタイミングだけです。 measurement_window が課金条件にどう現れ、照合と請求のクロックをどう駆動するかは、Accountability を参照してください。

Webhook の集約

複数のメディアバイが以下を共有する場合、呼び出し数削減のため Webhook を集約すべきです。

同一 Webhook URL
同一のレポート頻度
同一のレポート期間

例: バイヤーが同一エンドポイントで日次レポートを受けるアクティブキャンペーンを 100 件持つ場合

集約なし: 1 日 100 件の Webhook（非効率）
集約あり: 1 日 1 件の Webhook に 100 キャンペーンをまとめる（最適）

media_buy_deliveries 配列には Webhook 1 件あたり 1〜N のメディアバイが含まれます。バイヤーは配列を反復して各キャンペーンを処理してください。 Aggregated webhook example:

{
  "notification_type": "scheduled",
  "reporting_period": {
    "start": "2024-02-05T00:00:00Z",
    "end": "2024-02-05T23:59:59Z"
  },
  "currency": "USD",
  "media_buy_deliveries": [
    { "media_buy_id": "mb_001", "totals": { "impressions": 50000, "spend": 1750 }, ... },
    { "media_buy_id": "mb_002", "totals": { "impressions": 48500, "spend": 1695 }, ... },
    // ... 98 more media buys
  ]
}

バイヤーは配列を反復し、各メディアバイを個別に処理します。集計値が必要な場合は各メディアバイの合計から算出してください。

部分的な失敗の扱い

複数メディアバイを 1 つの Webhook にまとめる際、キャンペーンごとにデータ可否が異なる場合があります。 方針: ステータス付きベストエフォート配信 パブリッシャーは利用可能なデータをすべて含めた集約 Webhook を送り、ステータスで可否を示すべきです。

{
  "notification_type": "scheduled",
  "sequence_number": 5,
  "reporting_period": {
    "start": "2024-02-05T00:00:00Z",
    "end": "2024-02-05T23:59:59Z"
  },
  "currency": "USD",
  "media_buy_deliveries": [
    {
      "media_buy_id": "mb_001",
      "status": "active",
      "totals": {
        "impressions": 50000,
        "spend": 1750
      }
    },
    {
      "media_buy_id": "mb_002",
      "status": "active",
      "totals": {
        "impressions": 48500,
        "spend": 1695
      }
    },
    {
      "media_buy_id": "mb_003",
      "status": "reporting_delayed",
      "message": "Reporting data temporarily unavailable for this campaign",
      "expected_availability": "2024-02-06T02:00:00Z"
    }
  ],
  "partial_data": true,
  "unavailable_count": 1
}

部分失敗の主なフィールド:

partial_data: いずれかのキャンペーンでデータ欠落がある場合に true
unavailable_count: 遅延/欠落しているキャンペーン数
status: キャンペーン単位のステータス（"active", "reporting_delayed", "failed"）
expected_availability: 遅延データの準備予定時刻（分かる場合）

部分配信を使うべきケース:

上流遅延: データソースの速度差があります
システム劣化: 部分的な障害が一部キャンペーンに影響
データ品質問題: 特定キャンペーンのみ検証に失敗
レートリミット: API 制限で全キャンペーンを取得できません

部分配信を使わないケース:

全体障害: "delayed" 通知を送る
全キャンペーンに影響: notification_type: "delayed" を使用
バイヤー側エンドポイント問題: サーキットブレーカーで送信を止める

バイヤー側の処理例:

function processAggregatedWebhook(webhook) {
  if (webhook.partial_data) {
    console.warn(`Partial data: ${webhook.unavailable_count} campaigns delayed`);
  }

  for (const delivery of webhook.media_buy_deliveries) {
    if (delivery.status === 'reporting_delayed') {
      // Mark campaign as pending, retry via polling or wait for next webhook
      markCampaignPending(delivery.media_buy_id, delivery.expected_availability);
    } else if (delivery.status === 'active') {
      // Process normal delivery data
      processCampaignMetrics(delivery);
    } else {
      console.error(`Unexpected status for ${delivery.media_buy_id}: ${delivery.status}`);
    }
  }
}

ベストプラクティス:

データがない場合もステータス付きで全キャンペーンを配列に含めます
遅延/失敗がある場合は partial_data: true を設定
分かる場合は expected_availability を返す
Webhook 全体をリトライしません。必要ならバイヤーは個別にポーリング
部分配信率をモニタリングし、システム的な問題を検知

プライバシーとコンプライアンス

GDPR/CCPA 向けの PII マスキング

パブリッシャーはすべての Webhook ペイロードから PII を削除し、GDPR/CCPA に準拠しなければなりません。レポート Webhook には集計・匿名化された指標のみを含めてください。 除去するもの:

ユーザー ID、デバイス ID、IP アドレス
メールアドレス、電話番号
正確な位置情報（緯度/経度）
Cookie ID、広告 ID（集計されていない場合）
PII を含むカスタムディメンション

保持してよいもの:

集計指標（インプレッション、消化額、クリックなど）
粗い地理情報（市/州/国。番地は不可）
デバイスタイプカテゴリ（モバイル/デスクトップ/タブレット）
ブラウザ/OS カテゴリ
時間ベースの集計

Example - Before PII Scrubbing (❌ DO NOT SEND):

{
  "media_buy_id": "mb_001",
  "user_events": [
    {
      "user_id": "user_12345",
      "ip_address": "192.168.1.100",
      "device_id": "abc-def-ghi",
      "impressions": 1,
      "lat": 40.7128,
      "lon": -74.0060
    }
  ]
}

Example - After PII Scrubbing (✅ CORRECT):

{
  "media_buy_id": "mb_001",
  "totals": {
    "impressions": 125000,
    "spend": 5625.00,
    "clicks": 250
  },
  "by_package": [
    {
      "package_id": "pkg_001",
      "impressions": 125000,
      "spend": 5625.00,
      "by_geo": [
        {
          "geo_level": "region",
          "geo_code": "US-NY",
          "geo_name": "New York",
          "impressions": 45000,
          "spend": 2025.00
        }
      ],
      "by_geo_truncated": false
    }
  ]
}

パブリッシャーの責任:

Webhook 配信ではなくデータ収集レイヤーで PII をマスクします
再識別されないよう集計閾値を設定（例: セグメントあたり 10 ユーザー以上）
収集データと Webhook で共有するデータの違いを明文化
GDPR 準拠のため DPA（データ処理契約）を提供
GDPR/CCPA の削除依頼に対応

バイヤーの責任:

requested_metrics やカスタムディメンションで PII を要求しません
Webhook データが集計・匿名化されていることを理解します
適切なデータ保持ポリシーを実装
プライバシーポリシー/ユーザー通知に Webhook データを含めます

実装ベストプラクティス

配列を扱う: 1 件でも media_buy_deliveries は配列として処理します
冪等なハンドラー: 重複通知を安全に処理（Webhook は at-least-once 配信）
シーケンス管理: sequence_number で欠落/順不同の通知を検知
フォールバックポーリング: Webhook 失敗時に備え定期ポーリングを継続
タイムゾーン意識: 期間計算のためパブリッシャーのタイムゾーンを保持
頻度の検証: リクエストした頻度が available_reporting_frequencies に含まれることを確認
指標の検証: リクエストした指標が available_metrics に含まれることを確認
PII コンプライアンス: Webhook ペイロードにユーザーレベルデータを含めない

Webhook Health Monitoring

Webhook 配信ステータスは AdCP のグローバルタスク管理システム で追跡します（Task Lifecycle 参照）。 reporting_webhook を設定してメディアバイを作成すると、パブリッシャーは配信用のタスクを生成します。バイヤーは標準のタスククエリで Webhook の健全性を監視できます。 タスク管理を使う利点:

すべての AdCP オペレーションで一貫したステータス管理
ポーリング/Webhook の標準パターンを利用
ステータス/履歴/エラーの既存インフラを活用
メディアバイ固有の健全性エンドポイントが不要

Webhook 配信が恒常的に失敗しサーキットブレーカーが開いた場合、パブリッシャーはタスクステータスを更新して問題を示します。バイヤーは通常のタスク監視で検知できます。

オフラインファイル配信ベースのレポーティング

例: オフライン配信 パブリッシャーが日次レポートをバイヤーのクラウドストレージへプッシュ:

s3://buyer-reports/publisher_name/2024/02/05/media_buy_delivery.json.gz

ファイルは Webhook と同じ構造で、すべてのキャンペーンを集約しています。バイヤーは都合の良いタイミングで処理します。 オフライン配信を使うケース:

同一バイヤーで 100 本超のアクティブキャンペーン
時間単位レポートが必要（コスト 24 倍削減）
詳細な内訳や多次元データでボリュームが大きい
バイヤーにバッチ処理基盤があります

セラーは、サポートするプッシュ型の配信方法とプロトコルを get_adcp_capabilities で宣言します。get_media_buy_delivery によるポーリングは常に利用可能です——これはすべての media_buy セラーの必須タスクです。

{
  "media_buy": {
    "reporting_delivery_methods": ["webhook", "offline"],
    "offline_delivery_protocols": ["s3", "gcs"]
  }
}

バイヤーはアカウント同期時にプロトコルの希望を表明します。セラーはサポートしていれば希望のプロトコルでバケットをプロビジョニングします:

{
  "accounts": [{
    "brand": { "domain": "nova-brands.com" },
    "operator": "pinnacle-media.com",
    "billing": "operator",
    "preferred_reporting_protocol": "s3"
  }]
}

プロダクトは reporting_capabilities でサポートするケイデンスとメトリクスを宣言します:

{
  "reporting_capabilities": {
    "available_reporting_frequencies": ["daily"],
    "supports_webhooks": true,
    "available_metrics": ["impressions", "spend", "clicks"],
    "date_range_support": "date_range"
  }
}

オフライン配信では、セラーはアカウントごとにストレージをプロビジョニングし、帯域外でバイヤーに読み取りアクセスを付与します。セラーはアカウントごとに専用バケットを使っても、アカウントごとの prefix で分離した共有バケットを使ってもよく、いずれの場合もバイヤーは自分のアカウントのパス配下のデータにのみアクセスできます。複数の購買プラットフォームが同じブランドで動作する場合、それぞれが別個のアカウント（オペレーター/エージェントでスコープ）を得るため、データはプレフィックスで分離されます。バケットの場所は sync_accounts が返すアカウントオブジェクトに現れます:

{
  "account_id": "acc_pinnacle_001",
  "status": "active",
  "reporting_bucket": {
    "protocol": "s3",
    "bucket": "seller-reports",
    "prefix": "accounts/pinnacle/adcp",
    "region": "us-east-1",
    "format": "jsonl",
    "compression": "gzip",
    "file_retention_days": 30,
    "setup_instructions": "https://seller.example.com/docs/bucket-access"
  }
}

バイヤーは自分のスケジュールでバケットから読み取ります。セラーはプロダクトのレポート頻度でファイルをプッシュします。 配信方法がレポートの経路を決めます:

get_media_buy_delivery はすべての media_buy セラーの必須タスクです。セラーがどのプッシュ方法をサポートするかに関わらず、ポーリングは常にベースラインとして利用可能です。
reporting_delivery_methods に offline が含まれ、アカウントに reporting_bucket が存在する場合、セラーは詳細な配信データをバケットにもプッシュします。バッチ基盤を持つバイヤーは効率のためバケットから読むべきです。
バケット内のファイルは file_retention_days（reporting_bucket で宣言）の間保持されます。バイヤーはこのウィンドウ内にファイルを読まなければなりません。
get_media_buys は常に、ステータス・合計・ペーシングのスナップショットを持つメディアバイオブジェクトを返します。詳細なレポートではなくステータス確認に使ってください。

オフラインファイル配信では、パブリッシャーは JSON Lines (JSONL)、CSV、Parquet、Avro、ORC でレポートデータを提供できます。いずれも Webhook ペイロードのネスト構造を保つためバッチ処理に適しています。 JSONL と CSV は .jsonl.gz/.csv.gz のように gzip 圧縮してストレージと転送コストを削減できます。Parquet、Avro、ORC は内部圧縮を使うため、これらのフォーマットではトップレベルの compression フィールドは無視されます。

JSON Lines (JSONL)

1 行 1 メディアバイ（改行区切り JSON）。各行にレポート期間とパッケージレベルのデータを持つ 1 つのデリバリーオブジェクトが含まれます。ネスト構造を保持しつつ、行単位で簡単にパースできるためストリーミング処理に適しています。 Example JSONL file:

{"notification_type": "scheduled", "sequence_number": 5, "next_expected_at": "2024-02-06T08:00:00Z", "reporting_period": {"start": "2024-02-05T00:00:00Z", "end": "2024-02-05T23:59:59Z"}, "currency": "USD", "media_buy_id": "mb_001", "media_buy_id": "campaign_a", "status": "active", "totals": {"impressions": 50000, "spend": 1750.00, "clicks": 100, "ctr": 0.002}, "by_package": [{"package_id": "pkg_001", "impressions": 30000, "spend": 1050.00, "pacing_index": 0.95, "pricing_model": "cpm", "rate": 0.035, "currency": "USD"}, {"package_id": "pkg_002", "impressions": 20000, "spend": 700.00, "pacing_index": 0.98, "pricing_model": "cpm", "rate": 0.035, "currency": "USD"}]}
{"notification_type": "scheduled", "sequence_number": 5, "next_expected_at": "2024-02-06T08:00:00Z", "reporting_period": {"start": "2024-02-05T00:00:00Z", "end": "2024-02-05T23:59:59Z"}, "currency": "USD", "media_buy_id": "mb_002", "media_buy_id": "campaign_b", "status": "active", "totals": {"impressions": 200000, "spend": 9000.00, "clicks": 400, "ctr": 0.002}, "by_package": [{"package_id": "pkg_003", "impressions": 200000, "spend": 9000.00, "pacing_index": 1.02, "pricing_model": "cpm", "rate": 45.00, "currency": "USD"}]}
{"notification_type": "scheduled", "sequence_number": 5, "next_expected_at": "2024-02-06T08:00:00Z", "reporting_period": {"start": "2024-02-05T00:00:00Z", "end": "2024-02-05T23:59:59Z"}, "currency": "USD", "media_buy_id": "mb_003", "media_buy_id": "campaign_c", "status": "active", "totals": {"impressions": 75000, "spend": 3375.00, "clicks": 150, "ctr": 0.002}, "by_package": [{"package_id": "pkg_004", "impressions": 75000, "spend": 3375.00, "pacing_index": 0.96, "pricing_model": "cpcv", "rate": 0.045, "currency": "USD"}]}

CSV

For tabular analysis CSV files require unnesting nested arrays. Each record should be unnested to the by_package level, meaning one row per package with parent-level data (reporting period, media buy info, totals) duplicated. Example CSV structure:

notification_type,sequence_number,next_expected_at,reporting_period_start,reporting_period_end,currency,media_buy_id,media_buy_id,status,totals_impressions,totals_spend,totals_clicks,totals_ctr,by_package_package_id,by_package_impressions,by_package_spend,by_package_clicks,by_package_pacing_index,by_package_pricing_model,by_package_rate,by_package_currency
scheduled,5,2024-02-06T08:00:00Z,2024-02-05T00:00:00Z,2024-02-05T23:59:59Z,USD,mb_001,active,50000,1750.00,100,0.002,pkg_001,30000,1050.00,60,0.95,cpm,0.035,USD
scheduled,5,2024-02-06T08:00:00Z,2024-02-05T00:00:00Z,2024-02-05T23:59:59Z,USD,mb_001,active,50000,1750.00,100,0.002,pkg_002,20000,700.00,40,0.98,cpm,0.035,USD
scheduled,5,2024-02-06T08:00:00Z,2024-02-05T00:00:00Z,2024-02-05T23:59:59Z,USD,mb_002,active,200000,9000.00,400,0.002,pkg_003,200000,9000.00,400,1.02,cpm,45.00,USD
scheduled,5,2024-02-06T08:00:00Z,2024-02-05T00:00:00Z,2024-02-05T23:59:59Z,USD,mb_003,active,75000,3375.00,150,0.002,pkg_004,75000,3375.00,150,0.96,cpcv,0.045,USD

Parquet

For high-volume analytics Columnar format optimized for analytics workloads. Excellent compression ratios. Supports nested structures natively. Best for data warehouses and big data processing. Example Parquet schema:

{
  "type": "record",
  "name": "MediaBuyDelivery",
  "fields": [
    {"name": "notification_type", "type": "string"},
    {"name": "sequence_number", "type": "int"},
    {"name": "next_expected_at", "type": "string"},
    {"name": "reporting_period", "type": {
      "type": "record",
      "name": "ReportingPeriod",
      "fields": [
        {"name": "start", "type": "string"},
        {"name": "end", "type": "string"}
      ]
    }},
    {"name": "currency", "type": "string"},
    {"name": "media_buy_id", "type": "string"},
    {"name": "media_buy_id", "type": "string"},
    {"name": "status", "type": "string"},
    {"name": "totals", "type": {
      "type": "record",
      "name": "Totals",
      "fields": [
        {"name": "impressions", "type": "long"},
        {"name": "spend", "type": "double"},
        {"name": "clicks", "type": "long"},
        {"name": "ctr", "type": "double"}
      ]
    }},
    {"name": "by_package", "type": {
      "type": "array",
      "items": {
        "type": "record",
        "name": "PackageDelivery",
        "fields": [
          {"name": "package_id", "type": "string"},
          {"name": "impressions", "type": "long"},
          {"name": "spend", "type": "double"},
          {"name": "pacing_index", "type": "double"},
          {"name": "pricing_model", "type": "string"},
          {"name": "rate", "type": "double"},
          {"name": "currency", "type": "string"}
        ]
      }
    }}
  ]
}

Avro

スキーマリッチなストリーミングパイプライン向け スキーマを埋め込んだ行指向フォーマット。自己記述的で、リーダーは外部のスキーマファイルを必要としません。スキーマの進化（フィールドの追加/削除）を優雅に扱えます。Kafka と Hadoop のエコシステムで一般的。内部圧縮（snappy、deflate、zstd）を使用します。 Avro スキーマの例:

{
  "type": "record",
  "name": "MediaBuyDelivery",
  "namespace": "org.example.reporting",
  "fields": [
    {"name": "notification_type", "type": "string"},
    {"name": "sequence_number", "type": "int"},
    {"name": "next_expected_at", "type": "string"},
    {"name": "reporting_period", "type": {
      "type": "record",
      "name": "ReportingPeriod",
      "fields": [
        {"name": "start", "type": "string"},
        {"name": "end", "type": "string"}
      ]
    }},
    {"name": "currency", "type": "string"},
    {"name": "media_buy_id", "type": "string"},
    {"name": "status", "type": "string"},
    {"name": "totals", "type": {
      "type": "record",
      "name": "Totals",
      "fields": [
        {"name": "impressions", "type": "long"},
        {"name": "spend", "type": "double"},
        {"name": "clicks", "type": "long"},
        {"name": "ctr", "type": "double"}
      ]
    }},
    {"name": "by_package", "type": {
      "type": "array",
      "items": {
        "type": "record",
        "name": "PackageDelivery",
        "fields": [
          {"name": "package_id", "type": "string"},
          {"name": "impressions", "type": "long"},
          {"name": "spend", "type": "double"},
          {"name": "pacing_index", "type": "double"},
          {"name": "pricing_model", "type": "string"},
          {"name": "rate", "type": "double"},
          {"name": "currency", "type": "string"}
        ]
      }
    }}
  ]
}

ORC

Hive/Spark 分析向け Hadoop エコシステムのツール（Hive、Spark、Presto）での読み取り中心の分析に最適化された列指向フォーマット。述語プッシュダウン、組み込みインデックス、軽量圧縮（snappy、zlib、zstd）が I/O を削減します。struct と array 型を通じてネスト構造をサポートします。 ORC は Parquet と同じ論理スキーマを使います。データウェアハウスが Hive ネイティブなら ORC を、より広いツール互換性なら Parquet を選んでください。 File Structure: Each file contains one media buy delivery per line (JSONL), row (CSV/Parquet/ORC), or record (Avro). Files may contain:

Multiple media buy deliveries (one per line/row)
Multiple reporting periods for the same media buy (separate rows)
Multiple media buys (each with its own rows)

Processing Recommendations:

Process files in chronological order using file timestamps
Handle duplicate files gracefully (idempotent processing)
Validate file integrity using checksums if provided
Monitor for missing files and alert on gaps

オフライン配信のセキュリティ考慮事項

オフラインファイルは file_retention_days の間 at rest で存在するため、IAM ポリシーの設定ミスはテナントをまたいで過去のレポートを漏洩させます。一般的なセキュリティ管理が適用されます。オフライン固有の要件は次のとおりです:

アクセスは秘匿ではなく IAM レイヤーでスコープする。 バイヤーの読み取りアクセスは {bucket}/{prefix}/* にスコープされなければなりません（MUST。S3 のバケットポリシー条件、GCS の resource.name.startsWith(...) による条件付き IAM バインディング、またはプレフィックスにスコープした Azure SAS）。セラーがアカウントごとに一つのプレフィックス配下にしか書き込まない場合でも、バケット全体の読み取り付与は非適合です。
リストもスコープする。 プレフィックスのスコープは、オブジェクトレベルの操作（s3:GetObject）とリスト（s3:prefix 条件付きの s3:ListBucket）の両方をカバーしなければなりません（MUST）。GetObject をプレフィックスにスコープしつつ ListBucket を未スコープのままにするポリシーは、バイヤーが他テナントのプレフィックス名を列挙できてしまいます——そのオブジェクトへの読み取りアクセスがなくてもテナント分離の失敗です。GCS の storage.objects.list と Azure の list SAS 権限にも同じことが当てはまります。
アカウント終了時にアクセスを取り消す。 セラーが account.status の inactive・suspended・closed への遷移を出すとき、セラーは関連する認証情報の受け入れを停止しなければならず（MUST）、バイヤーはそのステータス変更を、自分側で対応する IAM の信頼を削除するトリガーとして扱うべきです（SHOULD）。廃止されたバケットに付与されたままのセラー IAM ロールは横展開のリスクです。

PII のスクラビング要件（上記参照）はオフラインファイルにも同様に適用されます——ファイルは at rest で蓄積するため、配信時ではなく収集レイヤーでスクラブしてください。 setup_instructions はセラー提供の URL です。これはオペレーター向けのドキュメントであり、エージェントが消費するコンテンツではありません。バイヤーエージェントはこの URL を自動取得してはならず（MUST NOT）、人間のオペレーターに提示すべきです（SHOULD）。実装が取得を選ぶ場合（例: オペレーターに見せる前に対象をプレビューする）、Webhook URL の SSRF 検証を適用し、取得したコンテンツは間接プロンプトインジェクションの防御なしに LLM コンテキストへ渡してはなりません（MUST NOT）——このフィールドのセラー制御のテキストは、認証情報のローテーション、請求の変更、下流エージェントの挙動の改変を指示しうる。

Data Reconciliation

get_media_buy_delivery API はすべてのキャンペーン指標の正式な信頼できる唯一の情報源です。 ポーリングは常にベースラインとして利用可能です。セラーがプッシュ型の配信（Webhook やオフラインバケット）もサポートする場合、それらの方法はタイムリーなデータを提供しますが、get_media_buy_delivery が照合の経路であり続けます。照合は あらゆるレポート配信方法 で重要です。

Webhooks: ネットワーク障害やサーキットブレーカーで欠落する場合があります
オフラインファイル: 遅延・破損・処理失敗の可能性があります
ポーリング: API 障害中にデータを欠損する場合があります
遅延データ: 初回レポートから 24〜48 時間以上後に届くインプレッションがある（全手段共通）

Reconciliation Process

バイヤーは定期的に配信データを API と照合し、精度を確認すべきです。 Recommended Reconciliation Schedule:

Hourly delivery: Reconcile via API daily
Daily delivery: Reconcile via API weekly
Monthly delivery: Reconcile via API at month end + 7 days
Campaign close: Always reconcile after campaign_end + attribution_window

Reconciliation Logic:

async function reconcileWebhookData(mediaBuyId, startDate, endDate) {
  // Get authoritative data from API
  const apiData = await adcp.getMediaBuyDelivery({
    media_buy_id: mediaBuyId,
    date_range: { start: startDate, end: endDate }
  });

  // Compare with webhook data in local database
  const webhookData = await db.getWebhookTotals(mediaBuyId, startDate, endDate);

  const discrepancy = {
    impressions: apiData.totals.impressions - webhookData.impressions,
    spend: apiData.totals.spend - webhookData.spend,
    clicks: apiData.totals.clicks - webhookData.clicks
  };

  // Acceptable discrepancy thresholds
  const impressionVariance = Math.abs(discrepancy.impressions) / apiData.totals.impressions;
  const spendVariance = Math.abs(discrepancy.spend) / apiData.totals.spend;

  if (impressionVariance > 0.02 || spendVariance > 0.01) {
    // Significant discrepancy (>2% impressions or >1% spend)
    console.warn(`Reconciliation discrepancy for ${mediaBuyId}:`, discrepancy);

    // Update local database with authoritative API data
    await db.updateCampaignTotals(mediaBuyId, apiData.totals);

    // Alert if discrepancy is unusually large
    if (impressionVariance > 0.10 || spendVariance > 0.05) {
      await alertOps(`Large reconciliation discrepancy detected`, {
        media_buy_id: mediaBuyId,
        webhook_totals: webhookData,
        api_totals: apiData.totals,
        discrepancy
      });
    }
  }

  return {
    status: impressionVariance < 0.02 ? 'reconciled' : 'discrepancy_found',
    api_data: apiData.totals,
    webhook_data: webhookData,
    discrepancy
  };
}

Why Discrepancies Occur:

Delivery failures: Webhooks missed, offline files corrupted, API timeouts during polling
Late-arriving data: Impressions attributed after initial reporting (all delivery methods)
Data corrections: Publisher adjusts metrics after initial reporting
Processing errors: Buyer-side failures to process delivered data
Timezone differences: Period boundaries may differ between delivery and API query

Source of Truth Rules:

For billing: Always use get_media_buy_delivery API at campaign end + attribution window
For real-time decisions: Use delivered data (webhook/file/poll) for speed, reconcile later
For discrepancies: API data wins, update local records accordingly
For audits: API provides complete historical data, delivered data is ephemeral

Best Practices:

Store webhook sequence_number to detect missed notifications
Run automated reconciliation daily for active campaigns
Alert on discrepancies >2% for impressions or >1% for spend
Use API data for all financial reporting and invoicing
Document reconciliation process for audit compliance

Late-Arriving Impressions

Ad serving data often arrives with delays due to attribution windows, offline tracking, and pipeline latency. Publishers declare expected_delay_minutes in reporting_capabilities:

Display/Video: Typically 4-6 hours
Audio: Typically 8-12 hours
CTV: May be 24+ hours

This represents when most data is available, not all data.

遅延データの扱い

過去の期間に遅延データが届いた場合、その期間を is_adjusted: true 付きで再送します。

{
  "notification_type": "adjusted",
  "reporting_period": {
    "start": "2024-02-01T00:00:00Z",
    "end": "2024-02-01T23:59:59Z"
  },
  "media_buy_deliveries": [{
    "media_buy_id": "mb_001",
    "is_adjusted": true,
    "totals": {
      "impressions": 51000,  // Updated total (was 50000)
      "spend": 1785          // Updated spend (was 1750)
    }
  }]
}

バイヤー側の処理:

function processWebhook(webhook) {
  for (const delivery of webhook.media_buy_deliveries) {
    if (delivery.is_adjusted) {
      // Replace entire period with updated totals
      db.replaceCampaignPeriod(
        delivery.media_buy_id,
        webhook.reporting_period,
        delivery.totals
      );
    } else {
      // Normal new period data
      db.insertCampaignPeriod(delivery.media_buy_id, webhook.reporting_period, delivery.totals);
    }
  }
}

調整済み期間を送るべき場合:

大きなデータ変化（インプレッション ±2% 超、または消化額 ±1% 超）
campaign_end + attribution_window 時点での最終照合
データ品質修正

ポーリングのみの場合、バイヤーは API 結果を時系列で比較することで調整を検知します。

Webhook の信頼性

レポート Webhook は AdCP 標準の信頼性パターンに従います。

At-least-once 配信: 同じ通知が複数回届く場合があります
ベストエフォート順序: 順不同で届く場合があります
タイムアウトとリトライ: 配信失敗時は回数を限定して再試行

実装の詳細は Webhooks を参照してください。

最適化の戦略

コンバージョン最適化

メディアバイパッケージに最適化目標を設定することで、特定の成果（目標 CPC、CPV、ROAS、CPA など）に向けた配信を促します。指標目標（クリック、視聴数）はイベント設定不要で機能します。イベント目標にはイベントソースの設定とコンバージョンデータが必要です。完全なセットアップ手順は Conversion Tracking を、optimization_goals 配列のリファレンスは Optimization Goals を参照してください。

予算最適化

update_media_buy で成果の高低パッケージ間での 再配分
ペーシング調整 — even、asap、front_loaded の配信方式を切り替え
消化効率 — パッケージ間でのコンバージョンあたりコストを比較し、優れたパッケージへ予算をシフト

クリエイティブ最適化

get_media_buy_delivery でクリエイティブ別の内訳を使った パフォーマンス分析
A/B テスト — creative_assignments でウェイト付き複数クリエイティブを割り当て
リフレッシュ戦略 — 疲弊を防ぐため、ライブラリ対応のセラーには sync_creatives で、インライン専用のセラーには update_media_buy のインライン packages[].creatives でクリエイティブを交換

ターゲティング改善

地理的最適化 — 地域別配信データに基づき targeting_overlay を調整
フリクエンシー管理 — 配信パターンに基づき frequency_cap（クールダウン抑制または max_impressions/per/window 上限）をチューニング

パフォーマンスフィードバックループ

ビジネス成果をパブリッシャーにフィードバックすることで、AI 主導の最適化を可能にします。詳細な API は provide_performance_feedback を参照してください。

パフォーマンスインデックスの概念

相対的な成果を示す正規化スコア。

0.0 = 測定可能な価値や影響なし
1.0 = ベースライン/想定パフォーマンス
> 1.0 = 平均以上（例: 1.45 は 45% 改善）
< 1.0 = 平均未満（例: 0.8 は 20% 低下）

パフォーマンスデータの共有

バイヤーは provide_performance_feedback タスクを使って任意で成果を共有できます。

{
  "media_buy_id": "gam_1234567890",
  "measurement_period": {
    "start": "2024-01-15T00:00:00Z",
    "end": "2024-01-21T23:59:59Z"
  },
  "performance_index": 1.35,
  "metric_type": "conversion_rate"
}

サポートされる指標

overall_performance: キャンペーン全体の成果
conversion_rate: クリック後/視聴後コンバージョン率
brand_lift: ブランド認知/想起のリフト
click_through_rate: クリエイティブのエンゲージメント
completion_rate: 動画/音声の完了率
viewability: ビューアブル率
brand_safety: ブランドセーフティ順守
cost_efficiency: 望む成果あたりのコスト

パブリッシャーが活用する方法

パブリッシャーはパフォーマンスインデックスを活用して:

配信最適化: 高成果セグメントへ配信をシフト
価格調整: 実証された価値に基づき CPM を更新
プロダクト改善: 成果パターンに基づきプロダクト定義を磨く
アルゴリズム強化: 実際のビジネス成果で ML モデルを学習

プライバシーとデータ共有

パフォーマンス共有は任意でありバイヤーが制御します
集計されたパフォーマンス傾向はプラットフォーム全体の改善に利用される場合があります
個別キャンペーンの詳細はバイヤーとパブリッシャーの関係内に留まる

ディメンション内訳

配信データは各パッケージ内で複数のディメンションに分解できます。バイヤーは get_media_buy_delivery の reporting_dimensions パラメーターで特定の内訳を指定します。各内訳は by_package 項目内に by_* 配列として現れ、by_creative と同じ構成パターンに従います。

ディメンション	内訳フィールド	必須フィールド	追加フィールド	ケイパビリティ宣言
地理	`by_geo`	`geo_level`, `geo_code`, `impressions`, `spend`	`system`, `country`, `geo_name`	`supports_geo_breakdown`
デバイスタイプ	`by_device_type`	`device_type`, `impressions`, `spend`	—	`supports_device_type_breakdown`
デバイスプラットフォーム	`by_device_platform`	`device_platform`, `impressions`, `spend`	—	`supports_device_platform_breakdown`
オーディエンス	`by_audience`	`audience_id`, `audience_source`, `impressions`, `spend`	`audience_name`	`supports_audience_breakdown`
プレースメント	`by_placement`	`placement_id`, `impressions`, `spend`	`publisher_domain`, `placement_name`	`supports_placement_breakdown`

各内訳エントリは delivery-metrics（clicks、conversions、その他の任意メトリクス）のすべてのフィールドに加え、ディメンション固有のフィールドを継承します。各エントリには必須フィールド列に示したフィールドが必要です。どのディメンションが利用可能かはプロダクトの reporting_capabilities で確認してください。同じセラーの異なるプロダクトが異なる内訳をサポートしうるため、プロダクトレベルのケイパビリティが権威的です。supports_geo_breakdown は利用可能なレベルとシステムを宣言するオブジェクトで、この表の他のケイパビリティ宣言はブール値のフラグです。supports_geo_breakdown 内では、country と region はブール値で、metro は metro-system の値でキー付けされ、ネイティブな postal_area は ISO 3166-1 alpha-2 の国でキー付けされ、国ローカルな postal-system 値の配列を持ちます。geo の行は geo_level: "metro" と "postal_area" で system を使います。ネイティブな郵便の行は country も含みます。非推奨の国融合型の郵便システムは互換性のため引き続き受け付けられます。プレースメントのアイデンティティはパブリッシャースコープです。プレースメント行は publisher_domain（プロダクトの placements[] エントリ由来のパブリッシャー名前空間）を運んでよく（MAY）、それが存在する場合、バイヤーはマルチパブリッシャープロダクトについて {publisher_domain, placement_id} を安定したプレースメントのアイデンティティとして扱えます。セラーは、プロダクトのプレースメントがそれを運ぶ場合は常に publisher_domain を出すべきです（SHOULD。kind: "publisher_ref" では常に真）。セラーがそれを省略してよいのは、セラーエージェント自身のドメインが名前空間であるレガシーな単一パブリッシャーの文脈における kind: "seller_inline" のプレースメントに限られます。publisher_domain が省略された場合、バイヤーはそのレガシーな単一パブリッシャーの文脈でのみ placement_id をセラーエージェント自身のパブリッシャードメインに対して解釈してよく（MAY）、それ以外ではパブリッシャー横断のプレースメントキーを推測すべきではありません。各プレースメントは正確に一つのパブリッシャー名前空間に属するため、publisher_domain は単一値です。内訳はオプトイン方式で、明示的に指定しない限りディメンションデータは返されません。指定したディメンションをサポートしていないセラーはそれを黙って省略します。各内訳配列には limit を超える追加行の有無を示す by_*_truncated ブール値が付属します。

ターゲティングの一貫性

レポーティングは AdCP の Targeting アプローチに沿って設計されており、以下を可能にします。

キャンペーンライフサイクル全体での 一貫した分析
ターゲティングパラメーターによる きめ細かい内訳
ポートフォリオ最適化のための キャンペーン横断インサイト

Target → Measure → Optimize

ターゲティングとレポーティングの一貫性が好循環を生み出します。

Target: ブリーフとオーバーレイでオーディエンスを定義（例:「主要都市圏のモバイルユーザー」）
Measure: 同じ属性でレポート（デバイスタイプと地域別のパフォーマンスを追跡）
Optimize: 配信改善にパフォーマンスをフィードバック（高成果セグメントへ予算をシフト）

標準指標

すべてのプラットフォームがサポートしなければなりませんコア指標:

impressions: 広告表示数
spend: 通貨建て消化額
clicks: クリック数（該当する場合）
ctr: クリック率（clicks/impressions）

任意のオプション指標:

conversions: クリック後/視聴後コンバージョン
viewability: ビューアブルインプレッションの割合
completion_rate: 動画/音声の完了率
engagement_rate: プラットフォーム固有のエンゲージメント指標

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

プラットフォームによってレポーティング/最適化の機能は異なります。

Google Ad Manager

包括的なディメンション別レポーティング、リアルタイム/ヒストリカルデータ、高度なビューアビリティ指標

Kevel

リアルタイムレポーティング API、カスタム指標サポート、柔軟な集計オプション

Triton Digital

音声固有指標（完了率、スキップ率）、局別パフォーマンスデータ、デイパート分析

高度な分析

キャンペーン横断分析

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

予測インサイト

ヒストリカルデータに基づく パフォーマンス予測
AI 分析による 最適化レコメンデーション
プロアクティブな調整のための トレンド予測

レスポンスタイム

最適化オペレーションには予測可能なタイミングがあります。

デリバリーレポート: 約 60 秒（データ集計）
キャンペーン更新: 分〜日単位（変更内容による）
パフォーマンス分析: 約 1 秒（キャッシュ済み指標）

ベストプラクティス

頻繁にレポートする: 定期的なレポーティングが最適化機会を増やす
ペーシングを追跡する: 目標に対する配信を監視し、過不足を防ぐ
パターンを分析する: ディメンション横断でパフォーマンストレンドを探す
レイテンシを考慮する: 一部の指標には帰属遅延がある場合があります
指標を正規化する: パフォーマンス比較に一貫したベースラインを使用します

メディアバイライフサイクルとの統合

最適化/レポーティングはアクティブなキャンペーン全期間を通じて継続するフェーズです。

作成との連携: 学習を活かして将来のキャンペーン設定を改善
更新の指針: キャンペーン変更のためのデータドリブンな意思決定
スケールの実現: 実証された戦略を類似キャンペーンへ展開
AI へのフィード: パフォーマンスデータが自動最適化を向上

​主な最適化タスク

​デリバリーレポート

​キャンペーン更新

​最適化ワークフロー

​メトリクスのライフサイクル

​標準メトリクスのフロー（例: clicks、viewable_rate）

​ベンダー証明メトリクスのフロー（例: Adelaide アテンション、Scope3 排出量、Kantar ブランドリフト）

​なぜ両方のフローが重要か

​レイヤー間で必要な整合性

​実例: Adelaide アテンションのエンドツーエンド

​パフォーマンス監視

​リアルタイム指標

​ヒストリカル分析

​アラート/通知

​配信方法

​Webhook ベースのレポーティング

​Webhook 設定

​サポートされる頻度

​提供可能な指標

​ベンダー定義メトリクス

​パブリッシャーのコミットメント

​Webhook ペイロード

​タイムゾーンの扱い

​遅延レポーティング

​計測成熟ウィンドウ

​Webhook の集約

​部分的な失敗の扱い

​プライバシーとコンプライアンス

GDPR/CCPA 向けの PII マスキング

​実装ベストプラクティス

​Webhook Health Monitoring

​オフラインファイル配信ベースのレポーティング

​JSON Lines (JSONL)

​CSV

​Parquet

​Avro

​ORC

​オフライン配信のセキュリティ考慮事項

​Data Reconciliation

​Reconciliation Process

​Late-Arriving Impressions

​遅延データの扱い

​Webhook の信頼性

​最適化の戦略

​コンバージョン最適化

​予算最適化

​クリエイティブ最適化

​ターゲティング改善

​パフォーマンスフィードバックループ

​パフォーマンスインデックスの概念

​パフォーマンスデータの共有

​サポートされる指標

​パブリッシャーが活用する方法

​プライバシーとデータ共有

​ディメンション内訳

​ターゲティングの一貫性

​Target → Measure → Optimize

​標準指標

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

​Google Ad Manager

​Kevel

​Triton Digital

​高度な分析

​キャンペーン横断分析

​予測インサイト

​レスポンスタイム

​ベストプラクティス

​メディアバイライフサイクルとの統合

​関連ドキュメント