GPT 參考資料

本參考資料使用 TypeScript 標記法來描述型別。下表提供簡短說明和範例。

輸入運算式
string 原始字串型別。
string[] 陣列類型，值只能是字串。
number | string 聯集型別，值可以是數字或字串。
Array<number | string> 陣列型別，其中的值是複合 (聯集) 型別。
[number, string] 元組型別，其中值為雙元素陣列，且必須依序包含數字和字串。
Slot 物件類型，值為 googletag.Slot 的執行個體。
() => void 沒有定義引數和傳回值的函式型別。

如要進一步瞭解支援的型別和型別運算式，請參閱 TypeScript 手冊 。

型別註解

變數、參數名稱、屬性名稱或函式簽章後方的冒號表示型別註解。型別註解會說明冒號左側元素可接受或傳回的型別。下表列出您可能會在本參考資料中看到的型別註解範例。

型別註解
param: string 表示 param 接受或傳回字串值。這個語法用於變數、參數、屬性和傳回型別。
param?: number | string 表示 param 為選用項目，但指定時可接受數字或字串。這個語法用於參數和屬性。
...params: Array<() => void> 指出 params 是接受函式的 其餘參數 。其餘參數接受指定類型的不限數量值。

googletag

Google 發布商廣告代碼用於 API 的全域命名空間。
命名空間
config
頁面層級設定的主要設定介面。
enums
這是 GPT 用於列舉型別的命名空間。
events
這是 GPT 用於事件的命名空間。
secureSignals
這是 GPT 用於管理安全信號的命名空間。
介面
CommandArray
指令陣列會接受一連串的函式，並依序叫用這些函式。
CompanionAdsService
隨播廣告服務。
PrivacySettingsConfig
隱私權設定的設定物件。
PubAdsService
發布商廣告服務。
ResponseInformation
代表單一廣告回應的物件。
RewardedPayload
代表與獎勵廣告相關聯獎勵的物件。
Service
基本服務類別，包含所有服務通用的方法。
SizeMappingBuilder
大小對應規格物件的建構工具。
Slot
Slot 是指代表網頁上單一廣告版位的物件。
型別別名
GeneralSize
插槽的有效大小設定，可為一或多個大小。
MultiSize
有效大小的清單。
NamedSize
廣告版位可擁有的命名大小。
SingleSize
版位的單一有效大小。
SingleSizeArray
代表 [寬度、高度] 的兩個數字陣列。
SizeMapping
可視區域大小與廣告大小的對應關係。
SizeMappingArray
大小對應清單。
變數
apiReady
這個標記表示 GPT API 已載入，隨時可供呼叫。
cmd
全域指令佇列的參照，用於非同步執行與 GPT 相關的呼叫。
pubadsReady
此標記表示 PubAdsService 已啟用、載入且可正常運作。
secureSignalProviders
安全信號供應商陣列的參照。
函式
companionAds
傳回 CompanionAdsService 的參照。
defineOutOfPageSlot
使用指定廣告單元路徑建構非頁內廣告版位。
defineSlot
使用指定廣告單元路徑和大小建構廣告版位，並將其與網頁上包含廣告的 div 元素 ID 建立關聯。
destroySlots
毀損指定位置，從 GPT 移除這些位置的所有相關物件和參照。
disablePublisherConsole
停用 Google 發布商控制台。
display
指示廣告空間服務轉譯廣告空間。
enableServices
啟用網頁上廣告版位定義的所有 GPT 服務。
getVersion
傳回 GPT 的目前版本。
openConsole
開啟 Google 發布商控制台。
pubads
傳回 PubAdsService 的參照。
setAdIframeTitle
從這一刻起，為 PubAdsService 建立的所有廣告容器 iframe 設定標題。
setConfig
設定網頁的一般設定選項。
sizeMapping
建立新的 SizeMappingBuilder。

型別別名

GeneralSize

GeneralSize: SingleSize | MultiSize
插槽的有效大小設定，可為一或多個大小。

MultiSize

MultiSize: SingleSize[]
有效大小的清單。

NamedSize

NamedSize: "fluid" | ["fluid"]
廣告版位可擁有的命名大小。在大多數情況下，大小是固定大小的矩形，但有時我們需要其他類型的大小規格。只有下列具名大小有效：
  • 自動調整大小：廣告容器會佔用上層 div 的 100% 寬度，然後調整高度以配合廣告素材內容。與網頁上一般區塊元素的行為類似。用於原生廣告 (請參閱相關文章)。請注意，fluid 和 ['fluid'] 都是可接受的形式，可將廣告空間大小宣告為彈性。

SingleSize

版位的單一有效大小。

SingleSizeArray

SingleSizeArray: [number, number]
代表 [寬度、高度] 的兩個數字陣列。

SizeMapping

可視區域大小與廣告大小的對應關係。用於回應式廣告。

SizeMappingArray

SizeMappingArray: SizeMapping[]
大小對應清單。

變數

Const apiReady

apiReady: boolean | undefined
這個旗標表示 GPT API 已載入，隨時可供呼叫。在 API 準備就緒前，這個屬性只會是 undefined。

請注意，處理非同步作業的建議方式是使用 googletag.cmd，在 GPT 準備就緒時將回呼排入佇列。這些回呼不必檢查 googletag.apiReady，因為 API 設定完成後，系統保證會執行這些回呼。

Const cmd

cmd: ((this: typeof globalThis) => void)[] | CommandArray
參考全域指令佇列，以非同步方式執行與 GPT 相關的呼叫。

網頁上的 GPT 代碼語法會將 googletag.cmd 變數初始化為空白 JavaScript 陣列，而 cmd.push 是標準的 Array.push 方法，可將元素加到陣列結尾。載入 GPT JavaScript 時，系統會檢查陣列並依序執行所有函式。然後，指令碼會將 cmd 替換為 CommandArray 物件，該物件的 push 方法定義為執行傳遞給它的函式引數。這項機制可讓 GPT 非同步擷取 JavaScript，同時允許瀏覽器繼續顯示網頁，進而縮短使用者感受到的延遲時間。
範例

JavaScript

googletag.cmd.push(() => {
  googletag.defineSlot("/1234567/sports", [160, 600]).addService(googletag.pubads());
});

JavaScript (舊版)

googletag.cmd.push(function () {
  googletag.defineSlot("/1234567/sports", [160, 600]).addService(googletag.pubads());
});

TypeScript

googletag.cmd.push(() => {
  googletag.defineSlot("/1234567/sports", [160, 600])!.addService(googletag.pubads());
});

Const pubadsReady

pubadsReady: boolean | undefined
這個標記表示 PubAdsService 已啟用、載入且可正常運作。在呼叫 enableServices，以及載入並初始化 PubAdsService 之前，這個屬性只會是 undefined。

secureSignalProviders

secureSignalProviders: SecureSignalProvider[] | SecureSignalProvidersArray | undefined
安全信號供應商陣列的參照。

安全信號供應商陣列會接受一連串的信號產生函式，並依序叫用這些函式。這個函式旨在取代標準陣列，用於將信號產生函式加入佇列，以便在 GPT 載入後呼叫。
範例

JavaScript

window.googletag = window.googletag || { cmd: [] };
googletag.secureSignalProviders = googletag.secureSignalProviders || [];
googletag.secureSignalProviders.push({
  id: "collector123",
  collectorFunction: () => {
    return Promise.resolve("signal");
  },
});

JavaScript (舊版)

window.googletag = window.googletag || { cmd: [] };
googletag.secureSignalProviders = googletag.secureSignalProviders || [];
googletag.secureSignalProviders.push({
  id: "collector123",
  collectorFunction: function () {
    return Promise.resolve("signal");
  },
});

TypeScript

window.googletag = window.googletag || { cmd: [] };
googletag.secureSignalProviders = googletag.secureSignalProviders || [];
googletag.secureSignalProviders.push({
  id: "collector123",
  collectorFunction: () => {
    return Promise.resolve("signal");
  },
});
另請參閱

函式

companionAds

companionAds(): CompanionAdsService
傳回 CompanionAdsService 的參照。
傳回
CompanionAdsService隨播廣告服務。

defineOutOfPageSlot

defineOutOfPageSlot(adUnitPath: string, div?: string | OutOfPageFormat): Slot | null
使用指定廣告單元路徑建構頁面外廣告版位。

如果是自訂頁面外廣告，div 是包含廣告的 div 元素 ID。詳情請參閱非頁內廣告素材一文。

如果是 GPT 管理的非頁內廣告，div 是支援的 OutOfPageFormat。
範例

JavaScript

// Define a custom out-of-page ad slot.
googletag.defineOutOfPageSlot("/1234567/sports", "div-1");

// Define a GPT managed web interstitial ad slot.
googletag.defineOutOfPageSlot("/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL);

JavaScript (舊版)

// Define a custom out-of-page ad slot.
googletag.defineOutOfPageSlot("/1234567/sports", "div-1");

// Define a GPT managed web interstitial ad slot.
googletag.defineOutOfPageSlot("/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL);

TypeScript

// Define a custom out-of-page ad slot.
googletag.defineOutOfPageSlot("/1234567/sports", "div-1");

// Define a GPT managed web interstitial ad slot.
googletag.defineOutOfPageSlot("/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL);
另請參閱
參數
adUnitPath: string包含聯播網代碼和廣告單元代碼的完整廣告單元路徑。
Optional div: string | OutOfPageFormat包含這個廣告單元或 OutOfPageFormat 的 div ID。
傳回
Slot | null新建立的運算單元，或 null (如果無法建立運算單元)。

defineSlot

defineSlot(adUnitPath: string, size: GeneralSize, div?: string): Slot | null
使用指定廣告單元路徑和大小建構廣告版位，並將其與網頁上包含廣告的 div 元素 ID 建立關聯。
範例

JavaScript

googletag.defineSlot("/1234567/sports", [728, 90], "div-1");

JavaScript (舊版)

googletag.defineSlot("/1234567/sports", [728, 90], "div-1");

TypeScript

googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
另請參閱
參數
adUnitPath: string包含聯播網代碼和單元代碼的完整廣告單元路徑。
size: GeneralSize新增的廣告空間寬度和高度。如果未提供回應式大小對應，或可視區域大小小於對應中提供的最小大小，廣告請求就會使用這個大小。
Optional div: string包含這個廣告單元的 div ID。
傳回
Slot | null新建立的運算單元，或 null (如果無法建立運算單元)。

destroySlots

destroySlots(slots?: Slot[]): boolean
毀損指定位置，從 GPT 移除這些位置的所有相關物件和參照。這個 API 不支援回傳廣告空間和隨播廣告空間。

在廣告空間上呼叫這個 API 會清除廣告，並從 GPT 維護的內部狀態中移除廣告空間物件。在 slot 物件上呼叫任何其他函式都會導致未定義的行為。請注意，如果發布商網頁保留對該插槽的參照，瀏覽器可能仍不會釋放與該插槽相關聯的記憶體。呼叫這個 API 可讓與該廣告版位相關聯的 div 供重複使用。

具體來說，移除廣告版位會從 GPT 的長效網頁瀏覽中移除廣告，因此日後的請求不會受到涉及這則廣告的路障型廣告或競爭排除條件影響。如果未先呼叫這個函式，就從網頁中移除廣告空間的 div，就會導致未定義的行為。
範例

JavaScript

// The calls to construct an ad and display contents.
const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
googletag.display("div-1");
const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2");
googletag.display("div-2");

// This call to destroy only slot1.
googletag.destroySlots([slot1]);

// This call to destroy both slot1 and slot2.
googletag.destroySlots([slot1, slot2]);

// This call to destroy all slots.
googletag.destroySlots();

JavaScript (舊版)

// The calls to construct an ad and display contents.
var slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
googletag.display("div-1");
var slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2");
googletag.display("div-2");

// This call to destroy only slot1.
googletag.destroySlots([slot1]);

// This call to destroy both slot1 and slot2.
googletag.destroySlots([slot1, slot2]);

// This call to destroy all slots.
googletag.destroySlots();

TypeScript

// The calls to construct an ad and display contents.
const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1")!;
googletag.display("div-1");
const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2")!;
googletag.display("div-2");

// This call to destroy only slot1.
googletag.destroySlots([slot1]);

// This call to destroy both slot1 and slot2.
googletag.destroySlots([slot1, slot2]);

// This call to destroy all slots.
googletag.destroySlots();
參數
Optional slots: Slot[]要摧毀的格位陣列。陣列為選填，如未指定，系統會毀損所有插槽。
傳回
boolean如果已毀損，則為 true，否則為 false。

disablePublisherConsole

disablePublisherConsole(): void
停用 Google 發布商控制台。
另請參閱

螢幕

display(divOrSlot: string | Element | Slot): void
指示廣告空間服務轉譯廣告空間。每個廣告版位在每個網頁上只能顯示一次。所有時段都必須定義，且必須與服務建立關聯，才會顯示。元素出現在 DOM 中之前，不得進行顯示呼叫。一般來說，只要將廣告版位放在方法呼叫中指定的 div 元素內的指令碼區塊中即可。

如果使用單一請求架構 (SRA)，系統會在呼叫這個方法時，一次擷取所有未擷取的廣告版位。如要強制廣告空間不顯示廣告，必須移除整個 div。
另請參閱
參數
divOrSlot: string | Element | Slot包含廣告版位的 div 元素 ID、div 元素或版位物件。如果提供 div 元素，則該元素必須具有與傳遞至 defineSlot 的 ID 相符的「id」屬性。

enableServices

enableServices(): void
啟用網頁上廣告版位定義的所有 GPT 服務。

getVersion

getVersion(): string
傳回目前版本的 GPT。
另請參閱
傳回
string目前執行的 GPT 版本字串。

openConsole

openConsole(div?: string): void
開啟 Google 發布商控制台。
範例

JavaScript

// Calling with div ID.
googletag.openConsole("div-1");

// Calling without div ID.
googletag.openConsole();

JavaScript (舊版)

// Calling with div ID.
googletag.openConsole("div-1");

// Calling without div ID.
googletag.openConsole();

TypeScript

// Calling with div ID.
googletag.openConsole("div-1");

// Calling without div ID.
googletag.openConsole();
另請參閱
參數
Optional div: string廣告版位 div ID。這個值為選用項目。如果提供廣告版位，發布商控制台會嘗試開啟，並顯示指定廣告版位的詳細資料。

pubads

pubads(): PubAdsService
傳回 PubAdsService 的參照。
傳回
PubAdsService發布商廣告服務。

setAdIframeTitle

setAdIframeTitle(title: string): void
從這一刻起，為 PubAdsService 建立的所有廣告容器 iframe 設定標題。
範例

JavaScript

googletag.setAdIframeTitle("title");

JavaScript (舊版)

googletag.setAdIframeTitle("title");

TypeScript

googletag.setAdIframeTitle("title");
參數
title: string所有廣告容器 iframe 的新標題。

setConfig

setConfig(config: PageSettingsConfig): void
設定網頁的一般設定選項。
參數
config: PageSettingsConfig

sizeMapping

sizeMapping(): SizeMappingBuilder
建立新的 SizeMappingBuilder。
另請參閱
傳回
SizeMappingBuilder新版建構工具。

googletag.CommandArray

指令陣列會接受一連串的函式，並依序叫用這些函式。這個陣列的用途是取代標準陣列，用於將函式加入佇列，以便在 GPT 載入後叫用。
方法
push
依序執行引數中指定的函式序列。

方法

推入

push(...f: ((this: typeof globalThis) => void)[]): number
依序執行引數中指定的函式序列。
範例

JavaScript

googletag.cmd.push(() => {
  googletag.defineSlot("/1234567/sports", [160, 600]).addService(googletag.pubads());
});

JavaScript (舊版)

googletag.cmd.push(function () {
  googletag.defineSlot("/1234567/sports", [160, 600]).addService(googletag.pubads());
});

TypeScript

googletag.cmd.push(() => {
  googletag.defineSlot("/1234567/sports", [160, 600])!.addService(googletag.pubads());
});
參數
Rest ...f: ((this: typeof globalThis) => void)[]要執行的 JavaScript 函式。執行階段繫結一律為 globalThis。請考慮傳遞箭頭函式，保留封閉詞法環境的 this 值。
傳回
number目前處理的指令數量。這與 Array.push 的傳回值 (陣列目前的長度) 相容。

googletag.CompanionAdsService

延長 Service
隨播廣告服務。影片廣告會使用這項服務顯示隨播廣告。
方法
addEventListener
註冊監聽器，讓您在網頁上發生特定 GPT 事件時，設定及呼叫 JavaScript 函式。
getSlots
取得與這項服務相關聯的時段清單。
removeEventListener
移除先前註冊的接聽程式。
setRefreshUnfilledSlots
設定系統是否會自動為尚未獲得廣告的隨播廣告版位補上廣告。
另請參閱

方法

setRefreshUnfilledSlots

setRefreshUnfilledSlots(value: boolean): void
設定系統是否要自動為尚未獲得廣告的隨播廣告版位補上廣告。

在網頁的生命週期內，這個方法可以多次呼叫，用來開啟及關閉補上廣告功能。只有向 PubAdsService 註冊的版位才會補上廣告。由於政策限制，放送 Ad Exchange 影片時，這個方法無法填滿空白的隨播廣告位置。
範例

JavaScript

googletag.companionAds().setRefreshUnfilledSlots(true);

JavaScript (舊版)

googletag.companionAds().setRefreshUnfilledSlots(true);

TypeScript

googletag.companionAds().setRefreshUnfilledSlots(true);
參數
value: booleantrue 自動填回未填入的時段，false 則維持不變。

googletag.PrivacySettingsConfig

隱私權設定的設定物件。
屬性
childDirectedTreatment?
指出是否應將網頁視為兒童導向。
limitedAds?
啟用「受限制的廣告」模式，協助發布商遵守法規。
nonPersonalizedAds?
啟用放送功能，以非個人化廣告模式放送廣告，協助發布商遵守法規。
restrictDataProcessing?
啟用受限的處理模式，協助發布商遵守法規。
trafficSource?
指出請求代表購買或自然流量。
underAgeOfConsent?
指出是否要將廣告請求標示為來自未滿規定年齡的使用者。
另請參閱

屬性

Optional childDirectedTreatment

childDirectedTreatment?: boolean
指出是否應將網頁視為兒童導向。設為 null 即可清除設定。

Optional limitedAds

limitedAds?: boolean
啟用以受限制的廣告模式放送廣告，協助發布商符合法規要求。

您可以透過兩種方式，指示 GPT 請求受限制的廣告：只有從受限制的廣告網址載入 GPT 時，才能手動設定受限制的廣告。如果 GPT 是從標準網址載入，嘗試修改這項設定會產生發布商控制台警告。

請注意，使用 CMP 時，不必手動啟用受限制的廣告。
範例

JavaScript

// Manually enable limited ads serving.
// GPT must be loaded from the limited ads URL to configure this setting.
googletag.pubads().setPrivacySettings({
  limitedAds: true,
});

JavaScript (舊版)

// Manually enable limited ads serving.
// GPT must be loaded from the limited ads URL to configure this setting.
googletag.pubads().setPrivacySettings({
  limitedAds: true,
});

TypeScript

// Manually enable limited ads serving.
// GPT must be loaded from the limited ads URL to configure this setting.
googletag.pubads().setPrivacySettings({
  limitedAds: true,
});
另請參閱

Optional nonPersonalizedAds

nonPersonalizedAds?: boolean
啟用放送功能，以非個人化廣告模式放送廣告，協助發布商遵守法規。

Optional restrictDataProcessing

restrictDataProcessing?: boolean
啟用受限的處理模式，協助發布商遵守法規。

Optional trafficSource

trafficSource?: TrafficSource
指出請求代表購買或自然流量。這個值會填入 Ad Manager 報表中的「流量來源」維度。如未設定，報表中的流量來源預設為 undefined。
範例

JavaScript

// Indicate requests represent organic traffic.
googletag.pubads().setPrivacySettings({
  trafficSource: googletag.enums.TrafficSource.ORGANIC,
});

// Indicate requests represent purchased traffic.
googletag.pubads().setPrivacySettings({
  trafficSource: googletag.enums.TrafficSource.PURCHASED,
});

JavaScript (舊版)

// Indicate requests represent organic traffic.
googletag.pubads().setPrivacySettings({
  trafficSource: googletag.enums.TrafficSource.ORGANIC,
});

// Indicate requests represent purchased traffic.
googletag.pubads().setPrivacySettings({
  trafficSource: googletag.enums.TrafficSource.PURCHASED,
});

TypeScript

// Indicate requests represent organic traffic.
googletag.pubads().setPrivacySettings({
  trafficSource: googletag.enums.TrafficSource.ORGANIC,
});

// Indicate requests represent purchased traffic.
googletag.pubads().setPrivacySettings({
  trafficSource: googletag.enums.TrafficSource.PURCHASED,
});

Optional underAgeOfConsent

underAgeOfConsent?: boolean
指出是否要將廣告請求標示為來自未滿規定年齡的使用者。設為 null 即可清除設定。

googletag.PubAdsService

延長 Service
發布商廣告服務。這項服務可用於從 Google Ad Manager 帳戶擷取及顯示廣告。
方法
addEventListener
註冊監聽器，讓您在網頁上發生特定 GPT 事件時，設定及呼叫 JavaScript 函式。
clear
從指定插槽移除廣告，並以空白內容取代。
clearCategoryExclusions
清除所有網頁層級廣告類別排除標籤。
clearTargeting
清除特定鍵或所有鍵的自訂指定目標參數。
collapseEmptyDivs
啟用收合廣告版位 div，這樣如果沒有可顯示的廣告內容，廣告版位就不會佔用網頁空間。
disableInitialLoad
在網頁載入時停用廣告請求，但允許透過 PubAdsService.refresh 呼叫請求廣告。
display
使用指定廣告單元路徑和大小建構並顯示廣告版位。
enableLazyLoad
根據設定物件定義，在 GPT 中啟用延遲載入。
enableSingleRequest
啟用單一要求模式，同時擷取多個廣告。
enableVideoAds
向 GPT 發出信號，表示網頁上會顯示影片廣告。
get
傳回與指定鍵相關聯的 AdSense 屬性值。
getAttributeKeys
傳回這項服務中已設定的屬性鍵。
getSlots
取得與這項服務相關聯的時段清單。
getTargeting
傳回已設定的特定自訂服務層級指定目標參數。
getTargetingKeys
傳回所有已設定的自訂服務層級指定目標鍵清單。
isInitialLoadDisabled
傳回先前呼叫 PubAdsService.disableInitialLoad 是否成功停用廣告的初始請求。
refresh
擷取並顯示網頁上特定或所有版位的新廣告。
removeEventListener
移除先前註冊的接聽程式。
set
為適用於「發布商廣告」服務中所有廣告版位的 AdSense 屬性設定值。
setCategoryExclusion
為指定標籤名稱設定網頁層級廣告類別排除條件。
setCentering
啟用及停用廣告的水平置中功能。
setForceSafeFrame
設定是否應強制使用 SafeFrame 容器顯示網頁上的所有廣告。
setLocation
傳遞網站的位置資訊，方便您將委刊項指定到特定地區。
setPrivacySettings
使用設定物件，透過單一 API 設定所有隱私權設定。
setPublisherProvidedId
設定發布商提供 ID 的值。
setSafeFrameConfig
設定 SafeFrame 設定的網頁層級偏好設定。
setTargeting
為特定鍵設定自訂指定目標參數，適用於所有 Publisher Ads 服務廣告版位。
setVideoContent
設定要與廣告請求一併傳送的影片內容資訊，以利指定目標和排除內容。
updateCorrelator
變更隨廣告請求傳送的關聯值，有效啟動新的網頁瀏覽。

方法

清楚

clear(slots?: Slot[]): boolean
從指定插槽移除廣告，並以空白內容取代。系統會將這些廣告空間標示為未擷取。

特別是，清除廣告空間會從 GPT 的長效網頁瀏覽中移除廣告，因此未來的請求不會受到涉及這則廣告的連鎖廣告或競爭排除條件影響。
範例

JavaScript

const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
googletag.display("div-1");
const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2");
googletag.display("div-2");

// This call to clear only slot1.
googletag.pubads().clear([slot1]);

// This call to clear both slot1 and slot2.
googletag.pubads().clear([slot1, slot2]);

// This call to clear all slots.
googletag.pubads().clear();

JavaScript (舊版)

var slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
googletag.display("div-1");
var slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2");
googletag.display("div-2");

// This call to clear only slot1.
googletag.pubads().clear([slot1]);

// This call to clear both slot1 and slot2.
googletag.pubads().clear([slot1, slot2]);

// This call to clear all slots.
googletag.pubads().clear();

TypeScript

const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1")!;
googletag.display("div-1");
const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2")!;
googletag.display("div-2");

// This call to clear only slot1.
googletag.pubads().clear([slot1]);

// This call to clear both slot1 and slot2.
googletag.pubads().clear([slot1, slot2]);

// This call to clear all slots.
googletag.pubads().clear();
參數
Optional slots: Slot[]要清除的時段陣列。陣列為選填，如未指定，系統會清除所有時段。
傳回
boolean如果已清除時段，則傳回 true，否則傳回 false。

clearCategoryExclusions

clearCategoryExclusions(): PubAdsService
清除所有網頁層級廣告類別排除標籤。如要重新整理時段，這個方法就非常實用。
範例

JavaScript

// Set category exclusion to exclude ads with 'AirlineAd' labels.
googletag.pubads().setCategoryExclusion("AirlineAd");

// Make ad requests. No ad with 'AirlineAd' label will be returned.

// Clear category exclusions so all ads can be returned.
googletag.pubads().clearCategoryExclusions();

// Make ad requests. Any ad can be returned.

JavaScript (舊版)

// Set category exclusion to exclude ads with 'AirlineAd' labels.
googletag.pubads().setCategoryExclusion("AirlineAd");

// Make ad requests. No ad with 'AirlineAd' label will be returned.

// Clear category exclusions so all ads can be returned.
googletag.pubads().clearCategoryExclusions();

// Make ad requests. Any ad can be returned.

TypeScript

// Set category exclusion to exclude ads with 'AirlineAd' labels.
googletag.pubads().setCategoryExclusion("AirlineAd");

// Make ad requests. No ad with 'AirlineAd' label will be returned.

// Clear category exclusions so all ads can be returned.
googletag.pubads().clearCategoryExclusions();

// Make ad requests. Any ad can be returned.
另請參閱
傳回
PubAdsService呼叫方法的服務物件。

clearTargeting

clearTargeting(key?: string): PubAdsService
清除特定鍵或所有鍵的自訂指定目標參數。
範例

JavaScript

googletag.pubads().setTargeting("interests", "sports");
googletag.pubads().setTargeting("colors", "blue");
googletag.pubads().setTargeting("fruits", "apple");

googletag.pubads().clearTargeting("interests");
// Targeting 'colors' and 'fruits' are still present, while 'interests'
// was cleared.

googletag.pubads().clearTargeting();
// All targeting has been cleared.

JavaScript (舊版)

googletag.pubads().setTargeting("interests", "sports");
googletag.pubads().setTargeting("colors", "blue");
googletag.pubads().setTargeting("fruits", "apple");

googletag.pubads().clearTargeting("interests");
// Targeting 'colors' and 'fruits' are still present, while 'interests'
// was cleared.

googletag.pubads().clearTargeting();
// All targeting has been cleared.

TypeScript

googletag.pubads().setTargeting("interests", "sports");
googletag.pubads().setTargeting("colors", "blue");
googletag.pubads().setTargeting("fruits", "apple");

googletag.pubads().clearTargeting("interests");
// Targeting 'colors' and 'fruits' are still present, while 'interests'
// was cleared.

googletag.pubads().clearTargeting();
// All targeting has been cleared.
另請參閱
參數
Optional key: string指定目標參數鍵。這個鍵是選用項目，如果未指定，系統會清除所有指定目標參數。
傳回
PubAdsService呼叫方法的服務物件。

collapseEmptyDivs

collapseEmptyDivs(collapseBeforeAdFetch?: boolean): boolean
啟用收合廣告版位 div，這樣如果沒有可顯示的廣告內容，廣告版位就不會佔用網頁空間。必須先設定這個模式，才能啟用服務。
另請參閱
參數
Optional collapseBeforeAdFetch: boolean是否要在擷取廣告前收合廣告空間。這個參數為選填，如未提供，系統會使用 false 做為預設值。
傳回
boolean如果已啟用 div 摺疊模式，則傳回 true；如果方法是在啟用服務後呼叫，導致無法啟用摺疊模式，則傳回 false。

disableInitialLoad

disableInitialLoad(): void
在網頁載入時停用廣告請求，但允許透過 PubAdsService.refresh 呼叫請求廣告。啟用服務前，請先設定這項功能。必須使用非同步模式，否則無法使用 refresh 請求廣告。
另請參閱

螢幕

display(adUnitPath: string, size: GeneralSize, div?: string | Element, clickUrl?: string): void
使用指定廣告單元路徑和大小建構及顯示廣告版位。這個方法不適用於單一請求模式。

注意：呼叫這個方法時，系統會建立廣告空間和網頁狀態的快照，確保傳送廣告請求及算繪回應時的一致性。呼叫這個方法後，對廣告空間或網頁狀態所做的任何變更 (包括指定目標、隱私權設定、強制使用 SafeFrame 等)，只會套用至後續的 display() 或 refresh() 請求。
範例

JavaScript

googletag.pubads().display("/1234567/sports", [728, 90], "div-1");

JavaScript (舊版)

googletag.pubads().display("/1234567/sports", [728, 90], "div-1");

TypeScript

googletag.pubads().display("/1234567/sports", [728, 90], "div-1");
另請參閱
參數
adUnitPath: string要算繪的廣告空間廣告單元路徑。
size: GeneralSize插槽的寬度和高度。
Optional div: string | Element包含插槽的 div ID 或 div 元素本身。
Optional clickUrl: string要在這個位置使用的點擊網址。

enableLazyLoad

enableLazyLoad(config?: {
  fetchMarginPercent?: number;
  mobileScaling?: number;
  renderMarginPercent?: number;
}): void
根據設定物件定義，在 GPT 中啟用延遲載入。如需更詳細的範例，請參閱延遲載入範例。

注意：只有在所有廣告空間都位於擷取邊界外時，SRA 才會延遲擷取廣告。
範例

JavaScript

googletag.pubads().enableLazyLoad({
  // Fetch slots within 5 viewports.
  fetchMarginPercent: 500,
  // Render slots within 2 viewports.
  renderMarginPercent: 200,
  // Double the above values on mobile.
  mobileScaling: 2.0,
});

JavaScript (舊版)

googletag.pubads().enableLazyLoad({
  // Fetch slots within 5 viewports.
  fetchMarginPercent: 500,
  // Render slots within 2 viewports.
  renderMarginPercent: 200,
  // Double the above values on mobile.
  mobileScaling: 2.0,
});

TypeScript

googletag.pubads().enableLazyLoad({
  // Fetch slots within 5 viewports.
  fetchMarginPercent: 500,
  // Render slots within 2 viewports.
  renderMarginPercent: 200,
  // Double the above values on mobile.
  mobileScaling: 2.0,
});
另請參閱
參數
Optional config: {
  fetchMarginPercent?: number;
  mobileScaling?: number;
  renderMarginPercent?: number;
}		設定物件可自訂延遲行為。如果省略任何設定，系統會使用 Google 預設設定，並隨時間調整。如要停用特定設定 (例如擷取邊界)，請將值設為 -1。
  • fetchMarginPercent

    廣告版位與目前可視區域的最小距離，以可視區域大小的百分比表示。值為 0 表示「版位進入可視區域時」，值為 100 表示「廣告距離可視區域 1 個版位時」，依此類推。
  • renderMarginPercent

    廣告空間與目前可視區域的最小距離，必須達到這個距離，系統才會顯示廣告。這樣一來，系統就能預先擷取廣告，但會等待算繪及下載其他子資源。這個值的作用與 fetchMarginPercent 相同，都是以檢視區塊的百分比表示。
  • mobileScaling

    套用至行動裝置邊界的乘數。因此行動裝置和電腦的邊界可能不同。舉例來說，如果值為 2.0，系統會將行動裝置上的所有邊界乘以 2，增加擷取及算繪前，廣告空間可達到的最小距離。

enableSingleRequest

enableSingleRequest(): boolean
啟用單一要求模式，同時擷取多個廣告。這項功能需要先定義所有發布商廣告版位，並加入 PubAdsService，才能啟用服務。啟用服務前，必須先設定單一要求模式。
另請參閱
傳回
boolean如果已啟用單一請求模式，則傳回 true；如果方法是在服務啟用後呼叫，導致無法啟用單一請求模式，則傳回 false。

enableVideoAds

enableVideoAds(): void
向 GPT 發出信號，表示網頁上會顯示影片廣告。這項功能可對多媒體廣告和影片廣告啟用競爭排除限制。如果知道影片內容，請呼叫 PubAdsService.setVideoContent，以便對多媒體廣告使用內容排除條件。

get

get(key: string): string
傳回與指定鍵相關聯的 AdSense 屬性值。
範例

JavaScript

googletag.pubads().set("adsense_background_color", "#FFFFFF");
googletag.pubads().get("adsense_background_color");
// Returns '#FFFFFF'.

JavaScript (舊版)

googletag.pubads().set("adsense_background_color", "#FFFFFF");
googletag.pubads().get("adsense_background_color");
// Returns '#FFFFFF'.

TypeScript

googletag.pubads().set("adsense_background_color", "#FFFFFF");
googletag.pubads().get("adsense_background_color");
// Returns '#FFFFFF'.
另請參閱
參數
key: string要尋找的屬性名稱。
傳回
string屬性鍵的目前值，或 null (如果沒有該鍵)。

getAttributeKeys

getAttributeKeys(): string[]
傳回這項服務中已設定的屬性鍵。
範例

JavaScript

googletag.pubads().set("adsense_background_color", "#FFFFFF");
googletag.pubads().set("adsense_border_color", "#AABBCC");
googletag.pubads().getAttributeKeys();
// Returns ['adsense_background_color', 'adsense_border_color'].

JavaScript (舊版)

googletag.pubads().set("adsense_background_color", "#FFFFFF");
googletag.pubads().set("adsense_border_color", "#AABBCC");
googletag.pubads().getAttributeKeys();
// Returns ['adsense_background_color', 'adsense_border_color'].

TypeScript

googletag.pubads().set("adsense_background_color", "#FFFFFF");
googletag.pubads().set("adsense_border_color", "#AABBCC");
googletag.pubads().getAttributeKeys();
// Returns ['adsense_background_color', 'adsense_border_color'].
傳回
string[]這個服務上設定的屬性鍵陣列。排序方式未定義。

getTargeting

getTargeting(key: string): string[]
傳回已設定的特定自訂服務層級指定目標參數。
範例

JavaScript

googletag.pubads().setTargeting("interests", "sports");

googletag.pubads().getTargeting("interests");
// Returns ['sports'].

googletag.pubads().getTargeting("age");
// Returns [] (empty array).

JavaScript (舊版)

googletag.pubads().setTargeting("interests", "sports");

googletag.pubads().getTargeting("interests");
// Returns ['sports'].

googletag.pubads().getTargeting("age");
// Returns [] (empty array).

TypeScript

googletag.pubads().setTargeting("interests", "sports");

googletag.pubads().getTargeting("interests");
// Returns ['sports'].

googletag.pubads().getTargeting("age");
// Returns [] (empty array).
參數
key: string要尋找的指定鍵。
傳回
string[]與這個鍵相關聯的值，如果沒有這類鍵，則為空陣列。

getTargetingKeys

getTargetingKeys(): string[]
傳回已設定的所有自訂服務層級指定目標鍵清單。
範例

JavaScript

googletag.pubads().setTargeting("interests", "sports");
googletag.pubads().setTargeting("colors", "blue");

googletag.pubads().getTargetingKeys();
// Returns ['interests', 'colors'].

JavaScript (舊版)

googletag.pubads().setTargeting("interests", "sports");
googletag.pubads().setTargeting("colors", "blue");

googletag.pubads().getTargetingKeys();
// Returns ['interests', 'colors'].

TypeScript

googletag.pubads().setTargeting("interests", "sports");
googletag.pubads().setTargeting("colors", "blue");

googletag.pubads().getTargetingKeys();
// Returns ['interests', 'colors'].
傳回
string[]指定鍵陣列。排序方式未定義。

isInitialLoadDisabled

isInitialLoadDisabled(): boolean
傳回先前呼叫 PubAdsService.disableInitialLoad 是否成功停用廣告的初始請求。
傳回
boolean如果先前呼叫 PubAdsService.disableInitialLoad 成功，則傳回 true，否則傳回 false。

refresh

refresh(slots?: Slot[], options?: {
  changeCorrelator: boolean;
}): void
擷取並顯示網頁上特定或所有版位的新廣告。僅適用於非同步顯示模式。

如要在所有瀏覽器中正常運作，呼叫 refresh 前必須先呼叫 display 廣告空間。如果省略對 display 的呼叫，重新整理可能會發生非預期的行為。如要停止 display 擷取廣告，可以使用 PubAdsService.disableInitialLoad 方法。

重新整理廣告空間會從 GPT 的長效網頁瀏覽中移除舊廣告，因此日後的請求不會受到涉及該廣告的路障型廣告或競爭排除條件影響。
範例

JavaScript

const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
googletag.display("div-1");
const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2");
googletag.display("div-2");

// This call to refresh fetches a new ad for slot1 only.
googletag.pubads().refresh([slot1]);

// This call to refresh fetches a new ad for both slot1 and slot2.
googletag.pubads().refresh([slot1, slot2]);

// This call to refresh fetches a new ad for each slot.
googletag.pubads().refresh();

// This call to refresh fetches a new ad for slot1, without changing
// the correlator.
googletag.pubads().refresh([slot1], { changeCorrelator: false });

// This call to refresh fetches a new ad for each slot, without
// changing the correlator.
googletag.pubads().refresh(null, { changeCorrelator: false });

JavaScript (舊版)

var slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
googletag.display("div-1");
var slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2");
googletag.display("div-2");

// This call to refresh fetches a new ad for slot1 only.
googletag.pubads().refresh([slot1]);

// This call to refresh fetches a new ad for both slot1 and slot2.
googletag.pubads().refresh([slot1, slot2]);

// This call to refresh fetches a new ad for each slot.
googletag.pubads().refresh();

// This call to refresh fetches a new ad for slot1, without changing
// the correlator.
googletag.pubads().refresh([slot1], { changeCorrelator: false });

// This call to refresh fetches a new ad for each slot, without
// changing the correlator.
googletag.pubads().refresh(null, { changeCorrelator: false });

TypeScript

const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1")!;
googletag.display("div-1");
const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2")!;
googletag.display("div-2");

// This call to refresh fetches a new ad for slot1 only.
googletag.pubads().refresh([slot1]);

// This call to refresh fetches a new ad for both slot1 and slot2.
googletag.pubads().refresh([slot1, slot2]);

// This call to refresh fetches a new ad for each slot.
googletag.pubads().refresh();

// This call to refresh fetches a new ad for slot1, without changing
// the correlator.
googletag.pubads().refresh([slot1], { changeCorrelator: false });

// This call to refresh fetches a new ad for each slot, without
// changing the correlator.
googletag.pubads().refresh(null, { changeCorrelator: false });
另請參閱
參數
Optional slots: Slot[]要重新整理的時段。陣列為選用項目；如未指定，系統會重新整理所有位置。
Optional options: {
  changeCorrelator: boolean;
}		與此重新整理呼叫相關聯的設定選項。
  • changeCorrelator

    指定是否要產生新的相互關係值來擷取廣告。廣告伺服器會短暫保留這個 Correlator 值 (目前為 30 秒，但可能會變更)，因此如果系統在非常短的時間內收到具有相同 Correlator 值的多個請求，就會將其視為單一的網頁瀏覽事件。根據預設，每次重新整理都會產生新的關聯器。

    注意：這個選項不會影響 GPT 的長期網頁瀏覽，因為這項功能會自動反映網頁上目前的廣告，且沒有到期時間。

set

set(key: string, value: string): PubAdsService
為適用於「發布商廣告」服務中所有廣告版位的 AdSense 屬性設定值。

如果針對同一個鍵多次呼叫這個函式，系統會覆寫先前為該鍵設定的值。呼叫 display 或 refresh 前，必須先設定所有值。
範例

JavaScript

googletag.pubads().set("adsense_background_color", "#FFFFFF");

JavaScript (舊版)

googletag.pubads().set("adsense_background_color", "#FFFFFF");

TypeScript

googletag.pubads().set("adsense_background_color", "#FFFFFF");
另請參閱
參數
key: string屬性名稱。
value: string屬性值。
傳回
PubAdsService呼叫方法的服務物件。

setCategoryExclusion

setCategoryExclusion(categoryExclusion: string): PubAdsService
為指定標籤名稱設定網頁層級廣告類別排除條件。
範例

JavaScript

// Label = AirlineAd.
googletag.pubads().setCategoryExclusion("AirlineAd");

JavaScript (舊版)

// Label = AirlineAd.
googletag.pubads().setCategoryExclusion("AirlineAd");

TypeScript

// Label = AirlineAd.
googletag.pubads().setCategoryExclusion("AirlineAd");
另請參閱
參數
categoryExclusion: string要新增的廣告類別排除標籤。
傳回
PubAdsService呼叫方法的服務物件。

setCentering

setCentering(centerAds: boolean): void
啟用及停用廣告的水平置中功能。這項功能預設為停用。在舊版 gpt_mobile.js 中，系統預設會啟用置中功能。

呼叫 display 或 refresh 前，請先叫用這個方法，因為只有在呼叫這個方法後要求的廣告才會置中。
範例

JavaScript

// Make ads centered.
googletag.pubads().setCentering(true);

JavaScript (舊版)

// Make ads centered.
googletag.pubads().setCentering(true);

TypeScript

// Make ads centered.
googletag.pubads().setCentering(true);
參數
centerAds: booleantrue 可將廣告置中，false 則可將廣告靠左對齊。

setForceSafeFrame

setForceSafeFrame(forceSafeFrame: boolean): PubAdsService
設定是否應強制使用 SafeFrame 容器顯示網頁上的所有廣告。

使用這個 API 時，請注意下列事項：
  • 這項設定只會對相應廣告空間的後續廣告請求生效。
  • 如果指定版位層級設定，系統一律會覆寫網頁層級設定。
  • 如果設為 true (在版位層級或網頁層級)，無論在 Google Ad Manager 使用者介面中選擇哪個選項，廣告一律會使用 SafeFrame 容器顯示。
  • 不過，如果設為 false 或未指定，系統會根據廣告素材類型和 Google Ad Manager 使用者介面中的選取項目，使用 SafeFrame 容器顯示廣告。
  • 請謹慎使用此 API，因為這可能會影響嘗試脫離 iframe 的廣告素材行為，或影響廣告素材直接在發布商網頁中顯示的行為。
範例

JavaScript

googletag.pubads().setForceSafeFrame(true);

// The following slot will be opted-out of the page-level force
// SafeFrame instruction.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setForceSafeFrame(false)
  .addService(googletag.pubads());

// The following slot will have SafeFrame forced.
googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads());

googletag.display("div-1");
googletag.display("div-2");

JavaScript (舊版)

googletag.pubads().setForceSafeFrame(true);

// The following slot will be opted-out of the page-level force
// SafeFrame instruction.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setForceSafeFrame(false)
  .addService(googletag.pubads());

// The following slot will have SafeFrame forced.
googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads());

googletag.display("div-1");
googletag.display("div-2");

TypeScript

googletag.pubads().setForceSafeFrame(true);

// The following slot will be opted-out of the page-level force
// SafeFrame instruction.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")!
  .setForceSafeFrame(false)
  .addService(googletag.pubads());

// The following slot will have SafeFrame forced.
googletag.defineSlot("/1234567/news", [160, 600], "div-2")!.addService(googletag.pubads());

googletag.display("div-1");
googletag.display("div-2");
另請參閱
參數
forceSafeFrame: booleantrue，強制網頁上的所有廣告在 SafeFrame 中顯示，以及 false 將先前的設定變更為 false。如果先前未指定，將此值設為 false 不會造成任何變更。
傳回
PubAdsService呼叫函式的服務物件。

setLocation

setLocation(address: string): PubAdsService
傳遞網站的位置資訊，方便您將委刊項指定至特定位置。
範例

JavaScript

// Postal code:
googletag.pubads().setLocation("10001,US");

JavaScript (舊版)

// Postal code:
googletag.pubads().setLocation("10001,US");

TypeScript

// Postal code:
googletag.pubads().setLocation("10001,US");
參數
address: string任意形式的地址。
傳回
PubAdsService呼叫方法的服務物件。

setPrivacySettings

setPrivacySettings(privacySettings: PrivacySettingsConfig): PubAdsService
透過設定物件，使用單一 API 設定所有隱私權設定。
範例

JavaScript

googletag.pubads().setPrivacySettings({
  restrictDataProcessing: true,
});

// Set multiple privacy settings at the same time.
googletag.pubads().setPrivacySettings({
  childDirectedTreatment: true,
  underAgeOfConsent: true,
});

// Clear the configuration for childDirectedTreatment.
googletag.pubads().setPrivacySettings({
  childDirectedTreatment: null,
});

JavaScript (舊版)

googletag.pubads().setPrivacySettings({
  restrictDataProcessing: true,
});

// Set multiple privacy settings at the same time.
googletag.pubads().setPrivacySettings({
  childDirectedTreatment: true,
  underAgeOfConsent: true,
});

// Clear the configuration for childDirectedTreatment.
googletag.pubads().setPrivacySettings({
  childDirectedTreatment: null,
});

TypeScript

googletag.pubads().setPrivacySettings({
  restrictDataProcessing: true,
});

// Set multiple privacy settings at the same time.
googletag.pubads().setPrivacySettings({
  childDirectedTreatment: true,
  underAgeOfConsent: true,
});

// Clear the configuration for childDirectedTreatment.
googletag.pubads().setPrivacySettings({
  childDirectedTreatment: null,
});
另請參閱
參數
privacySettings: PrivacySettingsConfig包含隱私權設定的物件。
傳回
PubAdsService呼叫函式的服務物件。

setPublisherProvidedId

setPublisherProvidedId(ppid: string): PubAdsService
設定發布商提供的 ID 值。
範例

JavaScript

googletag.pubads().setPublisherProvidedId("12JD92JD8078S8J29SDOAKC0EF230337");

JavaScript (舊版)

googletag.pubads().setPublisherProvidedId("12JD92JD8078S8J29SDOAKC0EF230337");

TypeScript

googletag.pubads().setPublisherProvidedId("12JD92JD8078S8J29SDOAKC0EF230337");
另請參閱
參數
ppid: string發布商提供的英數字元 ID。長度必須介於 32 到 150 個字元之間。
傳回
PubAdsService呼叫方法的服務物件。

setSafeFrameConfig

setSafeFrameConfig(config: SafeFrameConfig): PubAdsService
設定 SafeFrame 設定的網頁層級偏好設定。系統會忽略設定物件中無法辨識的鍵。如果為可辨識的鍵傳遞無效值，系統會忽略整個設定。

如果指定版位層級偏好設定，系統會覆寫這些網頁層級偏好設定。
範例

JavaScript

googletag.pubads().setForceSafeFrame(true);

const pageConfig = {
  allowOverlayExpansion: true,
  allowPushExpansion: true,
  sandbox: true,
};

const slotConfig = { allowOverlayExpansion: false };

googletag.pubads().setSafeFrameConfig(pageConfig);

// The following slot will not allow for expansion by overlay.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setSafeFrameConfig(slotConfig)
  .addService(googletag.pubads());

// The following slot will inherit the page level settings, and hence
// would allow for expansion by overlay.
googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads());

googletag.display("div-1");
googletag.display("div-2");

JavaScript (舊版)

googletag.pubads().setForceSafeFrame(true);

var pageConfig = {
  allowOverlayExpansion: true,
  allowPushExpansion: true,
  sandbox: true,
};

var slotConfig = { allowOverlayExpansion: false };

googletag.pubads().setSafeFrameConfig(pageConfig);

// The following slot will not allow for expansion by overlay.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setSafeFrameConfig(slotConfig)
  .addService(googletag.pubads());

// The following slot will inherit the page level settings, and hence
// would allow for expansion by overlay.
googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads());

googletag.display("div-1");
googletag.display("div-2");

TypeScript

googletag.pubads().setForceSafeFrame(true);

const pageConfig = {
  allowOverlayExpansion: true,
  allowPushExpansion: true,
  sandbox: true,
};

const slotConfig = { allowOverlayExpansion: false };

googletag.pubads().setSafeFrameConfig(pageConfig);

// The following slot will not allow for expansion by overlay.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")!
  .setSafeFrameConfig(slotConfig)
  .addService(googletag.pubads());

// The following slot will inherit the page level settings, and hence
// would allow for expansion by overlay.
googletag.defineSlot("/1234567/news", [160, 600], "div-2")!.addService(googletag.pubads());

googletag.display("div-1");
googletag.display("div-2");
另請參閱
參數
config: SafeFrameConfig設定物件。
傳回
PubAdsService呼叫方法的服務物件。

setTargeting

setTargeting(key: string, value: string | string[]): PubAdsService
為特定鍵設定自訂指定目標參數，適用於所有 Publisher Ads 服務廣告版位。針對相同鍵多次呼叫此函式會覆寫舊值。這些鍵是在 Google Ad Manager 帳戶中定義。
範例

JavaScript

// Example with a single value for a key.
googletag.pubads().setTargeting("interests", "sports");

// Example with multiple values for a key inside in an array.
googletag.pubads().setTargeting("interests", ["sports", "music"]);

JavaScript (舊版)

// Example with a single value for a key.
googletag.pubads().setTargeting("interests", "sports");

// Example with multiple values for a key inside in an array.
googletag.pubads().setTargeting("interests", ["sports", "music"]);

TypeScript

// Example with a single value for a key.
googletag.pubads().setTargeting("interests", "sports");

// Example with multiple values for a key inside in an array.
googletag.pubads().setTargeting("interests", ["sports", "music"]);
另請參閱
參數
key: string指定目標參數鍵。
value: string | string[]指定目標參數值或值陣列。
傳回
PubAdsService呼叫方法的服務物件。

setVideoContent

setVideoContent(videoContentId: string, videoCmsId: string): void
設定要與廣告請求一併傳送的影片內容資訊，以利指定目標和排除內容。呼叫這個方法時，系統會自動啟用影片廣告。對於 videoContentId 和 videoCmsId，請使用提供給 Google Ad Manager 內容擷取服務的值。
另請參閱
參數
videoContentId: string影片內容 ID。
videoCmsId: string影片 CMS ID。

updateCorrelator

updateCorrelator(): PubAdsService
變更隨廣告請求傳送的關聯值，有效啟動新的網頁瀏覽。同一次網頁瀏覽的所有廣告請求都會使用相同的 Correlator，但每次網頁瀏覽的 Correlator 都不一樣。僅適用於非同步模式。

注意：這不會影響 GPT 的長期網頁瀏覽，後者會自動反映網頁上實際顯示的廣告，且沒有到期時間。
範例

JavaScript

// Assume that the correlator is currently 12345. All ad requests made
// by this page will currently use that value.

// Replace the current correlator with a new correlator.
googletag.pubads().updateCorrelator();

// The correlator will now be a new randomly selected value, different
// from 12345. All subsequent ad requests made by this page will use
// the new value.

JavaScript (舊版)

// Assume that the correlator is currently 12345. All ad requests made
// by this page will currently use that value.

// Replace the current correlator with a new correlator.
googletag.pubads().updateCorrelator();

// The correlator will now be a new randomly selected value, different
// from 12345. All subsequent ad requests made by this page will use
// the new value.

TypeScript

// Assume that the correlator is currently 12345. All ad requests made
// by this page will currently use that value.

// Replace the current correlator with a new correlator.
googletag.pubads().updateCorrelator();

// The correlator will now be a new randomly selected value, different
// from 12345. All subsequent ad requests made by this page will use
// the new value.
傳回
PubAdsService呼叫函式的服務物件。

googletag.ResponseInformation

代表單一廣告回應的物件。
屬性
advertiserId
廣告主的 ID。
campaignId
廣告活動的 ID。
creativeId
廣告素材的 ID。
creativeTemplateId
廣告的範本 ID。
lineItemId
商品項目的 ID。
另請參閱

屬性

advertiserId

advertiserId: number
廣告主的 ID。

campaignId

campaignId: number
廣告活動的 ID。

creativeId

creativeId: number
廣告素材的 ID。

creativeTemplateId

creativeTemplateId: number
廣告的範本 ID。

lineItemId

lineItemId: number
商品項目的 ID。

googletag.RewardedPayload

代表與獎勵廣告相關聯獎勵的物件
屬性
amount
獎勵內含的商品數量。
type
獎勵中包含的項目類型 (例如「金幣」)。
另請參閱

屬性

amount

amount: number
獎勵內含的商品數量。

type

type: string
獎勵中包含的項目類型 (例如「金幣」)。

googletag.Service

基本服務類別，包含所有服務通用的方法。
方法
addEventListener
註冊監聽器，讓您在網頁上發生特定 GPT 事件時，設定及呼叫 JavaScript 函式。
getSlots
取得與這項服務相關聯的時段清單。
removeEventListener
移除先前註冊的接聽程式。

方法

addEventListener

addEventListener<K extends keyof EventTypeMap>(eventType: K, listener: ((arg: EventTypeMap[K]) => void)): Service
註冊監聽器，讓您在網頁上發生特定 GPT 事件時，設定及呼叫 JavaScript 函式。支援的事件如下：呼叫監聽器時，系統會將適當事件類型的物件傳遞至監聽器。
範例

JavaScript

// 1. Adding an event listener for the PubAdsService.
googletag.pubads().addEventListener("slotOnload", (event) => {
  console.log("Slot has been loaded:");
  console.log(event);
});

// 2. Adding an event listener with slot specific logic.
// Listeners operate at service level, which means that you cannot add
// a listener for an event for a specific slot only. You can, however,
// programmatically filter a listener to respond only to a certain ad
// slot, using this pattern:
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotOnload", (event) => {
  if (event.slot === targetSlot) {
    // Slot specific logic.
  }
});

JavaScript (舊版)

// 1. Adding an event listener for the PubAdsService.
googletag.pubads().addEventListener("slotOnload", function (event) {
  console.log("Slot has been loaded:");
  console.log(event);
});

// 2. Adding an event listener with slot specific logic.
// Listeners operate at service level, which means that you cannot add
// a listener for an event for a specific slot only. You can, however,
// programmatically filter a listener to respond only to a certain ad
// slot, using this pattern:
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotOnload", function (event) {
  if (event.slot === targetSlot) {
    // Slot specific logic.
  }
});

TypeScript

// 1. Adding an event listener for the PubAdsService.
googletag.pubads().addEventListener("slotOnload", (event) => {
  console.log("Slot has been loaded:");
  console.log(event);
});

// 2. Adding an event listener with slot specific logic.
// Listeners operate at service level, which means that you cannot add
// a listener for an event for a specific slot only. You can, however,
// programmatically filter a listener to respond only to a certain ad
// slot, using this pattern:
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotOnload", (event) => {
  if (event.slot === targetSlot) {
    // Slot specific logic.
  }
});
另請參閱
參數
eventType: K代表 GPT 產生的事件類型字串。事件類型會區分大小寫。
listener: ((arg: EventTypeMap[K]) => void)函式，採用單一事件物件引數。
傳回
Service呼叫方法的服務物件。

getSlots

getSlots(): Slot[]
取得與這項服務相關聯的時段清單。
傳回
Slot[]按照加入服務的順序排列。

removeEventListener

removeEventListener<K extends keyof EventTypeMap>(eventType: K, listener: ((event: EventTypeMap[K]) => void)): void
移除先前註冊的接聽程式。
範例

JavaScript

googletag.cmd.push(() => {
  // Define a new ad slot.
  googletag.defineSlot("/6355419/Travel", [728, 90], "div-for-slot").addService(googletag.pubads());

  // Define a new function that removes itself via removeEventListener
  // after the impressionViewable event fires.
  const onViewableListener = (event) => {
    googletag.pubads().removeEventListener("impressionViewable", onViewableListener);
    setTimeout(() => {
      googletag.pubads().refresh([event.slot]);
    }, 30000);
  };

  // Add onViewableListener as a listener for impressionViewable events.
  googletag.pubads().addEventListener("impressionViewable", onViewableListener);
  googletag.enableServices();
});

JavaScript (舊版)

googletag.cmd.push(function () {
  // Define a new ad slot.
  googletag.defineSlot("/6355419/Travel", [728, 90], "div-for-slot").addService(googletag.pubads());

  // Define a new function that removes itself via removeEventListener
  // after the impressionViewable event fires.
  var onViewableListener = function (event) {
    googletag.pubads().removeEventListener("impressionViewable", onViewableListener);
    setTimeout(function () {
      googletag.pubads().refresh([event.slot]);
    }, 30000);
  };

  // Add onViewableListener as a listener for impressionViewable events.
  googletag.pubads().addEventListener("impressionViewable", onViewableListener);
  googletag.enableServices();
});

TypeScript

googletag.cmd.push(() => {
  // Define a new ad slot.
  googletag
    .defineSlot("/6355419/Travel", [728, 90], "div-for-slot")!
    .addService(googletag.pubads());

  // Define a new function that removes itself via removeEventListener
  // after the impressionViewable event fires.
  const onViewableListener = (event: googletag.events.ImpressionViewableEvent) => {
    googletag.pubads().removeEventListener("impressionViewable", onViewableListener);
    setTimeout(() => {
      googletag.pubads().refresh([event.slot]);
    }, 30000);
  };

  // Add onViewableListener as a listener for impressionViewable events.
  googletag.pubads().addEventListener("impressionViewable", onViewableListener);
  googletag.enableServices();
});
參數
eventType: K代表 GPT 產生的事件類型字串。事件類型會區分大小寫。
listener: ((event: EventTypeMap[K]) => void)函式，採用單一事件物件引數。

googletag.SizeMappingBuilder

大小對應規格物件的建構工具。我們提供這個建構工具，方便您輕鬆建構尺寸規格。
方法
addSize
將單一大小的陣列 (代表可視區域) 對應至單一或多個大小的陣列 (代表插槽)。
build
根據新增至這個建構工具的對應項目，建構尺寸對應規格。
另請參閱

方法

addSize

addSize(viewportSize: SingleSizeArray, slotSize: GeneralSize): SizeMappingBuilder
將單一大小的陣列 (代表可視區域) 對應至代表廣告空間的單一或多個大小的陣列。
範例

JavaScript

// Mapping 1
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [728, 90])
  .addSize([640, 480], "fluid")
  .addSize([0, 0], [88, 31]) // All viewports &lt; 640x480
  .build();

// Mapping 2
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [])
  .addSize([640, 480], [120, 60])
  .addSize([0, 0], [])
  .build();

// Mapping 2 will not show any ads for the following viewport sizes:
// [1024, 768] > size >= [980, 690] and
// [640, 480] > size >= [0, 0]

JavaScript (舊版)

// Mapping 1
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [728, 90])
  .addSize([640, 480], "fluid")
  .addSize([0, 0], [88, 31]) // All viewports &lt; 640x480
  .build();

// Mapping 2
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [])
  .addSize([640, 480], [120, 60])
  .addSize([0, 0], [])
  .build();

// Mapping 2 will not show any ads for the following viewport sizes:
// [1024, 768] > size >= [980, 690] and
// [640, 480] > size >= [0, 0]

TypeScript

// Mapping 1
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [728, 90])
  .addSize([640, 480], "fluid")
  .addSize([0, 0], [88, 31]) // All viewports &lt; 640x480
  .build();

// Mapping 2
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [])
  .addSize([640, 480], [120, 60])
  .addSize([0, 0], [])
  .build();

// Mapping 2 will not show any ads for the following viewport sizes:
// [1024, 768] > size >= [980, 690] and
// [640, 480] > size >= [0, 0]
參數
viewportSize: SingleSizeArray這個對應項目的可視區域大小。
slotSize: GeneralSize這個對應項目廣告空間的大小。
傳回
SizeMappingBuilder這個建構工具的參照。

建構

build(): SizeMappingArray
從新增至這個建構工具的對應項目，建構大小對應規格。

如果提供任何無效的對應項目，這個方法會傳回 null。否則，系統會傳回正確格式的規格，以傳遞至 Slot.defineSizeMapping。

注意：呼叫這個方法後，建構工具的行為未定義。
傳回
SizeMappingArray這個建構工具建立的結果。如果提供無效的大小對應，則可為空值。

googletag.Slot

Slot 是指代表網頁上單一廣告版位的物件。
方法
addService
將服務新增至這個版位。
clearCategoryExclusions
清除這個廣告空間的所有廣告空間層級廣告類別排除標籤。
clearTargeting
清除這個版位的特定或所有自訂版位層級指定目標參數。
defineSizeMapping
為這個廣告空間設定從最小可視區域大小到廣告空間大小的對應陣列。
get
傳回與這個廣告空間指定鍵相關聯的 AdSense 屬性值。
getAdUnitPath
傳回廣告單元的完整路徑，包括聯播網代碼和廣告單元路徑。
getAttributeKeys
傳回此時段設定的屬性鍵清單。
getCategoryExclusions
傳回這個廣告空間的廣告類別排除標籤。
getResponseInformation
傳回廣告回應資訊。
getSlotElementId
傳回定義廣告空間時提供的廣告空間 ID div。
getTargeting
傳回在這個插槽中設定的特定自訂指定目標參數。
getTargetingKeys
傳回在這個廣告空間中設定的所有自訂指定目標鍵清單。
set
為這個廣告版位設定 AdSense 屬性的值。
setCategoryExclusion
在這個版位上設定版位層級的廣告類別排除標籤。
setClickUrl
設定使用者點按廣告後重新導向的點擊網址。
setCollapseEmptyDiv
設定在廣告版位沒有廣告時，是否應隱藏該版位 div。
setConfig
設定這個時段的一般設定選項。
setForceSafeFrame
設定是否應強制使用 SafeFrame 容器顯示這個廣告版位中的廣告。
setSafeFrameConfig
設定 SafeFrame 設定的版位層級偏好設定。
setTargeting
為這個廣告空間設定自訂指定目標參數。
updateTargetingFromMap
從 JSON 物件中的鍵/值對應，為這個廣告空間設定自訂指定目標參數。

方法

addService

addService(service: Service): Slot
將 Service 新增至這個時段。
範例

JavaScript

googletag.defineSlot("/1234567/sports", [160, 600], "div").addService(googletag.pubads());

JavaScript (舊版)

googletag.defineSlot("/1234567/sports", [160, 600], "div").addService(googletag.pubads());

TypeScript

googletag.defineSlot("/1234567/sports", [160, 600], "div")!.addService(googletag.pubads());
另請參閱
參數
service: Service要新增的服務。
傳回
Slot呼叫方法的 slot 物件。

clearCategoryExclusions

clearCategoryExclusions(): Slot
清除這個廣告空間的所有廣告類別排除標籤。
範例

JavaScript

// Set category exclusion to exclude ads with 'AirlineAd' labels.
const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setCategoryExclusion("AirlineAd")
  .addService(googletag.pubads());

// Make an ad request. No ad with 'AirlineAd' label will be returned
// for the slot.

// Clear category exclusions so all ads can be returned.
slot.clearCategoryExclusions();

// Make an ad request. Any ad can be returned for the slot.

JavaScript (舊版)

// Set category exclusion to exclude ads with 'AirlineAd' labels.
var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setCategoryExclusion("AirlineAd")
  .addService(googletag.pubads());

// Make an ad request. No ad with 'AirlineAd' label will be returned
// for the slot.

// Clear category exclusions so all ads can be returned.
slot.clearCategoryExclusions();

// Make an ad request. Any ad can be returned for the slot.

TypeScript

// Set category exclusion to exclude ads with 'AirlineAd' labels.
const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setCategoryExclusion("AirlineAd")
  .addService(googletag.pubads());

// Make an ad request. No ad with 'AirlineAd' label will be returned
// for the slot.

// Clear category exclusions so all ads can be returned.
slot.clearCategoryExclusions();

// Make an ad request. Any ad can be returned for the slot.
傳回
Slot呼叫方法的 slot 物件。

clearTargeting

clearTargeting(key?: string): Slot
清除這個版位的特定或所有自訂版位層級指定目標參數。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setTargeting("allow_expandable", "true")
  .setTargeting("interests", ["sports", "music"])
  .setTargeting("color", "red")
  .addService(googletag.pubads());

slot.clearTargeting("color");
// Targeting 'allow_expandable' and 'interests' are still present,
// while 'color' was cleared.

slot.clearTargeting();
// All targeting has been cleared.

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setTargeting("allow_expandable", "true")
  .setTargeting("interests", ["sports", "music"])
  .setTargeting("color", "red")
  .addService(googletag.pubads());

slot.clearTargeting("color");
// Targeting 'allow_expandable' and 'interests' are still present,
// while 'color' was cleared.

slot.clearTargeting();
// All targeting has been cleared.

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setTargeting("allow_expandable", "true")
  .setTargeting("interests", ["sports", "music"])
  .setTargeting("color", "red")
  .addService(googletag.pubads());

slot.clearTargeting("color");
// Targeting 'allow_expandable' and 'interests' are still present,
// while 'color' was cleared.

slot.clearTargeting();
// All targeting has been cleared.
另請參閱
參數
Optional key: string指定目標參數鍵。這個鍵是選用項目，如果未指定，系統會清除所有指定目標參數。
傳回
Slot呼叫方法的 slot 物件。

defineSizeMapping

defineSizeMapping(sizeMapping: SizeMappingArray): Slot
為這個廣告空間設定從最小可視區域大小到廣告空間大小的對應陣列。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

const mapping = googletag
  .sizeMapping()
  .addSize([100, 100], [88, 31])
  .addSize(
    [320, 400],
    [
      [320, 50],
      [300, 50],
    ],
  )
  .build();

slot.defineSizeMapping(mapping);

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

var mapping = googletag
  .sizeMapping()
  .addSize([100, 100], [88, 31])
  .addSize(
    [320, 400],
    [
      [320, 50],
      [300, 50],
    ],
  )
  .build();

slot.defineSizeMapping(mapping);

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

const mapping = googletag
  .sizeMapping()
  .addSize([100, 100], [88, 31])
  .addSize(
    [320, 400],
    [
      [320, 50],
      [300, 50],
    ],
  )
  .build();

slot.defineSizeMapping(mapping!);
另請參閱
參數
sizeMapping: SizeMappingArray大小對應陣列。您可以使用 SizeMappingBuilder 建立這個物件。每個尺寸對應都是由兩個元素組成的陣列：SingleSizeArray 和 GeneralSize。
傳回
Slot呼叫方法的 slot 物件。

get

get(key: string): string
傳回與這個廣告空間指定鍵相關聯的 AdSense 屬性值。如要查看這個版位繼承的服務層級屬性，請使用 PubAdsService.get。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .set("adsense_background_color", "#FFFFFF")
  .addService(googletag.pubads());

slot.get("adsense_background_color");
// Returns '#FFFFFF'.

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .set("adsense_background_color", "#FFFFFF")
  .addService(googletag.pubads());

slot.get("adsense_background_color");
// Returns '#FFFFFF'.

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .set("adsense_background_color", "#FFFFFF")
  .addService(googletag.pubads());

slot.get("adsense_background_color");
// Returns '#FFFFFF'.
另請參閱
參數
key: string要尋找的屬性名稱。
傳回
string屬性鍵的目前值，或 null (如果沒有該鍵)。

getAdUnitPath

getAdUnitPath(): string
傳回廣告單元的完整路徑，包括聯播網代碼和廣告單元路徑。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

slot.getAdUnitPath();
// Returns '/1234567/sports'.

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

slot.getAdUnitPath();
// Returns '/1234567/sports'.

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

slot.getAdUnitPath();
// Returns '/1234567/sports'.
傳回
string廣告單元路徑。

getAttributeKeys

getAttributeKeys(): string[]
傳回此時段設定的屬性鍵清單。如要查看這個時段繼承的服務層級屬性鍵，請使用 PubAdsService.getAttributeKeys。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .set("adsense_background_color", "#FFFFFF")
  .set("adsense_border_color", "#AABBCC")
  .addService(googletag.pubads());

slot.getAttributeKeys();
// Returns ['adsense_background_color', 'adsense_border_color'].

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .set("adsense_background_color", "#FFFFFF")
  .set("adsense_border_color", "#AABBCC")
  .addService(googletag.pubads());

slot.getAttributeKeys();
// Returns ['adsense_background_color', 'adsense_border_color'].

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .set("adsense_background_color", "#FFFFFF")
  .set("adsense_border_color", "#AABBCC")
  .addService(googletag.pubads());

slot.getAttributeKeys();
// Returns ['adsense_background_color', 'adsense_border_color'].
傳回
string[]屬性鍵陣列。排序方式未定義。

getCategoryExclusions

getCategoryExclusions(): string[]
傳回這個廣告空間的廣告類別排除標籤。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setCategoryExclusion("AirlineAd")
  .setCategoryExclusion("TrainAd")
  .addService(googletag.pubads());

slot.getCategoryExclusions();
// Returns ['AirlineAd', 'TrainAd'].

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setCategoryExclusion("AirlineAd")
  .setCategoryExclusion("TrainAd")
  .addService(googletag.pubads());

slot.getCategoryExclusions();
// Returns ['AirlineAd', 'TrainAd'].

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setCategoryExclusion("AirlineAd")
  .setCategoryExclusion("TrainAd")
  .addService(googletag.pubads());

slot.getCategoryExclusions();
// Returns ['AirlineAd', 'TrainAd'].
傳回
string[]這個廣告空間的廣告類別排除標籤，如果未設定任何標籤，則為空陣列。

getResponseInformation

getResponseInformation(): ResponseInformation
傳回廣告回應資訊。這是根據該廣告空間的最後一個廣告回應。如果在版位沒有廣告時呼叫此方法，系統會傳回 null。
傳回
ResponseInformation最新的廣告回應資訊，如果版位沒有廣告，則為 null。

getSlotElementId

getSlotElementId(): string
傳回定義廣告空間時提供的廣告空間 ID。div
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

slot.getSlotElementId();
// Returns 'div'.

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

slot.getSlotElementId();
// Returns 'div'.

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

slot.getSlotElementId();
// Returns 'div'.
傳回
string運算單元 div ID。

getTargeting

getTargeting(key: string): string[]
傳回在這個廣告空間中設定的特定自訂指定目標參數。不含服務層級指定目標參數。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setTargeting("allow_expandable", "true")
  .addService(googletag.pubads());

slot.getTargeting("allow_expandable");
// Returns ['true'].

slot.getTargeting("age");
// Returns [] (empty array).

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setTargeting("allow_expandable", "true")
  .addService(googletag.pubads());

slot.getTargeting("allow_expandable");
// Returns ['true'].

slot.getTargeting("age");
// Returns [] (empty array).

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setTargeting("allow_expandable", "true")
  .addService(googletag.pubads());

slot.getTargeting("allow_expandable");
// Returns ['true'].

slot.getTargeting("age");
// Returns [] (empty array).
參數
key: string要尋找的指定鍵。
傳回
string[]與這個鍵相關聯的值，如果沒有這類鍵，則為空陣列。

getTargetingKeys

getTargetingKeys(): string[]
傳回這個插槽中設定的所有自訂指定目標鍵清單。不含服務層級指定鍵。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setTargeting("allow_expandable", "true")
  .setTargeting("interests", ["sports", "music"])
  .addService(googletag.pubads());

slot.getTargetingKeys();
// Returns ['interests', 'allow_expandable'].

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setTargeting("allow_expandable", "true")
  .setTargeting("interests", ["sports", "music"])
  .addService(googletag.pubads());

slot.getTargetingKeys();
// Returns ['interests', 'allow_expandable'].

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setTargeting("allow_expandable", "true")
  .setTargeting("interests", ["sports", "music"])
  .addService(googletag.pubads());

slot.getTargetingKeys();
// Returns ['interests', 'allow_expandable'].
傳回
string[]指定鍵陣列。排序方式未定義。

set

set(key: string, value: string): Slot
為這個廣告版位設定 AdSense 屬性的值。這會覆寫此鍵在服務層級設定的任何值。

針對相同鍵多次呼叫這個方法，會覆寫先前為該鍵設定的值。呼叫 display 或 refresh 前，必須先設定所有值。
範例

JavaScript

// Setting an attribute on a single ad slot.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .set("adsense_background_color", "#FFFFFF")
  .addService(googletag.pubads());

JavaScript (舊版)

// Setting an attribute on a single ad slot.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .set("adsense_background_color", "#FFFFFF")
  .addService(googletag.pubads());

TypeScript

// Setting an attribute on a single ad slot.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .set("adsense_background_color", "#FFFFFF")
  .addService(googletag.pubads());
另請參閱
參數
key: string屬性名稱。
value: string屬性值。
傳回
Slot呼叫方法的 slot 物件。

setCategoryExclusion

setCategoryExclusion(categoryExclusion: string): Slot
在這個版位上設定版位層級的廣告類別排除標籤。
範例

JavaScript

// Label = AirlineAd
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setCategoryExclusion("AirlineAd")
  .addService(googletag.pubads());

JavaScript (舊版)

// Label = AirlineAd
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setCategoryExclusion("AirlineAd")
  .addService(googletag.pubads());

TypeScript

// Label = AirlineAd
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setCategoryExclusion("AirlineAd")
  .addService(googletag.pubads());
另請參閱
參數
categoryExclusion: string要新增的廣告類別排除標籤。
傳回
Slot呼叫方法的 slot 物件。

setClickUrl

setClickUrl(value: string): Slot
設定使用者點按廣告後重新導向的點擊網址。

即使點擊網址遭到取代，Google Ad Manager 伺服器仍會記錄點擊次數。系統會將與放送廣告素材相關聯的任何到達網頁網址，附加至提供的值。後續呼叫會覆寫該值。這項功能僅適用於非 SRA 要求。
範例

JavaScript

googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setClickUrl("http://www.example.com?original_click_url=")
  .addService(googletag.pubads());

JavaScript (舊版)

googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setClickUrl("http://www.example.com?original_click_url=")
  .addService(googletag.pubads());

TypeScript

googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setClickUrl("http://www.example.com?original_click_url=")
  .addService(googletag.pubads());
參數
value: string要設定的點擊網址。
傳回
Slot呼叫方法的 slot 物件。

setCollapseEmptyDiv

setCollapseEmptyDiv(collapse: boolean, collapseBeforeAdFetch?: boolean): Slot
設定在廣告版位沒有廣告時，是否應隱藏該版位 div。這會覆寫服務層級設定。
範例

JavaScript

googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setCollapseEmptyDiv(true, true)
  .addService(googletag.pubads());
// The above will cause the div for this slot to be collapsed
// when the page is loaded, before ads are requested.

googletag
  .defineSlot("/1234567/sports", [160, 600], "div-2")
  .setCollapseEmptyDiv(true)
  .addService(googletag.pubads());
// The above will cause the div for this slot to be collapsed
// only after GPT detects that no ads are available for the slot.

JavaScript (舊版)

googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setCollapseEmptyDiv(true, true)
  .addService(googletag.pubads());
// The above will cause the div for this slot to be collapsed
// when the page is loaded, before ads are requested.

googletag
  .defineSlot("/1234567/sports", [160, 600], "div-2")
  .setCollapseEmptyDiv(true)
  .addService(googletag.pubads());
// The above will cause the div for this slot to be collapsed
// only after GPT detects that no ads are available for the slot.

TypeScript

googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")!
  .setCollapseEmptyDiv(true, true)
  .addService(googletag.pubads());
// The above will cause the div for this slot to be collapsed
// when the page is loaded, before ads are requested.

googletag
  .defineSlot("/1234567/sports", [160, 600], "div-2")!
  .setCollapseEmptyDiv(true)
  .addService(googletag.pubads());
// The above will cause the div for this slot to be collapsed
// only after GPT detects that no ads are available for the slot.
另請參閱
參數
collapse: boolean如果未傳回廣告，是否要收合版位。
Optional collapseBeforeAdFetch: boolean是否要在擷取廣告前收合廣告空間。如果摺疊不是 true，則會遭到忽略。
傳回
Slot呼叫方法的 slot 物件。

setConfig

setConfig(slotConfig: SlotSettingsConfig): void
設定這個時段的一般設定選項。
參數
slotConfig: SlotSettingsConfig設定物件。

setForceSafeFrame

setForceSafeFrame(forceSafeFrame: boolean): Slot
設定是否應強制使用 SafeFrame 容器顯示這個版位中的廣告。

使用這個 API 時，請注意下列事項：
  • 這項設定只會對相應廣告空間的後續廣告請求生效。
  • 如果指定版位層級設定，系統一律會覆寫網頁層級設定。
  • 如果設為 true (在版位層級或網頁層級)，無論在 Google Ad Manager 使用者介面中選擇哪個選項，廣告一律會使用 SafeFrame 容器顯示。
  • 不過，如果設為 false 或未指定，系統會根據廣告素材類型和 Google Ad Manager 使用者介面中的選取項目，使用 SafeFrame 容器顯示廣告。
  • 請謹慎使用此 API，因為這可能會影響嘗試脫離 iframe 的廣告素材行為，或影響廣告素材直接在發布商網頁中顯示的行為。
範例

JavaScript

googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setForceSafeFrame(true)
  .addService(googletag.pubads());

JavaScript (舊版)

googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setForceSafeFrame(true)
  .addService(googletag.pubads());

TypeScript

googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setForceSafeFrame(true)
  .addService(googletag.pubads());
另請參閱
參數
forceSafeFrame: booleantrue：強制在這個廣告空間中，以 SafeFrame 顯示所有廣告。false：選擇不採用網頁層級設定 (如有)。如果未在網頁層級指定，將此值設為 false 不會造成任何變更。
傳回
Slot呼叫方法的 slot 物件。

setSafeFrameConfig

setSafeFrameConfig(config: SafeFrameConfig): Slot
設定 SafeFrame 設定的版位層級偏好設定。系統會忽略設定物件中無法辨識的鍵。如果為可辨識的鍵傳遞無效值，系統會忽略整個設定。

如果指定這些版位層級偏好設定，系統會覆寫所有網頁層級偏好設定。
範例

JavaScript

googletag.pubads().setForceSafeFrame(true);

// The following slot will have a sandboxed safeframe that only
// disallows top-level navigation.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setSafeFrameConfig({ sandbox: true })
  .addService(googletag.pubads());

// The following slot will inherit page-level settings.
googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads());

googletag.display("div-1");
googletag.display("div-2");

JavaScript (舊版)

googletag.pubads().setForceSafeFrame(true);

// The following slot will have a sandboxed safeframe that only
// disallows top-level navigation.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setSafeFrameConfig({ sandbox: true })
  .addService(googletag.pubads());

// The following slot will inherit page-level settings.
googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads());

googletag.display("div-1");
googletag.display("div-2");

TypeScript

googletag.pubads().setForceSafeFrame(true);

// The following slot will have a sandboxed safeframe that only
// disallows top-level navigation.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")!
  .setSafeFrameConfig({ sandbox: true })
  .addService(googletag.pubads());

// The following slot will inherit page-level settings.
googletag.defineSlot("/1234567/news", [160, 600], "div-2")!.addService(googletag.pubads());

googletag.display("div-1");
googletag.display("div-2");
另請參閱
參數
config: SafeFrameConfig設定物件。
傳回
Slot呼叫方法的 slot 物件。

setTargeting

setTargeting(key: string, value: string | string[]): Slot
為這個廣告空間設定自訂指定目標參數。針對同一個鍵多次呼叫這個方法，會覆寫舊值。在這裡設定的值會覆寫在服務層級設定的指定目標參數。這些鍵是在 Google Ad Manager 帳戶中定義。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Example with a single value for a key.
slot.setTargeting("allow_expandable", "true");

// Example with multiple values for a key inside in an array.
slot.setTargeting("interests", ["sports", "music"]);

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Example with a single value for a key.
slot.setTargeting("allow_expandable", "true");

// Example with multiple values for a key inside in an array.
slot.setTargeting("interests", ["sports", "music"]);

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

// Example with a single value for a key.
slot.setTargeting("allow_expandable", "true");

// Example with multiple values for a key inside in an array.
slot.setTargeting("interests", ["sports", "music"]);
另請參閱
參數
key: string指定目標參數鍵。
value: string | string[]指定目標參數值或值陣列。
傳回
Slot呼叫方法的 slot 物件。

updateTargetingFromMap

updateTargetingFromMap(map: {
  [adUnitPath: string]: string | string[];
}): Slot
從 JSON 物件中的鍵/值對應，為這個廣告空間設定自訂指定目標參數。這與為物件的所有鍵值呼叫 Slot.setTargeting 相同。這些鍵是在 Google Ad Manager 帳戶中定義。

注意：
  • 如果覆寫，系統只會保留最後一個值。
  • 如果值是陣列，系統會覆寫先前的值，不會合併。
  • 這裡設定的值會覆寫在服務層級設定的指定目標參數。
範例

JavaScript

const slot = googletag.defineSlot("/1234567/sports", [160, 600], "div");

slot.updateTargetingFromMap({
  color: "red",
  interests: ["sports", "music", "movies"],
});

JavaScript (舊版)

var slot = googletag.defineSlot("/1234567/sports", [160, 600], "div");

slot.updateTargetingFromMap({
  color: "red",
  interests: ["sports", "music", "movies"],
});

TypeScript

const slot = googletag.defineSlot("/1234567/sports", [160, 600], "div")!;

slot.updateTargetingFromMap({
  color: "red",
  interests: ["sports", "music", "movies"],
});
參數
map: {
  [adUnitPath: string]: string | string[];
}		指定目標參數鍵/值對應。
傳回
Slot呼叫方法的 slot 物件。

googletag.config

頁面層級設定的主要設定介面。
介面
AdExpansionConfig
控制廣告展開的設定。
AdSenseAttributesConfig
用來控管 AdSense 廣告行為的設定。
ComponentAuctionConfig
代表裝置端廣告競價中的單一元件競價。
InterstitialConfig
這個物件定義單一插頁式廣告版位的行為。
LazyLoadConfig
控制 GPT 中延遲載入功能的設定。
PageSettingsConfig
頁面層級設定的主要設定介面。
PrivacyTreatmentsConfig
用來控管發布商隱私權處理方式的設定。
PublisherProvidedSignalsConfig
發布商提供的信號 (PPS) 設定物件。
SafeFrameConfig
在 GPT 中控管 SafeFrame 的設定。
SlotSettingsConfig
版位層級設定的主要設定介面。
TaxonomyData
包含單一「分類方式」的值的物件。
VideoAdsConfig
設定：設定影片廣告相關設定。
型別別名
InterstitialTrigger
支援插頁式廣告觸發條件。
PrivacyTreatment
支援的發布商隱私權處理方式。
Taxonomy

型別別名

InterstitialTrigger

InterstitialTrigger: "unhideWindow" | "navBar"
支援插頁式廣告觸發條件。

PrivacyTreatment

PrivacyTreatment: "disablePersonalization"
支援的發布商隱私權處理方式。

分類

Taxonomy: "IAB_AUDIENCE_1_1" | "IAB_CONTENT_2_2"
發布商提供的信號 (PPS) 支援的分類。
另請參閱

googletag.config.AdExpansionConfig

控制廣告展開的設定。
屬性
enabled?
廣告展開功能是否已啟用。
範例

JavaScript

// Enable ad slot expansion across the entire page.
googletag.setConfig({
  adExpansion: { enabled: true },
});

JavaScript (舊版)

// Enable ad slot expansion across the entire page.
googletag.setConfig({
  adExpansion: { enabled: true },
});

TypeScript

// Enable ad slot expansion across the entire page.
googletag.setConfig({
  adExpansion: { enabled: true },
});

屬性

Optional 已啟用

enabled?: boolean
廣告展開功能是否啟用。

設定這個值會覆寫 Google Ad Manager 中設定的預設值。
另請參閱

googletag.config.AdSenseAttributesConfig

控制 AdSense 廣告行為的設定。

這些屬性可用於根據每個要求覆寫伺服器端設定。
屬性
adsense_ad_format?
AdSense 廣告格式。
adsense_channel_ids?
AdSense 管道 ID。
adsense_test_mode?
是否啟用測試模式。
document_language?
顯示廣告的網頁語言。
page_url?
顯示廣告的網頁網址。
另請參閱

屬性

Optional adsense_ad_format

adsense_ad_format?: "120x240_as" | "120x600_as" | "125x125_as" | "160x600_as" | "180x150_as" | "200x200_as" | "234x60_as" | "250x250_as" | "300x250_as" | "336x280_as" | "468x60_as" | "728x90_as"
AdSense 廣告格式。

Optional adsense_channel_ids

adsense_channel_ids?: string
AdSense 管道 ID。

有效值為以「+」分隔的管道 ID。

範例：271828183+314159265
另請參閱

Optional adsense_test_mode

adsense_test_mode?: "on"
是否啟用測試模式。

設為 on 時，廣告會標示為僅供測試，不會計入計數或帳單。如果是正式版，非測試流量，則必須取消設定這項設定。

Optional document_language

document_language?: string
顯示廣告的網頁語言。

允許的值為有效的 ISO 639-1 語言代碼。

範例：en
另請參閱

Optional page_url

page_url?: string
顯示廣告的網頁網址。

允許的值為有效網址。

範例：http://www.example.com

googletag.config.ComponentAuctionConfig

代表裝置端廣告競價中的單一元件競價。
屬性
auctionConfig
這個元件競價的競價設定物件。
configKey
與這個元件競價相關聯的設定鍵。
另請參閱

屬性

auctionConfig

auctionConfig: {
  auctionSignals?: unknown;
  decisionLogicURL: string;
  interestGroupBuyers?: string[];
  perBuyerExperimentGroupIds?: {
    [buyer: string]: number;
  };
  perBuyerGroupLimits?: {
    [buyer: string]: number;
  };
  perBuyerSignals?: {
    [buyer: string]: unknown;
  };
  perBuyerTimeouts?: {
    [buyer: string]: number;
  };
  seller: string;
  sellerExperimentGroupId?: number;
  sellerSignals?: unknown;
  sellerTimeout?: number;
  trustedScoringSignalsURL?: string;
}
這個元件競價的競價設定物件。

如果這個值設為 null，系統會刪除指定 configKey 的所有現有設定。
範例

JavaScript

const componentAuctionConfig = {
  // Seller URL should be https and the same as decisionLogicURL's origin
  seller: "https://testSeller.com",
  decisionLogicURL: "https://testSeller.com/ssp/decision-logic.js",
  interestGroupBuyers: ["https://example-buyer.com"],
  auctionSignals: { auction_signals: "auction_signals" },
  sellerSignals: { seller_signals: "seller_signals" },
  perBuyerSignals: {
    // listed on interestGroupBuyers
    "https://example-buyer.com": {
      per_buyer_signals: "per_buyer_signals",
    },
  },
};

const auctionSlot = googletag.defineSlot("/1234567/example", [160, 600]);

// To add configKey to the component auction:
auctionSlot.setConfig({
  componentAuction: [
    {
      configKey: "https://testSeller.com",
      auctionConfig: componentAuctionConfig,
    },
  ],
});

// To remove configKey from the component auction:
auctionSlot.setConfig({
  componentAuction: [
    {
      configKey: "https://testSeller.com",
      auctionConfig: null,
    },
  ],
});

JavaScript (舊版)

var componentAuctionConfig = {
  // Seller URL should be https and the same as decisionLogicURL's origin
  seller: "https://testSeller.com",
  decisionLogicURL: "https://testSeller.com/ssp/decision-logic.js",
  interestGroupBuyers: ["https://example-buyer.com"],
  auctionSignals: { auction_signals: "auction_signals" },
  sellerSignals: { seller_signals: "seller_signals" },
  perBuyerSignals: {
    // listed on interestGroupBuyers
    "https://example-buyer.com": {
      per_buyer_signals: "per_buyer_signals",
    },
  },
};

var auctionSlot = googletag.defineSlot("/1234567/example", [160, 600]);

// To add configKey to the component auction:
auctionSlot.setConfig({
  componentAuction: [
    {
      configKey: "https://testSeller.com",
      auctionConfig: componentAuctionConfig,
    },
  ],
});

// To remove configKey from the component auction:
auctionSlot.setConfig({
  componentAuction: [
    {
      configKey: "https://testSeller.com",
      auctionConfig: null,
    },
  ],
});

TypeScript

const componentAuctionConfig = {
  // Seller URL should be https and the same as decisionLogicURL's origin
  seller: "https://testSeller.com",
  decisionLogicURL: "https://testSeller.com/ssp/decision-logic.js",
  interestGroupBuyers: ["https://example-buyer.com"],
  auctionSignals: { auction_signals: "auction_signals" },
  sellerSignals: { seller_signals: "seller_signals" },
  perBuyerSignals: {
    // listed on interestGroupBuyers
    "https://example-buyer.com": {
      per_buyer_signals: "per_buyer_signals",
    },
  },
};

const auctionSlot = googletag.defineSlot("/1234567/example", [160, 600])!;

// To add configKey to the component auction:
auctionSlot.setConfig({
  componentAuction: [
    {
      configKey: "https://testSeller.com",
      auctionConfig: componentAuctionConfig,
    },
  ],
});

// To remove configKey from the component auction:
auctionSlot.setConfig({
  componentAuction: [
    {
      configKey: "https://testSeller.com",
      auctionConfig: null,
    },
  ],
});
另請參閱

configKey

configKey: string
與這個元件競價相關聯的設定鍵。

這個值不得為空，且不得重複。如果兩個 ComponentAuctionConfig 物件共用相同的 configKey 值，最後設定的物件會覆寫先前的設定。

googletag.config.InterstitialConfig

這個物件定義單一插頁式廣告版位的行為。
屬性
requireStorageAccess?
是否需要取得本機儲存空間的存取權，才能顯示這個插頁式廣告。
triggers?
這個插頁式廣告的插頁式觸發條件設定。

屬性

Optional requireStorageAccess

requireStorageAccess?: boolean
是否需要本機儲存空間同意聲明才能顯示這個插頁式廣告。

GPT 會使用本機儲存空間，強制執行插頁式廣告的展示頻率上限。不過，未提供本機儲存空間同意聲明的使用者，仍有資格看到插頁式廣告。將這項屬性設為 true 可停用預設行為，並確保插頁式廣告只會向已同意本機儲存空間的使用者顯示。
範例

JavaScript

// Opt out of showing interstitials to users
// without local storage consent.
const interstitialSlot = googletag.defineOutOfPageSlot(
  "/1234567/sports",
  googletag.enums.OutOfPageFormat.INTERSTITIAL,
);

interstitialSlot.setConfig({
  interstitial: {
    requireStorageAccess: true, // defaults to false
  },
});

JavaScript (舊版)

// Opt out of showing interstitials to users
// without local storage consent.
var interstitialSlot = googletag.defineOutOfPageSlot(
  "/1234567/sports",
  googletag.enums.OutOfPageFormat.INTERSTITIAL,
);

interstitialSlot.setConfig({
  interstitial: {
    requireStorageAccess: true, // defaults to false
  },
});

TypeScript

// Opt out of showing interstitials to users
// without local storage consent.
const interstitialSlot = googletag.defineOutOfPageSlot(
  "/1234567/sports",
  googletag.enums.OutOfPageFormat.INTERSTITIAL,
)!;

interstitialSlot.setConfig({
  interstitial: {
    requireStorageAccess: true, // defaults to false
  },
});
另請參閱

Optional triggers

triggers?: Partial<Record<InterstitialTrigger, boolean>>
這個插頁式廣告的插頁式觸發條件設定。

將插頁式觸發條件的值設為 true 可啟用，設為 false 則可停用。這會覆寫在 Google Ad Manager 中設定的預設值。
範例

JavaScript

// Define a GPT managed web interstitial ad slot.
const interstitialSlot = googletag.defineOutOfPageSlot(
  "/1234567/sports",
  googletag.enums.OutOfPageFormat.INTERSTITIAL,
);

// Enable optional interstitial triggers.
// Change this value to false to disable.
const enableTriggers = true;

interstitialSlot.setConfig({
  interstitial: {
    triggers: {
      navBar: enableTriggers,
      unhideWindow: enableTriggers,
    },
  },
});

JavaScript (舊版)

// Define a GPT managed web interstitial ad slot.
var interstitialSlot = googletag.defineOutOfPageSlot(
  "/1234567/sports",
  googletag.enums.OutOfPageFormat.INTERSTITIAL,
);

// Enable optional interstitial triggers.
// Change this value to false to disable.
var enableTriggers = true;

interstitialSlot.setConfig({
  interstitial: {
    triggers: {
      navBar: enableTriggers,
      unhideWindow: enableTriggers,
    },
  },
});

TypeScript

// Define a GPT managed web interstitial ad slot.
const interstitialSlot = googletag.defineOutOfPageSlot(
  "/1234567/sports",
  googletag.enums.OutOfPageFormat.INTERSTITIAL,
)!;

// Enable optional interstitial triggers.
// Change this value to false to disable.
const enableTriggers = true;

interstitialSlot.setConfig({
  interstitial: {
    triggers: {
      navBar: enableTriggers,
      unhideWindow: enableTriggers,
    },
  },
});
另請參閱

googletag.config.LazyLoadConfig

控制 GPT 中延遲載入功能的設定。
屬性
fetchMarginPercent?
廣告版位與目前可視區域的最小距離，以可視區域大小的百分比表示。系統必須達到這個距離，才會要求放送廣告。
mobileScaling?
套用至行動裝置邊界的乘數。
renderMarginPercent?
廣告版位與目前可視區域的最小距離，以可視區域大小的百分比表示。系統必須達到這個距離，才會顯示廣告。
另請參閱

屬性

Optional fetchMarginPercent

fetchMarginPercent?: number
廣告請求前，版位與目前可視區域的最小距離，以可視區域大小的百分比表示。

搭配 renderMarginPercent 使用時，這項設定可預先擷取廣告，但會等待算繪及下載其他子資源。因此，這個值一律應大於或等於 renderMarginPercent。

值為 0 表示「當廣告空間進入可視區域時」，100 表示「當廣告距離可視區域 1 個可視區域時」，依此類推。

Optional mobileScaling

mobileScaling?: number
套用至行動裝置邊界的乘數。這個乘數會套用至 fetchMarginPercent 和 renderMarginPercent。

這樣一來，行動裝置和電腦就能使用不同的邊界，因為可視區域大小和捲動速度可能不同。舉例來說，如果值為 2.0，系統會將行動裝置上的所有邊界乘以 2，增加擷取及算繪前，廣告空間與可視區域的最小距離。

Optional renderMarginPercent

renderMarginPercent?: number
廣告空間與目前可視區域的最小距離，以可視區域大小的百分比表示。

搭配 fetchMarginPercent 使用時，這項設定可預先擷取廣告，但會等待算繪及下載其他子資源。因此，這個值應一律小於或等於 fetchMarginPercent。

值為 0 表示「當廣告空間進入可視區域時」，100 表示「當廣告距離可視區域 1 個視埠時」，依此類推。

googletag.config.PageSettingsConfig

網頁層級設定的主要設定介面。

可透過單一 API 呼叫設定多項功能。

以下列出的所有屬性都是範例，不代表實際使用 setConfig 的功能。如需功能集，請參閱下方的 PageSettingsConfig 類型中的欄位。

範例：
  • 系統只會修改 googletag.setConfig 呼叫中指定的功能。
      // Configure feature alpha.
  googletag.setConfig({
      alpha: {...}
  });

  // Configure feature bravo. Feature alpha is unchanged.
  googletag.setConfig({
     bravo: {...}
  });
  • 每次呼叫 googletag.setConfig 時，系統都會更新特定功能的所有設定。
      // Configure feature charlie to echo = 1, foxtrot = true.
  googletag.setConfig({
      charlie: {
          echo: 1,
          foxtrot: true,
      }
  });

  // Update feature charlie to echo = 2. Since foxtrot was not specified,
  // the value is cleared.
  googletag.setConfig({
      charlie: {
          echo: 2
      }
  });
  • 如要清除某項功能的所有設定，請傳遞 null。
      // Configure features delta, golf, and hotel.
  googletag.setConfig({
      delta: {...},
      golf: {...},
      hotel: {...},
  });

  // Feature delta and hotel are cleared, but feature golf remains set.
  googletag.setConfig({
      delta: null,
      hotel: null,
  });
屬性
adExpansion?
控制廣告展開的設定。
adsenseAttributes?
設定 AdSense 屬性。
adYield?
已淘汰。 
categoryExclusion?
設定廣告類別排除條件。
centering?
設定，可控制廣告的水平置中。
collapseDiv?
設定廣告版位的收合行為。
disableInitialLoad?
設定廣告請求時間。
lazyLoad?
控制 GPT 中延遲載入功能的設定。
location?
設定指定地理區域，讓委刊項在特定地理位置放送。
pps?
控制發布商提供的信號 (PPS) 的設定。
privacyTreatments?
用來控管發布商隱私權處理方式的設定。
safeFrame?
控制 GPT 中 SafeFrame 使用情形的設定。
singleRequest?
啟用或停用單一請求架構 (SRA) 的設定。
targeting?
用於控管指定鍵/值的設定。
threadYield?
這項設定可控管 GPT 在請求及顯示廣告素材時，是否應產生 JS 執行緒。
videoAds?
控制影片廣告的設定。

屬性

Optional adExpansion

adExpansion?: AdExpansionConfig
控制廣告展開的設定。

Optional adsenseAttributes

adsenseAttributes?: AdSenseAttributesConfig
設定 AdSense 屬性。

透過這項設定設定的 AdSense 屬性，會套用至網頁上的所有廣告版位。這項設定可多次呼叫，用來定義多個屬性值，或覆寫現有值。

AdSense 屬性變更只會套用至呼叫這個方法後要求的廣告。因此，建議您在呼叫 googletag.display 或 PubAdsService.refresh 之前，先呼叫這個方法。
範例

JavaScript

// Set the document language and page URL.
googletag.setConfig({
  adsenseAttributes: { document_language: "en", page_url: "http://www.example.com" },
});

// Clear the page URL only.
googletag.setConfig({ adsenseAttributes: { page_url: null } });

// Clear all AdSense attributes.
googletag.setConfig({ adsenseAttributes: null });

JavaScript (舊版)

// Set the document language and page URL.
googletag.setConfig({
  adsenseAttributes: { document_language: "en", page_url: "http://www.example.com" },
});

// Clear the page URL only.
googletag.setConfig({ adsenseAttributes: { page_url: null } });

// Clear all AdSense attributes.
googletag.setConfig({ adsenseAttributes: null });

TypeScript

// Set the document language and page URL.
googletag.setConfig({
  adsenseAttributes: { document_language: "en", page_url: "http://www.example.com" },
});

// Clear the page URL only.
googletag.setConfig({ adsenseAttributes: { page_url: null } });

// Clear all AdSense attributes.
googletag.setConfig({ adsenseAttributes: null });

Optional adYield

adYield?: "DISABLED" | "ENABLED_ALL_SLOTS"

Optional categoryExclusion

categoryExclusion?: string[]
設定廣告類別排除條件。
範例

JavaScript

// Label = AirlineAd.
googletag.setConfig({ categoryExclusion: ["AirlineAd"] });

// Clearing category exclusion setting.
googletag.setConfig({ categoryExclusion: null });

JavaScript (舊版)

// Label = AirlineAd.
googletag.setConfig({ categoryExclusion: ["AirlineAd"] });

// Clearing category exclusion setting.
googletag.setConfig({ categoryExclusion: null });

TypeScript

// Label = AirlineAd.
googletag.setConfig({ categoryExclusion: ["AirlineAd"] });

// Clearing category exclusion setting.
googletag.setConfig({ categoryExclusion: null });
另請參閱

Optional 置中

centering?: boolean
設定，可控制廣告的水平置中。預設會停用置中功能。

水平置中變更只會套用至呼叫這個方法後要求的廣告。因此，建議您在呼叫 googletag.display 或 PubAdsService.refresh 之前，先呼叫這個方法。
範例

JavaScript

// Make ads centered.
googletag.setConfig({ centering: true });

// Clear the centering setting.
googletag.setConfig({ centering: null });

JavaScript (舊版)

// Make ads centered.
googletag.setConfig({ centering: true });

// Clear the centering setting.
googletag.setConfig({ centering: null });

TypeScript

// Make ads centered.
googletag.setConfig({ centering: true });

// Clear the centering setting.
googletag.setConfig({ centering: null });

Optional collapseDiv

collapseDiv?: "DISABLED" | "BEFORE_FETCH" | "ON_NO_FILL"
用來控制廣告版位收合行為的設定。

收合的廣告版位不會佔用網頁空間。

支援的值：
  • null (預設)：不會收合插槽。
  • DISABLED：無論是否傳回廣告，版位都不會收合。
  • BEFORE_FETCH：版位一開始會處於收合狀態，並在傳回廣告時展開。
  • ON_NO_FILL：版位一開始會展開，如果沒有傳回廣告，就會收合。
範例

JavaScript

// Collapse the div for this slot if no ad is returned.
googletag.setConfig({ collapseDiv: "ON_NO_FILL" });

// Collapse the div for this slot by default, and expand only
// if an ad is returned.
googletag.setConfig({ collapseDiv: "BEFORE_FETCH" });

// Do not collapse the div for this slot.
googletag.setConfig({ collapseDiv: "DISABLED" });

// Clear the collapse setting.
googletag.setConfig({ collapseDiv: null });

JavaScript (舊版)

// Collapse the div for this slot if no ad is returned.
googletag.setConfig({ collapseDiv: "ON_NO_FILL" });

// Collapse the div for this slot by default, and expand only
// if an ad is returned.
googletag.setConfig({ collapseDiv: "BEFORE_FETCH" });

// Do not collapse the div for this slot.
googletag.setConfig({ collapseDiv: "DISABLED" });

// Clear the collapse setting.
googletag.setConfig({ collapseDiv: null });

TypeScript

// Collapse the div for this slot if no ad is returned.
googletag.setConfig({ collapseDiv: "ON_NO_FILL" });

// Collapse the div for this slot by default, and expand only
// if an ad is returned.
googletag.setConfig({ collapseDiv: "BEFORE_FETCH" });

// Do not collapse the div for this slot.
googletag.setConfig({ collapseDiv: "DISABLED" });

// Clear the collapse setting.
googletag.setConfig({ collapseDiv: null });
另請參閱

Optional disableInitialLoad

disableInitialLoad?: boolean
設定廣告請求時機。

根據預設，googletag.display 方法會註冊廣告版位，並為這些版位請求廣告。不過，有時您可能希望將這些動作分開，以便更精確地控制廣告內容的載入時間。

啟用這項設定後，系統會在呼叫 display() 方法時，不會為已註冊的廣告空間要求廣告。您必須另外呼叫 PubAdsService.refresh，才能啟動廣告請求。

呼叫 googletag.enableServices 前，必須先呼叫這個方法。
範例

JavaScript

// Prevent requesting ads when `display()` is called.
googletag.setConfig({ disableInitialLoad: true });

JavaScript (舊版)

// Prevent requesting ads when `display()` is called.
googletag.setConfig({ disableInitialLoad: true });

TypeScript

// Prevent requesting ads when `display()` is called.
googletag.setConfig({ disableInitialLoad: true });
另請參閱

Optional lazyLoad

lazyLoad?: LazyLoadConfig
用於控管 GPT 中延遲載入功能的設定。

延遲載入技術可延遲廣告請求和顯示，直到廣告接近使用者的可視區域為止。如需更詳細的範例，請參閱延遲載入範例。

注意：如果啟用 singleRequest，只有在所有廣告空間都位於擷取邊界外時，延遲擷取才會運作。

呼叫 setConfig() 時，如果未指定任何延遲載入設定，系統會使用 Google 設定的預設值。這些預設值可能會隨時間調整。如要停用特定設定，請將值設為 null。
範例

JavaScript

// Enable lazy loading.
googletag.setConfig({
  lazyLoad: {
    // Fetch slots within 5 viewports.
    fetchMarginPercent: 500,
    // Render slots within 2 viewports.
    renderMarginPercent: 200,
    // Double the above values on mobile.
    mobileScaling: 2.0,
  },
});

// Clear fetch margin only.
googletag.setConfig({
  lazyLoad: { fetchMarginPercent: null },
});

// Clear all lazy loading settings.
googletag.setConfig({ lazyLoad: null });

JavaScript (舊版)

// Enable lazy loading.
googletag.setConfig({
  lazyLoad: {
    // Fetch slots within 5 viewports.
    fetchMarginPercent: 500,
    // Render slots within 2 viewports.
    renderMarginPercent: 200,
    // Double the above values on mobile.
    mobileScaling: 2.0,
  },
});

// Clear fetch margin only.
googletag.setConfig({
  lazyLoad: { fetchMarginPercent: null },
});

// Clear all lazy loading settings.
googletag.setConfig({ lazyLoad: null });

TypeScript

// Enable lazy loading.
googletag.setConfig({
  lazyLoad: {
    // Fetch slots within 5 viewports.
    fetchMarginPercent: 500,
    // Render slots within 2 viewports.
    renderMarginPercent: 200,
    // Double the above values on mobile.
    mobileScaling: 2.0,
  },
});

// Clear fetch margin only.
googletag.setConfig({
  lazyLoad: { fetchMarginPercent: null },
});

// Clear all lazy loading settings.
googletag.setConfig({ lazyLoad: null });
另請參閱

Optional location

location?: string
設定委刊項的指定地理區域。
範例

JavaScript

// Geo-target line items to US postal code 10001.
googletag.setConfig({ location: "10001,US" });

// Clear the location setting.
googletag.setConfig({ location: null });

JavaScript (舊版)

// Geo-target line items to US postal code 10001.
googletag.setConfig({ location: "10001,US" });

// Clear the location setting.
googletag.setConfig({ location: null });

TypeScript

// Geo-target line items to US postal code 10001.
googletag.setConfig({ location: "10001,US" });

// Clear the location setting.
googletag.setConfig({ location: null });
另請參閱

Optional pps

控制發布商提供的信號 (PPS) 的設定。

Optional privacyTreatments

privacyTreatments?: PrivacyTreatmentsConfig
用來控管發布商隱私權處理方式的設定。

Optional safeFrame

safeFrame?: SafeFrameConfig
控制 GPT 中 SafeFrame 使用情形的設定。

透過這項設定設定的值會套用至網頁上的所有廣告版位。個別廣告版位可能會透過 SlotSettingsConfig.safeFrame 覆寫這些值。
範例

JavaScript

// Force SafeFrame for all ads on the page.
googletag.setConfig({
  safeFrame: { forceSafeFrame: true },
});

// Configure SafeFrame to allow overlay expansion.
googletag.setConfig({
  safeFrame: { allowOverlayExpansion: true },
});

// Clear forceSafeFrame setting.
googletag.setConfig({
  safeFrame: { forceSafeFrame: null },
});

// Clear all SafeFrame settings.
googletag.setConfig({ safeFrame: null });

JavaScript (舊版)

// Force SafeFrame for all ads on the page.
googletag.setConfig({
  safeFrame: { forceSafeFrame: true },
});

// Configure SafeFrame to allow overlay expansion.
googletag.setConfig({
  safeFrame: { allowOverlayExpansion: true },
});

// Clear forceSafeFrame setting.
googletag.setConfig({
  safeFrame: { forceSafeFrame: null },
});

// Clear all SafeFrame settings.
googletag.setConfig({ safeFrame: null });

TypeScript

// Force SafeFrame for all ads on the page.
googletag.setConfig({
  safeFrame: { forceSafeFrame: true },
});

// Configure SafeFrame to allow overlay expansion.
googletag.setConfig({
  safeFrame: { allowOverlayExpansion: true },
});

// Clear forceSafeFrame setting.
googletag.setConfig({
  safeFrame: { forceSafeFrame: null },
});

// Clear all SafeFrame settings.
googletag.setConfig({ safeFrame: null });

Optional singleRequest

singleRequest?: boolean
啟用或停用單一請求架構 (SRA) 的設定。

啟用 SRA 後，系統會將 googletag.display 或 PubAdsService.refresh 呼叫前定義的所有廣告版位，批次處理為單一廣告請求。這不僅能提升成效，也是確保路障型廣告和競爭排除條件能正常運作的必要條件。

如果停用 SRA，系統會個別請求每個廣告版位。這是 GPT 的預設行為。

呼叫 googletag.enableServices 前必須先呼叫這個方法。
範例

JavaScript

// Enable Single Request Architecture.
googletag.setConfig({ singleRequest: true });

JavaScript (舊版)

// Enable Single Request Architecture.
googletag.setConfig({ singleRequest: true });

TypeScript

// Enable Single Request Architecture.
googletag.setConfig({ singleRequest: true });
另請參閱

Optional targeting

targeting?: Record<string, string | string[]>
用於控管鍵/值指定目標的設定。

透過這項設定指定的目標，會套用至網頁上的所有廣告版位。這個設定可能會多次呼叫，以定義多個指定目標鍵/值，或覆寫現有值。指定鍵是在 Google Ad Manager 帳戶中定義。
範例

JavaScript

// Setting a single targeting key-value.
googletag.setConfig({ targeting: { interests: "sports" } });

// Setting multiple values for a single targeting key
googletag.setConfig({ targeting: { interests: ["sports", "music"] } });

// Setting multiple targeting key-values at once.
googletag.setConfig({ targeting: { interests: ["sports", "music"], color: "red" } });

// Clearing a single targeting key.
googletag.setConfig({ targeting: { interests: null } });

JavaScript (舊版)

// Setting a single targeting key-value.
googletag.setConfig({ targeting: { interests: "sports" } });

// Setting multiple values for a single targeting key
googletag.setConfig({ targeting: { interests: ["sports", "music"] } });

// Setting multiple targeting key-values at once.
googletag.setConfig({ targeting: { interests: ["sports", "music"], color: "red" } });

// Clearing a single targeting key.
googletag.setConfig({ targeting: { interests: null } });

TypeScript

// Setting a single targeting key-value.
googletag.setConfig({ targeting: { interests: "sports" } });

// Setting multiple values for a single targeting key
googletag.setConfig({ targeting: { interests: ["sports", "music"] } });

// Setting multiple targeting key-values at once.
googletag.setConfig({ targeting: { interests: ["sports", "music"], color: "red" } });

// Clearing a single targeting key.
googletag.setConfig({ targeting: { interests: null } });
另請參閱

Optional threadYield

threadYield?: "DISABLED" | "ENABLED_ALL_SLOTS"
這項設定可控制 GPT 在請求及顯示素材資源時，是否應產生 JS 執行緒。

GPT 只會為支援 Scheduler.postTask 或 Scheduler.yield API 的瀏覽器產生執行緒。

支援的值：
  • null (預設)：GPT 會為可視區域外的廣告空間產生 JS 執行緒。
  • ENABLED_ALL_SLOTS：無論版位是否位於可視區域內，GPT 都會為所有版位產生 JS 執行緒。
  • DISABLED：GPT 不會產生 JS 執行緒。
範例

JavaScript

// Disable yielding.
googletag.setConfig({ threadYield: "DISABLED" });

// Enable yielding for all slots.
googletag.setConfig({ threadYield: "ENABLED_ALL_SLOTS" });

// Enable yielding only for slots outside of the viewport (default).
googletag.setConfig({ threadYield: null });

JavaScript (舊版)

// Disable yielding.
googletag.setConfig({ threadYield: "DISABLED" });

// Enable yielding for all slots.
googletag.setConfig({ threadYield: "ENABLED_ALL_SLOTS" });

// Enable yielding only for slots outside of the viewport (default).
googletag.setConfig({ threadYield: null });

TypeScript

// Disable yielding.
googletag.setConfig({ threadYield: "DISABLED" });

// Enable yielding for all slots.
googletag.setConfig({ threadYield: "ENABLED_ALL_SLOTS" });

// Enable yielding only for slots outside of the viewport (default).
googletag.setConfig({ threadYield: null });
另請參閱

Optional videoAds

videoAds?: VideoAdsConfig
控管影片廣告的設定。
範例

JavaScript

// Enable video ads and set video content and content source IDs.
googletag.setConfig({
  videoAds: {
    enableVideoAds: true,
    videoContentId: "e1eGlRL7ju8",
    videoCmsId: "1234567",
  },
});

JavaScript (舊版)

// Enable video ads and set video content and content source IDs.
googletag.setConfig({
  videoAds: {
    enableVideoAds: true,
    videoContentId: "e1eGlRL7ju8",
    videoCmsId: "1234567",
  },
});

TypeScript

// Enable video ads and set video content and content source IDs.
googletag.setConfig({
  videoAds: {
    enableVideoAds: true,
    videoContentId: "e1eGlRL7ju8",
    videoCmsId: "1234567",
  },
});
另請參閱

googletag.config.PrivacyTreatmentsConfig

用來控管發布商隱私權處理方式的設定。
屬性
treatments
要啟用的發布商隱私權處理方式陣列。

屬性

治療方式

treatments: "disablePersonalization"[]
可啟用的一系列發布商隱私權處理方式。
範例

JavaScript

// Disable personalization across the entire page.
googletag.setConfig({
  privacyTreatments: { treatments: ["disablePersonalization"] },
});

JavaScript (舊版)

// Disable personalization across the entire page.
googletag.setConfig({
  privacyTreatments: { treatments: ["disablePersonalization"] },
});

TypeScript

// Disable personalization across the entire page.
googletag.setConfig({
  privacyTreatments: { treatments: ["disablePersonalization"] },
});

googletag.config.PublisherProvidedSignalsConfig

發布商提供的信號 (PPS) 設定物件。
屬性
taxonomies
包含 Taxonomy 對應項的物件，或用於清除設定的空值。
範例

JavaScript

googletag.setConfig({
  pps: {
    taxonomies: {
      IAB_AUDIENCE_1_1: { values: ["6", "626"] },
      // '6' = 'Demographic | Age Range | 30-34'
      // '626' = 'Interest | Sports | Darts'
      IAB_CONTENT_2_2: { values: ["48", "127"] },
      // '48' = 'Books and Literature | Fiction'
      // '127' = 'Careers | Job Search'
    },
  },
});

JavaScript (舊版)

googletag.setConfig({
  pps: {
    taxonomies: {
      IAB_AUDIENCE_1_1: { values: ["6", "626"] },
      // '6' = 'Demographic | Age Range | 30-34'
      // '626' = 'Interest | Sports | Darts'
      IAB_CONTENT_2_2: { values: ["48", "127"] },
      // '48' = 'Books and Literature | Fiction'
      // '127' = 'Careers | Job Search'
    },
  },
});

TypeScript

googletag.setConfig({
  pps: {
    taxonomies: {
      IAB_AUDIENCE_1_1: { values: ["6", "626"] },
      // '6' = 'Demographic | Age Range | 30-34'
      // '626' = 'Interest | Sports | Darts'
      IAB_CONTENT_2_2: { values: ["48", "127"] },
      // '48' = 'Books and Literature | Fiction'
      // '127' = 'Careers | Job Search'
    },
  },
});
另請參閱

屬性

分類

taxonomies: Partial<Record<Taxonomy, TaxonomyData>>
包含 Taxonomy 對應項的物件，或用於清除設定的空值。

googletag.config.SafeFrameConfig

在 GPT 中控管 SafeFrame 的設定。
屬性
allowOverlayExpansion?
SafeFrame 是否應允許廣告內容透過疊加網頁內容的方式展開。
allowPushExpansion?
SafeFrame 是否應允許廣告內容擴展，並將網頁內容往外推。
forceSafeFrame?
是否應強制使用 SafeFrame 容器顯示廣告。
sandbox?
SafeFrame 是否應使用 HTML5 sandbox 屬性，禁止在沒有使用者互動的情況下進行頂層導覽。
useUniqueDomain?
已淘汰。 SafeFrame 是否應為預訂廣告素材使用隨機子網域。
另請參閱

屬性

Optional allowOverlayExpansion

allowOverlayExpansion?: boolean
SafeFrame 是否應允許廣告內容透過疊加網頁內容的方式展開。

Optional allowPushExpansion

allowPushExpansion?: boolean
SafeFrame 是否應允許廣告內容擴展，並將網頁內容往外推。

Optional forceSafeFrame

forceSafeFrame?: boolean
是否應強制使用 SafeFrame 容器顯示廣告。

Optional sandbox

sandbox?: boolean
SafeFrame 是否應使用 HTML5 sandbox 屬性，禁止在沒有使用者互動的情況下進行頂層導覽。唯一有效值為 true (無法強制設為 false)。請注意，沙箱屬性會停用外掛程式 (例如 Flash)。

Optional useUniqueDomain

useUniqueDomain?: boolean
SafeFrame 是否應為預訂廣告素材使用隨機子網域。傳遞 null 可清除儲存的值。

注意：這項功能預設為啟用。
另請參閱

googletag.config.SlotSettingsConfig

設定廣告空間層級設定的主要介面。

可透過單一 API 呼叫，為單一廣告空間設定多項功能。

以下列出的所有屬性都是範例，並未反映實際使用 setConfig 的功能。如需功能組合，請參閱下方的 SlotSettingsConfig 類型中的欄位。

範例：
  • 系統只會修改 Slot.setConfig 呼叫中指定的特徵。
      const slot = googletag.defineSlot("/1234567/example", [160, 600]);

  // Configure feature alpha.
  slot.setConfig({
      alpha: {...}
  });

  // Configure feature bravo. Feature alpha is unchanged.
  slot.setConfig({
     bravo: {...}
  });
  • 每次呼叫 Slot.setConfig 時，系統都會更新特定功能的設定。
      // Configure feature charlie to echo = 1, foxtrot = true.
  slot.setConfig({
      charlie: {
          echo: 1,
          foxtrot: true,
      }
  });

  // Update feature charlie to echo = 2. Since foxtrot was not specified,
  // the value is cleared.
  slot.setConfig({
      charlie: {
          echo: 2
      }
  });
  • 如要清除某項功能的所有設定，請傳遞 null。
      // Configure features delta, golf, and hotel.
  slot.setConfig({
      delta: {...},
      golf: {...},
      hotel: {...},
  });

  // Feature delta and hotel are cleared, but feature golf remains set.
  slot.setConfig({
      delta: null,
      hotel: null,
  });
屬性
adExpansion?
設定廣告擴展功能。
adsenseAttributes?
設定 AdSense 屬性。
categoryExclusion?
設定廣告類別排除條件。
clickUrl?
設定使用者點按廣告後重新導向的網址。
collapseDiv?
設定，用於設定廣告空間的收合行為。
componentAuction?
要納入裝置端廣告競價的元件競價陣列。
interstitial?
設定插頁式廣告空間行為的設定。
safeFrame?
設定在 GPT 中使用 SafeFrame。
targeting?
用於設定鍵/值指定目標的設定。

屬性

Optional adExpansion

adExpansion?: AdExpansionConfig
設定廣告擴展功能。
另請參閱

Optional adsenseAttributes

adsenseAttributes?: AdSenseAttributesConfig
設定 AdSense 屬性。

透過這項設定設定的 AdSense 屬性只會套用至廣告空間。這項設定可多次呼叫，用來定義多個屬性值，或覆寫現有值。

AdSense 屬性變更只會套用至呼叫這個方法後要求的廣告。因此，建議您在呼叫 googletag.display 或 PubAdsService.refresh 之前，先呼叫這個方法。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Set the AdSense ad format and channel IDs.
slot.setConfig({
  adsenseAttributes: {
    adsense_ad_format: "120x240_as",
    adsense_channel_ids: "271828183+314159265",
  },
});

// Clear the AdSense channel IDs only.
slot.setConfig({ adsenseAttributes: { adsense_channel_ids: null } });

// Clear all AdSense attributes.
slot.setConfig({ adsenseAttributes: null });

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Set the AdSense ad format and channel IDs.
slot.setConfig({
  adsenseAttributes: {
    adsense_ad_format: "120x240_as",
    adsense_channel_ids: "271828183+314159265",
  },
});

// Clear the AdSense channel IDs only.
slot.setConfig({ adsenseAttributes: { adsense_channel_ids: null } });

// Clear all AdSense attributes.
slot.setConfig({ adsenseAttributes: null });

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

// Set the AdSense ad format and channel IDs.
slot.setConfig({
  adsenseAttributes: {
    adsense_ad_format: "120x240_as",
    adsense_channel_ids: "271828183+314159265",
  },
});

// Clear the AdSense channel IDs only.
slot.setConfig({ adsenseAttributes: { adsense_channel_ids: null } });

// Clear all AdSense attributes.
slot.setConfig({ adsenseAttributes: null });

Optional categoryExclusion

categoryExclusion?: string[]
設定廣告類別排除條件。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Label = AirlineAd
slot.setConfig({
  categoryExclusion: ["AirlineAd"],
});

// Clearing category exclusion setting.
slot.setConfig({ categoryExclusion: null });

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Label = AirlineAd
slot.setConfig({
  categoryExclusion: ["AirlineAd"],
});

// Clearing category exclusion setting.
slot.setConfig({ categoryExclusion: null });

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

// Label = AirlineAd
slot.setConfig({
  categoryExclusion: ["AirlineAd"],
});

// Clearing category exclusion setting.
slot.setConfig({ categoryExclusion: null });
另請參閱

Optional clickUrl

clickUrl?: string
設定使用者點按廣告後重新導向的網址。

即使點擊網址遭到取代，Google Ad Manager 伺服器仍會記錄點擊。系統會將與放送廣告素材相關聯的任何到達網頁網址，附加至提供的值。如果多次設定這個值，系統會覆寫先前設定的值。傳入 null 會清除值。

注意：這項設定僅適用於非 SRA 要求。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Sets the click URL to 'http://www.example.com?original_click_url='.
slot.setConfig({
  clickUrl: "http://www.example.com?original_click_url=",
});

// Clears the click URL.
slot.setConfig({
  clickUrl: null,
});

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Sets the click URL to 'http://www.example.com?original_click_url='.
slot.setConfig({
  clickUrl: "http://www.example.com?original_click_url=",
});

// Clears the click URL.
slot.setConfig({
  clickUrl: null,
});

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

// Sets the click URL to 'http://www.example.com?original_click_url='.
slot.setConfig({
  clickUrl: "http://www.example.com?original_click_url=",
});

// Clears the click URL.
slot.setConfig({
  clickUrl: null,
});

Optional collapseDiv

collapseDiv?: "DISABLED" | "BEFORE_FETCH" | "ON_NO_FILL"
設定廣告版位的收合行為。

收合的廣告版位不會佔用網頁空間。

支援的值：
  • null (預設)：不會收合插槽。
  • DISABLED：無論是否傳回廣告，版位都不會收合。
  • BEFORE_FETCH：版位一開始會處於收合狀態，並在傳回廣告時展開。
  • ON_NO_FILL：版位一開始會展開，如果沒有傳回廣告，就會收合。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Collapse the div for this slot if no ad is returned.
slot.setConfig({
  collapseDiv: "ON_NO_FILL",
});

// Collapse the div for this slot by default, and expand only
// if an ad is returned.
slot.setConfig({
  collapseDiv: "BEFORE_FETCH",
});

// Do not collapse the div for this slot.
slot.setConfig({
  collapseDiv: "DISABLED",
});

// Clear the collapse setting.
slot.setConfig({
  collapseDiv: null,
});

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Collapse the div for this slot if no ad is returned.
slot.setConfig({
  collapseDiv: "ON_NO_FILL",
});

// Collapse the div for this slot by default, and expand only
// if an ad is returned.
slot.setConfig({
  collapseDiv: "BEFORE_FETCH",
});

// Do not collapse the div for this slot.
slot.setConfig({
  collapseDiv: "DISABLED",
});

// Clear the collapse setting.
slot.setConfig({
  collapseDiv: null,
});

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

// Collapse the div for this slot if no ad is returned.
slot.setConfig({
  collapseDiv: "ON_NO_FILL",
});

// Collapse the div for this slot by default, and expand only
// if an ad is returned.
slot.setConfig({
  collapseDiv: "BEFORE_FETCH",
});

// Do not collapse the div for this slot.
slot.setConfig({
  collapseDiv: "DISABLED",
});

// Clear the collapse setting.
slot.setConfig({
  collapseDiv: null,
});
另請參閱

Optional componentAuction

componentAuction?: ComponentAuctionConfig[]
要納入裝置端廣告競價的元件競價陣列。

Optional interstitial

interstitial?: InterstitialConfig
設定插頁式廣告版位行為的設定。
另請參閱

Optional safeFrame

safeFrame?: SafeFrameConfig
設定在 GPT 中使用 SafeFrame。

透過這項設定設定的值只會套用至廣告版位，並覆寫透過 PageSettingsConfig.safeFrame 設定的值。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Force SafeFrame for the slot.
slot.setConfig({
  safeFrame: { forceSafeFrame: true },
});

// Configure SafeFrame to allow overlay expansion for the slot.
slot.setConfig({
  safeFrame: { allowOverlayExpansion: true },
});

// Clear forceSafeFrame setting for the slot.
slot.setConfig({
  safeFrame: { forceSafeFrame: null },
});

// Clear all SafeFrame settings for the slot.
slot.setConfig({ safeFrame: null });

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Force SafeFrame for the slot.
slot.setConfig({
  safeFrame: { forceSafeFrame: true },
});

// Configure SafeFrame to allow overlay expansion for the slot.
slot.setConfig({
  safeFrame: { allowOverlayExpansion: true },
});

// Clear forceSafeFrame setting for the slot.
slot.setConfig({
  safeFrame: { forceSafeFrame: null },
});

// Clear all SafeFrame settings for the slot.
slot.setConfig({ safeFrame: null });

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

// Force SafeFrame for the slot.
slot.setConfig({
  safeFrame: { forceSafeFrame: true },
});

// Configure SafeFrame to allow overlay expansion for the slot.
slot.setConfig({
  safeFrame: { allowOverlayExpansion: true },
});

// Clear forceSafeFrame setting for the slot.
slot.setConfig({
  safeFrame: { forceSafeFrame: null },
});

// Clear all SafeFrame settings for the slot.
slot.setConfig({ safeFrame: null });

Optional targeting

targeting?: Record<string, string | string[]>
設定鍵/值指定目標。

透過這項設定指定的目標只會套用至廣告版位。這個設定可能會多次呼叫，以定義多個指定目標鍵/值，或覆寫現有值。指定鍵是在 Google Ad Manager 帳戶中定義。
範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Setting a single targeting key-value.
slot.setConfig({ targeting: { interests: "sports" } });

// Setting multiple values for a single targeting key.
slot.setConfig({ targeting: { interests: ["sports", "music"] } });

// Setting multiple targeting key-values at once.
slot.setConfig({ targeting: { interests: ["sports", "music"], color: "red" } });

// Clearing a single targeting key.
slot.setConfig({ targeting: { interests: null } });

// Clear all targeting keys.
slot.setConfig({ targeting: null });

JavaScript (舊版)

var slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());

// Setting a single targeting key-value.
slot.setConfig({ targeting: { interests: "sports" } });

// Setting multiple values for a single targeting key.
slot.setConfig({ targeting: { interests: ["sports", "music"] } });

// Setting multiple targeting key-values at once.
slot.setConfig({ targeting: { interests: ["sports", "music"], color: "red" } });

// Clearing a single targeting key.
slot.setConfig({ targeting: { interests: null } });

// Clear all targeting keys.
slot.setConfig({ targeting: null });

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());

// Setting a single targeting key-value.
slot.setConfig({ targeting: { interests: "sports" } });

// Setting multiple values for a single targeting key.
slot.setConfig({ targeting: { interests: ["sports", "music"] } });

// Setting multiple targeting key-values at once.
slot.setConfig({ targeting: { interests: ["sports", "music"], color: "red" } });

// Clearing a single targeting key.
slot.setConfig({ targeting: { interests: null } });

// Clear all targeting keys.
slot.setConfig({ targeting: null });
另請參閱

googletag.config.TaxonomyData

包含單一「分類方式」的值的物件。
屬性
values
分類值清單。

屬性

值

values: readonly string[]
分類值清單。

googletag.config.VideoAdsConfig

設定：設定影片廣告相關設定。
屬性
enableVideoAds
網頁上是否會顯示影片廣告。
videoCmsId?
影片內容來源 ID。
videoContentId?
影片內容 ID。
另請參閱

屬性

enableVideoAds

enableVideoAds: boolean
網頁上是否會顯示影片廣告。

設為 true 時，系統會對多媒體和影片廣告啟用內容排除限制。

如果知道影片內容，請將 videoContentId 和 videoCmsId 設為提供給 Google Ad Manager 內容擷取服務的值，以便對多媒體廣告套用內容排除條件。

Optional videoCmsId

videoCmsId?: string
影片內容來源 ID。

這是 Google Ad Manager 內容擷取服務指派的不重複值，用於識別 videoContentId 指定的影片內容來源。
另請參閱

Optional videoContentId

videoContentId?: string
影片內容 ID。

這是專屬值，用於識別 videoCmsId 指定內容來源中的特定影片。這個值是由代管影片內容的內容管理系統指派。
另請參閱

googletag.enums

這是 GPT 用於列舉型別的命名空間。
列舉
OutOfPageFormat
GPT 支援的非頁內廣告格式。
TrafficSource
GPT 支援的流量來源。

列舉

OutOfPageFormat

OutOfPageFormat
GPT 支援的非頁內格式。
另請參閱
列舉成員
BOTTOM_ANCHOR
錨定格式，版位會固定在可視區域底部。
GAME_MANUAL_INTERSTITIAL
手動插頁式遊戲廣告格式。

注意：手動插頁式遊戲廣告為僅限部分對象使用的格式。
INTERSTITIAL
網頁插頁式廣告素材格式。
LEFT_SIDE_RAIL
左側邊欄格式。
REWARDED
獎勵格式。
RIGHT_SIDE_RAIL
右側邊欄格式。
TOP_ANCHOR
錨定格式，廣告版位會固定在可視區域頂端。

TrafficSource

TrafficSource
GPT 支援的流量來源。
另請參閱
列舉成員
ORGANIC
直接輸入網址、站內搜尋或應用程式下載。
PURCHASED
從非自有資源重新導向而來的流量 (自他處取得或來自獎勵活動)。

googletag.events

這是 GPT 用於事件的命名空間。您的程式碼可以使用 Service.addEventListener 回應這些事件。
介面
Event
所有 GPT 事件的基礎介面。
EventTypeMap
這是偽類型，可將事件名稱對應至 Service.addEventListener 和 Service.removeEventListener 的對應事件物件類型。
GameManualInterstitialSlotClosedEvent
使用者關閉遊戲手動插頁式廣告空間時，系統會觸發這個事件。
GameManualInterstitialSlotReadyEvent
當手動插頁式遊戲廣告版位準備向使用者顯示時，系統會觸發這個事件。
ImpressionViewableEvent
根據 Active View 條件，當曝光次數可視時，系統就會觸發這項事件。
RewardedSlotClosedEvent
使用者關閉獎勵廣告版位時，系統會觸發這個事件。
RewardedSlotGrantedEvent
觀看獎勵廣告後獲得獎勵時，系統會觸發這個事件。
RewardedSlotReadyEvent
當獎勵廣告準備好顯示時，就會觸發這個事件。
SlotOnloadEvent
當廣告素材的 iframe 觸發載入事件時，系統會觸發這個事件。
SlotRenderEndedEvent
廣告素材程式碼注入廣告空間時，系統會觸發這個事件。
SlotRequestedEvent
系統為特定版位請求廣告時，會觸發這個事件。
SlotResponseReceived
收到特定廣告空間的廣告回應時，系統會觸發這個事件。
SlotVisibilityChangedEvent
每當廣告空間區域的螢幕顯示百分比變更時，系統就會觸發這個事件。

googletag.events.Event

所有 GPT 事件的基本介面。下列所有 GPT 事件都會包含下列欄位。
屬性
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
另請參閱

屬性

serviceName

serviceName: string
觸發事件的服務名稱。

slot

slot: Slot
觸發事件的廣告空間。

googletag.events.EventTypeMap

這是偽類型，可將事件名稱對應至 Service.addEventListener 和 Service.removeEventListener 的對應事件物件類型。僅供參考和確保型別安全。
屬性
gameManualInterstitialSlotClosed
gameManualInterstitialSlotReady
impressionViewable
rewardedSlotClosed
rewardedSlotGranted
rewardedSlotReady
slotOnload
slotRenderEnded
slotRequested
slotResponseReceived
slotVisibilityChanged

屬性

gameManualInterstitialSlotClosed

gameManualInterstitialSlotReady

impressionViewable

rewardedSlotClosed

rewardedSlotGranted

rewardedSlotReady

slotOnload

slotOnload: SlotOnloadEvent
events.SlotOnloadEvent 的別名。

slotRenderEnded

slotRequested

slotResponseReceived

slotResponseReceived: SlotResponseReceived
events.SlotResponseReceived 的別名。

slotVisibilityChanged

googletag.events.GameManualInterstitialSlotClosedEvent

延長 Event
當使用者關閉手動插頁式遊戲廣告空間時，系統會觸發這個事件。

注意：手動插頁式遊戲廣告是僅限部分對象使用的格式。
屬性
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
範例

JavaScript

// This listener is called when a game manual interstitial slot is closed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotClosed", (event) => {
    const slot = event.slot;
    console.log("Game manual interstital slot", slot.getSlotElementId(), "is closed.");

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

JavaScript (舊版)

// This listener is called when a game manual interstitial slot is closed.
var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotClosed", function (event) {
    var slot = event.slot;
    console.log("Game manual interstital slot", slot.getSlotElementId(), "is closed.");

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

TypeScript

// This listener is called when a game manual interstitial slot is closed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotClosed", (event) => {
    const slot = event.slot;
    console.log("Game manual interstital slot", slot.getSlotElementId(), "is closed.");

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}
另請參閱

googletag.events.GameManualInterstitialSlotReadyEvent

延長 Event
當手動插頁式遊戲廣告版位準備向使用者顯示時，系統會觸發這個事件。

注意：手動插頁式遊戲廣告是僅限部分對象使用的格式。
屬性
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
方法
makeGameManualInterstitialVisible
向使用者顯示手動插頁式遊戲廣告。
範例

JavaScript

// This listener is called when a game manual interstitial slot is ready to
// be displayed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotReady", (event) => {
    const slot = event.slot;
    console.log(
      "Game manual interstital slot",
      slot.getSlotElementId(),
      "is ready to be displayed.",
    );

    // Replace with custom logic.
    const displayGmiAd = true;
    if (displayGmiAd) {
      event.makeGameManualInterstitialVisible();
    }

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

JavaScript (舊版)

// This listener is called when a game manual interstitial slot is ready to
// be displayed.
var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotReady", function (event) {
    var slot = event.slot;
    console.log(
      "Game manual interstital slot",
      slot.getSlotElementId(),
      "is ready to be displayed.",
    );

    // Replace with custom logic.
    var displayGmiAd = true;
    if (displayGmiAd) {
      event.makeGameManualInterstitialVisible();
    }

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

TypeScript

// This listener is called when a game manual interstitial slot is ready to
// be displayed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotReady", (event) => {
    const slot = event.slot;
    console.log(
      "Game manual interstital slot",
      slot.getSlotElementId(),
      "is ready to be displayed.",
    );

    // Replace with custom logic.
    const displayGmiAd = true;
    if (displayGmiAd) {
      event.makeGameManualInterstitialVisible();
    }

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}
另請參閱

方法

makeGameManualInterstitialVisible

makeGameManualInterstitialVisible(): void
向使用者顯示手動插頁式遊戲廣告。

googletag.events.ImpressionViewableEvent

延長 Event
根據 Active View 條件，當曝光次數可視時，系統就會觸發這項事件。
屬性
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
範例

JavaScript

// This listener is called when an impression becomes viewable.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("impressionViewable", (event) => {
  const slot = event.slot;
  console.log("Impression for slot", slot.getSlotElementId(), "became viewable.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

JavaScript (舊版)

// This listener is called when an impression becomes viewable.
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("impressionViewable", function (event) {
  var slot = event.slot;
  console.log("Impression for slot", slot.getSlotElementId(), "became viewable.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

TypeScript

// This listener is called when an impression becomes viewable.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("impressionViewable", (event) => {
  const slot = event.slot;
  console.log("Impression for slot", slot.getSlotElementId(), "became viewable.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另請參閱

googletag.events.RewardedSlotClosedEvent

延長 Event
使用者關閉獎勵廣告版位時，系統會觸發這個事件。這項事件可能會在授予獎勵之前或之後觸發。如要判斷是否已授予獎勵，請改用 events.RewardedSlotGrantedEvent。
屬性
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
範例

JavaScript

const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called when the user closes a rewarded ad slot.
  googletag.pubads().addEventListener("rewardedSlotClosed", (event) => {
    const slot = event.slot;
    console.log("Rewarded ad slot", slot.getSlotElementId(), "has been closed.");

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

JavaScript (舊版)

var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called when the user closes a rewarded ad slot.
  googletag.pubads().addEventListener("rewardedSlotClosed", function (event) {
    var slot = event.slot;
    console.log("Rewarded ad slot", slot.getSlotElementId(), "has been closed.");

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

TypeScript

const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called when the user closes a rewarded ad slot.
  googletag.pubads().addEventListener("rewardedSlotClosed", (event) => {
    const slot = event.slot;
    console.log("Rewarded ad slot", slot.getSlotElementId(), "has been closed.");

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}
另請參閱

googletag.events.RewardedSlotGrantedEvent

延長 Event
觀看獎勵廣告後獲得獎勵時，系統會觸發這個事件。如果使用者在符合獎勵授予條件前關閉廣告，系統就不會觸發這個事件。
屬性
payload
包含所發放獎勵相關資訊的物件。
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
範例

JavaScript

const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotGranted", (event) => {
    const slot = event.slot;
    console.group("Reward granted for slot", slot.getSlotElementId(), ".");

    // Log details of the reward.
    console.log("Reward type:", event.payload?.type);
    console.log("Reward amount:", event.payload?.amount);
    console.groupEnd();

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

JavaScript (舊版)

var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotGranted", function (event) {
    var _a, _b;
    var slot = event.slot;
    console.group("Reward granted for slot", slot.getSlotElementId(), ".");

    // Log details of the reward.
    console.log("Reward type:", (_a = event.payload) === null || _a === void 0 ? void 0 : _a.type);
    console.log(
      "Reward amount:",
      (_b = event.payload) === null || _b === void 0 ? void 0 : _b.amount,
    );
    console.groupEnd();

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

TypeScript

const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotGranted", (event) => {
    const slot = event.slot;
    console.group("Reward granted for slot", slot.getSlotElementId(), ".");

    // Log details of the reward.
    console.log("Reward type:", event.payload?.type);
    console.log("Reward amount:", event.payload?.amount);
    console.groupEnd();

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}
另請參閱

屬性

payload

包含所發放獎勵相關資訊的物件。

googletag.events.RewardedSlotReadyEvent

延長 Event
當獎勵廣告準備好顯示時，就會觸發這個事件。發布商有責任在顯示廣告前，先向使用者提供觀看廣告的選項。
屬性
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
方法
makeRewardedVisible
顯示獎勵廣告。
範例

JavaScript

// This listener is called when a rewarded ad slot becomes ready to be
// displayed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotReady", (event) => {
    const slot = event.slot;
    console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed.");

    // Replace with custom logic.
    const userHasConsented = true;
    if (userHasConsented) {
      event.makeRewardedVisible();
    }

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

JavaScript (舊版)

// This listener is called when a rewarded ad slot becomes ready to be
// displayed.
var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotReady", function (event) {
    var slot = event.slot;
    console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed.");

    // Replace with custom logic.
    var userHasConsented = true;
    if (userHasConsented) {
      event.makeRewardedVisible();
    }

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}

TypeScript

// This listener is called when a rewarded ad slot becomes ready to be
// displayed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotReady", (event) => {
    const slot = event.slot;
    console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed.");

    // Replace with custom logic.
    const userHasConsented = true;
    if (userHasConsented) {
      event.makeRewardedVisible();
    }

    if (slot === targetSlot) {
      // Slot specific logic.
    }
  });
}
另請參閱

方法

makeRewardedVisible

makeRewardedVisible(): void
顯示獎勵廣告。使用者同意觀看廣告後，才能呼叫這個方法。

googletag.events.SlotOnloadEvent

延長 Event
當廣告素材的 iframe 觸發載入事件時，系統會觸發這個事件。以同步顯示模式顯示 Rich Media 廣告時，系統不會使用 iframe，因此不會觸發 SlotOnloadEvent。
屬性
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
範例

JavaScript

// This listener is called when a creative iframe load event fires.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotOnload", (event) => {
  const slot = event.slot;
  console.log("Creative iframe for slot", slot.getSlotElementId(), "has loaded.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

JavaScript (舊版)

// This listener is called when a creative iframe load event fires.
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotOnload", function (event) {
  var slot = event.slot;
  console.log("Creative iframe for slot", slot.getSlotElementId(), "has loaded.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

TypeScript

// This listener is called when a creative iframe load event fires.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotOnload", (event) => {
  const slot = event.slot;
  console.log("Creative iframe for slot", slot.getSlotElementId(), "has loaded.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另請參閱

googletag.events.SlotRenderEndedEvent

延長 Event
當廣告素材程式碼注入廣告空間時，系統會觸發這個事件。這個事件會在擷取廣告素材的資源前發生，因此廣告素材可能尚未顯示。如要瞭解版位的所有廣告素材資源何時載入完成，請改用 events.SlotOnloadEvent。
屬性
advertiserId
所顯示廣告的廣告主 ID。
campaignId
所顯示廣告的廣告活動 ID。
companyIds
對已放送的候補廣告出價的公司 ID。
creativeId
已算繪預訂廣告的廣告素材 ID。
creativeTemplateId
已放送預訂廣告的廣告素材範本 ID。
isBackfill
廣告是否為候補廣告。
isEmpty
是否為該廣告空間傳回廣告。
labelIds
已淘汰。 
lineItemId
所放送預訂廣告的委刊項 ID。
responseIdentifier
回應 ID 是廣告回應的專屬 ID。
serviceName
觸發事件的服務名稱。
size
顯示所顯示廣告素材的像素大小。
slot
觸發事件的廣告空間。
slotContentChanged
版位內容是否已隨顯示的廣告變更。
sourceAgnosticCreativeId
已放送的預訂或候補廣告的廣告素材 ID。
sourceAgnosticLineItemId
所顯示預訂或候補廣告的委刊項 ID。
yieldGroupIds
用於放送備用廣告的收益群組 ID。
範例

JavaScript

// This listener is called when a slot has finished rendering.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotRenderEnded", (event) => {
  const slot = event.slot;
  console.group("Slot", slot.getSlotElementId(), "finished rendering.");

  // Log details of the rendered ad.
  console.log("Advertiser ID:", event.advertiserId);
  console.log("Campaign ID:", event.campaignId);
  console.log("Company IDs:", event.companyIds);
  console.log("Creative ID:", event.creativeId);
  console.log("Creative Template ID:", event.creativeTemplateId);
  console.log("Is backfill?:", event.isBackfill);
  console.log("Is empty?:", event.isEmpty);
  console.log("Line Item ID:", event.lineItemId);
  console.log("Size:", event.size);
  console.log("Slot content changed?", event.slotContentChanged);
  console.log("Source Agnostic Creative ID:", event.sourceAgnosticCreativeId);
  console.log("Source Agnostic Line Item ID:", event.sourceAgnosticLineItemId);
  console.log("Yield Group IDs:", event.yieldGroupIds);
  console.groupEnd();

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

JavaScript (舊版)

// This listener is called when a slot has finished rendering.
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotRenderEnded", function (event) {
  var slot = event.slot;
  console.group("Slot", slot.getSlotElementId(), "finished rendering.");

  // Log details of the rendered ad.
  console.log("Advertiser ID:", event.advertiserId);
  console.log("Campaign ID:", event.campaignId);
  console.log("Company IDs:", event.companyIds);
  console.log("Creative ID:", event.creativeId);
  console.log("Creative Template ID:", event.creativeTemplateId);
  console.log("Is backfill?:", event.isBackfill);
  console.log("Is empty?:", event.isEmpty);
  console.log("Line Item ID:", event.lineItemId);
  console.log("Size:", event.size);
  console.log("Slot content changed?", event.slotContentChanged);
  console.log("Source Agnostic Creative ID:", event.sourceAgnosticCreativeId);
  console.log("Source Agnostic Line Item ID:", event.sourceAgnosticLineItemId);
  console.log("Yield Group IDs:", event.yieldGroupIds);
  console.groupEnd();

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

TypeScript

// This listener is called when a slot has finished rendering.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotRenderEnded", (event) => {
  const slot = event.slot;
  console.group("Slot", slot.getSlotElementId(), "finished rendering.");

  // Log details of the rendered ad.
  console.log("Advertiser ID:", event.advertiserId);
  console.log("Campaign ID:", event.campaignId);
  console.log("Company IDs:", event.companyIds);
  console.log("Creative ID:", event.creativeId);
  console.log("Creative Template ID:", event.creativeTemplateId);
  console.log("Is backfill?:", event.isBackfill);
  console.log("Is empty?:", event.isEmpty);
  console.log("Line Item ID:", event.lineItemId);
  console.log("Size:", event.size);
  console.log("Slot content changed?", event.slotContentChanged);
  console.log("Source Agnostic Creative ID:", event.sourceAgnosticCreativeId);
  console.log("Source Agnostic Line Item ID:", event.sourceAgnosticLineItemId);
  console.log("Yield Group IDs:", event.yieldGroupIds);
  console.groupEnd();

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另請參閱

屬性

advertiserId

advertiserId: number
所顯示廣告的廣告主 ID。如果是空白版位、候補廣告，以及由 PubAdsService 以外的服務放送的廣告素材，值為 null。

campaignId

campaignId: number
顯示廣告的廣告活動 ID。如果是空白版位、候補廣告，以及由 PubAdsService 以外的服務放送的廣告素材，值為 null。

companyIds

companyIds: number[]
對已放送的候補廣告出價的公司 ID。如果是空白版位、預訂廣告，以及由 PubAdsService 以外的服務放送的廣告素材，值為 null。

creativeId

creativeId: number
已放送預訂廣告的廣告素材 ID。如果是空白版位、候補廣告，以及由 PubAdsService 以外的服務放送的廣告素材，值為 null。

creativeTemplateId

creativeTemplateId: number
已放送預訂廣告的廣告素材範本 ID。如果是空白版位、候補廣告，以及由 PubAdsService 以外的服務放送的廣告素材，值為 null。

isBackfill

isBackfill: boolean
廣告是否為候補廣告。如果廣告是候補廣告，值為 true，否則為 false。

isEmpty

isEmpty: boolean
是否為該廣告空間傳回廣告。如果沒有傳回任何廣告，值為 true，否則為 false。

labelIds

labelIds: number[]

lineItemId

lineItemId: number
所放送預訂廣告的委刊項 ID。如果是空白版位、候補廣告，以及由 PubAdsService 以外的服務放送的廣告素材，值為 null。

responseIdentifier

responseIdentifier: string
回應 ID 是廣告回應的專屬 ID。您可在廣告審核中心 (ARC) 輸入這個值，找出並封鎖特定廣告。

size

size: string | number[]
顯示所顯示廣告素材的像素大小。例如：[728, 90]。如果廣告版位為空白，值為 null。

slotContentChanged

slotContentChanged: boolean
版位內容是否已隨顯示的廣告變更。如果內容已變更，值為 true，否則為 false。

sourceAgnosticCreativeId

sourceAgnosticCreativeId: number
已放送的預訂或候補廣告的廣告素材 ID。如果廣告不是預訂廣告或委刊項遞補廣告，或是廣告素材是由 PubAdsService 以外的服務算繪，則值為 null。

sourceAgnosticLineItemId

sourceAgnosticLineItemId: number
所顯示預訂或候補廣告的委刊項 ID。如果廣告不是預訂廣告或委刊項遞補廣告，或是廣告素材是由 PubAdsService 以外的服務算繪，則值為 null。

yieldGroupIds

yieldGroupIds: number[]
用於放送備用廣告的收益群組 ID。如果是空白版位、預訂廣告，以及由 PubAdsService 以外的服務放送的廣告素材，值為 null。

googletag.events.SlotRequestedEvent

延長 Event
系統為特定版位請求廣告時，會觸發這個事件。
屬性
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
範例

JavaScript

// This listener is called when the specified service issues an ad
// request for a slot. Each slot will fire this event, even though they
// may be batched together in a single request if single request
// architecture (SRA) is enabled.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotRequested", (event) => {
  const slot = event.slot;
  console.log("Slot", slot.getSlotElementId(), "has been requested.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

JavaScript (舊版)

// This listener is called when the specified service issues an ad
// request for a slot. Each slot will fire this event, even though they
// may be batched together in a single request if single request
// architecture (SRA) is enabled.
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotRequested", function (event) {
  var slot = event.slot;
  console.log("Slot", slot.getSlotElementId(), "has been requested.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

TypeScript

// This listener is called when the specified service issues an ad
// request for a slot. Each slot will fire this event, even though they
// may be batched together in a single request if single request
// architecture (SRA) is enabled.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotRequested", (event) => {
  const slot = event.slot;
  console.log("Slot", slot.getSlotElementId(), "has been requested.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另請參閱

googletag.events.SlotResponseReceived

延長 Event
收到特定廣告空間的廣告回應時，系統會觸發這個事件。
屬性
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
範例

JavaScript

// This listener is called when an ad response has been received
// for a slot.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotResponseReceived", (event) => {
  const slot = event.slot;
  console.log("Ad response for slot", slot.getSlotElementId(), "received.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

JavaScript (舊版)

// This listener is called when an ad response has been received
// for a slot.
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotResponseReceived", function (event) {
  var slot = event.slot;
  console.log("Ad response for slot", slot.getSlotElementId(), "received.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

TypeScript

// This listener is called when an ad response has been received
// for a slot.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotResponseReceived", (event) => {
  const slot = event.slot;
  console.log("Ad response for slot", slot.getSlotElementId(), "received.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另請參閱

googletag.events.SlotVisibilityChangedEvent

延長 Event
每當廣告空間區域在畫面上的百分比變更時，系統就會觸發這個事件。事件會受到節流，觸發頻率不會超過每 200 毫秒一次。
屬性
inViewPercentage
廣告可見區域的百分比。
serviceName
觸發事件的服務名稱。
slot
觸發事件的廣告空間。
範例

JavaScript

// This listener is called whenever the on-screen percentage of an
// ad slot's area changes.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotVisibilityChanged", (event) => {
  const slot = event.slot;
  console.group("Visibility of slot", slot.getSlotElementId(), "changed.");

  // Log details of the event.
  console.log("Visible area:", `${event.inViewPercentage}%`);
  console.groupEnd();

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

JavaScript (舊版)

// This listener is called whenever the on-screen percentage of an
// ad slot's area changes.
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotVisibilityChanged", function (event) {
  var slot = event.slot;
  console.group("Visibility of slot", slot.getSlotElementId(), "changed.");

  // Log details of the event.
  console.log("Visible area:", "".concat(event.inViewPercentage, "%"));
  console.groupEnd();

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});

TypeScript

// This listener is called whenever the on-screen percentage of an
// ad slot's area changes.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotVisibilityChanged", (event) => {
  const slot = event.slot;
  console.group("Visibility of slot", slot.getSlotElementId(), "changed.");

  // Log details of the event.
  console.log("Visible area:", `${event.inViewPercentage}%`);
  console.groupEnd();

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另請參閱

屬性

inViewPercentage

inViewPercentage: number
廣告可見區域的百分比。值為介於 0 至 100 之間的數字。

googletag.secureSignals

這是 GPT 用於管理安全信號的命名空間。
介面
BidderSignalProvider
傳回特定出價方的安全信號。
PublisherSignalProvider
傳回特定發布商的安全信號。
SecureSignalProvidersArray
管理安全信號的介面。
型別別名
SecureSignalProvider
介面：為特定出價方或供應商傳回安全信號。

型別別名

SecureSignalProvider

介面：為特定出價方或供應商傳回安全信號。必須提供 id 或 networkCode 其中一個，但不能兩者都提供。

googletag.secureSignals.BidderSignalProvider

為特定出價方傳回安全信號。

出價方安全信號供應商包含 2 個部分：

  1. 收集器函式，會傳回解析為安全信號的 Promise。
  2. id：用於識別與信號相關聯的出價方。
如要傳回發布商的安全信號，請改用 secureSignals.PublisherSignalProvider。
屬性
collectorFunction
這個函式會傳回 Promise，該函式會解析為安全信號。
id
與這個安全信號相關聯的收集器專屬 ID，已在 Google Ad Manager 中註冊。
範例

JavaScript

// id is provided
googletag.secureSignalProviders.push({
  id: "collector123",
  collectorFunction: () => {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});

JavaScript (舊版)

// id is provided
googletag.secureSignalProviders.push({
  id: "collector123",
  collectorFunction: function () {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});

TypeScript

// id is provided
googletag.secureSignalProviders!.push({
  id: "collector123",
  collectorFunction: () => {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});
另請參閱

屬性

collectorFunction

collectorFunction: (() => Promise<string>)
這個函式會傳回 Promise，該函式會解析為安全信號。

id

id: string
與這個安全信號相關聯的收集器專屬 ID，已在 Google Ad Manager 中註冊。

googletag.secureSignals.PublisherSignalProvider

傳回特定發布商的安全信號。

發布商信號供應商包含 2 個部分：

  1. 收集器函式，會傳回解析為安全信號的 Promise。
  2. networkCode，用於識別與信號相關聯的發布商。
如要傳回出價方的安全信號，請改用 secureSignals.BidderSignalProvider。
屬性
collectorFunction
這個函式會傳回 Promise，該函式會解析為安全信號。
networkCode
與這個安全信號相關聯的發布商網路代碼 (如廣告單元路徑所示)。
範例

JavaScript

// networkCode is provided
googletag.secureSignalProviders.push({
  networkCode: "123456",
  collectorFunction: () => {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});

JavaScript (舊版)

// networkCode is provided
googletag.secureSignalProviders.push({
  networkCode: "123456",
  collectorFunction: function () {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});

TypeScript

// networkCode is provided
googletag.secureSignalProviders!.push({
  networkCode: "123456",
  collectorFunction: () => {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});
另請參閱

屬性

collectorFunction

collectorFunction: (() => Promise<string>)
這個函式會傳回 Promise，該函式會解析為安全信號。

networkCode

networkCode: string
與這個安全信號相關聯的發布商網路代碼 (如廣告單元路徑所示)。

googletag.secureSignals.SecureSignalProvidersArray

管理安全信號的介面。
方法
clearAllCache
清除所有收集器在快取中的所有信號。
push
將新的 secureSignals.SecureSignalProvider 新增至信號供應商陣列，並開始信號產生程序。

方法

clearAllCache

clearAllCache(): void
清除快取中所有收集器的所有信號。

呼叫這個方法後，廣告請求含有目前和日後潛在網頁瀏覽信號的可能性也許會降低。因此，建議只在狀態出現重要變化時，才呼叫這個方法，例如：發生表示有新使用者的事件時 (登入、登出和註冊等)。

推入

push(provider: SecureSignalProvider): void
將新的 secureSignals.SecureSignalProvider 新增至信號供應商陣列，並開始信號產生程序。
參數
provider: SecureSignalProvider要新增至陣列的 secureSignals.SecureSignalProvider 物件。