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.

ユニバーサルマクロを使うと、各パブリッシャーのアドサーバー実装を意識せずに、クリエイティブに動的なトラッキングデータを含められます。マクロはインプレッション時に実際の値へ置き換えられるプレースホルダーです。

​
概要

AdCP にクリエイティブアセットを渡す際、ユニバーサルマクロのプレースホルダーを次の場所に含められます。
  • インプレッショントラッキング URL
  • クリックトラッキング URL
  • VAST トラッキングイベント
  • ランディングページ URL
例: 
https://track.brand.com/imp?
  campaign={MEDIA_BUY_ID}&
  creative={CREATIVE_ID}&
  device={DEVICE_ID}&
  cb={CACHEBUSTER}
インプレッション時には次のようになります: 
https://track.brand.com/imp?
  campaign=mb_spring_2025&
  creative=cr_video_30s&
  device=ABC-123-DEF&
  cb=87654321

​
フォーマット別に利用可能なマクロ

クリエイティブフォーマットによって利用できるマクロが異なります。各フォーマットで利用可能なマクロは list_creative_formats で確認してください。

​
共通マクロ（すべてのフォーマット）

MacroDescriptionExample Value
{MEDIA_BUY_ID}AdCP のメディアバイ識別子mb_spring_2025
{PACKAGE_ID}AdCP のパッケージ識別子pkg_ctv_prime
{CREATIVE_ID}AdCP のクリエイティブ識別子cr_video_30s
{CACHEBUSTER}キャッシュを防ぐランダム番号87654321
{TIMESTAMP}ミリ秒単位の Unix タイムスタンプ1704067200000
{CLICK_URL}パブリッシャーのクリックトラッキング URL(営業エージェントが自動挿入)

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

法規制準拠のために重要 - ユーザープライバシーの選択を尊重するため、クリエイティブロジックにこれらを使用してください。
MacroDescriptionExample Value
{GDPR}GDPR の適用フラグ1 (適用あり), 0 (適用なし)
{GDPR_CONSENT}IAB TCF 2.0 コンセント文字列CPc7TgPPc7TgPAGABC...
{US_PRIVACY}米国プライバシー (CCPA) 文字列1YNN
{GPP_STRING}Global Privacy Platform コンセント文字列DBABMA~1...
{LIMIT_AD_TRACKING}追跡制限が有効かどうか1 (制限), 0 (許可)
例 - プライバシー対応のトラッキング: 
// クリエイティブロジック内
if (GDPR == 1 && GDPR_CONSENT == '') {
  // 同意なし - トラッキングピクセルを読み込まない
} else {
  // トラッキングを読み込む
}

​
デバイスと環境マクロ

MacroDescriptionExample Value
{DEVICE_TYPE}デバイスカテゴリmobile, tablet, desktop, ctv, dooh
{OS}オペレーティングシステムiOS, Android, tvOS, Roku
{OS_VERSION}OS バージョン17.2, 14.0
{DEVICE_MAKE}デバイスメーカーApple, Samsung, Roku
{DEVICE_MODEL}デバイスモデルiPhone15,2, Roku Ultra
{USER_AGENT}完全なユーザーエージェント文字列Mozilla/5.0 ...
{APP_BUNDLE}アプリのバンドル ID（ドメインまたは数値）com.publisher.app, 123456789
{APP_NAME}人が読みやすいアプリ名Publisher News App

​
地理情報マクロ

MacroDescriptionExample Value
{COUNTRY}ISO 3166-1 alpha-2 の国コードUS, GB, CA, FR, JP, AU
{REGION}州/都道府県/地域コードNY, CA (米国州), ON (カナダ), IDF (フランス), NSW (オーストラリア)
{CITY}都市名New York, London, Tokyo, Sydney
{ZIP}郵便番号10001 (米国), SW1A 1AA (英国), 75001 (フランス), 100-0001 (日本)
{DMA}Nielsen DMA コード（米国テレビ市場）501 (New York), 803 (Los Angeles)
{LAT}緯度40.7128, 51.5074, 35.6762
{LONG}経度-74.0060, -0.1278, 139.6503

​
アイデンティティマクロ

MacroDescriptionExample Value
{DEVICE_ID}モバイル広告 ID (IDFA/AAID)ABC-123-DEF-456
{DEVICE_ID_TYPE}デバイス ID の種別idfa, aaid

​
Web コンテキストマクロ

ウェブ在庫の場合:
MacroDescriptionExample Value
{DOMAIN}広告が表示されるドメインnytimes.com
{PAGE_URL}ページのフル URL（エンコード済み）https%3A%2F%2F...
{REFERRER}HTTP リファラー URLhttps://google.com
{KEYWORDS}ページキーワード（カンマ区切り）business,finance,tech

​
掲出面とポジションのマクロ

MacroDescriptionExample Value
{PLACEMENT_ID}グローバルプレースメント ID（IAB 標準）12345678
{FOLD_POSITION}ファーストビューとの位置（ディスプレイ）above_fold, below_fold
{AD_WIDTH}広告枠の幅300, 728
{AD_HEIGHT}広告枠の高さ250, 90

​
動画コンテンツマクロ

コンテンツ文脈を持つ動画フォーマット向け:
MacroDescriptionExample Value
{VIDEO_ID}コンテンツ動画の識別子vid_12345
{VIDEO_TITLE}コンテンツ動画のタイトルBreaking News Story
{VIDEO_DURATION}コンテンツの尺（秒）600
{VIDEO_CATEGORY}IAB コンテンツカテゴリIAB1 (Arts & Entertainment)
{CONTENT_GENRE}コンテンツジャンルnews, sports, comedy
{CONTENT_RATING}コンテンツレーティングG, PG, TV-14
{PLAYER_WIDTH}動画プレーヤーの幅1920
{PLAYER_HEIGHT}動画プレーヤーの高さ1080

​
動画広告ポッドマクロ

コマーシャルブレイク内の動画広告向け:
MacroDescriptionExample Value
{POD_POSITION}広告ブレイク内の順番1, 2, 3
{POD_SIZE}そのブレイクの広告総数3
{AD_BREAK_ID}一意の広告ブレイク識別子break_mid_1
Note: 動画フォーマットは [CACHEBUSTING], [TIMESTAMP], [DOMAIN], [IFA] など IAB VAST 4.x マクロ もサポートします。これらは VAST XML でネイティブに機能します。

​
AXE 連携

MacroDescriptionExample Value
{AXEM}AXE のコンテキストメタデータ（エンコード済み）eyJjb250ZXh0IjoiLi4uIn0=
Note: パブリッシャー固有のカスタムマクロが、各クリエイティブフォーマット仕様の extra supported macros として定義されている場合があります。

​
使用例

​
トラッキング付き動画クリエイティブ

{
  "creative_id": "cr_video_30s",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "video_30s_vast"
  },
  "assets": {
    "vast_xml": {
      "asset_type": "vast",
      "delivery_type": "inline",
      "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<VAST version=\"4.2\">\n  <Ad>\n    <InLine>\n      <Impression><![CDATA[https://track.brand.com/imp?buy={MEDIA_BUY_ID}&pkg={PACKAGE_ID}&cre={CREATIVE_ID}&device={DEVICE_ID}&domain={DOMAIN}&cb=[CACHEBUSTING]]]></Impression>\n      <Creatives>\n        <Creative>\n          <Linear>\n            <Duration>00:00:30</Duration>\n            <TrackingEvents>\n              <Tracking event=\"firstQuartile\"><![CDATA[https://track.brand.com/q1?buy={MEDIA_BUY_ID}&cb=[CACHEBUSTING]]]></Tracking>\n              <Tracking event=\"complete\"><![CDATA[https://track.brand.com/complete?buy={MEDIA_BUY_ID}&cb=[CACHEBUSTING]]]></Tracking>\n            </TrackingEvents>\n            <VideoClicks>\n              <ClickThrough><![CDATA[https://brand.com/spring?campaign={MEDIA_BUY_ID}]]></ClickThrough>\n            </VideoClicks>\n            <MediaFiles>\n              <MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"1920\" height=\"1080\">\n                <![CDATA[https://cdn.brand.com/videos/spring_30s.mp4]]>\n              </MediaFile>\n            </MediaFiles>\n          </Linear>\n        </Creative>\n      </Creatives>\n    </InLine>\n  </Ad>\n</VAST>",
      "vast_version": "4.2"
    }
  }
}
ポイント:
  • AdCP マクロ（{MEDIA_BUY_ID}）と VAST マクロ（[CACHEBUSTING]）を組み合わせます
  • AdCP マクロは {波括弧} を使います
  • VAST マクロは [角括弧] を使います
  • 両方を同時に問題なく利用できます

​
トラッキング付きディスプレイクリエイティブ

{
  "creative_id": "cr_banner_300x250",
  "format_id": {
    "agent_url": "https://creative.adcontextprotocol.org",
    "id": "display_banner_300x250"
  },
  "assets": {
    "banner_image": {
      "url": "https://cdn.brand.com/banners/spring_300x250.jpg",
      "width": 300,
      "height": 250
    },
    "click_url": "https://brand.com/spring?campaign={MEDIA_BUY_ID}&creative={CREATIVE_ID}",
    "impression_trackers": [
      "https://track.brand.com/imp?buy={MEDIA_BUY_ID}&cre={CREATIVE_ID}&cb={CACHEBUSTER}"
    ]
  }
}
ポイント:
  • クリックとインプレッション URL にユニバーサルマクロを使用します
  • {CACHEBUSTER} を追加してキャッシュを防ぐ
  • 必要に応じてプライバシーマクロ（{GDPR} など）を追加します

​
ランディングページのパーソナライズ

<a href="https://brand.com/offer?
  buy={MEDIA_BUY_ID}&
  pkg={PACKAGE_ID}&
  device={DEVICE_TYPE}&
  country={COUNTRY}">
  Shop Now
</a>
ポイント:
  • リダイレクトやバックエンド処理なしで URL パラメーターをパーソナライズします
  • デバイスや地域に応じてコンテンツを最適化できます

​
実装のヒント

  • サポート有無を確認する: 各フォーマットの supported_macros と extra_supported_macros を確認します
  • 重複エンコードを避ける: URL を二重エンコードしない（例: {PAGE_URL} は既にエンコード済み）
  • フォールバックを用意する: マクロ値が提供されない場合に備え、デフォルト値やロジックを用意します
  • プライバシー対応を徹底する: {GDPR} や {LIMIT_AD_TRACKING} を尊重してトラッキングを制御します
  • テストする: preview_creative や sync_creatives の dry_run でマクロ置換を検証します

​
関連ドキュメント