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	發布商廣告服務。
RequestHook	透過 PubAdsService.registerRequestHook 註冊時，在每次廣告請求前叫用的回呼函式。
ResponseInformation	代表單一廣告回應的物件。
RewardedPayload	代表獎勵廣告相關獎勵的物件。
Service	基礎服務類別，包含所有服務通用的方法。
SizeMappingBuilder	大小對應規格物件的建構工具。
Slot	Slot 是代表網頁上單一廣告版位的物件。

型別別名
FluidSize	大小字串，廣告容器會採用父項 div 的 100% 寬度，然後調整高度以符合廣告素材內容。
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 服務。
getConfig	取得 setConfig 為網頁設定的一般設定選項凍結副本。
getVersion	傳回目前的 GPT 版本。
openConsole	開啟 Google 發布商控制台。
pubads	傳回 PubAdsService 的參照。
setAdIframeTitle	設定 PubAdsService 建立的所有廣告容器 iframe 標題 (從現在起)。
setConfig	設定頁面的一般設定選項。
sizeMapping	建立新的 SizeMappingBuilder。

型別別名

---

FluidSize

FluidSize: "fluid"

大小字串，廣告容器會採用父項 div 的 100% 寬度，然後調整高度以符合廣告素材內容。行為與網頁上的常規區塊元素類似。用於原生廣告和橫幅廣告 (請參閱相關文章)。

---

GeneralSize

GeneralSize: SingleSize | MultiSize

廣告版位的有效大小設定，可以是一或多個大小。

---

MultiSize

MultiSize: SingleSize[]

單一有效大小的清單。

---

NamedSize

NamedSize: FluidSize | [FluidSize]

版位可使用的具名大小。在大多數情況下，大小是固定大小的矩形，但有時我們需要其他類型的大小規格。只有下列是有效的指定大小：

• 自動調整：廣告容器會採用上層 div 的 100% 寬度，然後調整高度，以配合廣告素材內容。行為與網頁上的常規區塊元素類似。用於原生廣告和橫幅廣告 (請參閱相關文章)。請注意，fluid 和 ['fluid'] 都是將版位大小宣告為自動調整的有效形式。

---

SingleSize

SingleSize: SingleSizeArray | NamedSize

版位的單一有效大小。

---

SingleSizeArray

SingleSizeArray: [number, number]

由兩個數字組成的陣列，代表 [寬度, 高度]。

---

SizeMapping

SizeMapping: [SingleSizeArray, GeneralSize]

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

---

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 相關呼叫。

googletag.cmd 變數會由網頁上的 GPT 廣告代碼語法初始化為空白 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());
});

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");
  },
});

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);

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");

TypeScript

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

另請參閱

• 開始使用 Google 發布商廣告代碼

參數
adUnitPath: string	完整的廣告單元路徑，包含聯播網代碼和單元代碼。
size: GeneralSize	新增版位的寬度和高度。如果未提供回應式大小對應，或可視區域的大小小於對應中提供的最小大小，則廣告請求會使用這個大小。
Optional div: string	包含這個廣告單元的 div ID。

傳回
Slot | null	新建立的版位，如果無法建立版位，則為 null。

---

destroySlots

destroySlots(slots?: Slot[]): boolean

刪除指定版位，並從 GPT 移除這些版位的所有相關物件和參照。這個 API 不支援回傳廣告版位和隨播廣告版位。

在廣告版位上呼叫這個 API 會清除廣告，並從 GPT 維護的內部狀態中移除廣告版位物件。如果對版位物件呼叫任何其他函式，會導致未定義的行為。請注意，如果發布商網頁保留了該版位的參照，瀏覽器可能仍不會釋出與該版位相關聯的記憶體。呼叫這個 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();

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 發布商控制台。

另請參閱

• Google 發布商控制台

---

螢幕

display(divOrSlot: string | Element | Slot): void

指示版位服務顯示版位。每個廣告版位在每個頁面只能顯示一次。所有時段都必須定義並與服務建立關聯，才能顯示。元素出現在 DOM 之前，不得進行顯示呼叫。通常，您可以在方法呼叫中命名的 div 元素內，將其置於指令碼區塊中。

如果使用單一請求架構 (SRA)，則在呼叫此方法時，所有未擷取的廣告版位都會一次擷取。如要強制不顯示廣告版位，則必須移除整個 div。

另請參閱

• 開始使用 Google 發布商廣告代碼
• 顯示測試廣告
• 控管廣告載入和重新整理

參數
divOrSlot: string | Element | Slot	包含廣告版位或 div 元素的 div 元素 ID，或版位物件。如果提供 div 元素，則必須具有與傳入 defineSlot 的 ID 相符的「id」屬性。

---

enableServices

enableServices(): void

啟用已為網頁上廣告版位定義的所有 GPT 服務。

---

getConfig

getConfig(keys: string | string[]): Readonly<Pick<PageSettingsConfig, "adsenseAttributes" | "disableInitialLoad" | "targeting">>

取得由 setConfig 設定的網頁一般設定選項凍結副本。

這個方法不支援所有 setConfig() 屬性。支援的屬性如下：

• adsenseAttributes
• disableInitialLoad
• targeting

範例

JavaScript

// Get the value of the `targeting` setting.
const targetingConfig = googletag.getConfig("targeting");

// Get the value of the `adsenseAttributes` and `disableInitialLoad` settings.
const config = googletag.getConfig(["adsenseAttributes", "disableInitialLoad"]);

TypeScript

// Get the value of the `targeting` setting.
const targetingConfig = googletag.getConfig("targeting");

// Get the value of the `adsenseAttributes` and `disableInitialLoad` settings.
const config = googletag.getConfig(["adsenseAttributes", "disableInitialLoad"]);

參數
keys: string | string[]	要取得的設定選項鍵。

傳回
Readonly<Pick<PageSettingsConfig, "adsenseAttributes" | "disableInitialLoad" | "targeting">>	頁面設定選項的凍結副本。

---

getVersion

getVersion(): string

傳回目前的 GPT 版本。

另請參閱

• GPT 版本記錄

傳回
string	目前執行的 GPT 版本字串。

---

openConsole

openConsole(div?: string): void

開啟 Google 發布商控制台。

範例

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();

另請參閱

• Google 發布商控制台

參數
Optional div: string	廣告版位 div ID。這個值為選用。提供後，發布商控制台會嘗試開啟，並顯示指定廣告版位的詳細資料。

---

pubads

pubads(): PubAdsService

傳回 PubAdsService 的參照。

傳回
PubAdsService	發布商廣告服務。

---

setAdIframeTitle

setAdIframeTitle(title: string): void

設定 PubAdsService 建立的所有廣告容器 iframe 標題 (從此時開始)。

範例

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

push(...f: ((this: typeof globalThis) => void)[]): number

依序執行引數中指定的函式序列。

範例

JavaScript

googletag.cmd.push(() => {
  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 函式。 沿用自 Service.addEventListener 方法
getSlots	取得與這項服務相關聯的時段清單。 沿用自 Service.getSlots 方法
removeEventListener	移除先前註冊的事件監聽器。 沿用自 Service.removeEventListener 方法
setRefreshUnfilledSlots	設定是否要為尚未獲得廣告的隨播廣告版位自動補上廣告。

另請參閱

• 影片和音訊的隨播廣告

方法

---

setRefreshUnfilledSlots

setRefreshUnfilledSlots(value: boolean): void

設定是否要為尚未獲得廣告的隨播廣告版位自動補上廣告。

在網頁生命週期內，您可以多次呼叫這個方法，開啟或關閉自動補登功能。只有在 PubAdsService 註冊的版位才會自動補登。基於政策限制，這個方法並非用於在放送 Ad Exchange 影片時，填補空白的隨播廣告版位。

範例

JavaScript

googletag.companionAds().setRefreshUnfilledSlots(true);

TypeScript

googletag.companionAds().setRefreshUnfilledSlots(true);

參數
value: boolean	true：自動候補空缺位置。false：維持不變。

---

googletag.PrivacySettingsConfig

隱私權設定的設定物件。

屬性
childDirectedTreatment?	指出是否應將網頁視為兒童導向。
limitedAds?	在受限制的廣告模式下放送廣告，協助發布商遵循法規。
nonPersonalizedAds?	啟用非個人化廣告模式，協助發布商遵循法規。
restrictDataProcessing?	在受限的資料處理模式下放送廣告，協助發布商遵守法規。
tagForAgeTreatment?	年齡限制處理方式，指出廣告請求應視為兒童、青少年或未指定。
trafficSource?	指出請求代表購買或自然流量。
underAgeOfConsent?	指出是否要將廣告請求標示為來自未滿規定年齡的使用者。

另請參閱

• 調整隱私權設定

屬性

---

Optional childDirectedTreatment

childDirectedTreatment?: boolean

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

---

Optional limitedAds

limitedAds?: boolean

啟用受限制的廣告模式，協助發布商遵循法規。

您可以透過兩種方式，指示 GPT 請求受限制的廣告：

• 自動：使用 IAB 資訊公開和同意聲明架構第 2.0 版同意聲明管理平台的信號。
• 手動：將這個欄位的值設為 true。

只有從受限制的廣告網址載入 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,
});

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 tagForAgeTreatment

tagForAgeTreatment?: TagForAgeTreatment

年齡限制處理方式，指出廣告請求應視為兒童、青少年或未指定。

請諮詢法律顧問，根據您應盡的法律與法規要求，決定要對使用者採用的年齡處理設定。如要進一步瞭解這項設定，請參閱這篇說明中心文章。

設定這項屬性，即表示您確認這項通知正確無誤，且您有權代表網站擁有者採取行動。您瞭解，濫用這項設定可能導致 Google 帳戶遭到終止。

範例

JavaScript

// Enable teen privacy treatment.
googletag.pubads().setPrivacySettings({
  tagForAgeTreatment: googletag.enums.TagForAgeTreatment.TEEN,
});

// Clear age treatment configuration.
googletag.pubads().setPrivacySettings({
  tagForAgeTreatment: googletag.enums.TagForAgeTreatment.UNSPECIFIED,
});

TypeScript

// Enable teen privacy treatment.
googletag.pubads().setPrivacySettings({
  tagForAgeTreatment: googletag.enums.TagForAgeTreatment.TEEN,
});

// Clear age treatment configuration.
googletag.pubads().setPrivacySettings({
  tagForAgeTreatment: googletag.enums.TagForAgeTreatment.UNSPECIFIED,
});

---

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,
});

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 函式。 沿用自 Service.addEventListener 方法
clear	移除指定版位的廣告，並以空白內容取代。
clearCategoryExclusions	已淘汰。 清除所有網頁層級廣告類別排除標籤。
clearTargeting	已淘汰。 清除特定鍵或所有鍵的自訂指定目標參數。
collapseEmptyDivs	已淘汰。 ：啟用收合版位 div 元素的功能，這樣在沒有廣告素材可顯示時，就不會占用網頁空間。
disableInitialLoad	已淘汰。 停用載入網頁時的廣告請求，但允許透過 PubAdsService.refresh 呼叫請求廣告。
display	使用指定廣告單元路徑和大小，建構及顯示廣告版位。
enableLazyLoad	已淘汰。 ：在 GPT 中啟用延遲載入功能，如設定物件所定義。
enableSingleRequest	已淘汰。 啟用單一請求模式，同時擷取多則廣告。
enableVideoAds	已淘汰。 向 GPT 發出信號，表示網頁上會顯示影片廣告。
get	已淘汰。 傳回與指定鍵相關聯的 AdSense 屬性值。
getAttributeKeys	已淘汰。 傳回這項服務設定的屬性鍵。
getSlots	取得與這項服務相關聯的時段清單。 沿用自 Service.getSlots 方法
getTargeting	已淘汰。 傳回已設定的特定自訂服務層級指定參數。
getTargetingKeys	已淘汰。 傳回所有已設定的自訂服務層級指定鍵清單。
isInitialLoadDisabled	已淘汰。 傳回先前呼叫 PubAdsService.disableInitialLoad 是否成功停用初始廣告請求。
refresh	擷取並顯示網頁上特定或所有版位的新廣告。
registerRequestHook	註冊掛鉤，在全域逾時時間內，於網頁上每個廣告請求之前，與其他已註冊的掛鉤平行執行。
removeEventListener	移除先前註冊的事件監聽器。 沿用自 Service.removeEventListener 方法
set	已淘汰。 設定 AdSense 屬性的值，套用至發布商廣告服務下的所有廣告版位。
setCategoryExclusion	已淘汰。 為指定標籤名稱設定網頁層級廣告類別排除條件。
setCentering	已淘汰。 啟用及停用廣告水平置中。
setForceSafeFrame	已淘汰。 設定是否強制網頁上的所有廣告使用 SafeFrame 容器顯示。
setLocation	已淘汰。 傳遞網站的位置資訊，以便您將委刊項指定地理區域到特定位置。
setPrivacySettings	可使用設定物件，透過單一 API 設定所有隱私權設定。
setPublisherProvidedId	設定發布商提供的 ID 值。
setSafeFrameConfig	已淘汰。 設定 SafeFrame 的網頁層級偏好設定。
setTargeting	已淘汰。 為指定鍵設定自訂指定目標參數，套用至所有發布商廣告服務廣告版位。
setVideoContent	已淘汰。 設定要與廣告請求一併傳送的影片內容資訊，用於指定目標和內容排除。
updateCorrelator	變更與廣告請求一併傳送的關聯器，有效啟動新的網頁瀏覽。

方法

---

clear

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();

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

清除所有網頁層級廣告類別排除標籤。如要重新整理版位，這個方法就很實用。

已淘汰：請改用 PageSettingsConfig.categoryExclusion。

範例

JavaScript

// Set category exclusion to exclude ads with 'AirlineAd' labels.
googletag.setConfig({
  categoryExclusion: ["AirlineAd"],
});

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

// Clear category exclusions so all ads can be returned.
googletag.setConfig({
  categoryExclusion: null,
});

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

TypeScript

// Set category exclusion to exclude ads with 'AirlineAd' labels.
googletag.setConfig({
  categoryExclusion: ["AirlineAd"],
});

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

// Clear category exclusions so all ads can be returned.
googletag.setConfig({
  categoryExclusion: null,
});

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

另請參閱

• 封鎖廣告的自訂標籤

傳回
PubAdsService	呼叫方法的服務物件。

---

clearTargeting

clearTargeting(key?: string): PubAdsService

清除特定鍵或所有鍵的自訂指定目標參數。

已淘汰：請改用 PageSettingsConfig.targeting。

範例

JavaScript

googletag.setConfig({
  targeting: {
    interests: "sports",
    colors: "blue",
    fruits: "apple",
  },
});

googletag.setConfig({
  targeting: {
    interests: null,
  },
});
// Targeting 'colors' and 'fruits' are still present, while 'interests'
// was cleared.

googletag.setConfig({
  targeting: null,
});
// All targeting has been cleared.

TypeScript

googletag.setConfig({
  targeting: {
    interests: "sports",
    colors: "blue",
    fruits: "apple",
  },
});

googletag.setConfig({
  targeting: {
    interests: null,
  },
});
// Targeting 'colors' and 'fruits' are still present, while 'interests'
// was cleared.

googletag.setConfig({
  targeting: null,
});
// All targeting has been cleared.

另請參閱

• 鍵/值指定目標

參數
Optional key: string	指定目標參數鍵。這個鍵為選用，如未指定，系統會清除所有指定目標參數。

傳回
PubAdsService	呼叫方法的服務物件。

---

collapseEmptyDivs

collapseEmptyDivs(collapseBeforeAdFetch?: boolean): boolean

啟用收合版位 div 的功能，這樣在沒有可顯示的廣告素材時，就不會占用網頁上的任何空間。必須先設定這個模式，才能啟用服務。

已淘汰：請改用 PageSettingsConfig.collapseDiv。

另請參閱

• 收合空白廣告版位
• 盡量減少版面配置位移

參數
Optional collapseBeforeAdFetch: boolean	是否在擷取廣告前就收合版位。這個參數為選用。如未提供，系統會使用 false 做為預設值。

傳回
boolean	如果已啟用 div 摺疊模式，則傳回 true；如果因服務啟用後才呼叫方法，而無法啟用摺疊模式，則傳回 false。

---

disableInitialLoad

disableInitialLoad(): void

停用載入網頁時的廣告請求，但允許透過 PubAdsService.refresh 呼叫請求廣告。請務必在啟用服務前設定這項資訊。必須使用非同步模式，否則無法使用 refresh 請求廣告。

已淘汰：請改用 PageSettingsConfig.disableInitialLoad。

另請參閱

• 控管廣告載入和重新整理
• 控制 SRA 批次處理

---

螢幕

display(adUnitPath: string, size: GeneralSize, div?: string | Element, clickUrl?: string): void

使用指定的廣告單元路徑和大小，建構及顯示廣告版位。

這個方法是簡寫，等同於先呼叫 googletag.defineSlot，再立即呼叫 googletag.display。

這個方法的行為取決於是否啟用單一請求架構 (SRA)：

• 啟用 SRA：系統會將截至呼叫時定義的所有廣告版位批次處理，並一併提出請求。
• 停用 SRA (預設)：系統會個別請求廣告版位。

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

範例

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 中的延遲擷取功能才會運作。

已淘汰：請改用 PageSettingsConfig.lazyLoad。

範例

JavaScript

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,
  },
});

TypeScript

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,
  },
});

另請參閱

• 廣告最佳做法：優先處理「重要」廣告版位
• 延遲載入

參數

Optional config: {   fetchMarginPercent?: number;   mobileScaling?: number;   renderMarginPercent?: number; }

設定物件可自訂延遲行為。任何省略的設定都會使用 Google 設定的預設值，並會隨著時間調整。如要停用特定設定 (例如擷取邊界)，請將值設為 -1。 fetchMarginPercent 廣告版位與目前可視區域的最小距離，必須達到可視區域大小的一定百分比，系統才會擷取廣告。值為 0 表示「版位進入可視區域時」，100 表示「廣告距離可視區域 1 個可視區域時」，以此類推。 renderMarginPercent 廣告版位與目前可視區域的最小距離，必須達到這個距離，系統才會顯示廣告。這樣一來，系統就能預先擷取廣告，但會等到其他子資源轉譯及下載後，這個值與 fetchMarginPercent 相同，都是可視區域的百分比。 mobileScaling 套用至行動裝置邊界的調節係數。這樣一來，行動裝置和電腦就能有不同的邊界。舉例來說，如果值為 2.0，則行動裝置上的所有邊界都會乘以 2，增加廣告版位在擷取和算繪前的最小距離。

---

enableSingleRequest

enableSingleRequest(): boolean

啟用單一請求模式，同時擷取多個廣告。因此，您必須先定義所有發布商廣告版位，並將其新增至 PubAdsService，才能啟用這項服務。必須先設定單一請求模式，才能啟用服務。

已淘汰：請改用 PageSettingsConfig.singleRequest。

另請參閱

• 廣告最佳做法：正確使用單一請求架構
• 控制 SRA 批次處理

傳回
boolean	如果已啟用單一請求模式，則傳回 true；如果啟用服務後才呼叫方法，導致無法啟用單一請求模式，則傳回 false。

---

enableVideoAds

enableVideoAds(): void

向 GPT 發出信號，表示網頁上會顯示影片廣告。這樣一來，多媒體廣告和影片廣告就會套用競爭排除限制。如果影片內容已知，請呼叫 PubAdsService.setVideoContent，以便對多媒體廣告使用內容排除。

已淘汰：請改用 PageSettingsConfig.videoAds。

---

get

get(key: string): string

傳回與指定鍵相關聯的 AdSense 屬性值。

已淘汰：請改用 googletag.getConfig。

範例

JavaScript

googletag.setConfig({
  adsenseAttributes: {
    page_url: "http://www.example.com",
  },
});

const adsenseConfig = googletag.getConfig("adsenseAttributes").adsenseAttributes;
const pageUrl = adsenseConfig?.page_url || null;
// Returns 'http://www.example.com'.

TypeScript

googletag.setConfig({
  adsenseAttributes: {
    page_url: "http://www.example.com",
  },
});

const adsenseConfig = googletag.getConfig("adsenseAttributes").adsenseAttributes;
const pageUrl = adsenseConfig?.page_url || null;
// Returns 'http://www.example.com'.

另請參閱

• AdSense 屬性

參數
key: string	要尋找的屬性名稱。

傳回
string	屬性鍵的目前值，如果沒有該鍵，則為 null。

---

getAttributeKeys

getAttributeKeys(): string[]

傳回這項服務設定的屬性鍵。

已淘汰：請改用 googletag.getConfig。

範例

JavaScript

googletag.setConfig({
  adsenseAttributes: {
    page_url: "http://www.example.com",
    document_language: "en",
  },
});

const adsenseConfig = googletag.getConfig("adsenseAttributes").adsenseAttributes;
const adsenseAttributes = Object.keys(adsenseConfig || {});
// Returns ['page_url', 'document_language'].

TypeScript

googletag.setConfig({
  adsenseAttributes: {
    page_url: "http://www.example.com",
    document_language: "en",
  },
});

const adsenseConfig = googletag.getConfig("adsenseAttributes").adsenseAttributes;
const adsenseAttributes = Object.keys(adsenseConfig || {});
// Returns ['page_url', 'document_language'].

傳回
string[]	這項服務設定的屬性鍵陣列。未定義排序。

---

getTargeting

getTargeting(key: string): string[]

傳回已設定的特定自訂服務層級指定目標參數。

已淘汰：請改用 googletag.getConfig。

範例

JavaScript

googletag.setConfig({
  targeting: {
    interests: "sports",
  },
});

const targetingConfig = googletag.getConfig("targeting").targeting;

// Get targeting for a specific key.
const targeting = targetingConfig?.["interests"] || [];
// Returns ['sports'].

const ageTargeting = targetingConfig?.["age"] || [];
// Returns [] (empty array).

TypeScript

googletag.setConfig({
  targeting: {
    interests: "sports",
  },
});

const targetingConfig = googletag.getConfig("targeting").targeting;

// Get targeting for a specific key.
const targeting = targetingConfig?.["interests"] || [];
// Returns ['sports'].

const ageTargeting = targetingConfig?.["age"] || [];
// Returns [] (empty array).

參數
key: string	要尋找的指定鍵。

傳回
string[]	與這個鍵相關聯的值；如果沒有這類鍵，則為空陣列。

---

getTargetingKeys

getTargetingKeys(): string[]

傳回所有已設定的自訂服務層級指定鍵清單。

已淘汰：請改用 googletag.getConfig。

範例

JavaScript

googletag.setConfig({
  targeting: {
    interests: "sports",
    colors: "blue",
  },
});

const targetingConfig = googletag.getConfig("targeting").targeting;
const keys = Object.keys(targetingConfig || {});
// Returns ['interests', 'colors'].

TypeScript

googletag.setConfig({
  targeting: {
    interests: "sports",
    colors: "blue",
  },
});

const targetingConfig = googletag.getConfig("targeting").targeting;
const keys = Object.keys(targetingConfig || {});
// Returns ['interests', 'colors'].

傳回
string[]	指定鍵陣列。未定義排序。

---

isInitialLoadDisabled

isInitialLoadDisabled(): boolean

傳回先前的 PubAdsService.disableInitialLoad 呼叫是否成功停用初始廣告請求。

已淘汰：請改用 googletag.getConfig。

傳回
boolean	如果先前呼叫 PubAdsService.disableInitialLoad 成功，則傳回 true，否則傳回 false。

---

refresh

refresh(slots?: Slot[], options?: {
  changeCorrelator: boolean;
}): void

擷取並顯示網頁上特定或所有版位的新廣告。僅適用於非同步顯示模式。

為確保在所有瀏覽器中都能正常運作，請先呼叫 display 廣告版位，再呼叫 refresh。如果省略對 display 的呼叫，重新整理可能會發生非預期的行為。如有需要，您可以使用 PubAdsService.disableInitialLoad 方法，停止 display 擷取廣告。

重新整理版位會從 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 });

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 的長期網頁瀏覽，後者會自動反映目前網頁上的廣告，且沒有到期時間。

---

registerRequestHook

registerRequestHook(hook: RequestHook, hookId: string): (() => void)

Experimental 註冊掛鉤，在全域逾時時間內，於頁面上每個廣告請求前，與其他已註冊的掛鉤平行執行。

範例

JavaScript

// Register a request hook.
const unregister = googletag.pubads().registerRequestHook(async ({ slots }) => {
  const someAsynchronousAction = Promise.resolve();
  await someAsynchronousAction;
  for (const slot of slots) {
    slot.setConfig({ targeting: { hookApplied: "true" } });
  }
}, "my-hook");

// Unregister the hook.
unregister();

TypeScript

// Register a request hook.
const unregister = googletag.pubads().registerRequestHook(async ({ slots }) => {
  const someAsynchronousAction = Promise.resolve();
  await someAsynchronousAction;
  for (const slot of slots) {
    slot.setConfig({ targeting: { hookApplied: "true" } });
  }
}, "my-hook");

// Unregister the hook.
unregister();

參數
hook: RequestHook	這個函式會擷取包含請求版位清單的物件，並在所有非同步動作完成後，傳回已解析的 Promise。
hookId: string	用於標示掛鉤的 ID，可改善診斷功能。

傳回
(() => void)	用於取消註冊掛鉤的函式。

---

set

set(key: string, value: string): PubAdsService

設定 AdSense 屬性的值，套用至發布商廣告服務下的所有廣告版位。

如果針對同一個鍵多次呼叫這個方法，會覆寫該鍵先前設定的值。呼叫 display 或 refresh 之前，必須先設定所有值。

已淘汰：請改用 PageSettingsConfig.adsenseAttributes。

範例

JavaScript

googletag.setConfig({
  adsenseAttributes: {
    page_url: "http://www.example.com",
  },
});

TypeScript

googletag.setConfig({
  adsenseAttributes: {
    page_url: "http://www.example.com",
  },
});

另請參閱

• AdSense 屬性

參數
key: string	屬性名稱。
value: string	屬性值。

傳回
PubAdsService	呼叫方法的服務物件。

---

setCategoryExclusion

setCategoryExclusion(categoryExclusion: string): PubAdsService

為指定標籤名稱設定網頁層級廣告類別排除條件。

已淘汰：請改用 PageSettingsConfig.categoryExclusion。

範例

JavaScript

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

TypeScript

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

另請參閱

• 封鎖廣告的自訂標籤

參數
categoryExclusion: string	要新增的廣告類別排除標籤。

傳回
PubAdsService	呼叫方法的服務物件。

---

setCentering

setCentering(centerAds: boolean): void

啟用及停用廣告水平置中。置中功能預設為停用。在舊版 gpt_mobile.js 中，系統預設會啟用置中功能。

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

已淘汰：請改用 PageSettingsConfig.centering。

範例

JavaScript

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

TypeScript

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

參數
centerAds: boolean	true：將廣告置中。false：將廣告靠左對齊。

---

setForceSafeFrame

setForceSafeFrame(forceSafeFrame: boolean): PubAdsService

設定是否強制使用 SafeFrame 容器，顯示網頁上的所有廣告。

使用這個 API 時，請注意下列事項：

• 這項設定只會對各個版位後續提出的廣告請求生效。
• 如果指定了版位層級設定，則一律會覆寫網頁層級設定。
• 如果設為 true (在版位層級或網頁層級)，廣告一律會使用 SafeFrame 容器顯示，不受 Google Ad Manager 使用者介面中的選擇影響。
• 不過，如果設為 false 或未指定，系統會根據廣告素材類型和 Google Ad Manager 使用者介面中的選項，使用 SafeFrame 容器顯示廣告。
• 這個 API 可能會影響廣告素材的行為，例如廣告素材嘗試跳出 iframe，或需要直接在發布商網頁中顯示，因此請謹慎使用。

已淘汰：請改用 PageSettingsConfig.safeFrame。

範例

JavaScript

googletag.setConfig({
  safeFrame: {
    forceSafeFrame: true,
  },
});

// The following slot will be opted-out of the page-level force
// SafeFrame instruction.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setConfig({
    safeFrame: {
      forceSafeFrame: 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.setConfig({
  safeFrame: {
    forceSafeFrame: true,
  },
});

// The following slot will be opted-out of the page-level force
// SafeFrame instruction.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")!
  .setConfig({
    safeFrame: {
      forceSafeFrame: 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");

另請參閱

• 使用 SafeFrame 顯示廣告素材

參數
forceSafeFrame: boolean	true：強制網頁上的所有廣告在 SafeFrame 中顯示。false：將先前的設定變更為 false。如果先前未指定，將此值設為 false 不會造成任何變更。

傳回
PubAdsService	呼叫方法的服務物件。

---

setLocation

setLocation(address: string): PubAdsService

傳遞網站的位置資訊，以便將委刊項指定到特定地理區域。

已淘汰：請改用 PageSettingsConfig.location。

範例

JavaScript

// Postal code:
googletag.setConfig({
  location: "10001,US",
});

TypeScript

// Postal code:
googletag.setConfig({
  location: "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,
});

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");

TypeScript

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

另請參閱

• 關於發布商提供的 ID

參數
ppid: string	由發布商提供的英數字元 ID。長度必須介於 22 到 150 個字元之間。

傳回
PubAdsService	呼叫方法的服務物件。

---

setSafeFrameConfig

setSafeFrameConfig(config: SafeFrameConfig): PubAdsService

設定 SafeFrame 的網頁層級偏好設定。系統會忽略設定物件中任何無法辨識的鍵。如果為可辨識的鍵傳遞無效值，系統會忽略整個設定。

如果指定了版位層級偏好設定，這些網頁層級偏好設定會遭到覆寫。

已淘汰：請改用 PageSettingsConfig.safeFrame。

範例

JavaScript

googletag.setConfig({
  safeFrame: {
    forceSafeFrame: true,
    allowOverlayExpansion: true,
    allowPushExpansion: true,
    sandbox: true,
  },
});

googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setConfig({
    safeFrame: {
      allowOverlayExpansion: false,
    },
  })
  .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.setConfig({
  safeFrame: {
    forceSafeFrame: true,
    allowOverlayExpansion: true,
    allowPushExpansion: true,
    sandbox: true,
  },
});

googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")!
  .setConfig({
    safeFrame: {
      allowOverlayExpansion: false,
    },
  })
  .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");

另請參閱

• 使用 SafeFrame 顯示廣告素材

參數
config: SafeFrameConfig	設定物件。

傳回
PubAdsService	呼叫方法的服務物件。

---

setTargeting

setTargeting(key: string, value: string | string[]): PubAdsService

為指定鍵設定自訂指定目標參數，套用至所有發布商廣告服務廣告版位。如果對同一個鍵多次呼叫這個方法，會覆寫舊值。這些鍵是在 Google Ad Manager 帳戶中定義。

已淘汰：請改用 PageSettingsConfig.targeting。

範例

JavaScript

// Example with a single value for a key.
googletag.setConfig({
  targeting: {
    interests: "sports",
  },
});

// Example with multiple values for a key inside in an array.
googletag.setConfig({
  targeting: {
    interests: ["sports", "music"],
  },
});

TypeScript

// Example with a single value for a key.
googletag.setConfig({
  targeting: {
    interests: "sports",
  },
});

// Example with multiple values for a key inside in an array.
googletag.setConfig({
  targeting: {
    interests: ["sports", "music"],
  },
});

另請參閱

• 鍵/值指定目標

參數
key: string	指定目標參數鍵。
value: string | string[]	指定參數值或值陣列。

傳回
PubAdsService	呼叫方法的服務物件。

---

setVideoContent

setVideoContent(videoContentId: string, videoCmsId: string): void

設定要與廣告請求一併傳送的影片內容資訊，用於指定目標和內容排除。呼叫這個方法時，系統會自動啟用影片廣告。針對 videoContentId 和 videoCmsId，請使用提供給 Google Ad Manager 內容擷取服務的值。

已淘汰：請改用 PageSettingsConfig.videoAds。

另請參閱

• VAST 廣告代碼網址參數

參數
videoContentId: string	影片內容 ID。
videoCmsId: string	影片 CMS ID。

---

updateCorrelator

updateCorrelator(): PubAdsService

變更與廣告請求一併傳送的關聯器，有效啟動新的網頁瀏覽。來自同一次網頁瀏覽的所有廣告請求，其 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.

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.RequestHook

透過 PubAdsService.registerRequestHook 註冊時，在每次廣告請求前叫用的回呼函式。

---

googletag.ResponseInformation

代表單一廣告回應的物件。

屬性
advertiserId	廣告主的 ID。
campaignId	廣告活動 ID。
creativeId	廣告素材的 ID。
creativeTemplateId	廣告的範本 ID。
lineItemId	明細項目的 ID。

另請參閱

• Slot.getResponseInformation

屬性

---

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 函式。支援的事件如下：

• events.GameManualInterstitialSlotClosedEvent
• events.GameManualInterstitialSlotReadyEvent
• events.ImpressionViewableEvent
• events.RewardedSlotClosedEvent
• events.RewardedSlotGrantedEvent
• events.RewardedSlotReadyEvent
• events.SlotOnloadEvent
• events.SlotRenderEndedEvent
• events.SlotRequestedEvent
• events.SlotResponseReceived
• events.SlotVisibilityChangedEvent

。呼叫事件監聽器時，系統會將適當事件類型的物件傳遞給事件監聽器。

範例

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.
  }
});

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();
});

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 < 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 < 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	已淘汰。 傳回這個版位的廣告類別排除標籤。
getConfig	取得由 setConfig 設定的版位一般設定選項凍結副本。
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

將服務新增至這個版位。

範例

JavaScript

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

TypeScript

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

另請參閱

• 開始使用 Google 發布商廣告代碼
• 顯示測試廣告

參數
service: Service	要新增的服務。

傳回
Slot	呼叫方法的版位物件。

---

clearCategoryExclusions

clearCategoryExclusions(): Slot

清除這個版位的所有版位層級廣告類別排除標籤。

已淘汰：請改用 SlotSettingsConfig.categoryExclusion。

範例

JavaScript

// Set category exclusion to exclude ads with 'AirlineAd' labels.
const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setConfig({
    categoryExclusion: ["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.setConfig({
  categoryExclusion: null,
});

// 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")!
  .setConfig({
    categoryExclusion: ["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.setConfig({
  categoryExclusion: null,
});

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

傳回
Slot	呼叫方法的版位物件。

---

clearTargeting

clearTargeting(key?: string): Slot

清除這個版位特定或所有自訂版位層級指定目標參數。

已淘汰：請改用 SlotSettingsConfig.targeting。

範例

JavaScript

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

slot.setConfig({
  targeting: {
    color: null,
  },
});
// Targeting 'allow_expandable' and 'interests' are still present,
// while 'color' was cleared.

slot.setConfig({
  targeting: null,
});
// All targeting has been cleared.

TypeScript

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

slot.setConfig({
  targeting: {
    color: null,
  },
});
// Targeting 'allow_expandable' and 'interests' are still present,
// while 'color' was cleared.

slot.setConfig({
  targeting: null,
});
// All targeting has been cleared.

另請參閱

• 鍵/值指定目標

參數
Optional key: string	指定目標參數鍵。這個鍵為選用，如未指定，系統會清除所有指定目標參數。

傳回
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);

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	呼叫方法的版位物件。

---

get

get(key: string): string

傳回與這個版位指定鍵相關聯的 AdSense 屬性值。如要查看這個版位沿用的服務層級屬性，請使用 PubAdsService.get。

已淘汰：請改用 googletag.Slot.getConfig。

範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setConfig({
    adsenseAttributes: {
      page_url: "http://www.example.com",
    },
  })
  .addService(googletag.pubads());

const adsenseConfig = slot.getConfig("adsenseAttributes").adsenseAttributes;
const pageUrl = adsenseConfig?.page_url || null;
// Returns 'http://www.example.com'.

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setConfig({
    adsenseAttributes: {
      page_url: "http://www.example.com",
    },
  })
  .addService(googletag.pubads());

const adsenseConfig = slot.getConfig("adsenseAttributes").adsenseAttributes;
const pageUrl = adsenseConfig?.page_url || null;
// Returns 'http://www.example.com'.

另請參閱

• AdSense 屬性

參數
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'.

TypeScript

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

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

傳回
string	廣告單元路徑。

---

getAttributeKeys

getAttributeKeys(): string[]

傳回這個版位設定的屬性鍵清單。如要查看這個版位繼承的服務層級屬性鍵，請使用 PubAdsService.getAttributeKeys。

已淘汰：請改用 googletag.Slot.getConfig。

範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setConfig({
    adsenseAttributes: {
      page_url: "http://www.example.com",
      document_language: "en",
    },
  })
  .addService(googletag.pubads());

const adsenseConfig = slot.getConfig("adsenseAttributes").adsenseAttributes;
const adsenseAttributes = Object.keys(adsenseConfig || {});
// Returns ['page_url', 'document_language'].

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setConfig({
    adsenseAttributes: {
      page_url: "http://www.example.com",
      document_language: "en",
    },
  })
  .addService(googletag.pubads());

const adsenseConfig = slot.getConfig("adsenseAttributes").adsenseAttributes;
const adsenseAttributes = Object.keys(adsenseConfig || {});
// Returns ['page_url', 'document_language'].

傳回
string[]	屬性鍵陣列。未定義排序。

---

getCategoryExclusions

getCategoryExclusions(): string[]

傳回這個版位的廣告類別排除標籤。

已淘汰：請改用 googletag.Slot.getConfig。

範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setConfig({
    categoryExclusion: ["AirlineAd", "TrainAd"],
  })
  .addService(googletag.pubads());

const exclusions = slot.getConfig("categoryExclusion")?.categoryExclusion || [];
// Returns ['AirlineAd', 'TrainAd'].

TypeScript

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

const exclusions = slot.getConfig("categoryExclusion")?.categoryExclusion || [];
// Returns ['AirlineAd', 'TrainAd'].

傳回
string[]	這個版位的廣告類別排除標籤，如果未設定任何標籤，則為空白陣列。

---

getConfig

getConfig(keys: string | string[]): Readonly<Pick<SlotSettingsConfig, "adsenseAttributes" | "targeting" | "categoryExclusion">>

取得由 setConfig 設定的版位一般設定選項凍結副本。

這個方法不支援所有 setConfig() 屬性。支援的屬性如下：

• adsenseAttributes
• categoryExclusion
• targeting

範例

JavaScript

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

// Get the value of the `targeting` setting.
const targetingConfig = slot.getConfig("targeting");

// Get the value of the `adsenseAttributes` and `categoryExclusion` settings.
const config = slot.getConfig(["adsenseAttributes", "categoryExclusion"]);

TypeScript

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

// Get the value of the `targeting` setting.
const targetingConfig = slot.getConfig("targeting");

// Get the value of the `adsenseAttributes` and `categoryExclusion` settings.
const config = slot.getConfig(["adsenseAttributes", "categoryExclusion"]);

參數
keys: string | string[]	要取得的設定選項鍵。

傳回
Readonly<Pick<SlotSettingsConfig, "adsenseAttributes" | "targeting" | "categoryExclusion">>	版位設定選項的凍結副本。

---

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'.

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[]

傳回這個版位設定的特定自訂指定目標參數。不含服務層級指定目標參數。

已淘汰：請改用 googletag.Slot.getConfig。

範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setConfig({
    targeting: {
      allow_expandable: "true",
    },
  })
  .addService(googletag.pubads());

const targetingConfig = slot.getConfig("targeting").targeting;

// Get targeting for a specific key.
const targeting = targetingConfig?.["allow_expandable"] || [];
// Returns ['true'].

const ageTargeting = targetingConfig?.["age"] || [];
// Returns [] (empty array).

TypeScript

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

const targetingConfig = slot.getConfig("targeting").targeting;

// Get targeting for a specific key.
const targeting = targetingConfig?.["allow_expandable"] || [];
// Returns ['true'].

const ageTargeting = targetingConfig?.["age"] || [];
// Returns [] (empty array).

參數
key: string	要尋找的指定鍵。

傳回
string[]	與這個鍵相關聯的值；如果沒有這類鍵，則為空陣列。

---

getTargetingKeys

getTargetingKeys(): string[]

傳回這個版位設定的所有自訂指定鍵清單。不含服務層級指定鍵。

已淘汰：請改用 googletag.Slot.getConfig。

範例

JavaScript

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

const targetingConfig = slot.getConfig("targeting").targeting;
const keys = Object.keys(targetingConfig || {});
// Returns ['interests', 'allow_expandable'].

TypeScript

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

const targetingConfig = slot.getConfig("targeting").targeting;
const keys = Object.keys(targetingConfig || {});
// Returns ['interests', 'allow_expandable'].

傳回
string[]	指定鍵陣列。未定義排序。

---

set

set(key: string, value: string): Slot

設定這個廣告版位的 AdSense 屬性值。這會覆寫這個鍵在服務層級設定的所有值。

如果對同一個鍵多次呼叫這個方法，會覆寫該鍵先前設定的值。呼叫 display 或 refresh 前，必須先設定所有值。

已淘汰：請改用 SlotSettingsConfig.adsenseAttributes。

範例

JavaScript

// Setting an attribute on a single ad slot.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setConfig({
    adsenseAttributes: {
      page_url: "http://www.example.com",
    },
  })
  .addService(googletag.pubads());

TypeScript

// Setting an attribute on a single ad slot.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setConfig({
    adsenseAttributes: {
      page_url: "http://www.example.com",
    },
  })
  .addService(googletag.pubads());

另請參閱

• AdSense 屬性

參數
key: string	屬性名稱。
value: string	屬性值。

傳回
Slot	呼叫方法的版位物件。

---

setCategoryExclusion

setCategoryExclusion(categoryExclusion: string): Slot

在這個版位設定版位層級廣告類別排除標籤。

已淘汰：請改用 SlotSettingsConfig.categoryExclusion。

範例

JavaScript

// Label = AirlineAd.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .setConfig({
    categoryExclusion: ["AirlineAd"],
  })
  .addService(googletag.pubads());

TypeScript

// Label = AirlineAd.
googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .setConfig({
    categoryExclusion: ["AirlineAd"],
  })
  .addService(googletag.pubads());

另請參閱

• 封鎖廣告的自訂標籤

參數
categoryExclusion: string	要新增的廣告類別排除標籤。

傳回
Slot	呼叫方法的版位物件。

---

setClickUrl

setClickUrl(value: string): Slot

設定使用者點按廣告後，系統會將他們重新導向至哪個點擊網址。

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

已淘汰：請改用 SlotSettingsConfig.clickUrl。

範例

JavaScript

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

TypeScript

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

參數
value: string	要設定的點擊網址。

傳回
Slot	呼叫方法的版位物件。

---

setCollapseEmptyDiv

setCollapseEmptyDiv(collapse: boolean, collapseBeforeAdFetch?: boolean): Slot

設定版位中沒有廣告時，是否應隱藏版位 div。這會覆寫服務層級設定。

已淘汰：請改用 SlotSettingsConfig.collapseDiv。

範例

JavaScript

const slot1 = googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")
  .setConfig({
    collapseDiv: "BEFORE_FETCH",
  })
  .addService(googletag.pubads());
// The above will cause the div for this slot to be collapsed
// when the page is loaded, before ads are requested.

const slot2 = googletag
  .defineSlot("/1234567/sports", [160, 600], "div-2")
  .setConfig({
    collapseDiv: "ON_NO_FILL",
  })
  .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

const slot1 = googletag
  .defineSlot("/1234567/sports", [160, 600], "div-1")!
  .setConfig({
    collapseDiv: "BEFORE_FETCH",
  })
  .addService(googletag.pubads());
// The above will cause the div for this slot to be collapsed
// when the page is loaded, before ads are requested.

const slot2 = googletag
  .defineSlot("/1234567/sports", [160, 600], "div-2")!
  .setConfig({
    collapseDiv: "ON_NO_FILL",
  })
  .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	呼叫方法的版位物件。

---

setConfig

setConfig(slotConfig: SlotSettingsConfig): Slot

設定這個版位的一般設定選項。

參數
slotConfig: SlotSettingsConfig	設定物件。

傳回
Slot	呼叫方法的版位物件。

---

setForceSafeFrame

setForceSafeFrame(forceSafeFrame: boolean): Slot

設定是否強制使用 SafeFrame 容器，顯示這個版位中的廣告。

使用這個 API 時，請注意下列事項：

• 這項設定只會對各個版位後續提出的廣告請求生效。
• 如果指定了版位層級設定，則一律會覆寫網頁層級設定。
• 如果設為 true (在版位層級或網頁層級)，廣告一律會使用 SafeFrame 容器顯示，不受 Google Ad Manager 使用者介面中的選擇影響。
• 不過，如果設為 false 或未指定，系統會根據廣告素材類型和 Google Ad Manager 使用者介面中的選項，使用 SafeFrame 容器顯示廣告。
• 這個 API 可能會影響廣告素材的行為，例如廣告素材嘗試跳出 iframe，或需要直接在發布商網頁中顯示，因此請謹慎使用。

已淘汰：請改用 SlotSettingsConfig.safeFrame。

範例

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());

另請參閱

• 使用 SafeFrame 顯示廣告素材

參數
forceSafeFrame: boolean	true：強制這個版位中的所有廣告在 SafeFrame 中顯示。false：選擇不採用網頁層級設定 (如有)。如果未在網頁層級指定，將此值設為 false 不會產生任何影響。

傳回
Slot	呼叫方法的版位物件。

---

setSafeFrameConfig

setSafeFrameConfig(config: SafeFrameConfig): Slot

設定 SafeFrame 的版位層級偏好設定。系統會忽略設定物件中任何無法辨識的鍵。如果為已辨識的鍵傳遞無效值，系統會忽略整個設定。

如果指定這些版位層級偏好設定，就會覆寫任何網頁層級偏好設定。

已淘汰：請改用 SlotSettingsConfig.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");

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");

另請參閱

• 使用 SafeFrame 顯示廣告素材

參數
config: SafeFrameConfig	設定物件。

傳回
Slot	呼叫方法的版位物件。

---

setTargeting

setTargeting(key: string, value: string | string[]): Slot

為這個版位設定自訂指定目標參數。如果針對同一個鍵多次呼叫這個方法，舊值會遭到覆寫。在這裡設定的值會覆寫服務層級設定的指定目標參數。這些鍵是在 Google Ad Manager 帳戶中定義。

已淘汰：請改用 SlotSettingsConfig.targeting。

範例

JavaScript

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

// Example with a single value for a key.
slot.setConfig({
  targeting: {
    allow_expandable: "true",
  },
});

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

TypeScript

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

// Example with a single value for a key.
slot.setConfig({
  targeting: {
    allow_expandable: "true",
  },
});

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

另請參閱

• 鍵/值指定目標

參數
key: string	指定目標參數鍵。
value: string | string[]	指定參數值或值陣列。

傳回
Slot	呼叫方法的版位物件。

---

updateTargetingFromMap

updateTargetingFromMap(map: {
  [adUnitPath: string]: string | string[];
}): Slot

從 JSON 物件中的鍵：值對應，為這個版位設定自訂指定目標參數。這與為物件的所有鍵/值呼叫 Slot.setTargeting 相同。這些鍵是在 Google Ad Manager 帳戶中定義。

注意事項：

• 如果覆寫，系統只會保留最後一個值。
• 如果值是陣列，系統會覆寫任何先前的值，而不是合併。
• 這裡設定的值會覆寫服務層級設定的指定參數。

已淘汰：請改用 SlotSettingsConfig.targeting。

範例

JavaScript

const 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	呼叫方法的版位物件。

---

googletag.config

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

介面
AdExpansionConfig	控制廣告展開的設定。
AdSenseAttributesConfig	控制 AdSense 廣告行為的設定。
AutoRefreshConfig	自動重新整理設定。
ContinueButtonConfig	設定「繼續」按鈕的行為。
InterstitialConfig	這個物件用於定義單一插頁式廣告版位的行為。
LazyLoadConfig	控制 GPT 延遲載入功能的設定。
PageSettingsConfig	網頁層級設定的主要設定介面。
PrivacyTreatmentsConfig	控管發布商隱私權處理方式的設定。
PublisherProvidedSignalsConfig	發布商提供的信號 (PPS) 設定物件。
SafeFrameConfig	在 GPT 中控制 SafeFrame 的設定。
SlotSettingsConfig	版位層級設定的主要設定介面。
TaxonomyData	包含單一分類值的物件。
VideoAdsConfig	影片廣告相關設定。

型別別名
CollapseDivBehavior	控制廣告版位收合行為的支援值。
InterstitialTrigger	支援的插頁式廣告觸發條件。
PrivacyTreatment	支援的發布商隱私權處理方式。
Taxonomy	發布商提供的信號 (PPS) 支援的分類。

型別別名

---

CollapseDivBehavior

CollapseDivBehavior: "DISABLED" | "BEFORE_FETCH" | "ON_NO_FILL"

控制廣告版位收合行為的支援值。

另請參閱

• PageSettingsConfig.collapseDiv
• SlotSettingsConfig.collapseDiv

---

InterstitialTrigger

InterstitialTrigger: "unhideWindow" | "navBar" | "inactivity" | "endOfArticle" | "continueReading" | "backward"

支援的插頁式廣告觸發條件。

注意：2026 年 6 月 15 日起，系統將不再支援 backward 觸發條件，啟用後不會有任何作用。詳情請參閱 GPT 版本資訊。

---

PrivacyTreatment

PrivacyTreatment: "disablePersonalization"

支援的發布商隱私權處理方式。

---

分類

Taxonomy: "IAB_AUDIENCE_1_1" | "IAB_CONTENT_2_2"

發布商提供的信號 (PPS) 支援的分類。

另請參閱

• IAB 目標對象分類 1.1
• IAB 內容分類 2.2

---

googletag.config.AdExpansionConfig

控制廣告展開的設定。

屬性
enabled?	廣告展開功能是否啟用。

範例

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?	顯示廣告的網頁網址。

另請參閱

• PageSettingsConfig.adsenseAttributes
• SlotSettingsConfig.adsenseAttributes

屬性

---

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

另請參閱

• ISO 639 語言代碼清單

---

Optional page_url

page_url?: string

顯示廣告的網頁網址。

允許的值為有效網址。

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

---

googletag.config.AutoRefreshConfig

自動重新整理設定。

屬性
backForwardCache?	從往返快取還原網頁時，GPT 是否會自動重新整理正在瀏覽的廣告版位。
heavyAds?	如果 Chrome 的「耗用大量資源的廣告干預」在廣告版位的 iframe 上觸發，GPT 是否會自動重新整理廣告版位。

屬性

---

Optional backForwardCache

backForwardCache?: boolean

從往返快取還原網頁時，GPT 是否會自動重新整理正在瀏覽的廣告版位。預設為 true。

範例

JavaScript

// Set the auto refresh configuration, disabling auto refresh on
// back/forward cache restore.
googletag.setConfig({ autoRefresh: { backForwardCache: false } });

// Clear the auto refresh configuration, restoring to default behavior.
googletag.setConfig({ autoRefresh: null });

TypeScript

// Set the auto refresh configuration, disabling auto refresh on
// back/forward cache restore.
googletag.setConfig({ autoRefresh: { backForwardCache: false } });

// Clear the auto refresh configuration, restoring to default behavior.
googletag.setConfig({ autoRefresh: null });

另請參閱

• 往返快取

---

Optional heavyAds

heavyAds?: boolean

如果 Chrome 的「耗用大量資源的廣告干預」在廣告版位的 iframe 上觸發，GPT 是否會自動重新整理廣告版位。預設為 true。

範例

JavaScript

// Set the auto refresh configuration, disabling auto refresh on heavy
// ad intervention.
googletag.setConfig({ autoRefresh: { heavyAds: false } });

// Clear the auto refresh configuration, restoring to default behavior.
googletag.setConfig({ autoRefresh: null });

TypeScript

// Set the auto refresh configuration, disabling auto refresh on heavy
// ad intervention.
googletag.setConfig({ autoRefresh: { heavyAds: false } });

// Clear the auto refresh configuration, restoring to default behavior.
googletag.setConfig({ autoRefresh: null });

另請參閱

• 瞭解 Chrome 的「耗用大量資源的廣告干預」機制

---

googletag.config.ContinueButtonConfig

設定「繼續」按鈕的行為。

屬性
backgroundColor?	按鈕的背景顏色。
font?	按鈕文字的字型系列。
fontColor?	按鈕的文字顏色。
freqCapIntervalMinutes?	展示頻率上限間隔 (以分鐘為單位)。
targetId?	用來顯示/觸發「繼續」按鈕的 HTML 元素 ID。

另請參閱

• SlotSettingsConfig.continueButton

屬性

---

Optional backgroundColor

backgroundColor?: string

按鈕的背景顏色。

範例：'blue'、'#94B1FF'

---

Optional 字型

font?: string

按鈕文字的字型系列。

範例：'Arial'

---

Optional fontColor

fontColor?: string

按鈕的文字顏色。

範例：'white'、'#B73B87'

---

Optional freqCapIntervalMinutes

freqCapIntervalMinutes?: number

展示頻率上限間隔 (以分鐘為單位)。

必須是大於或等於 1 的整數。

---

Optional targetId

targetId?: string

用來顯示/觸發「繼續」按鈕的 HTML 元素 ID。

---

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
  },
});

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?: 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,
    },
  },
});

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?	廣告版位與目前可視區域的最小距離 (以可視區域大小的百分比表示)，達到這個距離後，系統才會顯示廣告。

另請參閱

• PageSettingsConfig.lazyLoad

屬性

---

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?	已淘汰。
autoRefresh?	設定自動廣告重新整理行為。
categoryExclusion?	設定廣告類別排除條件。
centering?	控制廣告水平置中的設定。
collapseDiv?	控制廣告版位收合行為的設定。
disableInitialLoad?	控制廣告請求時間的設定。
lazyLoad?	控制 GPT 延遲載入功能的設定。
location?	設定委刊項指定地理區域。
pps?	控管發布商提供的信號 (PPS) 的設定。
privacyTreatments?	控管發布商隱私權處理方式的設定。
requestHookTimeoutMs?	這項設定可控制 GPT 等待所有已註冊請求掛鉤完成的時間上限，超過這個時間就會繼續處理廣告請求。
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 });

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"

已淘汰：請改用 threadYield。這項功能將在近期內移除。

---

Optional autoRefresh

autoRefresh?: AutoRefreshConfig

設定自動廣告重新整理行為。

範例

JavaScript

// Set the auto refresh configuration.
googletag.setConfig({ autoRefresh: { heavyAds: false } });

// Clear the auto refresh configuration.
googletag.setConfig({ autoRefresh: null });

TypeScript

// Set the auto refresh configuration.
googletag.setConfig({ autoRefresh: { heavyAds: false } });

// Clear the auto refresh configuration.
googletag.setConfig({ autoRefresh: null });

---

Optional categoryExclusion

categoryExclusion?: string[]

設定廣告類別排除條件。

範例

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 });

TypeScript

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

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

---

Optional collapseDiv

collapseDiv?: CollapseDivBehavior

控制廣告版位收合行為的設定。

收合的廣告版位不會占用頁面空間。

支援的值：

• 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 });

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 });

TypeScript

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

另請參閱

• 控管廣告載入和重新整理
• 控制 SRA 批次處理

---

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 });

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?: string

將委刊項指定地理區域設為地理位置。

範例

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?: PublisherProvidedSignalsConfig

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

---

Optional privacyTreatments

privacyTreatments?: PrivacyTreatmentsConfig

控管發布商隱私權處理方式的設定。

---

Optional Experimental requestHookTimeoutMs

requestHookTimeoutMs?: number | "auto"

這項設定可控制 GPT 等待所有已註冊請求掛鉤完成的時間上限，超過這個時間就會繼續執行廣告請求。

所有已註冊的請求掛鉤都會平行執行。這項逾時設定定義了廣告請求程序暫停等待平行執行作業完成的時間上限。

支援的值：

• 正數 (以毫秒為單位)：自訂等待期。
• 'auto'：GPT 使用 Google 最佳化的逾時。
• null：停用逾時 (GPT 會無限期等待掛鉤完成)。

範例

JavaScript

// Set a 1000ms timeout for request hooks.
googletag.setConfig({ requestHookTimeoutMs: 1000 });

// Use a Google-optimized timeout for request hooks.
googletag.setConfig({ requestHookTimeoutMs: "auto" });

// Clear the timeout.
googletag.setConfig({ requestHookTimeoutMs: null });

TypeScript

// Set a 1000ms timeout for request hooks.
googletag.setConfig({ requestHookTimeoutMs: 1000 });

// Use a Google-optimized timeout for request hooks.
googletag.setConfig({ requestHookTimeoutMs: "auto" });

// Clear the timeout.
googletag.setConfig({ requestHookTimeoutMs: null });

---

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 });

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 });

TypeScript

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

另請參閱

• 路障型廣告簡介
• 廣告最佳做法：正確使用單一請求架構
• 控制 SRA 批次處理

---

Optional 指定目標

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 } });

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 });

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 });

另請參閱

• Scheduler

---

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",
  },
});

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

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	包含分類對應關係的物件，或空值 (用於清除設定)。

範例

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'
    },
  },
});

另請參閱

• 發布商提供的信號 (Beta 版) 簡介
• IAB 目標對象分類 1.1
• IAB 內容分類 2.2

屬性

---

分類

taxonomies: Partial<Record<Taxonomy, TaxonomyData>>

包含分類對應關係的物件，或空值 (用於清除設定)。

---

googletag.config.SafeFrameConfig

在 GPT 中控制 SafeFrame 的設定。

屬性
allowOverlayExpansion?	SafeFrame 是否應允許廣告素材透過疊加網頁內容展開。
allowPushExpansion?	SafeFrame 是否應允許廣告素材透過推送網頁內容展開。
forceSafeFrame?	是否應強制使用 SafeFrame 容器顯示廣告。
sandbox?	SafeFrame 是否應使用 HTML5 沙箱屬性，防止在沒有使用者互動的情況下進行頂層導覽。
useUniqueDomain?	已淘汰。 SafeFrame 是否應為預訂廣告素材使用隨機子網域。

另請參閱

• PageSettingsConfig.safeFrame
• SlotSettingsConfig.safeFrame

屬性

---

Optional allowOverlayExpansion

allowOverlayExpansion?: boolean

SafeFrame 是否應允許廣告素材透過疊加網頁內容展開。

---

Optional allowPushExpansion

allowPushExpansion?: boolean

SafeFrame 是否應允許廣告素材透過推送網頁內容展開。

---

Optional forceSafeFrame

forceSafeFrame?: boolean

是否應強制使用 SafeFrame 容器顯示廣告。

---

Optional 沙箱

sandbox?: boolean

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

---

Optional useUniqueDomain

useUniqueDomain?: boolean

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

注意：這項功能預設為啟用。

已淘汰：無法再停用這項功能。設定 useUniqueDomain 不會產生任何影響。

另請參閱

• 使用 SafeFrame 顯示廣告素材

---

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?	設定廣告版位的收合行為。
continueButton?	設定影片暫停廣告的繼續按鈕行為。
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 });

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 });

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,
});

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?: CollapseDivBehavior

設定廣告版位的收合行為。

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

支援的值：

• 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,
});

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 continueButton

continueButton?: ContinueButtonConfig

設定影片暫停廣告的繼續按鈕行為。

這些設定可自訂與影片暫停格式相關的離開和繼續閱讀互動的外觀和行為。

呼叫 setConfig() 時，未指定的任何繼續按鈕設定都會使用 Google 設定的預設值。

如要停用或清除所有繼續按鈕設定，請傳遞 null。

範例

JavaScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")
  .addService(googletag.pubads());
// Configure continue button settings.
slot.setConfig({
  continueButton: {
    font: "Arial",
    fontColor: "white",
    backgroundColor: "blue",
    targetId: "target-div-id",
    freqCapIntervalMinutes: 20,
  },
});

// Clear continue button settings.
slot.setConfig({ continueButton: null });

TypeScript

const slot = googletag
  .defineSlot("/1234567/sports", [160, 600], "div")!
  .addService(googletag.pubads());
// Configure continue button settings.
slot.setConfig({
  continueButton: {
    font: "Arial",
    fontColor: "white",
    backgroundColor: "blue",
    targetId: "target-div-id",
    freqCapIntervalMinutes: 20,
  },
});

// Clear continue button settings.
slot.setConfig({ continueButton: null });

---

Optional 插頁式廣告

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 });

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?: 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 });

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

values: readonly string[]

分類值清單。

---

googletag.config.VideoAdsConfig

影片廣告相關設定。

屬性
enableVideoAds	網頁是否會顯示影片廣告。
videoCmsId?	影片內容來源 ID。
videoContentId?	影片內容 ID。

另請參閱

• PageSettingsConfig.videoAds

屬性

---

enableVideoAds

enableVideoAds: boolean

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

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

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

---

Optional videoCmsId

videoCmsId?: string

影片內容來源 ID。

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

另請參閱

• cmsid (內容來源 ID)

---

Optional videoContentId

videoContentId?: string

影片內容 ID。

這是不重複的值，用於識別 videoCmsId 指定內容來源中的特定影片。這個值是由代管影片內容的內容管理平台指定。

另請參閱

• vid (影片 ID)

---

googletag.enums

這是 GPT 用於列舉類型的命名空間。

列舉
OutOfPageFormat	GPT 支援的非頁內廣告格式。
TagForAgeTreatment	GPT 支援的年齡處理方式設定。
TrafficSource	GPT 支援的流量來源。

列舉

---

OutOfPageFormat

OutOfPageFormat

GPT 支援的非頁內廣告格式。

另請參閱

• defineOutOfPageSlot

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

---

TagForAgeTreatment

TagForAgeTreatment

GPT 支援的年齡處理設定。

另請參閱

• PrivacySettingsConfig.tagForAgeTreatment

列舉成員
CHILD	表示廣告請求應採用 CHILD 年齡處理方式。
TEEN	表示廣告請求應採用 TEEN 年齡處理方式。
UNSPECIFIED	預設值。表示廣告請求不適用任何特定年齡限制處理信號。

---

TrafficSource

TrafficSource

GPT 支援的流量來源。

另請參閱

• PrivacySettingsConfig.trafficSource

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

---

googletag.events

這是 GPT 用於事件的命名空間。程式碼可以使用 Service.addEventListener 回應這些事件。

介面
Event	所有 GPT 事件的基本介面。
EventTypeMap	這是一種虛擬類型，可將事件名稱對應至 Service.addEventListener 和 Service.removeEventListener 的對應事件物件類型。
GameManualInterstitialSlotClosedEvent	使用者關閉手動插頁式遊戲廣告版位時，系統會觸發這個事件。
GameManualInterstitialSlotReadyEvent	當手動插頁式遊戲廣告版位已可向使用者顯示時，系統會觸發這個事件。
ImpressionViewableEvent	根據 Active View 標準，當曝光成為可視曝光時，系統就會觸發這個事件。
RewardedSlotClosedEvent	使用者關閉獎勵廣告版位時，系統會觸發這個事件。
RewardedSlotGrantedEvent	使用者觀看獎勵廣告並獲得獎勵時，系統會觸發這個事件。
RewardedSlotReadyEvent	獎勵廣告準備就緒，可以顯示時，就會觸發這個事件。
RewardedSlotVideoCompletedEvent	獎勵影片廣告播放完畢時，系統會觸發這個事件。
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	events.GameManualInterstitialSlotClosedEvent 的別名。
gameManualInterstitialSlotReady	events.GameManualInterstitialSlotReadyEvent 的別名。
impressionViewable	events.ImpressionViewableEvent 的別名。
rewardedSlotClosed	events.RewardedSlotClosedEvent 的別名。
rewardedSlotGranted	events.RewardedSlotGrantedEvent 的別名。
rewardedSlotReady	events.RewardedSlotReadyEvent 的別名。
rewardedSlotVideoCompleted	events.RewardedSlotVideoCompletedEvent 的別名。
slotOnload	events.SlotOnloadEvent 的別名。
slotRenderEnded	events.SlotRenderEndedEvent 的別名。
slotRequested	events.SlotRequestedEvent 的別名。
slotResponseReceived	events.SlotResponseReceived 的別名。
slotVisibilityChanged	events.SlotVisibilityChangedEvent 的別名。

屬性

---

gameManualInterstitialSlotClosed

gameManualInterstitialSlotClosed: GameManualInterstitialSlotClosedEvent

events.GameManualInterstitialSlotClosedEvent 的別名。

---

gameManualInterstitialSlotReady

gameManualInterstitialSlotReady: GameManualInterstitialSlotReadyEvent

events.GameManualInterstitialSlotReadyEvent 的別名。

---

impressionViewable

impressionViewable: ImpressionViewableEvent

events.ImpressionViewableEvent 的別名。

---

rewardedSlotClosed

rewardedSlotClosed: RewardedSlotClosedEvent

events.RewardedSlotClosedEvent 的別名。

---

rewardedSlotGranted

rewardedSlotGranted: RewardedSlotGrantedEvent

events.RewardedSlotGrantedEvent 的別名。

---

rewardedSlotReady

rewardedSlotReady: RewardedSlotReadyEvent

events.RewardedSlotReadyEvent 的別名。

---

rewardedSlotVideoCompleted

rewardedSlotVideoCompleted: RewardedSlotVideoCompletedEvent

events.RewardedSlotVideoCompletedEvent 的別名。

---

slotOnload

slotOnload: SlotOnloadEvent

events.SlotOnloadEvent 的別名。

---

slotRenderEnded

slotRenderEnded: SlotRenderEndedEvent

events.SlotRenderEndedEvent 的別名。

---

slotRequested

slotRequested: SlotRequestedEvent

events.SlotRequestedEvent 的別名。

---

slotResponseReceived

slotResponseReceived: SlotResponseReceived

events.SlotResponseReceived 的別名。

---

slotVisibilityChanged

slotVisibilityChanged: SlotVisibilityChangedEvent

events.SlotVisibilityChangedEvent 的別名。

---

googletag.events.GameManualInterstitialSlotClosedEvent

擴充 Event

使用者關閉手動插頁式遊戲廣告版位時，系統會觸發這個事件。

注意：手動插頁式遊戲廣告格式僅限部分對象使用。

屬性
serviceName	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
    }
  });
}

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	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
    }
  });
}

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(): boolean

向使用者顯示遊戲手冊插頁式廣告。傳回廣告是否成功顯示。

傳回
boolean

---

googletag.events.ImpressionViewableEvent

擴充 Event

根據 Active View 標準，當曝光成為可視曝光時，系統就會觸發這個事件。

屬性
serviceName	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
  }
});

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	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
    }
  });
}

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	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
    }
  });
}

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

payload: RewardedPayload

這個物件包含已發放獎勵的相關資訊。

---

googletag.events.RewardedSlotReadyEvent

擴充 Event

獎勵廣告準備就緒，可以顯示時，就會觸發這個事件。發布商必須先提供選項，讓使用者選擇是否觀看廣告，才能顯示廣告。

屬性
serviceName	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
    }
  });
}

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(): boolean

顯示獎勵廣告。使用者同意觀看廣告後，才能呼叫這個方法。

傳回
boolean	獎勵廣告是否成功顯示。

---

googletag.events.RewardedSlotVideoCompletedEvent

擴充 Event

獎勵影片廣告播放完畢時，系統會觸發這個事件。

屬性
serviceName	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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 video in a rewarded ad slot has
  // finished playing.
  googletag.pubads().addEventListener("rewardedSlotVideoCompleted", (event) => {
    const slot = event.slot;
    console.log("Video in rewarded ad slot", slot.getSlotElementId(), "has finished playing.");

    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 video in a rewarded ad slot has
  // finished playing.
  googletag.pubads().addEventListener("rewardedSlotVideoCompleted", (event) => {
    const slot = event.slot;
    console.log("Video in rewarded ad slot", slot.getSlotElementId(), "has finished playing.");

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

另請參閱

• 廣告事件監聽器
• 顯示獎勵廣告

---

googletag.events.SlotOnloadEvent

擴充 Event

廣告素材的 iframe 觸發載入事件時，系統會觸發這個事件。在同步算繪模式下算繪互動式多媒體廣告時，系統不會使用 iframe，因此不會觸發 SlotOnloadEvent。

屬性
serviceName	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
  }
});

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

廣告素材程式碼插入版位時，系統會觸發這個事件。這個事件會在擷取廣告素材資源前發生，因此廣告素材可能尚未顯示。Coworker: 如果需要知道版位的所有廣告素材資源何時載入完成，請改用 events.SlotOnloadEvent。

屬性
advertiserId	所顯示廣告的廣告主 ID。
campaignId	放送廣告的廣告活動 ID。
companyIds	對放送的候補廣告出價的公司 ID。
creativeId	已顯示預訂廣告的廣告素材 ID。
creativeTemplateId	已顯示預訂廣告的廣告素材範本 ID。
isBackfill	廣告是否為候補廣告。
isEmpty	廣告版位是否傳回廣告。
labelIds	已淘汰。
lineItemId	已顯示預訂廣告的商品項目 ID。
responseIdentifier	回應 ID 是廣告回應的專屬 ID。
serviceName	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
size	表示顯示的廣告素材像素大小。
slot	觸發事件的版位。 沿用自 Event.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.
  }
});

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	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
  }
});

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	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
  }
});

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	觸發事件的服務名稱。 沿用自 Event.serviceName 屬性
slot	觸發事件的版位。 沿用自 Event.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.
  }
});

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

SecureSignalProvider: BidderSignalProvider | PublisherSignalProvider

這個介面用於傳回特定出價方或供應商的安全信號。必須提供 id 或 networkCode，但不可同時提供。

---

googletag.secureSignals.BidderSignalProvider

傳回特定出價方的安全信號。

出價方安全信號供應商由 2 個部分組成：

1. 收集器函式，會傳回解析為安全信號的 Promise。
2. id：用於識別與信號相關聯的出價方。

。如要傳回發布商的安全信號，請改用 secureSignals.PublisherSignalProvider。

屬性
collectorFunction	這個函式會傳回 Promise，解析為安全信號。
id	在 Google Ad Manager 中註冊，與這個安全信號相關聯的收集器專屬 ID。

範例

JavaScript

// id is provided
googletag.secureSignalProviders.push({
  id: "collector123",
  collectorFunction: () => {
    // ...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

在 Google Ad Manager 中註冊，與這個安全信號相關聯的收集器專屬 ID。

---

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");
  },
});

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

push(provider: SecureSignalProvider): void

在信號供應商陣列中新增 secureSignals.SecureSignalProvider，並開始信號產生程序。

參數
provider: SecureSignalProvider	要新增至陣列的 secureSignals.SecureSignalProvider 物件。