巨集

巨集是廣告素材程式碼中的特殊字串。Google Ad Manager 之後會根據廣告素材設定，以其他的值或程式碼取代這個字串。巨集相當實用，因為在需要進行變更時，您不用直接更新廣告素材程式碼，只要更新巨集參照即可。

瞭解並正確使用巨集，對於解決常見的網址相關問題非常重要，例如上傳網址時發生錯誤、Urchin 流量監視器 (UTM) 參數遭到捨棄、重新導向不正確，以及確保網址中的字元有效。舉例來說，%epid! 巨集可用於在到達網頁網址中動態加入廣告單元 ID，協助解決重新導向或追蹤不正確的問題。

關於巨集的重要注意事項

區分大小寫
巨集的寫法有大小寫之分。請使用全大寫的 %%CACHEBUSTER%%，不要寫成 %%Cachebuster%%。
未逸出和逸出展開
未逸出和逸出的巨集版本會以不同方式展開。進一步瞭解如何使用逸出和未逸出的巨集。
巨集插入
如果是第三方廣告素材或 VAST 廣告代碼網址，只要 Ad Manager 辨識出第三方，就會自動插入巨集。如果是自訂廣告素材和廣告素材範本，您必須手動加入巨集。要是您不確定該將巨集放在何處，請與您的廣告素材廠商聯絡。
使用廣告素材範本進行廣告投放時，只有在範本中使用 Click 巨集，才會顯示輸入的到達網址。
保留的字元和網址編碼 (百分比符號編碼)
Ad Manager 會保留前方加上百分比符號的特定小寫字元：
%a %c %h %i %n %p %k

請不要在網址編碼中使用這些字串，以免干擾巨集展開。
程式輔助直接交易不支援巨集
請參閱程式輔助直接交易可用功能。

跳至清單中的特定巨集

我們針對每個巨集提供了建議用法，但您可依據實際需求將巨集應用在各種用途中。只要是廣告伺服器在放送廣告時處理到的程式碼，都可以加入巨集。這類程式碼包括：第三方或自訂廣告素材程式碼、Studio 程式碼、到達網址或廣告代碼。

顯示巨集
廣告單元
 到達網頁網址
 檔案伺服器
 高度與寬度
 模式比對
 代碼參數
 在新視窗中開啟目標
 目標視窗
 兒童導向內容通報標記
 年齡處理標記
 廣告素材範本專用的 URI 編碼

追蹤巨集
Cachebuster (隨機數字)
點擊
 展開
 裝置 ID (iOS、Android、Roku 和 tvOS)
預覽模式
 配置
 網站
 已瀏覽曝光

GDPR 的廣告請求巨集
GDPR
資訊公開和同意聲明字串
 額外同意聲明模式
 未滿法定同意年齡的歐洲經濟區和英國使用者

影片巨集
影片廣告長度 (以秒為單位)
影片廣告時間長度 (以毫秒為單位)
影片內容描述網址
 影片參照網址
 曝光有效期間

影片內容巨集
影片長度 (以毫秒為單位)
影片 ID
影片中繼資料
 內容來源 ID
自訂廣告 ID (FreeWheel)
IAB 類別 (FreeWheel)

請參閱動態廣告插播巨集 (DAI) 清單。

全部展開全部收合

顯示巨集

這類巨集經常用於顯示廣告素材，以確保廣告素材正確顯示並正常運作。

廣告單元

巨集
`%%ADUNIT%%`

廣告單元巨集會在廣告素材放送時，將 Google 發布商廣告代碼中的廣告單元路徑插入廣告素材程式碼中。

將 ADUNIT 巨集新增至第三方廣告素材程式碼片段的方法如下：

<script type="text/javascript">

  document.write('<sc'+'ript type="text/javascript" src="http://www.3rdparty.com/?dfpAdUnit=%%ADUNIT%%"></scr'+'ipt>');

  </script>

廣告單元巨集會展開為原始廣告請求中的完整廣告單元路徑，其中包括聯播網代碼。以下舉例說明廣告放送時，廣告單元路徑會如何展開：

<script type="text/javascript"> document.write('<sc'+'ript type="text/javascript" src="http://www.3rdparty.com/?dfpAdUnit=/1234/site/section"<>/scr'+'ipt>'); </script>

這個巨集只適用於已獲准的建議廣告單元。如果建議的廣告單元位於第 3 層，巨集置入廣告素材程式碼片段中以後，只會展開成第 2 層的廣告單元。建議的廣告單元獲得核准後，巨集才會在廣告素材程式碼片段中展開成第 3 層的廣告單元。

到達網頁網址

巨集	逸出級別
`%%DEST_URL_ESC%%`	逸出
`%%DEST_URL_ESC_ESC%%`	雙重逸出
`%%DEST_URL_UNESC%%`	未逸出

到達網頁網址巨集會展開成廣告素材的到達網址，而這可以是委刊項的到達網址，也可以是委刊項內廣告素材的取代到達網址。

到達網頁網址巨集適用於自訂廣告素材及廣告素材範本。如果您需要在廣告素材程式碼中置入廣告素材的到達網址，而到達網址會隨廣告素材或範本的套用目標委刊項改變，這個巨集就能派上用場。

到達網址巨集共有 3 種：逸出、雙重逸出和未逸出。一般來說，逸出次數 (只加上 ESC 一次、兩次或者完全不加) 取決於第三方點擊追蹤公司。有些第三方點擊追蹤公司會要求網址進行逸出，有些則無相關規定。第三方點擊追蹤公司要求的逸出級別通常是在廣告代碼中指定，方法是在 Ad Manager 的第三方廣告代碼或自訂廣告素材程式碼中加入 click= 字串：

click=：逸出一次 (%%DEST_URL_ESC%%)。
click0=：不要逸出 (%%DEST_URL_UNESC%%)。
click1=：逸出一次 (%%DEST_URL_ESC%%)。
click2=：逸出兩次 (%%DEST_URL_ESC_ESC%%)。

Ad Manager 也支援 %%DEST_URL%%，這個巨集的功用與 %%DEST_URL_ESC%% 相同。為求明確起見，建議您使用 %%DEST_URL_ESC%%，但不需重新編寫舊廣告素材和範本的程式碼。

如果範本程式碼片段包含 %u 或 %%DEST_URL%% 巨集，當您點按廣告素材時，系統會將您導向 xsd:string 網址；長度上限為 1024 個半形字元。

檔案伺服器

巨集
`%%FILE:file_display_name%%`

檔案伺服器巨集 %%FILE:file_display_name%% 會展開成已上傳的廣告素材資源的完整網址。您可以在自訂廣告素材程式碼中使用這個巨集，呼叫已上傳的素材資源 (例如圖片)。

如要使用這個巨集，請將 file_display_name 換成廣告素材資源的顯示名稱；您可以在 Ad Manager 的廣告素材詳情頁面中找到這個顯示名稱。

高度與寬度

巨集
`%%HEIGHT%%`
`%%WIDTH%%`

這些巨集會在廣告放送期間，根據 Ad Manager 中「指定廣告單元大小」欄位所定義的值，將廣告素材高度與寬度插入廣告素材的自訂程式碼中。

如果要建立廣告素材範本供各種大小的廣告素材重複使用，「高度」與「寬度」巨集就格外實用。您不須事先設定好每種廣告素材的大小，只要讓高度與寬度巨集根據實際需求，將高度與寬度值插入所有廣告素材即可。

模式比對

巨集
`%%PATTERN:key%%`
`%%PATTERN:TARGETINGMAP%%`
`%%PATTERN:url%%`

模式比對巨集可協助您將一或多個自訂變數 (例如指定值) 傳送給廣告素材。您可以使用這個巨集傳送鍵/值、取代整個指定字串或展開參照網址。如果您想根據自己掌握到的使用者相關資訊 (例如使用者喜歡的內容類別) 放送不同的廣告素材，可選擇使用這個巨集。

每個廣告素材最多只能包含 100 個替換模式比對巨集。

逸出模式比對巨集

模式比對巨集會照原樣傳回所收到的值。如果您在其中一個網址欄位 (例如影片廣告素材中的 [VAST 廣告代碼網址] 或 [第三方追蹤網址] 欄位) 中使用這個巨集，可能會希望展開的值以逸出形式傳回。若要達成這個目標，您需要在請求中讓這個值三重逸出。

%%PATTERN:key%%

舉例來說，假設某個委刊項有兩個廣告素材，分別針對男性和女性使用者設計。巨集中所使用的「鍵」必須是英數字元或底線 (_)。

整個巨集的運作流程如下：

系統使用鍵/值，將自訂值 (在此為使用者的性別資訊) 傳送至網頁的廣告代碼中：
googletag.defineSlot("/1234/adunit1/adunit2", [728, 90], "div-gpt-ad-123456789-0") .addService(googletag.pubads()) .setConfig({targeting: {gender: "male"}});
在自訂或第三方廣告素材中，運用以下巨集動態傳送自訂值 (使用者的性別)：<一些廣告素材指令碼>...&gender=%%PATTERN:gender%%
整個 %%PATTERN:gender%% 巨集會由「male」取代。
Ad Manager 會呼叫「male」廣告素材檔案，並向這位使用者放送。

%%PATTERN:TARGETINGMAP%%

您可以使用 %%PATTERN:TARGETINGMAP%% 取代整個指定對應，並且動態建立回傳式曝光代碼。

將 TARGETINGMAP 巨集新增至廣告代碼的方法如下：

.setConfig({targeting: %%PATTERN:TARGETINGMAP%% }).display();

下面是廣告獲得放送時的完整鍵/值字串範例：

.setConfig({targeting: {"key1":["value1"], "key2": ["value2","value3"]} }).display();

兩個 Ad Manager 聯播網之間的回傳式曝光代碼範例

您可以使用這個巨集，建立兩個 Ad Manager 聯播網 (聯播網 A 與聯播網 B) 之間的回傳式曝光代碼。

以下是 Ad Manager 聯播網 A 中預訂的廣告素材範例：

<script type='text/javascript' src='http://www.googletagservices.com/tag/js/gpt.js'>

    const slot = googletag.pubads().defineSlot('/network_B/Homepage', [468, 60])

 .addService(googletag.pubads());

slot.setConfig({targeting:"myAdUnit", "%%ADUNIT%%")});

    slot.setConfig({targeting: %%PATTERN:TARGETINGMAP%% });

    slot.display();

    </script>

如果沒有任何已售出的廣告活動可以放送，Ad Manager 聯播網 B 可以透過下方的回傳式曝光廣告素材將曝光歸還給聯播網 A：

<script src='//www.googletagservices.com/tag/js/gpt.js'>

    const slot = googletag.pubads()

     .defineSlot('%%PATTERN:myAdUnit%%', [468, 60])

 .addService(googletag.pubads());

slot.setConfig({targeting: %%PATTERN:TARGETINGMAP%%});

    slot.setConfig({targeting: {"kwd": "noloop"}}); // to avoid infinite loops

    slot.display();

    </script>

Ad Manager 和第三方廣告伺服器之間的回傳式曝光代碼範例

在傳送給第三方廣告伺服器的請求中，您也可以在回傳式曝光代碼中使用 TARGETINGMAP，以便在動態廣告素材中使用多個值。

以下是 Ad Manager 中的預訂廣告素材範例：

<script type="text/javascript">

    document.write('<sc'+'ript type="text/javascript" src="http://www.3rdparty.com/generatePassback.php?dfpAdUnit=%%ADUNIT%%&targeting='+encodeURIComponent(JSON.stringify(%%PATTERN:TARGETINGMAP%%))+'"></scr'+'ipt>');

    </script>

由 Ad Manager 放送時就會展開成：

 <script type="text/javascript">

    document.write('<sc'+'ript type="text/javascript" src="http://www.3rdparty.com/generatePassback.php?dfpAdUnit=/network_A/first_level_ad_unit/second_level_ad_unit&targeting=%7B%22kw%22%3A%5B%22testpercentp%22%5D%7D"></scr'+'ipt>');

    </script>

第三方現在可以存取動態產生的「dfpAdUnit」與「targeting」參數，並且建立下列回傳式曝光：

<script src='//www.googletagservices.com/tag/js/gpt.js'> const slot = googletag.pubads() .defineSlot('/network_A/first_level_ad_unit/second_level_ad_unit', [728, 90]).addService(googletag.pubads());
slot.setConfig({targeting: {"kw": "noloop"}}); // to avoid infinite loop (see https://support.google.com/admanager/answer/2811375) slot.setConfig({targeting: {"kw":["testpercentp"]}});

slot.display(); </script>

為了做到這一點，第三方將獲得類似下列的範本程式碼：

 myTargetingObject = JSON.parse('$targeting'); document.write('<sc'+'ript src="https://www.googletagservices.com/tag/js/gpt.js"></scr'+'ipt>');

    document.write('<scr'+'ipt>');

      callback = function() {

        const slot = googletag.pubads().defineSlot('$dfpAdUnit', [728, 90])

.addService(googletag.pubads());

    slot.setConfig({targeting: {"kw": "noloop"}});

        slot.setConfig({targeting: myTargetingObject});

        slot.display();

      };

    

      window.googletag = window.googletag || {};

      googletag.cmd = googletag.cmd || [];

      googletag.cmd.push(callback);

    

    document.write('</sc'+'ript>');

%%PATTERN:url%%

您也可以使用保留鍵 url 展開為推薦頁面的網址。

在 Campaign Manager 360 代碼中，如果有任何鍵/值使用 url 做為鍵名，都會以參照網址覆寫。

注意：url 保留鍵會逸出網址中的不安全字元。

代碼參數

巨集
`%%TAG_PARAM%%`

代碼參數巨集需要搭配其他廣告代碼參數，但只能與下列參數一起使用：

an
correlator
lip
mridx
msid
plcmt
pmad
pmnd
pmxd
pod
ppos
scor
us_privacy
vpmute
vpos

如果支援，該參數會展開為參數的值。

舉例來說，%%TAG_PARAM:correlator%% (支援) 會展開為廣告代碼中的 Correlator 值，但 %%TAG_PARAM:ppid%% (不支援) 則不會展開為任何值。

在新視窗中開啟目標

巨集
`%%TARGET_IN_NEW_WINDOW%%`

在新視窗中開啟目標巨集會針對廣告素材放送目標廣告單元，指出其目標視窗設定值是「_blank」(新視窗) 還是其他的值。

如果目標視窗是 _blank，巨集會展開成 1。
如果目標視窗是任何其他的值，或是未指定目標視窗，巨集會展開成 0。

如要插入實際的目標視窗設定值，請使用 %%TARGET_WINDOW%% 巨集。

目標視窗

巨集
`%%TARGET_WINDOW%%`

目標視窗巨集會展開成廣告素材放送目標廣告單元所指定的目標視窗。只要在廣告素材的程式碼中加入這個巨集，即可指定廣告素材獲得點擊時的動作；您可以根據每個廣告刊登網站的設定，將使用者導向至新視窗，或是在同一視窗中載入到達網頁。

舉例來說，假設 AdManager_News.com 廣告單元將目標視窗設為 _top，而 AdManager_Fashion.com 廣告單元則設為 _new。如果廣告素材程式碼包含 %%TARGET_WINDOW%% 巨集，該巨集將對 AdManager_News.com 的使用者展開成 _top，同時對 AdManager_Fashion.com 的使用者展開成 _new。

使用範例如下：

<a href="%%CLICK_URL_UNESC%%%%DEST_URL%%" target="%%TARGET_WINDOW%%"><img src="my ad"></a>

如要確認目標視窗設定值是「_blank」還是其他的值，請使用 %%TARGET_IN_NEW_WINDOW%% 巨集。

兒童導向內容標記 ^(已淘汰)

巨集
`%%TFCD%%`

透過兒童導向內容通報標記 (TFCD)，您可以通知第三方特定廣告請求來自含有兒童導向內容的網頁。這個巨集的立意是協助您遵守兒童網路隱私保護法 (COPPA)。

您可以採用 coppa=%%TFCD%% 或類似格式，在所有第三方廣告素材重新導向或請求中加入這個巨集，也可以在 JavaScript 中使用這個巨集，替 GPT 回傳式曝光代碼請求設定兒童導向內容通報標記。如果是兒童導向的內容，該巨集會展開為 1；如果是其他內容，則會展開為 0。系統會根據向 Ad Manager 提出請求的網頁、網站或行動應用程式來判斷內容性質。

如果您使用 Google 的廣告服務，且想要在網站或應用程式層級加入兒童導向內容通報標記，請參閱替網站或應用程式設定兒童導向內容通報標記。

年齡處理標記

巨集
`%%TFAT%%`

透過年齡處理標記 (TFAT)，您可以通知第三方有特定廣告請求來自設有年齡限制內容的網頁。這個巨集的立意是協助您遵守兒童網路隱私保護法 (COPPA)。

您可以採用 coppa=%%TFAT%% 或類似格式，在所有第三方廣告素材重新導向或請求中加入這個巨集，也可以在 JavaScript 中使用這個巨集，替 GPT 回傳式曝光代碼請求設定年齡處理標記。如果是兒童處理方式，該巨集會展開為 1；如果是青少年處理方式，則會展開為 2；如果沒有特定年齡處理方式，則會展開為 0。系統會根據向 Ad Manager 提出請求的網頁、網站或行動應用程式來判斷內容性質。

如果您使用 Google 的廣告服務，且想要在網站或應用程式層級導入兒童導向內容，請參閱「替網站或應用程式設定年齡處理方式標記」。

廣告素材範本專用的 URI 編碼

巨集
`[%URI_ENCODE:variable%]`

URI 編碼巨集會將廣告素材範本變數值中的空格和其他特殊字元轉譯成正確的格式，供 URI (又稱為「網址」) 使用。

這個巨集只適用於廣告素材範本，不支援自訂或第三方廣告素材，而且不會對已經編碼的字元做雙重編碼。

示例

假設廣告素材範本有一個名為「Color」的「list」變數，使用「dark blue」和「light green」這兩個值。Ad Manager 預設會將 [%Color%] 加入廣告素材範本的程式碼片段中：

<a href="https://paint.com/wall.html?color=[%Color%]">上色！</a>

建立廣告素材後，Ad Manager 會將 [%Color%] 換成所選清單項目的文字字串。由於 URI 僅接受經過編碼的空格，因此在這個範例中，包含空格字元的文字字串會截斷網址。為了避免發生這種問題，請使用 [%URI_ENCODE:Color%]。

<a href="https://paint.com/wall.html?color=[%URI_ENCODE:Color%]">上色！</a>

`[%Color%]`	`dark blue`
`[%URI_ENCODE:Color%]`	`dark%20blue`

如果您是透過廣告素材範本變數定義到達網址或重新導向網址，這個巨集特別實用。要是沒有採用正確的編碼，廣告素材中的完整網址可能無法正常運作。

示例

假設廣告素材範本有一個名為「LandingPage」的「URL」變數。Ad Manager 預設會將 [%LandingPage%] 加入廣告素材範本的程式碼片段中：

<a href="%%CLICK_URL_UNESC%%[%LandingPage%]">按這裡！</a>

如果 [%LandingPage%] 網址包含查詢參數 (例如 ?page=home&sport=baseball)，網址的格式將出現錯誤，而無法正常進行重新導向。在這個範例中，And 符號 (&) 後面的內容會被歸為完整網址的一部分，而非重新導向網址。為了避免發生這種問題，請使用 [%URI_ENCODE:LandingPage%]。

<a href="%%CLICK_URL_UNESC%%[%URI_ENCODE:LandingPage%]">按這裡！</a>

`[%LandingPage%]`	`https://www.mysportswebsite.com? page=home&sport=baseball`
`[%URI_ENCODE:LandingPage%]`	`https%3A%2F%2Fwww.mysportswebsite.com%3F page%3Dhome%26sport%3Dbaseball`

追蹤巨集

下列巨集的常見用途為追蹤及製作報表。

Cachebuster (隨機數字)

巨集
`%%CACHEBUSTER%%`

CacheBuster 巨集可確保系統在每次執行程式碼時，都會向廣告伺服器發出新的呼叫，以利您正確計算曝光次數。如果沒有將 CacheBuster 巨集加入廣告素材程式碼中，Google Ad Manager 和第三方廣告伺服器計算到的曝光次數比較容易出現落差。請注意，並不是所有第三方都需要使用 CacheBuster 巨集。

廣告素材供應商大多會在廣告代碼中提供預留位置，讓您插入 CacheBuster 巨集。舉例來說，假設您的第三方廣告素材程式碼含有類似下方的文字：

http://abc.3rd-party-serving.com/Targeting/;adServer.php?ab=cd&e=12fg=click&ord=[RANDOM_NUMBER]

您可選擇 [RANDOM_NUMBER] 並按一下 [插入 Cachebuster 巨集]，用巨集取代預留位置：

http://abc.3rd-party-serving.com/Targeting/adServer.php?ab=cd&e=12fg=click&ord=%%CACHEBUSTER%%

如果您在 Ad Manager 中使用 Campaign Manager 360 曝光追蹤程式，請選取標準廣告代碼，然後插入 CACHEBUSTER 巨集來縮小曝光次數的落差。

http://ad.doubleclick.net/ad/Nxxxx.site/Byyyy;sz=1x1; ord=%%CACHEBUSTER%%?

在 VAST 回應中使用 Cachebuster 巨集

針對指定廣告素材中發生的所有事件，%%CACHEBUSTER%% 巨集一律會展開成同一個隨機數字。這個巨集特別適用於影片廣告，因為每次發生影片追蹤事件，這個巨集在 VAST 回應中都會展開成隨機數字。

點擊

巨集	逸出級別
`%%CLICK_URL_UNESC%%`	未逸出
`%%CLICK_URL_ESC%%`	逸出
`%%CLICK_URL_ESC_ESC%%`	雙重逸出

Click 巨集會展開成特殊網址，方便您在 Ad Manager 中追蹤第三方廣告素材獲得的點擊。這個巨集在錨定標記 (<a>) 中通常會與廣告素材的到達網址配對使用。請勿輸入 Click 巨集做為圖片或 iframe 的來源。如果這麼做，系統會在每次顯示圖片或 iframe 時都記錄一次點擊，但這類點擊是不合規範的，最終會被視為無效點擊而遭篩除。

將 %%CLICK_URL_UNESC%% 用於連結的開頭。如果 click-tracker 是另一個網址的參數，請使用 %%CLICK_URL_ESC%%。

<a href="%%CLICK_URL_UNESC%%http://www.google.com">連結</a>

<a href="http://www.google.com?rd_url=%%CLICK_URL_ESC%%">連結</a>

進一步瞭解逸出和未逸出的巨集。

確認 Click 巨集是否導入成功

如果 Click 巨集位置錯誤，將無法追蹤點擊。請按照下列步驟確認 Ad Manager 會按照您預期的方式記錄點擊。

預覽廣告素材。
按一下預覽畫面。

Ad Manager 會顯示一則訊息，確認這些點擊將獲得記錄。要是您沒有看到這則訊息，表示 Click 巨集未正確導入。

展開

巨集	展開成什麼內容
`%eaid!`	委刊項 ID
`%eadv!`	所放送委刊項的廣告主 ID
`%ebuy!`	所放送委刊項的訂單 ID
`%ecid!`	廣告素材 ID
`%eenv!`	環境 (標記類型) 指標：`i` 代表 iFrame，`j` 代表 JavaScript
`%epid!`	委刊項放送目標廣告單元 ID
`%esid!`	委刊項放送目標廣告單元上方的最高級廣告單元 ID 這是舊版巨集，用於您的聯播網時可能無法正常運作。

您可以在自訂廣告素材程式碼或到達網址中使用展開巨集，以便在放送廣告素材到網頁時顯示 Ad Manager 中的 ID 值。這個巨集經常用於比對 Ad Manager 和發布商自有資料庫中的 ID，以利疑難排解或其他報表製作。

您可以使用 Ad Manager 到達網址適用的任何字元，分隔到達網址中的展開巨集。舉例來說，http://www.site.com/?%eaid!;%ecid! 可展開成 http://www.site.com/?1234567;4265598。

裝置 ID

巨集
`%%ADVERTISING_IDENTIFIER_PLAIN%%` (裝置 ID)
`%%ADVERTISING_IDENTIFIER_TYPE%%` (裝置類型)
`%%ADVERTISING_IDENTIFIER_IS_LAT%%` (限制廣告追蹤設定)

透過 %%ADVERTISING_IDENTIFIER_PLAIN%% 巨集，應用程式內發布商可向廣告合作夥伴傳送一個可重設的裝置 ID，以便放送按照興趣顯示的廣告。這樣一來，您就能輕鬆為廣告客戶和代理商提供可重設裝置 ID 存取權。

應用程式內發布商也可使用 %%ADVERTISING_IDENTIFIER_TYPE%% 巨集傳送裝置類型，以及運用 %%ADVERTISING_IDENTIFIER_IS_LAT%% 巨集傳送限制廣告追蹤 (LAT) 設定 (這項設定會指出裝置的「限制廣告追蹤」信號)。

進一步瞭解用於指定使用者的可重設裝置 ID，其中包括支援的裝置類型。

必要條件

您必須為廣告素材設定 HTTPS 加密。廣告素材和任何用於轉換追蹤的第三方像素都必須遵守這項規定。如果廣告素材未採用 HTTPS 加密，或者您覆寫自動 SSL 相容性，巨集將不會展開值，但廣告素材仍會放送。

運作方式

在 Ad Manager 中，發布商將巨集加到他們的廣告素材和/或追蹤網址中。
這個巨集展開後即包含使用者的裝置 ID、裝置類型和/或 LAT 設定。當程式碼呼叫第三方時，廣告素材中就會包含這些資訊。

如果廣告請求來自針對兒童的的應用程式 (TFCD) 或已啟用限制廣告追蹤 (LAT)，則裝置 ID 和裝置類型巨集不會展開。在這些情況下，這個巨集會傳回空的字串 ("")。

格式

這個巨集會傳送由 32 個大寫十六進位數字所組成的值，以連字號分為五組顯示，格式為 8-4-4-4-12，總共 36 個字元 (32 個英數字元和 4 個連字號)。

Example: 201F2EB1-8041-9E39-CD07-FCBBA5A29B41

如要瞭解支援的裝置類型和限制廣告追蹤 (LAT) 的可能值，請參閱本文。

預覽模式

巨集
`%%PREVIEW_MODE%%`

您可以在自訂廣告素材程式碼中使用預覽模式巨集，避免後端系統或第三方系統計算預覽曝光次數。如果您在 Ad Manager 預覽模式中查看廣告素材，巨集會展開為 true；如果是一般曝光，則會展開為 false。

配置

巨集
`%%SCHEME%%`

架構巨集會展開成 http: 或 https:，取決於何者符合廣告素材放送目標網頁的安全架構。您可以將這個巨集插入網址的開頭。

<img src=%%SCHEME%%//www.website.com/img/logo.gif>

網站

巨集
`%%SITE%%`

可展開成廣告代碼所含網址參數的網域 (例如 google.com)。您可以使用這個巨集，根據請求來源修改廣告素材。這個巨集不適用於標示為匿名的 Ad Exchange 廣告。

已瀏覽曝光

巨集	逸出級別
`%%VIEW_URL_ESC%%`	逸出
`%%VIEW_URL_UNESC%%`	未逸出

已瀏覽曝光巨集可讓 Ad Manager 在每次廣告素材下載到使用者的裝置並開始載入時，計算一次曝光。只能在非頁內廣告素材中使用這個巨集。

您可以透過多種方式傳送已瀏覽呼叫。我們建議您使用 <img> 標記：

 <img src="%%VIEW_URL_UNESC%%" style="display:none">

 <img src="[%Imagefile%]" border="0">

第一個 <img> 標記會從 VIEW_URL 擷取 1x1 圖片。將樣式設為 “display:none” 即可隱藏，但不會影響網頁的版面配置。

這類巨集最常用於應遵守 GDPR 的廣告請求。

注意：在 HTML5 廣告素材的 HTML 中導入資訊公開和同意聲明架構 (TCF) 巨集時，系統並不會展開這些巨集。只有多媒體重新導向和自訂多媒體廣告素材，可分別透過「第三方網址」及「HTML 程式碼」欄位，支援展開資訊公開和同意聲明架構巨集。

巨集
`${GDPR}`

這會展開成與請求相關聯的 gdpr= 值

資訊公開和同意聲明 (TC) 字串

巨集
`${GDPR_CONSENT_XXXX}`

這會展開成與請求相關聯的資訊公開和同意聲明 (TC) 字串。如果資訊公開和同意聲明 (TC) 字串為空白或無效，此巨集將不會展開。使用此巨集將資訊公開和同意聲明 (TC) 字串透過非程式輔助廣告素材的網址，傳送至第三方廣告素材供應商。

將第三方供應商的 IAB GVL ID 替換成「XXXX」。若 TC 字串為空白或無效，此巨集將不會展開。

若與您輸入的 IAB GVL ID 相關聯的第三方供應商沒有取得使用者同意，具有 ${GDPR_CONSENT_XXXX} 巨集的廣告素材就可能會被封鎖。

如果用於 VAST 代碼，且第三方供應商缺乏使用者同意聲明，則這個巨集將不會展開。

${GDPR_CONSENT_XXXX} 巨集只應在網址裡出現一次。聯絡第三方廣告素材合作夥伴，瞭解對方在傳遞資訊公開和同意聲明 (TC) 字串方面的規定，以及網址長度限制。在相關 IAB 資訊公開和同意聲明架構 2.0 版的請求上，巨集會更換為完整且未修改的資訊公開和同意聲明 (TC) 字串。

巨集
`${ADDTL_CONSENT}`

這會展開成與請求相關聯的額外同意聲明 (AC) 字串。

未滿法定同意年齡的歐洲經濟區和英國使用者

巨集
`%%TFUA%%`

這會展開成 1 的值，替請求設定未滿法定同意年齡的歐洲經濟區和英國使用者標記。

影片巨集

這類巨集常用於影片廣告素材，以納入相關背景或內容的詳情。

影片廣告長度 (以秒為單位)

巨集
`%%VIDEO_AD_DURATION_SECONDS%%`

展開為影片廣告時間長度 (以毫秒為單位)。對於 VAST 包裝函式/重新導向，這個巨集會展開為 Ad Manager 中宣告的廣告時間長度。

這個巨集可讓您透過第三方追蹤網址追蹤影片廣告時間長度。

影片長度 (以毫秒為單位)

巨集
`%%VIDEO_DURATION%%`

展開為影片廣告時間長度 (以毫秒為單位)。對於 VAST 包裝函式/重新導向，這個巨集會展開為 Ad Manager 中宣告的廣告時間長度。

這個巨集可讓您透過第三方追蹤網址追蹤影片廣告時間長度。

影片內容描述網址

巨集	逸出級別
`%%DESCRIPTION_URL_UNESC%%`	未逸出
`%%DESCRIPTION_URL_ESC%%`	逸出
`%%DESCRIPTION_URL_ESC_ESC%%`	雙重逸出

如果巨集位於網址內，請使用 %%DESCRIPTION_URL_ESC%% (單一逸出)；其他情況請使用 %%DESCRIPTION_URL_UNESC%% (未逸出)。進一步瞭解逸出和未逸出巨集

在重新導向廣告代碼中，這些巨集會從原始 Google 發布商廣告代碼的 description_url 查詢參數展開為內容描述網址參數。一般來說，內容描述網址需與參照網址相同。在以下兩種情況中，您必須指定 Google 發布商廣告代碼中的 description_url：出現 IMA SDK 可能無法正確偵測網頁網址的內嵌項目；或者您使用的是 Ad Exchange 影片廣告或 AdSense 影片廣告。

Ad Manager 也支援 %%DESCRIPTION_URL%%，這個巨集的功用與 %%DESCRIPTION_URL_UNESC%% 相同，因此您不需重新編寫舊廣告素材和範本的程式碼。

影片參照網址

巨集	逸出級別
`%%REFERRER_URL_UNESC%%`	未逸出
`%%REFERRER_URL_ESC%%`	單一逸出
`%%REFERRER_URL_ESC_ESC%%`	雙重逸出

如果巨集位於網址內，請使用 %%REFERRER_URL_ESC%% (單一逸出)；其他情況請使用 %%REFERRER_URL_UNESC%% (未逸出)。進一步瞭解逸出和未逸出的網址巨集

在重新導向廣告代碼中，這個巨集會展開為參照網址 (影片播放器所在的網頁網址)。運作方式如下：Ad Manager 剖析廣告代碼的網址查詢參數，接著找出參照網址，然後再以這個網址取代巨集文字。這個巨集僅適用於 Google IMA SDK，相關規定如下：

推薦連結網頁必須開放指令碼存取權，這個巨集才能正常運作。
該巨集無法在 iFrame 內部正常運作。

Ad Manager 也支援 %%REFERRER_URL%%，這個巨集的功用與 %%REFERRER_URL_UNESC%% 相同，因此您不需重新編寫舊廣告素材和範本的程式碼。

您可以將代碼參數巨集與部分影片參數搭配使用，以展開為這些參數的值。

曝光有效期間

巨集
`%%IMPRESSIONS_EXPIRATION_WINDOW_MINUTES%%`

展開後會顯示曝光相關事件 (例如點擊、轉換或觀看) 的處理時間範圍 (以分鐘為單位)。超過這個時間的事件會視為過期。這個巨集可協助賣方平台將出價有效期間與 Google 同步，減少報表資料差異。

影片內容巨集

這類巨集適用於指定影片內容來源的廣告。

僅適用於 Google Ad Manager 360。

影片長度 (以毫秒為單位)

巨集
`%%VIDEO_DURATION%%`

這會展開成影片長度 (以毫秒為單位)。

影片 ID

巨集
`%%VIDEO_ID%%`

展開為目前所播放影片內容的 ID。這是內容管理系統中的專屬 ID，或是影片廣告解決方案 MRSS 元素的 dfpvideo:ContentID 值。

影片中繼資料

巨集
`%%VIDEO_METADATA:key%%`

展開為與放送廣告素材的影片相關的中繼資料，取決於影片內容的鍵/值。這些鍵/值是在 Ad Manager 的「影片」分頁中完成設定。

影片中繼資料鍵經過指定後，即可透過影片中繼資料巨集展開。巨集中所使用的「鍵」必須是英數字元或底線 (_)。

影片標題

巨集	逸出級別
`%%VIDEO_TITLE%%`	單一逸出

影片標題巨集會展開為 Ad Manager 中定義的影片標題。

這個巨集必須擷取內容才能運作。

僅適用於 Google Ad Manager 360。

內容來源 ID

巨集
`%%CMS_ID%%`

content source ID 用於指定影片廣告。

content source ID 和 video ID 參數接受變數值。

如要將廣告指定到影片內容，主影片廣告代碼必須同時包含這兩個參數。

cmsid 是每個內容來源的專屬號碼。如要在 Ad Manager 中找出這組號碼，請依序點選「影片」>「內容來源」，然後按一下來源名稱。如要瞭解如何使用媒體 RSS (MRSS) 動態饋給擷取影片內容，請參閱這篇文章。

vid 是用來表示特定影片的字串或編號。這個 ID 是由代管內容的內容管理平台指定。如要在 Ad Manager 中找出這個 ID，請依序點選「影片」>「內容」，然後按一下特定影片內容。

使用範例
cmsid=[value]&vid=[value]

如果是為包含隨選影片的動態廣告插播建立廣告代碼，應使用巨集，因為此巨集會動態插入正確的內容來源和影片 ID。

範例：cmsid=%%CMS_ID%%&vid=%%VIDEO_ID%%

自訂廣告 ID (FreeWheel)

巨集
`%%FW_CAID%%`

這會展開成 FreeWheel 自訂廣告 ID。

這個巨集只適用於採用 FreeWheel 放送影片廣告的發布商。

IAB 類別 (FreeWheel)

巨集
`%%IAB_CATEGORIES%%`

用於傳送已使用標籤手動分類的廣告素材的廣告類別。這個巨集會傳回以逗號分隔的可用標準 IAB 類別清單 (轉換自 Google 所分類的類別)。

發布商可以使用這個巨集與 FreeWheel 共享影片廣告空間，並可將廣告類別做為自訂參數傳遞出去。舉例來說，您可以在 VAST 重新導向代碼中加入 &iab_categories=%%IAB_CATEGORIES%%。

這個頁面可能含有使用 AI 技術翻譯的內容，也許會有錯誤。

這對您有幫助嗎？

我們應如何改進呢？

巨集

關於巨集的重要注意事項

跳至清單中的特定巨集

顯示巨集

逸出模式比對巨集

%%PATTERN:key%%

%%PATTERN:TARGETINGMAP%%

%%PATTERN:url%%

示例

示例

追蹤巨集

在 VAST 回應中使用 Cachebuster 巨集

確認 Click 巨集是否導入成功

必要條件

運作方式

格式

影片巨集

影片內容巨集

這對您有幫助嗎？

還有其他問題嗎？

嘗試以下步驟：