Skip to main content

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.

マニフェストとメトリクスを含むバリアントレベルの内訳を持つクリエイティブ配信データを取得します。このタスクは、クリエイティブからどんなバリアントが作成されたか、それらがどのように見えたか（マニフェスト経由）、そしてどのようなパフォーマンスを発揮したかを返します。 これはクリエイティブプロトコルのタスクです。supported_protocols に "creative" を宣言し、クリエイティブエージェントのケイパビリティに "delivery" を持つすべてのエージェントで呼び出す — 専用のクリエイティブサービスであってもクリエイティブプロトコルを実装するセールスエージェントであっても同じです。 リクエストスキーマ: /schemas/v3/creative/get-creative-delivery-request.json レスポンススキーマ: /schemas/v3/creative/get-creative-delivery-response.json

​
リクエストパラメータ

スコーピングフィルター（media_buy_ids または creative_ids）のうち少なくとも1つが必須です。
パラメータタイプ必須説明
accountaccount-refNoアカウント参照。セラーが暗黙的解決をサポートする場合、{ "account_id": "..." } または { "brand": {...}, "operator": "..." } を渡します。結果をこのアカウント内のクリエイティブに限定します。
media_buy_idsstring[]Yes*パブリッシャー ID で特定のメディアバイにフィルタリング
creative_idsstring[]Yes*ID で特定のクリエイティブにフィルタリング
start_datestringNo配信期間の開始日（YYYY-MM-DD、プラットフォームのレポートタイムゾーンで解釈）
end_datestringNo配信期間の終了日（YYYY-MM-DD、プラットフォームのレポートタイムゾーンで解釈）
max_variantsintegerNoクリエイティブあたりの返却バリアント数の最大値。バリアント数の多いジェネレーティブクリエイティブに有用。
paginationobjectNoクリエイティブ配列のカーソルベースのページネーションパラメータ（max_results、cursor）。省略した場合、すべての一致するクリエイティブが返されます。
* media_buy_ids または creative_ids のうち少なくとも1つが必要。

​
レスポンス

フィールド説明
account_idアカウント識別子（特定のアカウントにスコープされた場合に存在）
media_buy_idセラーのメディアバイ識別子（リクエストが単一のバイにスコープされた場合に存在）
currency金額の ISO 4217 通貨コード（例: ‘USD’、‘EUR’）
reporting_period開始/終了タイムスタンプと timezone（IANA 識別子 — プラットフォームはネイティブタイムゾーンでレポートします）を持つ日付範囲
creativesバリアント内訳を持つクリエイティブ配信データの配列
pagination（オプション）max_results、cursor、has_more を持つページネーション情報。リクエストにページネーションパラメータが含まれた場合に存在。

​
クリエイティブオブジェクト

フィールド説明
creative_idクリエイティブ識別子
media_buy_idセラーのメディアバイ識別子（リクエストが複数のメディアバイにまたがった場合に存在）
format_idこのクリエイティブのフォーマット
totalsすべてのバリアントにわたる集計配信メトリクス
variant_countバリアントの総数（max_variants 使用時は variants 配列の長さを超える場合があります）
variantsバリアントレベルの配信データの配列（クリエイティブにまだバリアントがない場合は空）

​
バリアントオブジェクト

各バリアントは特定の実行を表します: 固定クリエイティブ（Tier 1）、プラットフォームが選択したアセットの組み合わせ（Tier 2）、または生成されたバリアント（Tier 3）。カタログ駆動パッケージでは、個別の広告実行としてレンダリングされた各カタログアイテムがバリアントになる — バリアントのマニフェストにはレンダリングされた特定のアイテムを含むカタログ参照が含まれます。
フィールド説明
variant_idプラットフォームが割り当てたバリアント識別子
manifest（オプション）レンダリングされたクリエイティブマニフェスト — 入力アセットではなく実際に配信された出力。format_id と解決済みアセットを含みます。すべてのプラットフォームがすべてのバリアントのマニフェストを提供できるわけではありません。
generation_context（オプション、Tier 3）生成をトリガーした入力シグナル — 例: ページトピック、会話テーマ、クエリカテゴリ。プラットフォームは生のユーザー入力ではなく、要約/匿名化されたシグナルを提供します。コンテンツコンテキストが AdCP コンテンツ標準を通じて管理される場合、特定のコンテンツアーティファクトにリンクする artifact 参照を含みます。ベンダー固有のコンテキスト構造のために ext をサポートします。
ext（オプション）プラットフォーム固有のデータ。ソーシャルプラットフォームはプラットフォームごとに異なるエンゲージメントメトリクス（アップボート、コメント、シェア）にこれを使用します。
標準メトリクスすべての配信メトリクス（impressions、spend、clicks、ctr など）
ctr、completion_rate、roas、cost_per_click などの派生メトリクスはプラットフォームが計算したものであり、丸め、アトリビューションウィンドウ、またはフィルタリングされたインプレッションにより、構成要素の単純な除算と等しくない場合があります。

​
Tier の動作

​
Tier 1: 標準クリエイティブ

1つのクリエイティブが1つのバリアントに1対1でマッピングされます。バリアントのメトリクスはクリエイティブのトータルと一致します。 
{
  "media_buy_id": "mb_12345",
  "currency": "USD",
  "reporting_period": {
    "start": "2026-01-20T00:00:00-05:00",
    "end": "2026-01-27T23:59:59-05:00",
    "timezone": "America/New_York"
  },
  "creatives": [
    {
      "creative_id": "hero_video_30s",
      "totals": {
        "impressions": 150000,
        "spend": 7500,
        "clicks": 4500,
        "ctr": 0.03,
        "completion_rate": 0.72
      },
      "variants": [
        {
          "variant_id": "hero_video_30s",
          "impressions": 150000,
          "spend": 7500,
          "clicks": 4500,
          "ctr": 0.03,
          "completion_rate": 0.72
        }
      ]
    }
  ]
}

​
プラットフォームエンゲージメントメトリクス

ソーシャルおよびフィードネイティブプラットフォームは、エンゲージメントタイプがプラットフォームごとに異なるため、各バリアントの ext フィールドにエンゲージメントデータを含める: 
{
  "variant_id": "promoted_post_running_community",
  "impressions": 85000,
  "spend": 4250,
  "clicks": 2550,
  "ctr": 0.03,
  "ext": {
    "upvotes": 1240,
    "comments": 87,
    "shares": 34,
    "saves": 156,
    "comment_sentiment": "positive"
  }
}
ext フィールドはプラットフォーム間で標準化されていない — 各プラットフォームが独自のエンゲージメントスキーマを定義します。複数のソーシャルプラットフォームにわたって集計するバイヤーはプラットフォーム固有のフィールドを共通モデルにマッピングすべきです。

​
Tier 2: アセットグループ最適化

バイヤーが selection_mode: "optimize" を持つフォーマットを使用して複数のアセット代替案を提供します。プラットフォームが組み合わせをテストし、どのアセットが選択されたかを示すマニフェストと共に各バリアントを返します。 
{
  "media_buy_id": "mb_12345",
  "currency": "USD",
  "reporting_period": {
    "start": "2026-01-20T00:00:00-05:00",
    "end": "2026-01-27T23:59:59-05:00",
    "timezone": "America/New_York"
  },
  "creatives": [
    {
      "creative_id": "summer_campaign_assets",
      "totals": {
        "impressions": 200000,
        "spend": 10000,
        "clicks": 8000,
        "ctr": 0.04
      },
      "variants": [
        {
          "variant_id": "var_headline_a_image_c",
          "manifest": {
            "format_id": {
              "agent_url": "https://creative.example.com",
              "id": "display_300x250"
            },
            "assets": {
              "headline_0_text": {
                "asset_type": "text",
                "content": "Summer Sale - 50% Off"
              },
              "image_0_url": {
                "asset_type": "image",
                "url": "https://cdn.brand.com/beach_hero.jpg",
                "width": 300,
                "height": 250
              }
            }
          },
          "impressions": 120000,
          "spend": 6000,
          "clicks": 6000,
          "ctr": 0.05
        },
        {
          "variant_id": "var_headline_b_image_d",
          "manifest": {
            "format_id": {
              "agent_url": "https://creative.example.com",
              "id": "display_300x250"
            },
            "assets": {
              "headline_0_text": {
                "asset_type": "text",
                "content": "Shop Summer Styles"
              },
              "image_0_url": {
                "asset_type": "image",
                "url": "https://cdn.brand.com/sunset_hero.jpg",
                "width": 300,
                "height": 250
              }
            }
          },
          "impressions": 80000,
          "spend": 4000,
          "clicks": 2000,
          "ctr": 0.025
        }
      ]
    }
  ]
}

​
Tier 3: ジェネレーティブクリエイティブ

プラットフォームがブランドマニフェストと入力コンテキストからバリアントを生成します。manifest には生成されたアセットが含まれる — バイヤーが提出したものとは完全に異なる場合があります。 パブリッシャーが AdCP コンテンツ標準を使用する場合、generation_context に特定のコンテンツ（記事、動画など）にバリアントをリンクする artifact 参照を含めることができます。プラットフォームはベンダー固有のコンテキスト構造のために ext を使用することもできます。 
{
  "media_buy_id": "mb_12345",
  "currency": "USD",
  "reporting_period": {
    "start": "2026-01-20T00:00:00-05:00",
    "end": "2026-01-27T23:59:59-05:00",
    "timezone": "America/New_York"
  },
  "creatives": [
    {
      "creative_id": "generative_banner",
      "totals": {
        "impressions": 300000,
        "spend": 15000,
        "clicks": 12000,
        "ctr": 0.04
      },
      "variants": [
        {
          "variant_id": "gen_mobile_morning",
          "generation_context": {
            "context_type": "web_page",
            "artifact": {
              "property_id": { "type": "domain", "value": "techreview.example.com" },
              "artifact_id": "article_semiconductor_trends_2026"
            },
            "topic": "technology, semiconductors",
            "device_class": "mobile"
          },
          "manifest": {
            "format_id": {
              "agent_url": "https://creative.example.com",
              "id": "display_300x250_generative"
            },
            "assets": {
              "hero_image": {
                "asset_type": "image",
                "url": "https://cdn.creative.example.com/generated/mobile_morning_v1.jpg",
                "width": 300,
                "height": 250
              },
              "headline": {
                "asset_type": "text",
                "content": "Start Your Summer Right"
              }
            }
          },
          "impressions": 180000,
          "spend": 9000,
          "clicks": 9000,
          "ctr": 0.05
        },
        {
          "variant_id": "gen_desktop_evening",
          "generation_context": {
            "context_type": "web_page",
            "topic": "lifestyle, evening entertainment",
            "device_class": "desktop"
          },
          "manifest": {
            "format_id": {
              "agent_url": "https://creative.example.com",
              "id": "display_728x90_generative"
            },
            "assets": {
              "hero_image": {
                "asset_type": "image",
                "url": "https://cdn.creative.example.com/generated/desktop_evening_v1.jpg",
                "width": 728,
                "height": 90
              },
              "headline": {
                "asset_type": "text",
                "content": "Evening Deals Await"
              }
            }
          },
          "impressions": 120000,
          "spend": 6000,
          "clicks": 3000,
          "ctr": 0.025
        }
      ]
    }
  ]
}

​
バリアントのプレビュー

request_type: "variant" を指定して preview_creative を使用し、特定のバリアントが配信時にどのように見えたかを確認します: 
{
  "request_type": "variant",
  "variant_id": "gen_mobile_morning"
}
各バリアントには完全な manifest が含まれているため、そのマニフェストを直接 preview_creative に渡して標準的な単一リクエストとして再レンダリングすることもできます。

​
配信レポートとの関係

タスクプロトコル提供する情報
get_media_buy_deliveryメディアバイWHERE と HOW MUCH: インプレッション、スペンド、プレースメントデータ、オプションの by_creative 内訳
get_creative_deliveryクリエイティブWHAT RAN と HOW: バリアントマニフェストとバリアントレベルのメトリクス
両方のレスポンスにわたってデータを相関させるために media_buy_id + creative_id を結合キーとして使用します。 セールスエージェントが両方のプロトコルを実装する場合、両方のタスクが同じエージェント URL で利用可能です。完全なパターンはセールスエージェントのクリエイティブ機能を参照。

​
クロスエージェント集計

複数のセラーにわたってキャンペーンを実施する場合、各エージェントで get_creative_delivery を個別に呼び出して結果を相関させる:
  • 結合キー: バイヤーが割り当てた creative_id を使用してエージェント間で同じクリエイティブを相関させる。アップロード時に concept_id を使用した場合、コンセプトでフィルタリングして関連するクリエイティブをグループ化します。
  • variant_id のスコープ: バリアント ID はエージェントとクリエイティブ内で一意であり、グローバルには一意ではありません。2つのエージェントが同じ variant_id 値を持つバリアントを生成する場合があります。集計ダッシュボードを構築する際はエージェント URL でプレフィックスを付ける。
  • タイムゾーン処理: 各エージェントは reporting_period.timezone を通じて独自のタイムゾーンでレポートする可能性があります。メトリクスを集計する前に共通のタイムゾーンに正規化します。
  • max_variants の選択: エージェントは max_variants が結果セットを制限する場合に返すバリアントを選択します。ほとんどのエージェントはインプレッション量（最も多く配信されたものが先）で優先度を付ける。代表的なサンプリングのためには、単一の大きな max_variants 値に頼るのではなく、異なる時間範囲で複数の呼び出しを行います。

​
クロスエージェントダッシュボードの構築

複数のエージェントからの配信データを統合ビューに集計する場合、以下の手順に従う:
  1. 収集: 同じ creative_ids フィルターを使用して、各エージェントで get_creative_delivery を並列に呼び出す。
  2. タイムゾーンの正規化: 合計する前に各エージェントの reporting_period を共通のタイムゾーンに変換します。
  3. creative_id でマージ: エージェント間で creative_id によって結果をグループ化します。totals（impressions、spend、clicks）を合計します。ctr などの派生メトリクスは平均しない — 合計されたコンポーネントから再計算します。
  4. variant_id にプレフィックス: agent_url + variant_id を組み合わせてグローバルに一意なバリアントキーを作成する（例: https://sales.pinnaclemedia-example.com/var_a1b2c3）。これにより、2つのエージェントが独立して同じバリアント ID を割り当てた場合の衝突を防ぐ。
  5. concept_id でグループ化: キャンペーンレベルのロールアップのために、concept_id を使用してサイズとセラーにわたる関連クリエイティブをグループ化します。コンセプトからクリエイティブへのマッピングは各エージェントの list_creatives から取得します。 
// 疑似コード: 3つのセラーから配信を集計
const agents = [pinnacle, novaSports, streamhaus];
const results = await Promise.all(
  agents.map(agent =>
    agent.getCreativeDelivery({
      creative_ids: ['acme_holiday_300x250'],
      start_date: '2026-11-01',
      end_date: '2026-11-15',
    })
  )
);

const merged = {};
for (const [i, result] of results.entries()) {
  if (result.errors) continue; // 失敗したエージェントをスキップ、後でリトライ
  for (const creative of result.creatives) {
    const key = creative.creative_id;
    if (!merged[key]) merged[key] = { impressions: 0, spend: 0, clicks: 0, variants: [] };
    merged[key].impressions += creative.totals.impressions;
    merged[key].spend += creative.totals.spend;
    merged[key].clicks += creative.totals.clicks || 0;
    for (const v of creative.variants || []) {
      merged[key].variants.push({
        ...v,
        variant_id: `${agents[i].url}/${v.variant_id}`, // グローバルに一意
      });
    }
  }
}
// 派生メトリクスを再計算
for (const c of Object.values(merged)) {
  c.ctr = c.impressions > 0 ? c.clicks / c.impressions : 0;
}

​
ケイパビリティ宣言

このタスクをサポートするエージェントは list_creative_formats レスポンスの capabilities 配列に "delivery" を宣言する: 
{
  "creative_agents": [{
    "agent_url": "https://ads.seller-example.com",
    "capabilities": ["validation", "assembly", "preview", "delivery"]
  }]
}
バイヤーはこれを list_creative_formats を呼び出してケイパビリティに "delivery" を持つエージェントの creative_agents 配列を確認することで発見します。これはセールスエージェントを含む、クリエイティブプロトコルを実装するすべてのエージェントに適用されます。