Skip to main content

​
カタログの移行

AdCP 3.0 は promoted_offerings クリエイティブアセットタイプと、メディアバイとクリエイティブマニフェストの promoted_offering 文字列フィールドを削除します。カタログは独自の同期タスク、フォーマットレベルの要件、コンバージョンイベント整合を持つファーストクラスのプロトコルオブジェクトになりました。

​
変更内容

v2 フィールドv3 フィールド変更タイプ
promoted_offerings（クリエイティブアセットタイプ）クリエイティブマニフェスト assets の catalog アセット置き換え
promoted_offering（メディアバイの文字列）削除削除
promoted_offering（クリエイティブマニフェストの文字列）assets の catalog アセット置き換え
カタログ同期なしsync_catalogs タスク新規
フォーマットカタログ要件なしFormat assets の catalog アセットタイプ新規
カタログイベントリンクなしCatalog の conversion_events新規

​
クリエイティブマニフェスト

​
変更内容

v2 では、カタログデータは creative_manifest.assets 内の promoted_offerings オブジェクトとして埋め込まれており、ブランドアイデンティティ、インラインオファリング、SI エージェント URL がまとめられていました。 v3 では、ブランドアイデンティティはタスク（build_creative、sync_creatives）のファーストクラスパラメーターとなり、カタログはマニフェストの assets の catalog アセットタイプとして含まれます。

​
変更前（v2）

{
  "creative_id": "product-carousel",
  "format_id": {
    "agent_url": "https://creatives.example.com",
    "id": "product_carousel"
  },
  "assets": {
    "promoted_offerings": {
      "brand": {
        "domain": "acmecorp.example.com"
      },
      "offerings": [
        {
          "offering_id": "winter-sale",
          "name": "Winter Sale Collection",
          "description": "50% off all winter items"
        }
      ]
    }
  }
}

​
変更後（v3）

{
  "$schema": "/schemas/core/creative-manifest.json",
  "format_id": {
    "agent_url": "https://creatives.example.com",
    "id": "product_carousel"
  },
  "assets": {
    "product_catalog": {
      "type": "product",
      "catalog_id": "winter-products"
    }
  }
}
主な違い:
  • ブランドアイデンティティ はクリエイティブアセットに埋め込まれるのではなく、タスクの brand パラメーターから来ます
  • カタログ はロール名（例: product_catalog）をキーとして assets マップの catalog アセットタイプになります
  • カタログはインラインで埋め込む代わりに catalog_id で同期データを参照する（ただしシンプルなケースではインラインアイテムもまだサポートされています）

​
メディアバイ

​
変更内容

promoted_offering 文字列フィールドはメディアバイオブジェクトから削除されました。何が宣伝されているかは、get_products/create_media_buy の brief と、クリエイティブのカタログ参照を通じて表現されます。

​
変更前（v2）

{
  "media_buy_id": "mb_123",
  "promoted_offering": "Winter Sale Collection",
  "status": "draft",
  "total_budget": {
    "amount": 10000,
    "currency": "USD"
  },
  "packages": []
}

​
変更後（v3）

{
  "media_buy_id": "mb_123",
  "status": "draft",
  "total_budget": {
    "amount": 10000,
    "currency": "USD"
  },
  "packages": []
}
レポートや表示目的で promoted_offering を使用していた場合、そのコンテキストは以下から得られます:
  • get_products と create_media_buy の brief フィールド
  • タスクの brand パラメーター
  • クリエイティブマニフェスト assets のカタログアセット

​
カタログの同期（v3 の新機能）

sync_catalogs タスクを使うと、バイヤーはクリエイティブを送信する前にカタログデータをセラーにプッシュできます。これはクリエイティブアセット内に製品データを埋め込むパターンを置き換える。 主な機能:
  • カタログごとの結果を持つバルク同期
  • 非同期承認ワークフロー（working、input-required、submitted）
  • カタログアイテムごとの承認/拒否を持つアイテムレベルレビュー
  • 探索モード — catalogs フィールドを省略して既存の同期済みカタログを確認します
  • バリデーションモード — strict、lenient、dry_run

​
ワークフロー

list_creative_formats → catalog アセットを確認 → sync_catalogs → catalog アセット付きで sync_creatives
  1. フォーマットの assets の catalog アセットタイプを通じて、フォーマットが必要とするカタログを発見します
  2. sync_catalogs を使ってそれらのカタログを同期します
  3. セラーがレビューを必要とする場合は承認を待つ
  4. 同期済みの catalog_id を参照するクリエイティブを送信します

カタログドキュメント

すべての13カタログタイプ、同期ワークフロー、アイテムレベルレビューを含む完全リファレンス。

​
フォーマットカタログ要件（v3 の新機能）

フォーマットは assets 配列の catalog アセットタイプとしてカタログニーズを宣言する: 
{
  "assets": [
    {
      "item_type": "individual",
      "asset_id": "product_catalog",
      "asset_type": "catalog",
      "required": true,
      "requirements": {
        "catalog_type": "product",
        "min_items": 3,
        "required_fields": ["name", "price", "image_url"]
      }
    }
  ]
}
フォーマット宣言は asset_type: "catalog" を使用し、以下を含む requirements オブジェクトを持ちます:
フィールドタイプ説明
catalog_typestring必須。カタログタイプ（例: product、store、job）
min_itemsintegerカタログが含まなければなりません最低アイテム数
max_itemsintegerフォーマットがレンダリングできる最大アイテム数
required_fieldsstring[]すべてのアイテムに存在しなければなりませんフィールド
feed_formatsstring[]受け付けるフィードフォーマット（例: google_merchant_center、linkedin_jobs）
これは、フォーマットが assets に promoted_offerings を暗黙的に必要としていた v2 のパターンを置き換える — 要件は明示的で発見可能になりました。

​
クリエイティブエージェントの移行

フォーマット定義を読んでカタログ要件を決定するクリエイティブエージェントは、カタログスロットを発見・充足する方法を変更する必要があります。 変更前（v2） — 専用の catalog_requirements フィールドを確認: 
// v2: カタログ要件は別のトップレベル配列だった
for (const req of format.catalog_requirements) {
  const catalogType = req.catalog_type;
  const minItems = req.min_items;
}
変更後（v3） — assets 配列を反復し、asset_type でフィルタリング: 
// v3: カタログは他のアセットと同様にアセットである
const catalogAssets = format.assets.filter(a => a.asset_type === "catalog");
for (const slot of catalogAssets) {
  const catalogType = slot.requirements.catalog_type;
  const minItems = slot.requirements.min_items;
  const slotId = slot.asset_id; // manifest.assets のキーとして使用
}
マニフェストを構築するとき、カタログアセットはフォーマット定義の asset_id でキー付けされます: 
{
  "assets": {
    "product_catalog": {
      "type": "product",
      "catalog_id": "winter-products"
    }
  }
}
フォーマットの assets 配列からの asset_id（例: product_catalog）がマニフェストの assets オブジェクトのキーになります。

​
コンバージョンイベント整合（v3 の新機能）

カタログはアイテムのコンバージョンを表すイベントタイプを宣言する: 
{
  "catalog_id": "job-feed",
  "type": "job",
  "content_id_type": "job_id",
  "conversion_events": ["submit_application", "complete_registration"]
}
これはカタログをコンバージョントラッキングシステムにリンクします。カタログアイテムに一致する content_ids を持つ log_event が送信されると、プラットフォームはどのイベントをアトリビュートするかを知ります。 content_id_type フィールドは content_ids 値が表す識別子タイプを宣言します。バーティカルカタログの場合、これはアイテムの正規 ID フィールド（job_id、hotel_id など）に一致します。プロダクトカタログの場合、クロスリテーラーマッチングのために sku と gtin を区別します。カスタム識別子スキームを使用する場合は省略します。
カタログタイプ典型的なコンバージョンイベント
productpurchase、add_to_cart
hotelpurchase（予約）
flightpurchase（予約）
jobsubmit_application
vehiclelead、schedule
real_estatelead、schedule
educationsubmit_application、complete_registration
destinationpurchase（予約）

コンバージョンイベント

カタログイベント整合の完全ドキュメント。

​
get_products の product_selectors がカタログに置き換えられました

get_products の product_selectors フィールドは catalog に置き換えられました。PromotedProducts スキーマは削除されました。

​
変更前

{
  "brand": { "domain": "acmecorp.com" },
  "product_selectors": {
    "manifest_gtins": ["00013000006040"],
    "manifest_tags": ["organic"]
  }
}

​
変更後

{
  "brand": { "domain": "acmecorp.com" },
  "catalog": {
    "type": "product",
    "gtins": ["00013000006040"],
    "tags": ["organic"]
  }
}

​
フィールドマッピング

古い（product_selectors）新しい（catalog）
manifest_gtinsgtins
manifest_skusids
manifest_tagstags
manifest_categorycategory
manifest_queryquery

​
レスポンスの変更

  • product_selectors_applied は catalog_applied になりました
  • catalog_match.matched_skus は catalog_match.matched_ids になりました

​
Product の新フィールド

  • catalog_types — このプロダクトがサポートするカタログタイプの配列（例: ["product"]、["job", "offering"]）
  • catalog_match.matched_ids — 汎用アイテム ID マッチ（matched_skus を置き換え）
  • catalog_match.matched_count — マッチしたアイテムの数

​
パッケージのカタログ

パッケージはカタログ主導のキャンペーンのための catalog フィールドを受け付けるようになりました。1つの予算エンベロープがカタログ全体を宣伝し、プラットフォームがアイテム間の配信を最適化します。

​
店舗キャッチメントターゲティング

targeting_overlay は store_catchments をサポートするようになった — 近接ターゲティングのために同期済みの店舗カタログを参照します。

​
カタログアイテムごとの配信

get_media_buy_delivery はカタログ主導のキャンペーンのためにパッケージ内に by_catalog_item 内訳を含むようになりました。

​
移行ステップ

1

クリエイティブアセットから promoted_offerings を削除する

creative_manifest.assets から promoted_offerings オブジェクトを削除します。ブランドアイデンティティは brand タスクパラメーターを通じて提供されるようになりました。
2

クリエイティブマニフェストにカタログアセットを追加する

カタログアイテムをレンダリングするクリエイティブ（製品カルーセル、店舗ロケーターなど）については、マニフェストの assets マップにカタログアセットを追加します。各カタログアセットは type と catalog_id を持つカタログオブジェクト（例: { "type": "product", "catalog_id": "winter-products" }）だ。
3

メディアバイから promoted_offering を削除する

create_media_buy リクエストから promoted_offering 文字列を削除します。宣伝するものを説明するために brief フィールドを使用します。
4

カタログ要件を発見する

list_creative_formats を呼び出し、各フォーマットの assets の catalog アセットタイプを確認して、必要なカタログタイプとフィールドを理解します。
5

クリエイティブを送信する前にカタログを同期する

sync_catalogs タスクを使ってカタログデータをセラーにプッシュします。セラーがレビューを必要とする場合は非同期承認を処理します。
6

アトリビューションのためにコンバージョンイベントとコンテンツ ID タイプを追加する

カタログに conversion_events を含めてカタログアイテムをコンバージョントラッキングセットアップにリンクします。イベントの content_ids を照合する識別子タイプ（例: sku、gtin、job_id）を宣言するために content_id_type を追加します。
7

v3 スキーマに対して検証する

クリエイティブマニフェスト、メディアバイ、カタログオブジェクトが v3 スキーマに対して検証されることを確認します。
関連: チャンネル | 価格 | ジオターゲティング | クリエイティブ | アトリビューション | AdCP 3.0 概要