マクロは、URL (クリエイティブにあるものなど) に有用な情報を設定するために使用されます。 これらは基本的に、広告呼び出し時の実際の値が何であれ、広告サーバーによって拡張される変数です。
このページには、サポートされているすべてのマクロに関する情報が含まれています。 マクロごとに、広告呼び出し中にマクロが置き換えられる情報を一覧表示します。
ヒント
URL エンコードとデコードの詳細については、「 関数マクロ」のセクションを参照してください。
クリエイティブをアップロードする際にマクロを > 使用する方法のその他の例については、「 クリエイティブ サービス」 ページを参照してください。
クリエイティブ マクロ
警告
クリエイティブ サービスを使用してクリエイティブを追加する場合、OpenRTB マクロ (${AUCTION_PRICE} など) はサポートされていません。 これらは、 入札応答でのみサポートされます。
Xandr では、 クリエイティブ サービスを使用してクリエイティブを追加する際に、次のクリエイティブ マクロがサポートされます。
| マクロ | 説明 |
|---|---|
${CLICK_URL} |
クリック トラッキング URL。 |
${CLICK_URL_ENC} |
エンコードされたクリック トラッキング URL (一部のサード パーティの広告サーバーにのみ必要) |
${AUCTION_ID} |
インプレッションにつながった特定のオークションの一意の 64 ビット識別子。 入札要求の各 placement_id には独自の一意のオークション ID があり、この ID はそのプレースメントの対応する入札応答とも一致します。このマクロは、調整と不一致の追跡に推奨されます。 |
${TAG_ID} |
入札要求を発信した Xandr TinyTag ID |
${EXT_APP_ID} |
インプレッションを要求するアプリケーションの外部識別子。 これは、モバイル アプリからのインプレッションに最も役立ちます。 |
${CREATIVE_ID} |
インプレッションを獲得したクリエイティブ ID。 |
${DEAL_ID} |
落札に関連付けられた Xandr 取引 ID (該当する場合)。 取引がない場合、0 が返されます。 |
${ECP} |
パブリッシャー側のオークションの推定クリア価格。 |
${RESERVE_PRICE} |
パブリッシャーが設定した予約価格。 |
${SESSION_FREQ} |
ユーザーのセッションの頻度。 |
${AGE} |
ユーザーの年齢 (可能な場合)。 整数 (例: 26) または 0。 |
${GENDER} |
ユーザーの性別 (利用可能な場合)。 値は 'f'、'm'、'u' です。 |
${CACHEBUSTER} |
URL キャッシュを防ぐために、ランダムに生成される文字列。 この値は入札応答ごとに 1 回生成されるため、入札要求に複数の placement_id 値が含まれている場合は、それら全体で同じキャッシュバスター値が使用されます。調整と不一致の追跡には、代わりに ${AUCTION_ID} を使用することをお勧めします。 |
${PRICE_PAID} |
このインプレッションに対して支払われた対価。 (値下げ前の入札とは対照的です。) |
${SECOND_PRICE} |
オークションで 2 番目に高い入札額を表す価格。 浮動小数点数形式で表されます (例: 1.23) |
${REFERER_URL} |
使用可能な場合は、このインベントリの参照 URL。 注: このフィールドは非推奨です (2016 年 5 月現在)。 代わりに ${REFERER_URL_ENC} を使用してください。 |
${REFERER_URL_ENC} |
エンコードされた参照 URL。 |
${BID_PRICE} |
値下げ後に支払われた価格とは対照的に、このインプレッションに対する入札単価。 |
${TAG_CODE1} |
配置に設定された統合コード。 |
${TAG_CODE2} |
配置に設定された追加の統合コード。 |
${INV_SOURCE_ID} |
非推奨です。 |
${USER_ID} |
インプレッションのユーザーを表す Xandr の 64 ビット文字列。 |
${USER_IP} |
ユーザーの IP アドレス。 |
${IS_PREVIEW} |
クリエイティブを "プレビュー" している場合は、サードパーティのサーバーにフラグを渡して、製品を運用中のインプレッションとしてカウントしないようにすることができます。 true の場合、"1" を渡します。false の場合、"0" を渡します。 |
${SELLER_MEMBER_ID} |
インプレッションが発生したパブリッシャーを所有するメンバー。 |
${SEG_IDS} |
このユーザーの Cookie 内の勝利した購入者に属するセグメントの ID (最終表示時刻の順)。 このマクロは、共有セグメント (サード パーティのデータ プロバイダーが所有するセグメントなど) では機能しないことに注意してください。 |
${SEG_CODES} |
このユーザーの Cookie 内の勝った購入者に属するセグメントのコード (最終表示時刻の順)。 このマクロは、共有セグメント (サード パーティのデータ プロバイダーが所有するセグメントなど) では機能しないことに注意してください。 |
${DATACENTER} |
データ センター ID (1 = NYM、2 = LAX、3 = AMS) |
${USER_CITY} |
ユーザーの市区町村の文字列 |
${USER_STATE} |
ユーザーの状態を示す文字列 (2 文字の省略形。FIPS 10-4 米国およびカナダ以外) |
${SITE_ID} |
インプレッションが配信されているサイトの ID |
${PUBLISHER_ID} |
インプレッションを販売しているパブリッシャーの ID |
${PUBLISHER_CODE} |
インプレッションを販売しているパブリッシャーのコード (利用可能な場合) |
${CREATIVE_CODE} |
提供されるクリエイティブのコード (利用可能な場合) |
${CREATIVE_SIZE} |
幅 x 提供されるクリエイティブの高さ (例: "300x250") |
${WIDTH} |
提供されるクリエイティブの幅 |
${HEIGHT} |
提供されるクリエイティブの高さ |
${SUPPLY_TYPE} |
このマクロには、インプレッションのサプライ タイプを示す数値が設定されます。 許可される値は次のとおりです。 0: web 1: モバイル Web 2: モバイル アプリ 4: ツール バー |
${TIMESTAMP} |
オークションの UNIX タイムスタンプ。 |
${USER_AGENT} |
要求の HTTP ヘッダーからのユーザー エージェント文字列。 ユーザーエージェントは、多くの場合、ユーザーに代わって動作するアプリケーション、オペレーティングシステム、およびソフトウェアベンダーなどの情報を識別します(例:「Mozilla/5.0 (Macintosh;U;Intel Mac OS X 10.5;en-US;rv:1.9.0.4) Gecko/2008102920 Firefox/3.0.4")。 |
${USER_AGENT_ENC} |
要求の HTTP ヘッダーからエンコードされたユーザー エージェント文字列。 |
${EXTENDED_IDS} |
識別子 (業界 ID とパブリッシャーが提供する ID) は、インプレッションのユーザーを表します。 これらは、要求で受信したときに渡され、次の形式に従って複数の識別子がサポートされます。 …&extended_ids=<source_1>,<id_1>\ <source_2>,<id_2>\ …提案される区切り記号は、ソースと値の間のコンマ、および異なる ID 型と値ペアの間のパイプ記号です。 |
欧州の広告在庫と通知の提供、透明性、選択肢
警告
お客様が米国の州プライバシー法、GDPR、および既存の ePrivacy 指令に基づく透明性、通知、選択/同意要件を満たすために、Xandr は IAB Europe Transparency & Consent Framework (以下「フレームワーク」) をサポートしています。
これは、マクロを使用して、該当する米国の州および EEA に所在するエンド ユーザーに通知、透明性、選択を表示し、承認されたベンダーに信号を送り、必要に応じて Xandr のプラットフォームを通じて Xandr および需要ソースとそのベンダーに同意および/または共有/販売しないシグナルを渡すためのリファレンスです。
このリソースは法的なアドバイスとして解釈されるべきではなく、Xandr は法律または規制への準拠を保証するものではありません。 企業とその個人データの収集、使用、および保存は各社により異なるため、米国の州法、GDPR および既存の eプライバシー指令を含む欧州の規制に基づく義務に関する独立した法的助言も求める必要があります。 あなたの状況に合わせた法的アドバイスを提供できるのは弁護士だけです。 このガイドのいずれの内容も、お客様のビジネスに合わせた法的アドバイスを提供することを目的としたものではなく、また、その代わりに使用されるべきものではありません。
当社の サービス ポリシーの一部 (購入、販売、およびデータ プロバイダー向け) には、お客様が知っておくべきプライバシー固有の義務が含まれていることに注意してください。 これらのサービス ポリシーは、2023 年 1 月 1 日に更新されました。
| マクロ | 説明 |
|---|---|
${GDPR_APPLIES} |
GDPR 規制が適用されるかどうかを指定します。 具体的には、ユーザーが GDPR の影響を受ける国または地域にいるかどうか、または要求と共に渡された GDPR 必須のシグナルがあるかどうかを示します。 はいの場合は 1、いいえの場合は 0。 |
${GDPR} |
${GDPR_APPLIES} と同じ機能を提供します。 |
${GDPR_CONSENT_STRING} |
これは IAB GDPR の同意文字列です。 GDPR が適用される場合は、 IAB GDPR の透明性と同意フレームワークに基づいて、ユーザーが承認したベンダーの一覧が表示されます。 |
${GDPR_CONSENT} |
これは、TCF 1.0 公式仕様に従った IAB GDPR 同意文字列です。 クライアントの利便性を考慮して下位互換性を維持するために含まれています。 |
${GDPR_CONSENT_[0-9]+} |
たとえば、GDPR_CONSENT_1、GDPR_CONSENT_12345 などです。これらはすべて、前述の '${GDPR_CONSENT_STRING}' と同じ GDPR 同意文字列に解決されます。 |
${GPP_SID} |
グローバル プライバシー プラットフォームのセクション (つまり、規制のフレームワーク) を適用する必要があるかどうかを指定します。 具体的には、ユーザーが GPP の対象となる法律の影響を受ける国または地域に居住しているかどうかを示します。 |
${GPP_STRING_XXXXX*} |
これは、IAB グローバル プライバシー プラットフォーム (GPP) の文字列です。 GPP のセクションが適用される場合、これにはユーザーの同意の選択を反映するフレームワークに依存する情報が含まれます。 注: * XXXXX は任意の数値 ID を表します |
次の表には、入札者クライアントが使用しない予約済みマクロ名が含まれています。 これらは他の Xandr テクノロジと競合するため、カスタム マクロには使用されません。
| 予約済みマクロ名 |
|---|
${ADV_CODE} |
${ANCOST} |
${BASE64_UID_ENC} |
${BASE64_UID} |
${BIDPRICE} |
${CND} |
${CONTENT} |
${CREATIVE_HEIGHT} |
${CREATIVE_WIDTH} |
${FLASH_BACKUP_URL} |
${FLASHVARS} |
${IE7_FLASH_JS_URL} |
${IF_CALLBACK_URL} |
${IO_CODE} |
${IO_ID} |
${IS_PREVIEW_COL} |
${IT_CALLBACK_URL} |
${MATCHED_PROFILE_CODE} |
${MATCHED_PROFILE_ID} |
${MEDIA_SUBTYPE} |
${MEDIA_TYPE} |
${MEDIA_URL_ENC} |
${MEDIA_URL} |
${PMT_RULE_CODE} |
${POP_CALLBACK_URL} |
${POP_CREATIVE_MAXIMIZED} |
${POP_IS_PREPOP} |
${POP_IS_TAG_INITIATED} |
${POP_WINDOW_LOCATION} |
${POP_WINDOW_MENUBAR} |
${POP_WINDOW_RESIZABLE} |
${POP_WINDOW_SCROLLBARS} |
${POP_WINDOW_STATUSBAR} |
${POP_WINDOW_TITLE} |
${POP_WINDOW_TOOLBARS} |
${PRICE_PAID_ENCR} |
${PT1} |
${PT2} |
${PT3} |
${PT4} |
${PT5} |
${SECOND_LEVEL_CATEGORY_ID} |
${SEG_CODES_COL} |
${SITE_CODE} |
${SSP_DATA} |
${TAG_HEIGHT} |
${TAG_WIDTH} |
${TOP_LEVEL_CATEGORY_ID} |
${TRACKER_ID} |
${UID} |
${USER_COUNTRY} |
${VENUE_ID} |
モバイル マクロ
| マクロ | 説明 |
|---|---|
${GEO_LAT} |
モバイル デバイスから GPS データを利用できる場合のユーザーの位置の緯度。 "snn.ddd,snn.ddd" の形式で表されます (例: +12.345 または -45.123)。ここで、南は負として表されます。 精度は小数点以下最大 5 桁です。 |
${GEO_LON} |
モバイル デバイスから GPS データを利用できる場合のユーザーの現在地の経度。 "snn.ddd,snn.ddd" の形式で表されます (例: +12.345 または -45.123)。ここで、西は負として表されます。 精度は小数点以下最大 5 桁です。 |
${EXT_APP_ID} |
インプレッションを要求するアプリケーションの外部識別子。 これは、モバイル アプリからのインプレッションに対してのみ役立ちます。 |
${DEVICE_MD5} |
モバイル デバイスを表す MD5 暗号化された一意の識別子。 |
${DEVICE_SHA1} |
モバイル デバイスを表す SHA1 で暗号化された一意の識別子。 |
${DEVICE_OPENUDID} |
モバイル デバイスを表す OPENUDID で暗号化された一意の識別子。 |
${DEVICE_ODIN} |
モバイル デバイスを表す ODIN 暗号化された一意の識別子。 |
${DEVICE_AAID} |
インプレッションが Android デバイスからのものである場合の Android 広告識別子。 |
${DEVICE_APPLE_IDA} |
インプレッションが Apple デバイスからのものである場合の Apple 広告識別子。 |
${DEVICE_MAKE_ID} |
モバイル デバイスメーカーの ID を表す Xandr 整数 (例: 26)。 モバイル デバイスの製造 ID の完全な一覧については、 デバイス製造サービスを参照してください。 |
${DEVICE_MODEL_ID} |
モバイル デバイス モデルの ID を表す Xandr 整数 (例: 301)。 モバイル デバイス モデル ID の完全な一覧については、 デバイス モデル サービスを参照してください。 |
${DEVICE_WIN_ID} |
このインプレッションが発生したデバイスの Windows 広告 ID (該当する場合)。 |
${CARRIER_ID} |
携帯電話会社 ID を表す Xandr 整数。 携帯電話会社 ID の完全な一覧については、「 キャリア サービス」を参照してください。 |
${SUPPLY_TYPE} |
このマクロには、インプレッションのサプライ タイプを示す数値が設定されます。 許可される値は次のとおりです。 0: web 1: モバイル Web 2: モバイル アプリ 4: ツール バー |
関数マクロ
関数マクロ。別のマクロで機能を実行する特別な種類のマクロです。 関数マクロは、カスタム マクロを含む他のクリエイティブ マクロと組み合わせて使用できますが、レンダリング時に認識されない場合は変換されず、関数は呼び出されません。
Xandr は現在、エンコードに関連するさまざまな目的に使用できる {$URL_ENC} 関数マクロをサポートしています。 主な使用例は、クリエイティブマクロを使用して広告サーバーから広告サーバーに URL を渡す必要があり、標準の URL フォーマットでサポートされていない文字が存在するために、プロセスのさまざまな手順でエンコードする必要がある場合です。
このマクロは、次のような形式になります。
${URL_ENC(${MACRO_NAME},#)}
ここで、 ${MACRO_NAME} はエンコードするマクロ、# はコンテンツをエンコードする回数を表す整数の 1、 2、または 3 です。 3 つを超えるエンコードはサポートされていないことに注意してください。
注:
それぞれのエンコーディングはリダイレクト チェーン内のステップに対応しており、サードパーティ製のクリック トラッカーがマクロとどのように連携しているかに対応しています。 通常、2 つ目の広告サーバーが関係している場合は最終ページ リンク先 URL にダブル エンコードが必要になり、3 つ目の広告サーバーの場合はトリプル エンコードが必要になります。
エンコードのどれがシングルか、ダブルか、トリプルかを判断するには、サードパーティのクリック トラッカーでチェックし、URL_ENC マクロが動作するかテストします。 マクロが機能しない場合、その結果としてリンクが壊れ、ユーザーが意図したリンク先 URL に到達できなくなる可能性があります。
エンコードの例
URL をエンコードするには、一度クリックします
${URL_ENC(${CLICK_URL},1)}
https://xandr.comがクリック URL として渡された場合、${URL_ENC(${CLICK_URL},1)} を使用して URL をシングル エンコードすると、https%3A%2F%2Fxandr.comがクリエイティブに設定されます。
メディア URL を 1 回エンコードするには:
${URL_ENC(${MEDIA_URL},1)}
メディア URL を 2 回エンコードするには:
${URL_ENC(${MEDIA_URL},2)}
ADFORMAT というカスタム マクロを一度エンコードするには:
${URL_ENC(${ADFORMAT},1)}