GPT 參考資料

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

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

設定是否要自動補上尚未填入廣告的隨播廣告版位。

這個方法可以在網頁生命週期內多次呼叫，以開啟或關閉補上廣告的功能。只有透過 PubAdsService 註冊的版位才會補上廣告。由於政策限制，這個方法無法在 Ad Exchange 影片放送時填入空白隨播廣告插播單元。

範例

JavaScript

googletag.companionAds().setRefreshUnfilledSlots(true);

JavaScript (舊版)

googletag.companionAds().setRefreshUnfilledSlots(true);

TypeScript

googletag.companionAds().setRefreshUnfilledSlots(true);

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

啟用放送模式，以受限制的廣告模式放送廣告，協助發布商符合法規規定。

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

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

範例

JavaScript

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

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

另請參閱

• 顯示受限制的廣告

讓廣告在非個人化廣告模式下放送，以符合發布商的法規遵循需求。

讓廣告在受限的處理模式下放送，以滿足發布商的法規遵循需求。

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

範例

JavaScript

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

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

JavaScript (舊版)

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

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

TypeScript

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

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

指出是否要將廣告請求標記為來自未滿法定同意年齡的使用者。設為 null 即可清除設定。

從指定的廣告位移除廣告，並用空白內容取代。系統會將這些版位標示為未擷取。

具體來說，清除版位會從 GPT 的長效網頁瀏覽中移除廣告，因此日後的請求不會受到涉及這則廣告的路障或競爭排除條件影響。

範例

JavaScript

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

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

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

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

JavaScript (舊版)

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

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

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

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

TypeScript

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

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

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

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

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

範例

JavaScript

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

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

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

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

JavaScript (舊版)

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

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

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

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

TypeScript

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

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

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

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

另請參閱

• 用來封鎖廣告的自訂標籤

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

範例

JavaScript

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

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

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

JavaScript (舊版)

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

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

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

TypeScript

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

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

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

另請參閱

• 指定鍵/值

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

另請參閱

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

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

另請參閱

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

根據指定廣告單元路徑和大小建構並顯示廣告版位。這個方法不適用於單一請求模式。

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

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

另請參閱

• 顯示測試廣告
• 控管廣告載入和重新整理

啟用 GPT 中的延遲載入功能，如設定物件所定義。如需更詳細的範例，請參閱 延遲載入範例。

注意：只有當所有時段都位於擷取邊界之外時，SRA 中的延遲擷取功能才會運作。

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

另請參閱

• 廣告最佳做法：優先顯示「重要」廣告位元
• 延遲載入

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

另請參閱

• 廣告最佳做法：正確使用單一請求架構
• 控制零售業務員批次處理作業

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

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

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

另請參閱

• AdSense 屬性

傳回已在這個服務上設定的屬性鍵。

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

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

範例

JavaScript

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

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

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

JavaScript (舊版)

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

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

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

TypeScript

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

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

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

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

範例

JavaScript

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

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

JavaScript (舊版)

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

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

TypeScript

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

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

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

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

為確保在所有瀏覽器中正常運作，請先呼叫 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 });

JavaScript (舊版)

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

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

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

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

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

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

TypeScript

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

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

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

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

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

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

另請參閱

• 控管廣告載入和重新整理
• 重新整理廣告版位

為適用於發布商廣告服務下所有廣告版位的 AdSense 屬性設定值。

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

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

另請參閱

• AdSense 屬性

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

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

另請參閱

• 封鎖廣告的自訂標籤

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

您應在呼叫 display 或 refresh 之前叫用此方法，因為只有在呼叫此方法後要求的廣告才會置中。

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

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

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

• 這項設定只會影響個別版位提出的「後續」廣告請求。
• 如果指定了版位層級設定，系統一律會覆寫網頁層級設定。
• 如果設定為 true (在版位層級或網頁層級)，系統一律會使用 SafeFrame 容器顯示廣告，不受 Google Ad Manager UI 中所做的選擇影響。
• 不過，如果設定為 false 或未指定，系統會根據廣告素材類型和 Google Ad Manager UI 中的選項，使用 SafeFrame 容器顯示廣告。
• 使用這個 API 時請務必小心謹慎，因為這個 API 可能會影響廣告素材跳脫 iframe 或直接透過發布商網頁顯示的廣告素材行為。

範例

JavaScript

googletag.pubads().setForceSafeFrame(true);

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

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

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

JavaScript (舊版)

googletag.pubads().setForceSafeFrame(true);

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

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

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

TypeScript

googletag.pubads().setForceSafeFrame(true);

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

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

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

另請參閱

• 使用 SafeFrame 顯示廣告素材

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

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

允許使用設定物件，從單一 API 設定所有隱私權設定。

範例

JavaScript

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

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

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

JavaScript (舊版)

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

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

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

TypeScript

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

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

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

另請參閱

• 調整隱私權設定
• 顯示受限制的廣告

為發布商提供的 ID 設定值。

範例

JavaScript

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

JavaScript (舊版)

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

TypeScript

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

另請參閱

• 關於發布商提供的 ID

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

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

範例

JavaScript

googletag.pubads().setForceSafeFrame(true);

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

const slotConfig = { allowOverlayExpansion: false };

googletag.pubads().setSafeFrameConfig(pageConfig);

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

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

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

JavaScript (舊版)

googletag.pubads().setForceSafeFrame(true);

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

var slotConfig = { allowOverlayExpansion: false };

googletag.pubads().setSafeFrameConfig(pageConfig);

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

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

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

TypeScript

googletag.pubads().setForceSafeFrame(true);

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

const slotConfig = { allowOverlayExpansion: false };

googletag.pubads().setSafeFrameConfig(pageConfig);

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

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

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

另請參閱

• 使用 SafeFrame 顯示廣告素材

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

範例

JavaScript

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

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

JavaScript (舊版)

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

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

TypeScript

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

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

另請參閱

• 指定鍵/值

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

另請參閱

• VAST 廣告代碼網址參數

變更與廣告請求一併傳送的 Correlator，有效啟動新的網頁瀏覽。同一個網頁檢視的所有廣告請求都會使用相同的 Correlator，而不同網頁檢視的 Correlator 則各不相同。僅適用於非同步模式。

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

範例

JavaScript

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

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

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

JavaScript (舊版)

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

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

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

TypeScript

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

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

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

廣告主的 ID。

廣告活動 ID。

廣告素材 ID。

廣告的範本 ID。

商品項目的 ID。

獎勵內含的商品數量。

獎勵中包含的項目類型 (例如「硬幣」)。

設定 SafeFrame 是否應允許隨著網頁內容重疊而展開廣告內容。

是否允許 SafeFrame 透過推送網頁內容，讓廣告內容展開。

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

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

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

另請參閱

• 使用 SafeFrame 顯示廣告素材

註冊一個監聽器，讓您可以在頁面上發生特定 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.
  }
});

JavaScript (舊版)

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

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

TypeScript

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

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

另請參閱

• 廣告事件監聽器

取得與這項服務相關的空檔清單。