> ## 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.
# カタログ
> AdCP のカタログはプラットフォーム全体で広告レンダリングにアイテムを提供する型付きデータフィードです。
# カタログ
カタログはセラーがブランドに優れた成果を提供できるよう渡すすべての材料です。EC ブランドはプロダクトカタログ（SKU、価格、画像）をプッシュして、プラットフォームがスポンサードプロダクトのカルーセルを構築できるようにします。旅行広告主はフライト、ホテル、目的地ガイドをプッシュします。雇用主は求人をプッシュします。小売業者は店舗の場所とリアルタイムの在庫をプッシュします。ブランドはオファリング、サービス、季節のキャンペーンをプッシュします。
材料が豊かであるほど、結果は良くなります。特に AI プラットフォームでは、カタログデータがクリエイティブのインプットそのものになる — プラットフォームの LLM は事前に構築されたバナーを配信するのではなく、プロダクト、オファリング、ブランドコンテキストから広告を組み立てる。しかしカタログは AI メディア以外でも重要だ: リテールメディアネットワーク、コマースプラットフォーム、ネイティブ広告ネットワークなど、データから動的に広告を組み立てるセラーはすべて、豊かなカタログフィードから恩恵を受けます。
カタログは測定とも直接つながっています。ストアカタログをプッシュすると、セラーは広告配信と店舗レベルの来客トラフィックを関連付けられます。プロダクトカタログをプッシュすると、リテールメディアネットワークは購買アトリビューションのループを閉じられます。より優れたクリエイティブを可能にする同じデータが、より優れた測定も可能にします。
### 仕組み
* **フォーマットが宣言する** — `assets` 配列内の `catalog` アセットタイプとして必要なカタログタイプを宣言します
* **バイヤーが同期する** — `sync_catalogs` を通じてセラーアカウントにカタログフィードをプッシュし、プラットフォームがレビューと承認を行います
* **クリエイティブが参照する** — マニフェストの `assets` マップ内でアイテムをインラインに埋め込む代わりに、`catalog_id` で同期済みカタログを参照します
## どのカタログタイプを使うべきか
広告するものに合ったカタログタイプを選ぶ。
| 広告するもの | カタログタイプ | アイテムスキーマ | 必須フィールド |
| ------------------------- | ------------- | --------------------------------------------------------------------- | --------------------------------------------- |
| 物理的な商品 / EC の SKU | `product` | *(既存フィード — Google Merchant、Shopify など)* | フィードフォーマットによる |
| 求人 / 採用 | `job` | [JobItem](/docs/creative/catalog-schemas#job-catalog) | `job_id`、`title`、`company_name`、`description` |
| ホテル / 宿泊施設 | `hotel` | [HotelItem](/docs/creative/catalog-schemas#hotel-catalog) | `hotel_id`、`name`、`location` |
| 車両（新車または中古車） | `vehicle` | [VehicleItem](/docs/creative/catalog-schemas#vehicle-catalog) | `vehicle_id`、`title`、`make`、`model`、`year` |
| フライト / 航空旅行 | `flight` | [FlightItem](/docs/creative/catalog-schemas#flight-catalog) | `flight_id`、`origin`、`destination` |
| 不動産物件 | `real_estate` | [RealEstateItem](/docs/creative/catalog-schemas#real-estate-catalog) | `listing_id`、`title`、`address` |
| 大学プログラム / コース | `education` | [EducationItem](/docs/creative/catalog-schemas#education-catalog) | `program_id`、`name`、`school` |
| 旅行目的地 | `destination` | [DestinationItem](/docs/creative/catalog-schemas#destination-catalog) | `destination_id`、`name` |
| モバイルアプリ | `app` | [AppItem](/docs/creative/catalog-schemas#app-catalog) | `app_id`、`name`、`platform` |
| 店舗の場所 | `store` | [StoreItem](#stores) | `store_id`、`name`、`location` |
| キャンペーン、サービス、イベント、アセットグループ | `offering` | [Offering](#offerings) | `offering_id`、`name` |
| 場所ごとの在庫水準 | `inventory` | *(既存フィードフォーマット)* | フィードフォーマットによる |
| セール、お得情報、価格設定 | `promotion` | *(既存フィードフォーマット)* | フィードフォーマットによる |
各バーティカルタイプ（job から app）は定義された AdCP スキーマを持ち、フィールドテーブルと開始テンプレートを含む例については[カタログアイテムスキーマ](/docs/creative/catalog-schemas)ページを参照。構造的タイプ（product、inventory、promotion）は `feed_format` と `feed_field_mappings` を通じて既存のフィードフォーマットにマッピングするフリーフォームスキーマを使用します。
## sync\_catalogs の位置づけ
`sync_catalogs` は**バイヤーからセラーへ**のタスクです。バイヤーはカタログフィードをセラーのアカウントにプッシュし、セラーはキャンペーンで使用される前にレビューと承認を行います。
### アクター
| アクター | 役割 |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| **バイヤー** | `sync_catalogs` を呼び出してセラーアカウントにカタログフィードをプッシュします。フィードデータ（プロダクト URL、インラインアイテム、在庫フィード）を所有します。 |
| **セラー** | カタログを受け取り、アイテムを検証し、コンテンツポリシーレビューを実施し、アイテムごとの承認状態を返します。他のソース（例: 小売業者のコマースプラットフォーム）からの既存カタログを持っている場合もあります。 |
| **オーケストレーター** | シーケンスを調整する — フォーマット要件を発見し、カタログを同期し、それらを参照するクリエイティブを提出します。 |
### ライフサイクル上の位置
`sync_catalogs` はフォーマット発見とクリエイティブ提出の間に位置します。バイヤーは同期前にフォーマットが必要とするカタログタイプを知る必要があり、クリエイティブが参照する前に承認されたカタログが必要です。
```mermaid theme={null}
sequenceDiagram
participant B as Buyer
participant S as Seller
rect rgb(240, 248, 255)
Note over B,S: 1. Discovery
B->>S: list_creative_formats
S->>B: Formats with catalog asset types
end
rect rgb(240, 255, 240)
Note over B,S: 2. Catalog sync
B->>S: sync_catalogs (product feed, inventory, stores...)
S->>B: Per-catalog results with item-level review
end
rect rgb(245, 240, 255)
Note over B,S: 3. Creative submission
B->>S: sync_creatives (catalog assets reference synced catalog_id)
S->>B: Creative approval status
end
rect rgb(255, 250, 240)
Note over B,S: 4. Campaign launch
B->>S: create_media_buy (packages reference creatives)
S->>B: Campaign status
end
```
これは[アカウント状態](/docs/building/by-layer/L2/account-state)に記載されているのと同じ依存関係の順序だ: `sync_catalogs` → `sync_creatives` → `create_media_buy`。
### sync\_catalogs とインラインの使い分け
すべてのワークフローが `sync_catalogs` を必要とするわけではありません。以下の場合に使用します:
* **プラットフォームレビューが必要** — コンテンツポリシーチェックを通過するプロダクトカタログ（Google Merchant Center のようなもの）
* **フィードが頻繁に変更される** — URL を指定してプラットフォームがスケジュールに従って再フェッチできるようにします
* **複数のクリエイティブが同じフィードを共有する** — 一度同期して、多くのクリエイティブから `catalog_id` で参照します
* **セラーがすでにデータを持っている可能性がある** — ディスカバリーモードを使用してアカウントに既に存在するものを確認します
少数のアイテムを含むシンプルなキャンペーンの場合、クリエイティブの `assets` マップ内のアセットとしてインラインカタログを使用することで十分だ — 同期ステップは不要。
## カタログタイプ
カタログタイプは2つのカテゴリに分類されます: データの役割を説明する**構造的**タイプと、業界固有のアイテムスキーマを定義する**バーティカル**タイプ。
### 構造的タイプ
| タイプ | アイテムスキーマ | 説明 |
| ----------- | -------------------------------------------------------------------------- | ------------------------------------------------ |
| `offering` | [Offering](https://adcontextprotocol.org/schemas/v3/core/offering.json) | AdCP Offering オブジェクト — キャンペーン、求人、イベント、サービス |
| `product` | *(既存フィードフォーマット)* | EC プロダクトエントリー（Google Merchant Center、Shopify など） |
| `inventory` | *(既存フィードフォーマット)* | 場所ごとのプロダクトの在庫と空き状況 |
| `store` | [StoreItem](https://adcontextprotocol.org/schemas/v3/core/store-item.json) | 住所とキャッチメントエリアを持つ物理的な場所 |
| `promotion` | *(既存フィードフォーマット)* | セール、お得情報、プロモーション価格 |
### バーティカルタイプ
各バーティカルタイプは定義された AdCP アイテムスキーマを持つため、フォーマットは `catalog_type: "hotel"` と宣言でき、プラットフォーム固有のドキュメントを参照することなく両側が必須フィールドを把握できます。
| タイプ | アイテムスキーマ | マッピング先 |
| ------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `hotel` | [HotelItem](https://adcontextprotocol.org/schemas/v3/core/hotel-item.json) | Google Hotel Center、Meta ホテルカタログ |
| `flight` | [FlightItem](https://adcontextprotocol.org/schemas/v3/core/flight-item.json) | Google DynamicFlightsAsset、Meta フライトカタログ |
| `job` | [JobItem](https://adcontextprotocol.org/schemas/v3/core/job-item.json) | LinkedIn Jobs XML、Google DynamicJobsAsset、schema.org JobPosting |
| `vehicle` | [VehicleItem](https://adcontextprotocol.org/schemas/v3/core/vehicle-item.json) | Meta Automotive Inventory、Microsoft Auto Inventory フィード |
| `real_estate` | [RealEstateItem](https://adcontextprotocol.org/schemas/v3/core/real-estate-item.json) | Google DynamicRealEstateAsset、Meta 住宅物件カタログ |
| `education` | [EducationItem](https://adcontextprotocol.org/schemas/v3/core/education-item.json) | Google DynamicEducationAsset、schema.org Course |
| `destination` | [DestinationItem](https://adcontextprotocol.org/schemas/v3/core/destination-item.json) | Meta 目的地カタログ、Google トラベル広告 |
| `app` | [AppItem](https://adcontextprotocol.org/schemas/v3/core/app-item.json) | Google App Campaigns、Apple Search Ads、Meta App Ads、TikTok App Campaigns、Snapchat App Install Ads |
## 型付きカタログアセット
バーティカルカタログアイテムは、オファリング型カタログと同じ `OfferingAssetGroup` 構造を使用する `assets` 配列をサポートします。これは具体的な問題を解決する: 標準カタログフィードには単一の `image_url` フィールドがあるが、Snap のホテル広告には 1080×1920 の縦型画像が必要で、ディスプレイバナーには 1920×1080 の横型ヒーロー画像が必要で、広告主のロゴは別のスロットに配置されます。型付きプールがなければ、クリエイティブエージェントはどのスロットにどの画像を使用するかを推測しなければなりません。
ロールでグループ化されたアセットを提供することで、各カタログアイテムは持っている画像を自己記述する:
```json theme={null}
{
"hotel_id": "grand-amsterdam",
"name": "Grand Hotel Amsterdam",
"price": { "amount": 289, "currency": "EUR", "period": "night" },
"image_url": "https://images.acmehotels.com/grand-amsterdam/hero.jpg",
"assets": [
{
"asset_group_id": "images_landscape",
"asset_type": "image",
"items": [
{ "url": "https://images.acmehotels.com/grand-amsterdam/landscape.jpg", "width": 1920, "height": 1080 }
]
},
{
"asset_group_id": "images_vertical",
"asset_type": "image",
"items": [
{ "url": "https://images.acmehotels.com/grand-amsterdam/vertical.jpg", "width": 1080, "height": 1920 }
]
},
{
"asset_group_id": "logo",
"asset_type": "image",
"items": [
{ "url": "https://images.acmehotels.com/logo.png", "width": 400, "height": 200 }
]
}
]
}
```
`asset_group_id` の語彙はプロトコルレベルでは標準化されていない — 各フォーマットはカタログアセットの `requirements` 内の `offering_asset_constraints` を通じて使用するグループ ID を定義します。一般的な慣例: `images_landscape`（16:9）、`images_vertical`（9:16）、`images_square`（1:1）、`logo`、`video`。動画プールは画像プールと並ぶ第一級のカタログアセットグループです——汎用の `video` プールに加えて、向き固有の `video_vertical`（9:16）と `video_horizontal`（16:9）のプール ID により、画像プールと同じ方法でフィードが向きごとの動画を運べます。
フォーマットは `field_bindings`（[フォーマットカタログ要件](#format-catalog-requirements) を参照）を使用して、テンプレートスロットがどのアセットグループにマッピングされるかを明示的に宣言します。
## Catalog オブジェクト
**スキーマ URL**: [`/schemas/core/catalog.json`](https://adcontextprotocol.org/schemas/v3/core/catalog.json)
```typescript test=false theme={null}
interface Catalog {
// Identity (required for sync_catalogs, optional for inline use)
catalog_id?: string; // Buyer's identifier — also used to reference synced catalogs
name?: string; // Human-readable name
// Type and sourcing
type: CatalogType; // Structural or vertical type
url?: string; // External feed URL
feed_format?: FeedFormat; // Feed format (google_merchant_center, facebook_catalog, shopify, linkedin_jobs, custom)
update_frequency?: string; // How often to re-fetch (realtime, hourly, daily, weekly)
items?: object[]; // Inline data — schema depends on catalog type
// Selectors
ids?: string[]; // Filter by item ID (offering_id or SKU)
gtins?: string[]; // Filter by GTIN (product type only)
tags?: string[]; // Filter by tag
category?: string; // Filter by category
query?: string; // Natural language filter
// Integration
conversion_events?: EventType[]; // Events to attribute to catalog items
content_id_type?: ContentIdType; // Identifier type for event attribution
// Feed normalization (for external feeds via url)
feed_field_mappings?: CatalogFieldMapping[]; // Map non-standard feed fields to AdCP schema
}
```
| フィールド | 型 | 必須 | 説明 |
| --------------------- | ---------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `catalog_id` | string | 同期時 | バイヤーの識別子。`sync_catalogs` に必須。クリエイティブで使用される場合、同期済みカタログを参照します。 |
| `name` | string | No | 人間が読める名前 |
| `type` | CatalogType | Yes | 構造的: `"offering"`、`"product"`、`"inventory"`、`"store"`、`"promotion"`。バーティカル: `"hotel"`、`"flight"`、`"job"`、`"vehicle"`、`"real_estate"`、`"education"`、`"destination"`、`"app"`。 |
| `url` | uri | No | 外部フィード URL。`items` と相互に排他的。 |
| `feed_format` | FeedFormat | No | 外部フィードのフォーマット（`google_merchant_center`、`facebook_catalog`、`shopify`、`linkedin_jobs`、`custom`） |
| `update_frequency` | string | No | 再フェッチスケジュール（`realtime`、`hourly`、`daily`、`weekly`） |
| `items` | object\[] | No | インラインカタログデータ。アイテムスキーマは `type` に依存する — 各バーティカルタイプに定義済みスキーマがある（HotelItem、JobItem など）。`url` と相互に排他的。 |
| `ids` | string\[] | No | 特定のアイテム ID（offering\_id または SKU）にフィルタリング |
| `gtins` | string\[] | No | GTIN でプロダクトカタログをフィルタリング（クロスリテーラーマッチング） |
| `tags` | string\[] | No | これらのタグを持つアイテムにフィルタリング（OR ロジック） |
| `category` | string | No | このカテゴリのアイテムにフィルタリング |
| `query` | string | No | 自然言語フィルター |
| `conversion_events` | EventType\[] | No | このカタログのアイテムにアトリビュートするイベントタイプ（例: 求人カタログの `submit_application`、プロダクトカタログの `purchase`） |
| `content_id_type` | ContentIdType | No | コンバージョンイベントの `content_ids` をカタログアイテムにマッチングするための識別子タイプ。値: `sku`、`gtin`、またはバーティカル固有の ID（`job_id`、`hotel_id` など）。カスタム識別子スキームの場合は省略。 |
| `feed_field_mappings` | CatalogFieldMapping\[] | No | 外部フィードの正規化ルール。非標準フィールド名、日付フォーマット、価格エンコーディング、画像 URL を AdCP カタログアイテムスキーマにマッピングします。[フィードフィールドマッピング](#feed-field-mappings)を参照。 |
## コンバージョンイベント
`conversion_events` フィールドはカタログアイテムとコンバージョントラッキングシステムの間に明示的なリンクを作成します。バイヤーがコンバージョンイベントを宣言してカタログを同期すると、プラットフォームはどのイベントをどのカタログアイテムにアトリビュートするかを認識します。イベントの `content_ids` フィールドは接続するアイテム ID を保持します。
`content_id_type` フィールドは `content_ids` 値がどの識別子タイプを表すかを宣言する — 例えば、クロスリテーラーのプロダクトマッチングには `gtin`、求人には `job_id`。これはプラットフォームにカタログアイテムのどのフィールドと照合するかを伝える。カスタム識別子スキームを使用する場合は `content_id_type` を省略します。
バーティカル別の自然なマッピング:
| カタログタイプ | 主なイベントタイプ |
| ------------- | -------------------------------------------- |
| `product` | `purchase`、`add_to_cart` |
| `hotel` | `purchase`（予約） |
| `flight` | `purchase`（予約） |
| `job` | `submit_application` |
| `vehicle` | `lead`、`schedule`（試乗） |
| `real_estate` | `lead`、`schedule`（内覧） |
| `education` | `submit_application`、`complete_registration` |
| `destination` | `purchase`（予約） |
| `app` | `app_install`、`app_launch` |
これらのマッピングはスキーマによって強制されるわけではない — バイヤーがカタログを同期する際に宣言します。`submit_application` と並んで `lead` イベントもトラッキングする求人カタログは完全に有効です。
```json theme={null}
{
"catalog_id": "job-feed",
"type": "job",
"content_id_type": "job_id",
"conversion_events": ["submit_application", "complete_registration"],
"url": "https://careers.acme.com/feed.xml",
"feed_format": "linkedin_jobs"
}
```
## カタログのソーシング
カタログデータを提供する方法は3つあり、それぞれ異なる成熟段階に適している:
### インラインアイテム
どのカタログタイプも `items` 配列を通じてアイテムを直接埋め込める。アイテムスキーマはカタログの `type` に依存する:
```json theme={null}
{
"assets": {
"offering_catalog": {
"type": "offering",
"items": [
{"offering_id": "summer-sale", "name": "Summer Sale", "landing_url": "https://acme.com/summer"}
]
}
}
}
```
バーティカルタイプは業界固有のアイテムスキーマを使用します:
```json theme={null}
{
"assets": {
"hotel_catalog": {
"type": "hotel",
"items": [
{
"hotel_id": "grand-amsterdam",
"name": "Grand Hotel Amsterdam",
"location": {"lat": 52.3676, "lng": 4.9041},
"star_rating": 5,
"price": {"amount": 289, "currency": "EUR", "period": "night"},
"amenities": ["spa", "pool", "restaurant", "wifi"]
}
]
}
}
}
```
### 外部フィード URL
AdCP の外部で管理されているフィードの場合、URL を指定してプラットフォームにフェッチさせる:
```json theme={null}
{
"assets": {
"product_catalog": {
"catalog_id": "product-feed",
"type": "product",
"url": "https://feeds.acmecorp.com/products.xml",
"feed_format": "google_merchant_center",
"update_frequency": "daily"
}
}
}
```
### 同期済みカタログへの参照
`sync_catalogs` を通じてアカウントに既に存在するカタログは、`catalog_id` で参照する:
```json theme={null}
{
"assets": {
"product_catalog": {
"catalog_id": "gmc-primary",
"type": "product",
"ids": ["SKU-123", "SKU-456"]
}
}
}
```
## カタログの同期
頻繁に変更されるカタログやプラットフォームレビューが必要なカタログには、`sync_catalogs` を使用してアカウント上でマネージドなライフサイクルを持たせる。これは `sync_creatives` と同じパターン — upsert セマンティクス、非同期承認、アイテムごとのステータス。
### なぜ同期するか
* **プラットフォームレビュー**: プロダクトカタログはコンテンツポリシーチェックを通過する（Google Merchant Center がプロダクトリストをレビューするように）。`sync_catalogs` はアイテムごとの承認ステータスを返します。
* **フィード管理**: 外部フィード URL を指定するとプラットフォームがスケジュールに従って再フェッチするため、バイヤーは変更のたびに再同期する必要がない。
* **マルチフィードクリエイティブ**: フォーマットは複数のカタログタイプ（product + inventory + store）を必要とすることがあります。カタログを別々に同期することで、クリエイティブが `catalog_id` で参照できます。
* **承認ワークフロー**: 非同期レスポンスにより、アイテムが承認、却下、または問題のフラグが立てられた時にバイヤーに通知します。
### 同期リクエスト
```json theme={null}
{
"account": { "account_id": "acct_acmecorp" },
"catalogs": [
{
"catalog_id": "product-feed",
"name": "Acme Product Catalog",
"type": "product",
"url": "https://feeds.acmecorp.com/products.xml",
"feed_format": "google_merchant_center",
"update_frequency": "daily"
},
{
"catalog_id": "inventory-feed",
"name": "Store Inventory",
"type": "inventory",
"url": "https://feeds.acmecorp.com/inventory.json",
"feed_format": "custom",
"update_frequency": "hourly"
},
{
"catalog_id": "store-locations",
"name": "Retail Locations",
"type": "store",
"url": "https://feeds.acmecorp.com/stores.json",
"feed_format": "custom",
"update_frequency": "weekly"
}
]
}
```
### アイテムレベルのレビューを含む同期レスポンス
```json theme={null}
{
"catalogs": [
{
"catalog_id": "product-feed",
"action": "created",
"platform_id": "plat_cat_001",
"item_count": 1250,
"items_approved": 1180,
"items_pending": 45,
"items_rejected": 25,
"item_issues": [
{
"item_id": "SKU-789",
"status": "rejected",
"reasons": ["Missing required field: image_url"]
},
{
"item_id": "SKU-456",
"status": "warning",
"reasons": ["Price format not recognized — using raw value"]
}
],
"next_fetch_at": "2025-03-01T06:00:00Z"
},
{
"catalog_id": "inventory-feed",
"action": "created",
"platform_id": "plat_cat_002",
"item_count": 8500,
"items_approved": 8500,
"next_fetch_at": "2025-02-28T13:00:00Z"
}
]
}
```
### ディスカバリーモード
`catalogs` を省略すると、変更なしでアカウント上のすべてのカタログをリストアップする:
```json theme={null}
{
"account": { "account_id": "acct_acmecorp" }
}
```
これは重要です。セラーは他のソースからブランドデータを既に持っている可能性があるからだ — 小売業者はコマースプラットフォームからブランドのプロダクトカタログを持っているかもしれない。ディスカバリーによりバイヤーはすべてを再アップロードするのではなく、既存の状態の上に構築できます。
## フィードフィールドマッピング
外部フィードは AdCP カタログアイテムスキーマと完全に一致することはほとんどない。フィールド名が異なり、日付はプラットフォーム固有のフォーマットを使用し、価格は整数のセントとしてエンコードされている場合があり、画像は型なし URL として届く。`feed_field_mappings` は宣言的な正規化レイヤーを提供する — `sync_catalogs` リクエスト内の catalog オブジェクトに含まれる — これによりバイヤーはすべてのフィードを前処理することなく変換を記述できます。
```json theme={null}
{
"catalog_id": "hotel-feed",
"type": "hotel",
"url": "https://feeds.partner.com/hotels.xml",
"feed_format": "custom",
"feed_field_mappings": [
{ "feed_field": "hotel_name", "catalog_field": "name" },
{ "feed_field": "nightly_cents", "catalog_field": "price.amount", "transform": "divide", "by": 100 },
{ "catalog_field": "price.currency", "value": "USD" },
{ "feed_field": "avail_date", "catalog_field": "valid_from", "transform": "date", "format": "YYYYMMDD", "timezone": "UTC" },
{ "feed_field": "primary_photo", "asset_group_id": "images_landscape" },
{ "feed_field": "snap_photo", "asset_group_id": "images_vertical" },
{ "feed_field": "logo_url", "asset_group_id": "logo" },
{ "feed_field": "facility_list", "catalog_field": "amenities", "transform": "split", "separator": "," },
{ "feed_field": "star_class", "catalog_field": "star_rating", "default": 0 }
]
}
```
各マッピングエントリは次のいずれかだ:
| パターン | 動作 |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `feed_field` + `catalog_field` | フィードフィールドをスキーマの同等フィールドに名前変更する（ネストフィールドはドット記法） |
| `feed_field` + `asset_group_id` | URL をアイテムの `assets` 配列の型付きアセットプールに配置する。URL はプールに応じて画像**または**動画アセットとしてラップされる（例: `video`、`video_vertical`、`video_horizontal` は動画アセットとしてラップ） |
| `value` + `catalog_field` | 静的リテラルを挿入する — フィードが省略するフィールドに便利（例: 常に USD の場合の通貨） |
| 上記いずれか + `transform` | 書き込み前に名前付き変換を適用する |
| 上記いずれか + `default` | フィードフィールドが存在しないか null の場合のフォールバック |
### サポートされているトランスフォーム
| トランスフォーム | パラメーター | 例 |
| --------- | --------------------------------------------- | --------------------------------------------- |
| `date` | `format`（入力日付パターン）、`timezone`（IANA、デフォルト UTC） | `"YYYYMMDD"` → `"2025-03-01"` |
| `divide` | `by`（除数、0 より大きい必要があります） | `1000` ÷ `100` → `10.00` |
| `boolean` | — | `"yes"` / `"1"` / `"true"` → `true` |
| `split` | `separator`（デフォルト `,`） | `"spa,pool,wifi"` → `["spa", "pool", "wifi"]` |
複数のマッピングがネストされたオブジェクトを組み立てられます。上記の `price.amount` と `price.currency` のマッピングは `price` オブジェクトの各フィールドを独立して書き込む。
## アイテムスキーマリファレンス
各バーティカルカタログタイプには、フィールドテーブル、必須フィールド、開始テンプレートを含む定義済みアイテムスキーマがあります。すべてのバーティカルタイプの最小例とフル例を含む完全なリファレンスについては\*\*[カタログアイテムスキーマ](/docs/creative/catalog-schemas)\*\*を参照。
プロダクトリスト、ストアロケーター、プロモーションコンテンツをレンダリングするフォーマットは、`assets` 配列内の `catalog` アセットタイプとして必要なカタログフィードを宣言します。各カタログアセットは `catalog_type`、`min_items`、`required_fields` などのフィールドを持つ `requirements` を持ちます。これにより購買エージェントはクリエイティブを提出する前にどのカタログを同期すべきかを把握できます。
```json theme={null}
{
"format_id": {
"agent_url": "https://creative.retailer.com/adcp",
"id": "product_carousel_with_inventory"
},
"name": "Product Carousel with Inventory",
"assets": [
{
"item_type": "individual",
"asset_id": "product_catalog",
"asset_type": "catalog",
"required": true,
"requirements": {
"catalog_type": "product",
"min_items": 3,
"required_fields": ["title", "price", "image_url"]
}
},
{
"item_type": "individual",
"asset_id": "inventory_catalog",
"asset_type": "catalog",
"required": true,
"requirements": {
"catalog_type": "inventory",
"required_fields": ["store_id", "quantity", "in_stock"]
}
}
]
}
```
購買エージェントはフォーマット発見後にフォーマットの `assets` 配列内のカタログアセットタイプを確認し、`sync_catalogs` 経由で必要なカタログを同期し、それらのカタログを参照するクリエイティブを提出します。
### フィールドバインディング
フォーマットはカタログアセットの `requirements` 内に `field_bindings` を宣言して、テンプレートスロットをカタログアイテムフィールドまたはアセットプールに明示的にマッピングできます。これによりフォーマットが自己記述的になる — クリエイティブエージェントはどのカタログフィールドがどのテンプレートスロットにマッピングされるかを推測する必要がなくなります。
```json theme={null}
{
"assets": [
{
"item_type": "individual",
"asset_id": "hotel_catalog",
"asset_type": "catalog",
"required": true,
"requirements": {
"catalog_type": "hotel",
"required_fields": ["name", "price.amount"],
"offering_asset_constraints": [
{ "asset_group_id": "images_landscape", "asset_type": "image", "required": true, "min_count": 1 },
{ "asset_group_id": "images_vertical", "asset_type": "image", "required": true, "min_count": 1 }
],
"field_bindings": [
{ "kind": "scalar", "asset_id": "headline", "catalog_field": "name" },
{ "kind": "scalar", "asset_id": "price_badge", "catalog_field": "price.amount" },
{ "kind": "asset_pool", "asset_id": "hero_image", "asset_group_id": "images_landscape" },
{ "kind": "asset_pool", "asset_id": "snap_background", "asset_group_id": "images_vertical" },
{ "kind": "asset_pool", "asset_id": "logo", "asset_group_id": "logo" }
]
}
}
]
}
```
繰り返し可能なグループ（各スライドが1つのカタログアイテムのカルーセル）の場合、カタログアセットの `requirements.field_bindings` 内で `format_group_id` と `catalog_item: true` を使用します:
```json theme={null}
{
"requirements": {
"catalog_type": "product",
"field_bindings": [
{
"kind": "catalog_group",
"format_group_id": "slide",
"catalog_item": true,
"per_item_bindings": [
{ "kind": "scalar", "asset_id": "title", "catalog_field": "name" },
{ "kind": "scalar", "asset_id": "price", "catalog_field": "price.amount" },
{ "kind": "asset_pool", "asset_id": "image", "asset_group_id": "images_landscape" }
]
}
]
}
}
```
フィールドバインディングは**オプション** — バインディングがない場合、クリエイティブエージェントはフィールド名とアセットタイプからマッピングを推測できます。バインディングを提供することで曖昧さがなくなり、レンダリング前の検証が可能になります。
| `kind` | 必須フィールド | 動作 |
| ----------------- | ---------------------------------------- | -------------------------------------------- |
| `"scalar"` | `asset_id` + `catalog_field` | 個々のテンプレートアセットをカタログアイテムフィールドにマッピング（ドット記法） |
| `"asset_pool"` | `asset_id` + `asset_group_id` | 個々のテンプレートアセットをカタログアイテムの型付きアセットプールにマッピング |
| `"catalog_group"` | `format_group_id` + `catalog_item: true` | フォーマットの repeatable\_group をカタログアイテムにわたって反復する |
## クリエイティブ内のカタログ
クリエイティブはマニフェストの `assets` マップのエントリとしてカタログを参照します。各カタログアセットはフォーマットで宣言された `asset_id`（例: `product_catalog`）でキー付けされます。これはデータ参照だ — クリエイティブにどのアイテムをレンダリングするかを伝える（カルーセルのプロダクト、ストアロケーターの場所）。キャンペーン展開ディレクティブではありません。キャンペーン構造と予算配分は `create_media_buy` パッケージによって処理されます。
フォーマットがカタログアセットタイプを宣言している場合、購買エージェントは必要なカタログをアカウントに同期し、クリエイティブの `assets` マップの対応するアセットキーを同期済みデータを参照するように設定します。
### ワークフロー
1. **フォーマット要件を発見する** — `list_creative_formats` を呼び出し、フォーマットの `assets` 配列で `catalog` アセットタイプとその `requirements` を確認します。
2. **カタログを同期する** — `sync_catalogs` を使用して必要なフィードをアカウントにプッシュします。承認を待つ。
3. **クリエイティブを提出する** — 対応するアセットキーで `catalog_id` により同期済みカタログを参照する:
```json theme={null}
{
"creatives": [
{
"creative_id": "product-carousel",
"format_id": {
"agent_url": "https://creative.retailer.com/adcp",
"id": "product_carousel_with_inventory"
},
"assets": {
"product_catalog": {
"catalog_id": "product-feed",
"type": "product",
"tags": ["summer"]
},
"banner_image": {
"url": "https://cdn.acmecorp.com/carousel-hero.jpg",
"width": 1200,
"height": 628
}
}
}
]
}
```
オファリング
**スキーマ URL**: [`/schemas/core/offering.json`](https://adcontextprotocol.org/schemas/v3/core/offering.json)
オファリングは `offering` 型カタログ内の個々のプロモート可能なアイテムだ — キャンペーン、プロダクト、サービス、プロモーション、または求人。各オファリングは独自の名前、有効期間、ランディング URL、クリエイティブアセット、地理的スコープを持つセマンティック単位です。
```typescript test=false theme={null}
type PostalArea =
| {
country: string; // ISO 3166-1 alpha-2
system: string; // Country-local postal system, e.g. 'zip', 'plz', 'postal_code'
values: string[];
}
| {
system: string; // Deprecated country-fused alias, e.g. 'us_zip'
values: string[];
};
interface Offering {
// Identity (required)
offering_id: string;
name: string;
// Description
description?: string;
tagline?: string;
// Validity window
valid_from?: string; // ISO 8601 datetime
valid_to?: string; // ISO 8601 datetime
// Destinations
checkout_url?: string; // Purchase/conversion URL
landing_url?: string; // Information page
// Creative assets
assets?: OfferingAssetGroup[]; // Structured asset groups
// Geographic scope
geo_targets?: {
countries?: string[];
regions?: string[];
metros?: { system: string; values: string[] }[];
postal_areas?: PostalArea[];
};
// Discovery
keywords?: string[];
categories?: string[];
}
```
| フィールド | 型 | 必須 | 説明 |
| -------------- | --------------------- | --- | ------------------------------------------------------------------------------------------- |
| `offering_id` | string | Yes | 一意の識別子 |
| `name` | string | Yes | 人間が読める名前 |
| `description` | string | No | 詳細な説明 |
| `tagline` | string | No | 短いプロモーションタグライン |
| `valid_from` | datetime | No | オファリングが利用可能になる時刻 |
| `valid_to` | datetime | No | オファリングが期限切れになる時刻 |
| `checkout_url` | uri | No | 購買フローの URL |
| `landing_url` | uri | No | アイテムごとのクリックスルー URL。カタログ駆動フォーマットでは、プラットフォームが広告のリンクアウトにマッピングするデスティネーションです。すべてのオファリングに含めるべきです。 |
| `assets` | OfferingAssetGroup\[] | No | このオファリングの構造化アセットグループ |
| `geo_targets` | object | No | 地理的スコープ — このオファリングが関連する場所 |
| `keywords` | string\[] | No | インテントマッチング用のキーワード |
| `categories` | string\[] | No | フィルタリング用のカテゴリ |
### OfferingAssetGroup
**スキーマ URL**: [`/schemas/core/offering-asset-group.json`](https://adcontextprotocol.org/schemas/v3/core/offering-asset-group.json)
オファリング内のクリエイティブアセットの型付きプール。フォーマットレベルのアセット定義と同じ `asset_group_id` の語彙を使用し、フォーマットが各オファリングが提供しなければなりませんものについてグループごとの制約を宣言できるようにします。
```typescript test=false theme={null}
interface OfferingAssetGroup {
asset_group_id: string; // e.g., 'headlines', 'images_landscape'
asset_type: AssetContentType; // Type of all items in this group
items: Asset[]; // The assets (must match asset_type)
}
```
| フィールド | 型 | 必須 | 説明 |
| ---------------- | ---------------- | --- | ------------------------------------------------------------------- |
| `asset_group_id` | string | Yes | フォーマットレベルの語彙と一致する（例: `headlines`、`descriptions`、`images_landscape`） |
| `asset_type` | AssetContentType | Yes | このグループのすべてのアイテムのコンテンツタイプ |
| `items` | Asset\[] | Yes | アセット。各アイテムは宣言された `asset_type` と一致しなければなりません |
### OfferingAssetConstraint
**スキーマ URL**: [`/schemas/core/requirements/offering-asset-constraint.json`](https://adcontextprotocol.org/schemas/v3/core/requirements/offering-asset-constraint.json)
各オファリングが提供しなければなりませんアセットグループを指定するためにフォーマットによって宣言されます。カタログアセットの `requirements` 内で使用して、カタログ内のオファリングが提供しなければなりませんものを制約します。
```typescript test=false theme={null}
interface OfferingAssetConstraint {
asset_group_id: string;
asset_type: AssetContentType;
required?: boolean; // default: true
min_count?: number;
max_count?: number;
asset_requirements?: AssetRequirements;
}
```
| フィールド | 型 | 必須 | 説明 |
| -------------------- | ---------------- | --- | --------------------------------------------------- |
| `asset_group_id` | string | Yes | この制約が適用されるグループ |
| `asset_type` | AssetContentType | Yes | 期待されるコンテンツタイプ |
| `required` | boolean | No | グループが存在しなければなりませんかどうか。デフォルトは `true`。 |
| `min_count` | integer | No | 必要な最小アイテム数 |
| `max_count` | integer | No | 許可される最大アイテム数 |
| `asset_requirements` | object | No | アイテムごとの技術的要件（例: テキストの `max_length`、画像の `min_width`） |
### オファリングのフォーマット要件
`list_creative_formats` を呼び出し、フォーマットの `assets` 配列で `catalog` アセットタイプを確認して、どのカタログタイプが必要で各オファリングが何を提供しなければなりませんかを確認します:
```json theme={null}
{
"assets": [
{
"item_type": "individual",
"asset_id": "offering_catalog",
"asset_type": "catalog",
"required": true,
"requirements": {
"catalog_type": "offering",
"offering_asset_constraints": [
{
"asset_group_id": "headlines",
"asset_type": "text",
"required": true,
"min_count": 3,
"max_count": 15,
"asset_requirements": {"max_length": 30}
},
{
"asset_group_id": "descriptions",
"asset_type": "text",
"required": true,
"min_count": 2,
"max_count": 5,
"asset_requirements": {"max_length": 90}
},
{
"asset_group_id": "images_landscape",
"asset_type": "image",
"required": true,
"min_count": 1,
"max_count": 20,
"asset_requirements": {"aspect_ratio": "1.91:1", "min_width": 1200, "min_height": 628}
},
{
"asset_group_id": "images_square",
"asset_type": "image",
"required": true,
"min_count": 1,
"max_count": 20,
"asset_requirements": {"aspect_ratio": "1:1", "min_width": 600, "min_height": 600}
}
]
}
}
]
}
```
ストア
**スキーマ URL**: [`/schemas/core/store-item.json`](https://adcontextprotocol.org/schemas/v3/core/store-item.json)
StoreItem は `store` 型カタログ内の物理的な場所を表します。各ストアは座標、オプションの住所、およびその場所周辺の地理的な到達範囲を定義する1つ以上のキャッチメントエリアを持ちます。
```typescript test=false theme={null}
interface StoreItem {
store_id: string; // Unique identifier
name: string; // Human-readable name
location: { lat: number; lng: number }; // WGS 84 coordinates
address?: {
street?: string;
city?: string;
region?: string; // ISO 3166-2 preferred
postal_code?: string;
country?: string; // ISO 3166-1 alpha-2
};
catchments?: Catchment[]; // Reachable areas around this store
phone?: string; // E.164 format
url?: string; // Store detail page
hours?: Record; // e.g., "09:00-21:00"
tags?: string[]; // For filtering (e.g., "flagship", "pickup")
}
```
| フィールド | 型 | 必須 | 説明 |
| ------------ | ------------ | --- | ------------------------------ |
| `store_id` | string | Yes | ターゲティング、在庫、クリエイティブ参照のための一意の識別子 |
| `name` | string | Yes | 人間が読めるストア名 |
| `location` | object | Yes | 緯度/経度座標（WGS 84） |
| `address` | object | No | 表示とジオコーディングフォールバックのための構造化住所 |
| `catchments` | Catchment\[] | No | 近接ターゲティング用のキャッチメントエリア |
| `phone` | string | No | 電話番号（E.164） |
| `url` | uri | No | ストア固有のページ URL |
| `hours` | object | No | 曜日ごとの営業時間 |
| `tags` | string\[] | No | ターゲティングとクリエイティブ選択のフィルタリング用タグ |
### キャッチメントエリア
**スキーマ URL**: [`/schemas/core/catchment.json`](https://adcontextprotocol.org/schemas/v3/core/catchment.json)
キャッチメントはストアがサービスを提供する地理的エリアを定義します。3つの方法がサポートされている — 各キャッチメントに対して1つだけ提供します:
**等時線インプット** — プラットフォームが移動時間と交通手段から形状を解決し、道路ネットワーク、交通ルート、地形を考慮する:
```json theme={null}
{
"catchment_id": "drive",
"label": "15-min drive",
"travel_time": { "value": 15, "unit": "min" },
"transport_mode": "driving"
}
```
**シンプルな半径** — ストアの座標を中心とする円:
```json theme={null}
{
"catchment_id": "local",
"radius": { "value": 5, "unit": "km" }
}
```
**事前計算された GeoJSON** — バイヤーがすでに境界を計算済み（TravelTime、Mapbox などを使用）またはカスタムのトレードエリアデータを持っている:
```json theme={null}
{
"catchment_id": "trade-area",
"label": "Primary trade area",
"geometry": {
"type": "Polygon",
"coordinates": [[[4.85, 52.35], [4.95, 52.35], [4.95, 52.40], [4.85, 52.40], [4.85, 52.35]]]
}
}
```
ストアは複数のキャッチメントを持てる — 異なる交通手段は異なる境界を生成します。都市部のフラッグシップストアは 10 分の徒歩キャッチメントと 15 分の自動車キャッチメントの両方を定義できる:
```json theme={null}
{
"store_id": "amsterdam-flagship",
"name": "Amsterdam Flagship",
"location": { "lat": 52.3676, "lng": 4.9041 },
"catchments": [
{
"catchment_id": "walk",
"travel_time": { "value": 10, "unit": "min" },
"transport_mode": "walking"
},
{
"catchment_id": "drive",
"travel_time": { "value": 15, "unit": "min" },
"transport_mode": "driving"
},
{
"catchment_id": "transit",
"travel_time": { "value": 20, "unit": "min" },
"transport_mode": "public_transport"
}
]
}
```
`catchment_id` はターゲティングが参照するものだ — キャンペーンは特定のストアの `walk` キャッチメントまたはカタログ内のすべてのストアの `drive` キャッチメントをターゲットにできます。
### インラインストアカタログ
```json theme={null}
{
"catalog_id": "retail-locations",
"name": "Retail Locations",
"type": "store",
"items": [
{
"store_id": "amsterdam-flagship",
"name": "Amsterdam Flagship",
"location": { "lat": 52.3676, "lng": 4.9041 },
"address": {
"street": "Kalverstraat 1",
"city": "Amsterdam",
"region": "NL-NH",
"postal_code": "1012 NX",
"country": "NL"
},
"catchments": [
{
"catchment_id": "walk",
"travel_time": { "value": 10, "unit": "min" },
"transport_mode": "walking"
},
{
"catchment_id": "drive",
"travel_time": { "value": 15, "unit": "min" },
"transport_mode": "driving"
}
],
"tags": ["flagship", "pickup"]
},
{
"store_id": "warehouse-east",
"name": "East Warehouse Store",
"location": { "lat": 52.2942, "lng": 4.9581 },
"catchments": [
{
"catchment_id": "local",
"radius": { "value": 10, "unit": "km" }
}
],
"tags": ["warehouse", "parking"]
}
]
}
```
## SI インテグレーション
カタログ内のオファリングはスポンサードインテリジェンスの会話を通じてプロモートできます。ブランドの SI エージェント URL は catalog ではなく[ブランドアイデンティティ](/docs/brand-protocol/brand-json)で宣言される — SI はブランドレベルの機能です。
`offering_id` がカタログアイテムを会話に接続する:
1. **ユーザーがインテントを表明する** — 「来週 LA へのフライトが必要です」
2. **パブリッシャーがオファリングにマッチする** — `keywords` を使用して関連するオファリングを見つけ、`valid_from`/`valid_to` を確認します
3. **パブリッシャーが SI セッションを開始する** — `offering_id` とユーザーコンテキストをブランドの SI エージェントに渡します
4. **ブランドエージェントが応答する** — コンテキスト情報、UI 要素、会話型エクスペリエンスで
ディスプレイクリエイティブと SI は共存できる: 同じオファリングがディスプレイ広告として機能し、会話型エクスペリエンスでも利用できます。
## ユースケース
### ユニバーサルフォーマット（アセットプール）
バイヤーは複数のオファリングを提供し、それぞれが独自のクリエイティブアセットプールを持ちます。パブリッシャーは最も関連性の高いオファリングを選び、最適なヘッドライン/画像の組み合わせを組み立てる:
```json theme={null}
{
"brand": { "domain": "acme.com" },
"assets": {
"offering_catalog": {
"type": "offering",
"items": [
{
"offering_id": "summer-sale",
"name": "Summer Sale",
"landing_url": "https://acme.com/summer",
"assets": [
{"asset_group_id": "headlines", "asset_type": "text", "items": [
{"content": "Shop the Summer Sale"},
{"content": "50% Off Everything"}
]},
{"asset_group_id": "images_landscape", "asset_type": "image", "items": [
{"url": "https://cdn.acme.com/summer-hero.jpg", "width": 1200, "height": 628}
]}
]
},
{
"offering_id": "new-arrivals",
"name": "New Arrivals",
"landing_url": "https://acme.com/new",
"assets": [
{"asset_group_id": "headlines", "asset_type": "text", "items": [
{"content": "Just Arrived"},
{"content": "New This Week"}
]},
{"asset_group_id": "images_landscape", "asset_type": "image", "items": [
{"url": "https://cdn.acme.com/new-arrivals.jpg", "width": 1200, "height": 628}
]}
]
}
]
}
}
}
```
### 同期済みフィードを使ったプロダクトカタログ
リテールメディアでは、プロダクトと在庫フィードを同期してからクリエイティブで参照する:
```json theme={null}
{
"brand": { "domain": "acmecorp.com" },
"assets": {
"product_catalog": {
"catalog_id": "product-feed",
"type": "product",
"tags": ["summer"]
}
}
}
```
パブリッシャーは同期済みプロダクトデータとリアルタイムの在庫からクリエイティブを組み立てる。
### 会話型のみ
事前構築されたクリエイティブなし — SI 会話に利用可能なオファリングのみ。ブランドの SI エージェント URL は[ブランドアイデンティティ](/docs/brand-protocol/brand-json)から発見されます:
```json theme={null}
{
"brand": { "domain": "saas-company.com" },
"assets": {
"offering_catalog": {
"type": "offering",
"items": [
{
"offering_id": "enterprise-demo",
"name": "Enterprise Demo",
"description": "See our platform in action with a personalized demo",
"keywords": ["demo", "enterprise", "trial", "pricing"]
},
{
"offering_id": "free-trial",
"name": "14-Day Free Trial",
"checkout_url": "https://saas-company.com/signup",
"keywords": ["trial", "free", "signup"]
}
]
}
}
}
```
### 場所固有のオファリング
複数の物理的な場所を持つブランド（レストラン、小売チェーン、求人募集）の場合、各オファリングは `geo_targets` を通じて地理的スコープを宣言する:
```json theme={null}
{
"brand": { "domain": "acme-restaurants.com" },
"assets": {
"offering_catalog": {
"type": "offering",
"items": [
{
"offering_id": "vacancy-amsterdam-chef",
"name": "Head Chef — Amsterdam",
"landing_url": "https://careers.acme-restaurants.com/vacancies/41",
"geo_targets": {
"countries": ["NL"],
"regions": ["NL-NH"]
},
"assets": [
{"asset_group_id": "headlines", "asset_type": "text", "items": [
{"content": "Head Chef Wanted in Amsterdam"},
{"content": "Join Our Amsterdam Kitchen Team"}
]}
]
}
]
}
}
}
```
オファリングの geo\_targets はオファリングが何であるかについてだ — アムステルダムの求人はロッテルダムにいる人には存在しません。キャンペーン全体の geo ターゲティングはパッケージの `targeting_overlay` に属します。
## メディアバイライフサイクル内のカタログ
カタログはメディアバイライフサイクル全体を流れる — プロダクト発見から配信レポートまで。
### カタログ駆動の発見
[`get_products`](/docs/media-buy/task-reference/get_products) に `catalog` を渡して、カタログアイテムにマッチするプロダクトを見つける。セラーはカタログアイテムをインベントリと照合し、マッチが存在するプロダクトを返します。プロダクトは `catalog_types` を通じてサポートするカタログタイプを宣言します。
### カタログ駆動パッケージ
[`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) のパッケージに `catalog` フィールドを含めてカタログ駆動にします。1つの予算エンベロープがカタログ全体をプロモートする — プラットフォームはパフォーマンスに基づいてアイテム間の配信を最適化します。これは Google Performance Max や Meta Dynamic Product Ads のようなカタログベースのキャンペーンタイプの AdCP 相当です。
### カタログアイテムとしてのバリアント
カタログ駆動パッケージでは、異なる広告実行としてレンダリングされる各カタログアイテムが[クリエイティブバリアント](/docs/creative/task-reference/get_creative_delivery)だ。バリアントのマニフェストには、レンダリングされた特定のアイテムと共にカタログ参照が含まれます。
### アイテムごとの配信レポート
[`get_media_buy_delivery`](/docs/media-buy/task-reference/get_media_buy_delivery) は各パッケージ内の `by_catalog_item` ブレークダウンを返し、アイテムごとのインプレッション、支出、クリック、コンバージョン、ROAS を表示します。
### コンバージョンアトリビューション
コンバージョンイベントは関与したカタログアイテムを識別する `content_ids` を持ちます。カタログの `content_id_type` は識別子タイプを宣言します。アトリビューションは広範だ — ユーザーはアイテム A をクリックしてアイテム B でコンバートするかもしれない。イベントは実際の `content_id` で発火します。[コンバージョントラッキング](/docs/media-buy/conversion-tracking)を参照。
### マクロによるアイテムレベルのトラッキング
インプレッションレベルのアトリビューション（どのアイテムがクリックされたか、どのアイテムが閲覧されたか）には、クリエイティブのトラッカーピクセル URL に[カタログアイテムマクロ](/docs/creative/universal-macros#catalog-item-macros)を使用します。マクロは `content_id_type` 列挙型を反映する — 配信時に使用される同じ識別子がコンバージョンイベントに現れる:
```json theme={null}
{
"impression_pixel": {
"url": "https://track.brand.com/imp?catalog={CATALOG_ID}&item={OFFERING_ID}&creative={CREATIVE_ID}&cb={CACHEBUSTER}",
"url_type": "tracker_pixel"
}
}
```
配信時に、プラットフォームは `{OFFERING_ID}` をレンダリングされている特定のオファリングで置換します。5つのオファリングを表示するカルーセルでは、各アイテムのインプレッションがそのアイテムの識別子で発火します。
カタログの `content_id_type` に一致するマクロを使用します:
| `content_id_type` | マクロ |
| ----------------- | ------------------ |
| `sku` | `{SKU}` |
| `gtin` | `{GTIN}` |
| `offering_id` | `{OFFERING_ID}` |
| `job_id` | `{JOB_ID}` |
| `hotel_id` | `{HOTEL_ID}` |
| `flight_id` | `{FLIGHT_ID}` |
| `vehicle_id` | `{VEHICLE_ID}` |
| `listing_id` | `{LISTING_ID}` |
| `store_id` | `{STORE_ID}` |
| `program_id` | `{PROGRAM_ID}` |
| `destination_id` | `{DESTINATION_ID}` |
| `app_id` | `{APP_ITEM_ID}` |
これにより閉じたアトリビューションループが作成されます: 同じ識別子がインプレッショントラッカー（配信時のマクロ経由）、クリックトラッカー、コンバージョンイベント（イベント時の `content_ids` 経由）に現れる。
### カタログコンテンツマクロ
上記のマクロは、レンダリングされたアイテムの**識別子**に解決されます。カタログ**コンテンツ**マクロは、カタログ駆動のクリエイティブテンプレート（`sponsored_placement` / DPA——Meta DPA、Snap Collection、TikTok Shopping）向けに、レンダリングされたアイテムのスカラー**フィールド値**に解決されます。各トークンは、[`field_bindings`](#field-bindings) が使うのと同じ `catalog_field` のドット記法パスを介して、カタログアイテムのフィールドに 1:1 でマップされます——コンテンツマクロは並行するものを定義するのではなく、その語彙を再利用します:
| マクロ | `catalog_field` |
| ----------------------- | ---------------- |
| `{ITEM_NAME}` | `name` |
| `{ITEM_DESCRIPTION}` | `description` |
| `{ITEM_TAGLINE}` | `tagline` |
| `{ITEM_PRICE}` | `price.amount` |
| `{ITEM_PRICE_CURRENCY}` | `price.currency` |
コンテンツマクロはシングルブレース `{MACRO}` 構文を使い、ID マクロと同じ[代入安全性のルール](/docs/creative/universal-macros#代入安全性カタログアイテムマクロ)（NFC 正規化 → RFC 3986 パーセントエンコード → 一巡のネスト展開禁止 → URL コンテキストのスコープ）の下で代入されます。`{{ダブルブレース}}` はコンテンツマクロ構文では**ありません**——セールスエージェントが中和しなければならない下流のアドサーバーマクロのために予約されたままです。URL 値と画像値のフィールド（`landing_url`、画像プール）は、コンテンツマクロではなく `field_bindings` を介して `url`/アセットスロットにバインドされます。
どのアイテムがレンダリングされるかは、[`sponsored_placement`](/docs/creative/canonical-formats) フォーマットの `fanout_mode` 列挙（Meta-DPA の広告ごとに 1 アイテムのパターンには `single_item`、`per_item`、または `multi_item_in_creative`）を介して**セラーが宣言**します——バイヤー側の選択フィールドはありません。ML 最適化された DPA サーフェスでは、プラットフォームがバイヤーの作成したオーバーレイテキストを上書きする場合があるため、コンテンツマクロはセラーが尊重してもよい（MAY）ヒントです。
## ベストプラクティス
### `asset_group_id` をフォーマットの語彙に合わせる
オファリングを構築する前に `list_creative_formats` からフォーマット定義を読む。`asset_group_id` の値は各カタログアセットの `requirements` 内の `offering_asset_constraints` でフォーマットが宣言しているものと正確に一致しなければなりません。`headlines`、`images`、`videos` などのグループ ID はフォーマット定義の語彙であり、プロトコル定数ではない — 各フォーマットは独自の ID を選択します。プロトコルはコンテナと制約メカニズムを提供します。フォーマットは語彙を定義します。
### 最小限以上のアセットを提供します
アセットプールを使用するフォーマットは最もパフォーマンスの高い組み合わせを選択します。許可される最大数のアイテムを提供することで、パブリッシャーに使える素材が増える。
### 有効期間を設定します
期間限定プロモーションには、常に `valid_from` と `valid_to` を設定します。パブリッシャーは期限切れのオファリングを自動的にフィルタリングします。
### 本質的に場所固有のオファリングには `geo_targets` を使います
オファリングのアイデンティティが地理的な場所に結びついている場合 — 求人募集、店内プロモーション、ローカルイベント — `geo_targets` でスコープを宣言します。これは広告ターゲティングではありません。オファリングが何であるかのプロパティです。
### カタログオファリングには常に `landing_url` を提供します
カタログ駆動クリエイティブでは、`landing_url` はプラットフォームが広告のリンクアウト URL（スワイプアップ、CTA ボタン、カルーセルカードリンク）にマッピングするアイテムごとのクリックスルーデスティネーションです。カタログ内のすべてのオファリングに `landing_url` を含めるべきです。直接コンバージョンがサポートされている場合は `checkout_url` も含めます。
### カタログアイテム間の予算配分
カタログアイテム間の予算配分はプラットフォームの最適化の決定だ — 一部のプラットフォームは均等に配分し、他はパフォーマンスシグナルに基づいて配分します。プロトコルは特定の配分方法を規定しません。予算は個々のオファリングではなく `create_media_buy` パッケージに属します。アイテムごとの予算上限が必要なキャンペーンの場合、オファリングごとに別のパッケージを使用します。
## 関連ドキュメント
* **[アカウント状態](/docs/building/by-layer/L2/account-state)** — カタログがアカウント状態とセットアップシーケンスにどのように組み込まれるか
* **[ブランドアイデンティティ](/docs/brand-protocol/brand-json)** — ブランドアイデンティティとアセット
* **[SI チャットプロトコル](/docs/sponsored-intelligence/si-chat-protocol)** — 会話型ブランドエクスペリエンス
* **[sync\_creatives](/docs/creative/task-reference/sync_creatives)** — クリエイティブマニフェストの提出
* **[list\_creative\_formats](/docs/creative/task-reference/list_creative_formats)** — フォーマット要件の発見