Xandr マクロ
マクロは、URL (クリエイティブに含まれるものなど) に役立つ情報を設定するために使用されます。 これらは基本的に、広告呼び出し時に実際の値が何であれ、広告サーバーによって拡張される変数です。
このページには、サポートされているすべてのマクロに関する情報が含まれています。 各マクロについて、広告呼び出し中にマクロがに置き換えられる情報を一覧表示します。
ヒント
URL エンコードとデコードの詳細については、「 関数マクロ」のセクションを参照してください。
クリエイティブのアップロード時にマクロを使用する > 方法の他の例については、 クリエイティブ サービス のページを参照してください。
警告
クリエイティブ サービスを使用してクリエイティブを追加する場合、OpenRTB マクロ (}など${AUCTION_PRICE
) はサポートされません。 これらは 入札応答でのみサポートされます。
Xandr では、 クリエイティブ サービスを使用してクリエイティブを追加するときに、次のクリエイティブ マクロがサポートされます。
マクロ | 説明 |
---|---|
${CLICK_URL} |
クリック追跡 URL。 |
${CLICK_URL_ENC} |
エンコードされたクリック追跡 URL (一部のサード パーティの広告サーバーにのみ必要) |
${AUCTION_ID} |
インプレッションにつながった個々のオークションを表す 64 ビットの文字列。 |
${TAG_ID} |
Bid Request を開始した Xandr TinyTag ID |
${EXT_APP_ID} |
インプレッションを要求するアプリケーションの外部識別子。 これは、モバイル アプリからのインプレッションに最も役立ちます。 |
${CREATIVE_ID} |
インプレッションを獲得したクリエイティブ ID。 |
${DEAL_ID} |
落札に関連付けられている Xandr Deal ID (該当する場合)。 取引がない場合、0 が返されます。 |
${ECP} |
公開元側のオークションの見積クリア価格。 |
${RESERVE_PRICE} |
パブリッシャーによって設定された予約価格。 |
${SESSION_FREQ} |
ユーザーのセッション頻度。 |
${AGE} |
ユーザーの年齢 (使用可能な場合)。 整数 (例: 26) または 0。 |
${GENDER} |
ユーザーの性別 (使用可能な場合)。 値は 'f','m','u' です。 |
${CACHEBUSTER} |
URL のキャッシュを制限するために使用される乱数文字列 |
${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} |
このユーザーのクッキー(最後に見た時間の順に)で、当選した購入者に属するセグメントの 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 型と値のペア間のパイプ 記号です。 |
警告
Xandrは、米国の州プライバシー法、GDPR、既存のePrivacyディレクティブに基づく透明性、通知、および選択/同意要件を満たすために、 IABヨーロッパ透明性 & 同意フレームワーク (「フレームワーク」)をサポートしています。
これは、公開元がマクロを使用して、該当する米国の州と EEA に配置されているエンド ユーザーに通知、透明性、選択を示し、承認されたベンダーに通知する場合、および Xandr と需要元と Xandr のプラットフォームを通じて必要なパス同意や Do Not Share/Sell シグナルを Xandr とデマンド ソースとそのベンダーに通知する場合のリファレンスです。
このリソースは法的アドバイスとして解釈されるべきではありません。Xandr は、法律や規制の遵守について保証しません。 すべての企業とその個人データの収集、使用、保管が異なるため、米国の州法、欧州の規制 (GDPR や既存の ePrivacy ディレクティブを含む) に基づく義務に関連する独立した法的アドバイスも求める必要があることに注意してください。 あなたの状況に合わせて特別に調整された法的アドバイスを提供できるのは弁護士だけです。 このガイドでは、ビジネスに合わせて調整された法的アドバイスを提供することを目的としたものではありません。または、代替として使用する必要があります。
サービス ポリシーの一部 (購入、販売、およびデータ プロバイダー向け) には、お客様が注意する必要があるプライバシー固有の義務が含まれています。 これらのサービス ポリシーは、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 同意文字列に '${GDPR_CONSENT_STRING}' 解決されます。 |
${GPP_SID} |
グローバル プライバシー プラットフォームのセクション (規制フレームワーク) を適用するかどうかを指定します。 具体的には、ユーザーがGPPの対象となる法律の影響を受ける国にいるかどうかを示します。 |
${GPP_STRING_XXXXX*} |
これは IAB グローバル プライバシー プラットフォーム (GPP) 文字列です。 GPP のセクションが適用される場合、これには、ユーザーの同意の選択を反映したフレームワークに依存する情報が含まれます。 注: * XXXXX は、任意の数値 ID を表すことができます |
次の表に、Bidder クライアントで使用されない予約済みマクロ名を示します。 これらは他の 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" (例: または -45.123 ) の形式で表され、 +12.345 south は負の値として表されます。 小数点以下最大 5 桁の有効桁数を指定できます。 |
${GEO_LON} |
モバイル デバイスから GPS データを利用できる場合の、ユーザーの位置情報の経度。 "snn.ddd,snn.ddd" (例: +12.345 または -45.123 ) の形式で表されます。west は負の値として表されます。 小数点以下最大 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 Make Service」を参照してください。 |
${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_ENC(${CLICK_URL},1)}
がクリック URL として渡された場合 https://xandr.com
は、 を使用して ${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 というカスタム マクロを 1 回エンコードするには:
${URL_ENC(${ADFORMAT},1)}