Skip to main content
テンプレートフォーマットを使うと、1 つのフォーマット定義で複数の寸法や尺のバリエーションに対応でき、類似フォーマットを大量に増やす必要がなくなります。多くのバリエーションをサポートするパブリッシャーでもフォーマット爆発を防げます。

​
課題: フォーマット爆発

テンプレートフォーマットを使わない場合、寸法が異なるたびに個別のフォーマット定義と format_id が必要です。 
{"format_id": {"agent_url": "...", "id": "display_300x250"}}
{"format_id": {"agent_url": "...", "id": "display_300x600"}}
{"format_id": {"agent_url": "...", "id": "display_728x90"}}
{"format_id": {"agent_url": "...", "id": "display_970x250"}}
// ... さらに 50+ サイズ
プレースメントが 50 サイズあるパブリッシャー → 50 個のフォーマット定義を作成・維持・文書化する必要が出る。

​
解決策: パラメータ付きテンプレートフォーマット

1 つのテンプレートフォーマット定義（例: display_static）が format_id オブジェクト内の寸法フィールドを受け入れ、クリエイティブが正確な寸法を指定できるようにします。

​
フォーマットタイプと format_id

2 種類のフォーマット定義 があり、そこから 3 種類の format_id が生成されます。

​
フォーマット定義

  1. 具体的フォーマット - 定義内で寸法が固定
    • 明示的な寸法を持つ renders 配列を持つ
    • 例: display_300x250 は常に 300×250px
    • パラメータは受け付けない
  2. テンプレートフォーマット - format_id でパラメータを受け取る
    • accepts_parameters 配列で受け付けるパラメータを列挙
    • 例: display_static は任意の寸法を取れる
    • パラメータ有無のどちらでも利用可

​
format_id の種類

  1. 具体的 format_id - 具体的フォーマットを参照
    • 例: {id: "display_300x250"}
    • パラメータなし（受け付けない）
  2. テンプレート format_id - パラメータなしでテンプレートを参照
    • 例: {id: "display_static"}
    • 任意寸法を受け入れるプレースメントで使用
  3. パラメータ付き format_id - テンプレート + パラメータ
    • 例: {id: "display_static", width: 300, height: 250}
    • クリエイティブがピクセル寸法を明示するときに使用

​
テンプレートフォーマット定義

パラメータを受け付けるフォーマット定義の例: 
{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_static"
  },
  "name": "Static Display Banner",
  "type": "display",
  "accepts_parameters": ["dimensions"],
  "renders": [
    {
      "role": "primary",
      "parameters_from_format_id": true
    }
  ],
  "assets": [
    {
      "item_type": "individual",
      "asset_id": "banner_image",
      "asset_type": "image",
      "required": true,
      "requirements": {
        "parameters_from_format_id": true
      }
    },
    {
      "item_type": "individual",
      "asset_id": "clickthrough_url",
      "asset_type": "url",
      "required": true
    }
  ]
}
主要フィールド:
  • accepts_parameters: ["dimensions"] - format_id に寸法（width/height ピクセル）を受け付ける
  • renders[].parameters_from_format_id: true - レンダリング寸法を format_id から取得
  • requirements.parameters_from_format_id: true - アセット寸法は format_id と一致する必要がある

​
パラメータ付き format_id（クリエイティブマニフェスト）

クリエイティブは format_id で正確な寸法を指定してテンプレートフォーマットを利用します。 
{
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_static",
    "width": 300,
    "height": 250
  },
  "assets": {
    "banner_image": {
      "asset_type": "image",
      "url": "https://cdn.example.com/banner-300x250.png",
      "width": 300,
      "height": 250
    },
    "clickthrough_url": {
      "asset_type": "url",
      "url": "https://example.com/landing"
    }
  }
}
この format_id はパラメータ付き: 同じ寸法なら常に同じ format_id オブジェクトになり、重複排除やキャッシュが容易になります。

​
パラメータの種類

テンプレートフォーマットは次の標準パラメータを受け付けられます。カスタムパラメータも定義できますが、標準を優先してください。

​
dimensions（推奨）

  • width (number): ピクセル幅
  • height (number): ピクセル高さ
  • オプション: min_width / min_height / max_width / max_height（フォーマット定義の requirements で使用）

​
duration

  • duration_ms (number): 再生時間（ミリ秒）
  • 動画/オーディオ/DOOH など尺が変化するフォーマット向け

​
aspect_ratio

  • aspect_ratio (string): 例 "16:9", "9:16", "1:1"
  • DOOH/動画でアスペクトを指定する場合

​
additional parameters

  • locale, language, placement_type など、ユースケースに応じて拡張可能

​
スキーマ設計のポイント

​
accepts_parameters

  • 受け付けるパラメータ名の配列
  • 例: "accepts_parameters": ["dimensions"]
  • 受け付けないパラメータは validation で拒否

​
parameters_from_format_id

  • renders[] や requirements で設定
  • true の場合、format_id に含まれる値がここへ流用される
  • フォーマット定義内で寸法/尺を固定せず、format_id から注入する

​
parameters_in_assets

  • アセット要件に parameters_from_format_id: true を設定すると、アセット寸法が format_id と一致することを強制
  • 例: 300x250 バナーの画像は width: 300, height: 250 を必須に

​
ベストプラクティス

  1. dimensions を標準化: 幅と高さを個別フィールドで表現し、文字列結合は避ける
  2. format_id を正規化: 同じパラメータセットなら同一の format_id オブジェクトになるようにする
  3. パラメータを必須化する場所を明確に: プレースメントでは常にパラメータ付き format_id を要求
  4. 部分指定を禁止: width だけ、height だけは無効（両方必須）
  5. パラメータ検証をスキーマで行う: Validation で不正な組み合わせを拒否

​
format_id の正規化ルール

​
等価性

format_id は次のフィールドを含めた完全一致で比較します。
  • agent_url
  • id
  • すべてのパラメータ（例: width/height または duration_ms）
大文字小文字や並び順の違いがあっても、同じキー/値セットなら等価です。

​
許可されない部分パラメータ

width のみ、height のみなど、必要パラメータの一部だけを渡すことはできません。スキーマが拒否します。 
// これらは同一 format_id（順序違いでも等価）
{"agent_url": "...", "id": "display_static", "width": 300, "height": 250}
{"id": "display_static", "agent_url": "...", "height": 250, "width": 300}

// これらは異なる format_id
{"agent_url": "...", "id": "display_static", "width": 300, "height": 250}
{"agent_url": "...", "id": "display_static", "width": 728, "height": 90}

// 無効: 部分指定は不可（スキーマが拒否）
{"agent_url": "...", "id": "display_static", "width": 300}  // ❌ height が不足

​
マッチングロジック

​
プレースメント検証

重要: プレースメントは必ずパラメータ付き format_id（寸法/尺を明示）を指定する必要があります。パラメータなしのテンプレート format_id はプレースメントでは使用不可です。 プレースメントでのパラメータ付きフォーマット（必須パターン）: 
// プレースメントがサポートする寸法を明示
{"format_ids": [
  {"agent_url": "...", "id": "display_static", "width": 300, "height": 250},
  {"agent_url": "...", "id": "display_static", "width": 728, "height": 90}
]}

// クリエイティブは format_id が完全一致する場合のみマッチ
{"format_id": {"agent_url": "...", "id": "display_static", "width": 300, "height": 250}}  // ✅ マッチ
{"format_id": {"agent_url": "...", "id": "display_static", "width": 728, "height": 90}}   // ✅ マッチ
{"format_id": {"agent_url": "...", "id": "display_static", "width": 160, "height": 600}}  // ❌ プレースメントに存在しない
{"format_id": {"agent_url": "...", "id": "display_static"}}                               // ❌ 寸法が不足

​
具体フォーマットからの移行

移行前（フォーマット爆発）: 
// 50 個のフォーマット定義が別々に存在
{
  "format_id": {"agent_url": "...", "id": "display_300x250"},
  "renders": [{"dimensions": {"width": 300, "height": 250}}]
}
{
  "format_id": {"agent_url": "...", "id": "display_728x90"},
  "renders": [{"dimensions": {"width": 728, "height": 90}}]
}
// ... 残り 48 件
移行後（単一のテンプレートフォーマット）: 
{
  "format_id": {"agent_url": "...", "id": "display_static"},
  "accepts_parameters": ["dimensions"],
  "assets": [...]
}
クリエイティブマニフェストの変更: 
// Before: format_id の文字列に寸法を埋め込む
{
  "format_id": {"agent_url": "...", "id": "display_300x250"},
  "assets": {...}
}

// After: format_id のフィールドとして寸法を構造化
{
  "format_id": {
    "agent_url": "...",
    "id": "display_static",
    "width": 300,
    "height": 250
  },
  "assets": {...}
}

​
よくあるパターン

​
IAB 標準ディスプレイサイズ

15 個の IAB サイズごとにフォーマットを定義する代わりに、1 つのテンプレートを使います。 
{
  "format_id": {"agent_url": "...", "id": "display_static"},
  "accepts_parameters": ["dimensions"]
}
クリエイティブ側はパラメータでサイズを指定:
  • 300×250: {id: "display_static", width: 300, height: 250}
  • 728×90: {id: "display_static", width: 728, height: 90}
  • 160×600: {id: "display_static", width: 160, height: 600}
  • など

​
動画の尺バリエーション

15/30/60 秒ごとに別定義を作る代わりに: 
{
  "format_id": {"agent_url": "...", "id": "video_hosted"},
  "accepts_parameters": ["duration"]
}
クリエイティブは尺を指定: {id: "video_hosted", duration_ms: 30000}

​
DOOH のスクリーンサイズ

ビルボードごとにフォーマットを作る代わりに: 
{
  "format_id": {"agent_url": "...", "id": "dooh_static"},
  "accepts_parameters": ["dimensions"]
}
クリエイティブはピクセル寸法を指定: {id: "dooh_static", width: 1920, height: 560} 注: すべての寸法はピクセル。実際の物理サイズ（例: 48 フィート × 14 フィート）はプレースメントのメタデータで管理します。

​
参考