此參考資料使用 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 是可接受函式的
其餘參數
。其餘參數接受指定類型值的數量沒有上限。 |
類型定義
類型 | |
---|---|
|
SingleSize | MultiSize
|
版位的有效大小設定,可以是一或多個大小。 |
|
|
SingleSize[]
|
單一有效尺寸的清單。 |
|
|
"fluid" | ["fluid"]
|
版位可擁有的已命名大小。在多數情況下,大小一律為固定大小的矩形,但在某些情況下,我們會需要其他類型的尺寸規格。只有下列有效的已命名大小:
|
|
|
SingleSizeArray | NamedSize
|
版位的單一有效大小。 |
|
|
[number, number]
|
兩個數字的陣列,代表 [寬度, 高度]。 |
|
|
[SingleSizeArray, GeneralSize]
|
可視區域大小與廣告大小的對應。用於回應式廣告。 |
|
|
SizeMapping[]
|
大小對應清單。 |
|
|
"unhideWindow" | "navBar"
|
支援的插頁式廣告觸發條件。 |
|
|
"disablePersonalization"
|
支援的發布商隱私權處理方式。 |
|
|
"IAB_AUDIENCE_1_1" | "IAB_CONTENT_2_2"
|
發布商提供的信號 (PPS) 支援的分類。 |
|
|
BidderSignalProvider | PublisherSignalProvider
|
為特定出價方或供應商傳回安全信號的介面。必須提供 |
列舉類型
列舉 | |
---|---|
googletag.enums.OutOfPageFormat
|
GPT 支援的非頁內廣告格式。
|
googletag.enums.TrafficSource
|
GPT 支援的流量來源。
|
googletag.enums.OutOfPageFormat
-
GPT 支援的非頁內廣告格式。
-
- 另請參閱
-
值 BOTTOM_ANCHOR
錨定格式:版位固定在可視區域底部。INTERSTITIAL
網站插頁式廣告素材格式。LEFT_SIDE_RAIL
左側邊欄格式。REWARDED
獎勵格式。RIGHT_SIDE_RAIL
右側邊欄格式。TOP_ANCHOR
錨定格式:版位固定在可視區域頂端。
googletag.enums.TrafficSource
-
GPT 支援的流量來源。
-
值 ORGANIC
直接網址輸入、站內搜尋或應用程式下載。PURCHASED
從非自有資源重新導向的流量 (取得或獎勵活動)。
googletag
Google 發布商廣告代碼為其 API 採用的全域命名空間。
變數摘要 | |
---|---|
apiReady
|
此標記表示 GPT API 已載入且可供呼叫。
|
cmd
|
GPT 相關呼叫的非同步執行作業的全域指令佇列參照。
|
pubadsReady
|
此標記表示
PubAdsService 已啟用、已載入且完全正常運作。 |
secureSignalProviders
|
安全信號提供者陣列的參照。
|
函式摘要 | |
---|---|
companionAds
|
傳回
CompanionAdsService 的參照。 |
defineOutOfPageSlot
|
使用指定廣告單元路徑建構非頁內廣告版位。
|
defineSlot
|
使用指定廣告單元路徑和大小建構廣告版位,然後將該廣告版位與要放送廣告的網頁 div 元素 ID 建立關聯。
|
destroySlots
|
刪除指定的版位,從 GPT 中移除所有相關物件和這些版位的參照。
|
disablePublisherConsole
|
停用 Google 發布商控制台。
|
display
|
指示運算單元服務轉譯版位。
|
enableServices
|
啟用網頁上廣告版位已定義的所有 GPT 服務。
|
getVersion
|
傳回最新版 GPT。
|
openConsole
|
開啟 Google 發布商控制台。
|
pubads
|
傳回
PubAdsService 的參照。 |
setAdIframeTitle
|
設定此後所有由
PubAdsService 建立的廣告容器 iframe 的標題。 |
setConfig
|
設定頁面的一般設定選項。
|
sizeMapping
|
建立新的
SizeMappingBuilder 。 |
googletag。apiReady
-
apiReady: boolean | undefined
-
此標記表示 GPT API 已載入且可供呼叫。在 API 準備就緒之前,這項屬性會保持
undefined
。
請注意,在 GPT 準備就緒時,建議使用 googletag.cmd 將回呼排入佇列。這些回呼不需要檢查 googletag.apiReady,因為在設定 API 後保證會在設定後執行。 -
- 範例
-
JavaScript
if (window.googletag && googletag.apiReady) { // GPT API can be called safely. }
JavaScript (舊版)
if (window.googletag && googletag.apiReady) { // GPT API can be called safely. }
TypeScript
if (window.googletag && googletag.apiReady) { // GPT API can be called safely. }
googletag。cmd
-
cmd: Array<(this: typeof globalThis) => void> | CommandArray
-
這個全域指令佇列的參照,用於非同步執行 GPT 相關呼叫。
googletag.cmd
變數是由網頁上的 GPT 廣告代碼語法初始化為空白的 JavaScript 陣列,而cmd.push
則是標準的Array.push
方法,可在陣列尾端新增元素。載入 GPT JavaScript 後,系統會檢查陣列並依序執行所有函式。接著,指令碼會將cmd
替換成CommandArray
物件,該物件的推送方法已定義為執行傳遞的函式引數。這項機制可讓 GPT 以非同步方式擷取 JavaScript,同時允許瀏覽器繼續顯示網頁,從而縮短使用者的延遲時間。 -
- 範例
-
JavaScript
googletag.cmd.push(() => { googletag.defineSlot("/1234567/sports", [160, 600]).addService(googletag.pubads()); });
JavaScript (舊版)
googletag.cmd.push(function () { googletag.defineSlot("/1234567/sports", [160, 600]).addService(googletag.pubads()); });
TypeScript
googletag.cmd.push(() => { googletag.defineSlot("/1234567/sports", [160, 600])!.addService(googletag.pubads()); });
googletag。pubadsReady
-
pubadsReady: boolean | undefined
-
此標記表示
PubAdsService
已啟用、已載入且完全正常運作。在呼叫enableServices
且載入並初始化PubAdsService
之前,這個屬性將只會是undefined
。 -
googletag。secureSignalProviders
-
secureSignalProviders: SecureSignalProvider[] | SecureSignalProvidersArray | undefined
-
安全信號提供者陣列的參照。
安全信號供應商陣列會接受一系列信號產生函式,並依序叫用這些函式。並用來取代標準陣列;這些陣列將用來將呼叫的信號產生函式排入佇列,以便在載入 GPT 後叫用這些函式。 -
- 範例
-
JavaScript
window.googletag = window.googletag || { cmd: [] }; googletag.secureSignalProviders = googletag.secureSignalProviders || []; googletag.secureSignalProviders.push({ id: "collector123", collectorFunction: () => { return Promise.resolve("signal"); }, });
JavaScript (舊版)
window.googletag = window.googletag || { cmd: [] }; googletag.secureSignalProviders = googletag.secureSignalProviders || []; googletag.secureSignalProviders.push({ id: "collector123", collectorFunction: function () { return Promise.resolve("signal"); }, });
TypeScript
window.googletag = window.googletag || { cmd: [] }; googletag.secureSignalProviders = googletag.secureSignalProviders || []; googletag.secureSignalProviders.push({ id: "collector123", collectorFunction: () => { return Promise.resolve("signal"); }, });
- 另請參閱
googletag。companionAds
-
companionAds(): CompanionAdsService
-
傳回
CompanionAdsService
的參照。 -
-
傳回 CompanionAdsService
隨播廣告服務。
googletag。defineOutOfPageSlot
-
defineOutOfPageSlot(adUnitPath: string, div?: string | OutOfPageFormat): Slot | null
-
使用指定廣告單元路徑建構非頁內廣告版位。
如果是自訂非頁廣告,div
是您要置入廣告的 div 元素 ID。詳情請參閱非頁內廣告素材相關文章。
對於 GPT 管理的非頁內廣告,div
是支援的 OutOfPageFormat。 -
- 範例
-
JavaScript
// Define a custom out-of-page ad slot. googletag.defineOutOfPageSlot("/1234567/sports", "div-1"); // Define a GPT managed web interstitial ad slot. googletag.defineOutOfPageSlot("/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL);
JavaScript (舊版)
// Define a custom out-of-page ad slot. googletag.defineOutOfPageSlot("/1234567/sports", "div-1"); // Define a GPT managed web interstitial ad slot. googletag.defineOutOfPageSlot("/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL);
TypeScript
// Define a custom out-of-page ad slot. googletag.defineOutOfPageSlot("/1234567/sports", "div-1"); // Define a GPT managed web interstitial ad slot. googletag.defineOutOfPageSlot("/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL);
- 另請參閱
-
參數 adUnitPath: string
包含聯播網代碼和廣告單元代碼的完整廣告單元路徑。div?: string | OutOfPageFormat
包含這個廣告單元或 OutOfPageFormat 的 div 編號。 -
傳回 Slot | null
新建立的運算單元;如果無法建立版位,則為null
。
googletag。defineSlot
-
defineSlot(adUnitPath: string, size: GeneralSize, div?: string): Slot | null
-
使用指定廣告單元路徑和大小建構廣告版位,然後將該廣告版位與要刊登廣告的網頁 div 元素 ID 建立關聯。
-
- 範例
-
JavaScript
googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
JavaScript (舊版)
googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
TypeScript
googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
- 另請參閱
-
參數 adUnitPath: string
包含聯播網代碼和單元代碼的完整廣告單元路徑。size: GeneralSize
新增版位的寬度和高度。這是指未提供回應式大小對應,或可視區域大小小於對應中提供的最小尺寸時,廣告請求中使用的大小。div?: string
要包含這個廣告單元的 div 編號。 -
傳回 Slot | null
新建立的運算單元;如果無法建立版位,則為null
。
googletag。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();
JavaScript (舊版)
// The calls to construct an ad and display contents. var slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1"); googletag.display("div-1"); var slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2"); googletag.display("div-2"); // This call to destroy only slot1. googletag.destroySlots([slot1]); // This call to destroy both slot1 and slot2. googletag.destroySlots([slot1, slot2]); // This call to destroy all slots. googletag.destroySlots();
TypeScript
// The calls to construct an ad and display contents. const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1")!; googletag.display("div-1"); const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2")!; googletag.display("div-2"); // This call to destroy only slot1. googletag.destroySlots([slot1]); // This call to destroy both slot1 and slot2. googletag.destroySlots([slot1, slot2]); // This call to destroy all slots. googletag.destroySlots();
-
參數 slots?: Slot[]
要刪除的運算單元陣列。陣列為選用項目,如未指定,所有運算單元都會遭到刪除。 -
傳回 boolean
如果版位已經刪除,則為true
,否則傳回false
。
googletag。disablePublisherConsole
-
disablePublisherConsole(): void
-
停用 Google 發布商控制台。
-
- 另請參閱
googletag。display
-
display(divOrSlot: string | Element | Slot): void
-
指示運算單元服務轉譯運算單元。每個廣告版位在每個網頁上只能顯示一次。所有版位都必須定義完畢,並與某個服務建立關聯,才能顯示出來。要等到元素出現在 DOM 時,才能發出顯示呼叫。常見的做法是將指令碼放在方法呼叫中命名的 div 元素指令碼區塊中。
如果使用了單一請求架構 (SRA),系統會一次呼叫此方法的所有未擷取廣告版位。如要強制廣告版位不顯示,您必須移除整個 div。 -
- 範例
-
JavaScript
googletag.cmd.push(() => { googletag.display("div-1"); });
JavaScript (舊版)
googletag.cmd.push(function () { googletag.display("div-1"); });
TypeScript
googletag.cmd.push(() => { googletag.display("div-1"); });
- 另請參閱
-
參數 divOrSlot: string | Element | Slot
可能是包含廣告版位的 div 元素 ID 或 div 元素,也可以是版位物件。如果提供 div 元素,則其「id」屬性必須與傳入defineSlot
的 ID 相符。
googletag。enableServices
-
enableServices(): void
-
啟用網頁中廣告版位已定義的所有 GPT 服務。
-
googletag。getVersion
-
getVersion(): string
-
傳回最新版 GPT。
-
- 另請參閱
-
傳回 string
目前執行中的 GPT 版本字串。
googletag。openConsole
-
openConsole(div?: string): void
-
開啟 Google 發布商控制台。
-
- 範例
-
JavaScript
// Calling with div ID. googletag.openConsole("div-1"); // Calling without div ID. googletag.openConsole();
JavaScript (舊版)
// Calling with div ID. googletag.openConsole("div-1"); // Calling without div ID. googletag.openConsole();
TypeScript
// Calling with div ID. googletag.openConsole("div-1"); // Calling without div ID. googletag.openConsole();
- 另請參閱
-
參數 div?: string
廣告版位 div ID。此為選填值。提供這個參數時,發布商控制台會嘗試開啟畫面,並顯示指定廣告版位的詳細資料。
googletag。pubads
-
pubads(): PubAdsService
-
傳回
PubAdsService
的參照。 -
-
傳回 PubAdsService
Publisher Ads 服務。
googletag。setAdIframeTitle
-
setAdIframeTitle(title: string): void
-
設定此後所有由
PubAdsService
建立的廣告容器 iframe 的標題。 -
- 範例
-
JavaScript
googletag.setAdIframeTitle("title");
JavaScript (舊版)
googletag.setAdIframeTitle("title");
TypeScript
googletag.setAdIframeTitle("title");
-
參數 title: string
所有廣告容器 iframe 的新標題。
googletag。setConfig
-
setConfig(config: PageSettingsConfig): void
-
設定頁面的一般設定選項。
-
-
參數 config: PageSettingsConfig
googletag。sizeMapping
-
sizeMapping(): SizeMappingBuilder
-
建立新的
SizeMappingBuilder
。 -
- 另請參閱
-
傳回 SizeMappingBuilder
新版建構工具。
googletag。CommandArray
指令陣列會接受一系列的函式並依序叫用。此做法旨在取代標準陣列,用來將載入 GPT 後叫用的函式排入佇列。
方法摘要 | |
---|---|
push
|
系統會依序執行引數中指定的函式序列。
|
push
-
push(...f: Array<(this: typeof globalThis) => void>): number
-
系統會依序執行引數中指定的函式序列。
-
- 範例
-
JavaScript
googletag.cmd.push(() => { googletag.defineSlot("/1234567/sports", [160, 600]).addService(googletag.pubads()); });
JavaScript (舊版)
googletag.cmd.push(function () { googletag.defineSlot("/1234567/sports", [160, 600]).addService(googletag.pubads()); });
TypeScript
googletag.cmd.push(() => { googletag.defineSlot("/1234567/sports", [160, 600])!.addService(googletag.pubads()); });
-
參數 ...f: Array<(this: typeof globalThis) => void>
將要執行的 JavaScript 函式。執行階段繫結一律為globalThis
。請考慮傳遞箭頭函式,保留所含詞典內容的this
值。 -
傳回 number
目前已處理的指令數量。這與Array.push
的傳回值 (陣列目前的長度) 相容。
googletag。CompanionAdsService
擴充
隨播廣告服務。影片廣告會使用這項服務顯示隨播廣告。
方法摘要 | |
---|---|
addEventListener
|
註冊事件監聽器,以便在網頁上發生特定 GPT 事件時,設定及呼叫 JavaScript 函式。
沿用自「
|
getSlots
|
取得與這項服務相關聯的運算單元清單。
沿用自「
|
removeEventListener
|
移除先前註冊的事件監聽器。
沿用自「
|
setRefreshUnfilledSlots
|
設定是否會自動補充未填入的隨播廣告版位。
|
- 另請參閱
setRefreshUnfilledSlots
-
setRefreshUnfilledSlots(value: boolean): void
-
設定是否要自動補充尚未填入廣告的隨播廣告。
您可以在頁面生命週期內多次呼叫這個方法,藉此開啟或關閉候補廣告。系統只會補充透過PubAdsService
註冊的版位。基於政策規定,放送 Ad Exchange 影片廣告時,此方法無法填滿空白的隨播廣告版位。 -
- 範例
-
JavaScript
googletag.companionAds().setRefreshUnfilledSlots(true);
JavaScript (舊版)
googletag.companionAds().setRefreshUnfilledSlots(true);
TypeScript
googletag.companionAds().setRefreshUnfilledSlots(true);
-
參數 value: boolean
true
會自動補充未填入的版位,false
則可保持不變。
googletag。PrivacySettingsConfig
隱私權設定的設定物件。
資源摘要 | |
---|---|
childDirectedTreatment
|
指出網頁是否應視為兒童導向內容。
|
limitedAds
|
允許在受限制的廣告模式下放送,以因應發布商的法規遵循需求。
|
nonPersonalizedAds
|
允許在非個人化廣告模式下放送,以協助遵循發布商的法規遵循需求。
|
restrictDataProcessing
|
允許廣告放送功能以受限處理模式執行,以便因應發布商的法規遵循需求。
|
trafficSource
|
表示要求代表付費流量或自然流量。
|
underAgeOfConsent
|
指出廣告請求是否來自未滿規定年齡的使用者。
|
- 另請參閱
childDirectedTreatment
-
childDirectedTreatment: null | boolean
-
指出網頁是否應視為兒童導向內容。如要清除設定,請設為
null
。 -
limitedAds
-
limitedAds: boolean
-
- 另請參閱
nonPersonalizedAds
-
nonPersonalizedAds: boolean
-
允許在非個人化廣告模式下放送,以協助發布商遵循發布商法規。
-
restrictDataProcessing
-
restrictDataProcessing: boolean
-
允許廣告放送在受限處理模式下執行,以便因應發布商的法規遵循需求。
-
trafficSource
-
trafficSource: TrafficSource
-
- 範例
-
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, });
underAgeOfConsent
-
underAgeOfConsent: null | boolean
-
表示是否將廣告請求標為來自未滿規定年齡的使用者。如要清除設定,請設為
null
。 -
googletag。PubAdsService
擴充
Publisher Ads 服務。這項服務是用來擷取及顯示 Google Ad Manager 帳戶中的廣告。
方法摘要 | |
---|---|
addEventListener
|
註冊事件監聽器,以便在網頁上發生特定 GPT 事件時,設定及呼叫 JavaScript 函式。
沿用自「
|
clear
|
從指定的版位移除廣告,並以空白內容取代。
|
clearCategoryExclusions
|
清除所有網頁層級廣告類別排除標籤。
|
clearTargeting
|
清除特定鍵或所有鍵的自訂指定參數。
|
collapseEmptyDivs
|
啟用收合版位 div,避免在沒有可顯示的廣告內容時佔用網頁上任何空間。
|
disableInitialLoad
|
停用在網頁載入時請求廣告,但允許透過
PubAdsService.refresh 呼叫請求廣告。 |
display
|
使用指定廣告單元路徑和大小建構及顯示廣告版位。
|
enableLazyLoad
|
按照設定物件所定義的 GPT 啟用延遲載入功能。
|
enableSingleRequest
|
啟用單一要求模式即可同時擷取多個廣告。
|
enableVideoAds
|
告知 GPT 這個網頁上將會顯示影片廣告。
|
get
|
傳回與指定鍵相關聯的 AdSense 屬性值。
|
getAttributeKeys
|
傳回已在這項服務上設定的屬性鍵。
|
getSlots
|
取得與這項服務相關聯的運算單元清單。
沿用自「
|
getTargeting
|
傳回已設定的特定自訂服務層級指定目標參數。
|
getTargetingKeys
|
傳回已設定的所有自訂服務層級指定鍵清單。
|
isInitialLoadDisabled
|
傳回前一個
PubAdsService.disableInitialLoad 呼叫是否成功停用廣告的初始請求。 |
refresh
|
擷取並顯示網頁上特定或所有版位的新廣告。
|
removeEventListener
|
移除先前註冊的事件監聽器。
沿用自「
|
set
|
設定 AdSense 屬性的值,該屬性值適用於發布商廣告服務下所有廣告版位。
|
setCategoryExclusion
|
針對特定標籤名稱設定網頁層級排除廣告類別。
|
setCentering
|
啟用及停用廣告水平中心。
|
setForceSafeFrame
|
設定是否應使用 SafeFrame 容器顯示網頁上的所有廣告。
|
setLocation
|
傳送網站的位置資訊,方便您將委刊項指定到特定位置。
|
setPrivacySettings
|
可使用設定物件,透過單一 API 設定所有隱私權設定。
|
setPublisherProvidedId
|
設定發布商提供的 ID 值。
|
setSafeFrameConfig
|
設定 SafeFrame 設定的網頁層級偏好設定。
|
setTargeting
|
設定特定鍵的自訂指定參數,並套用至所有發布商廣告服務廣告版位。
|
setVideoContent
|
設定要與廣告請求一起傳送的影片內容資訊,做為指定目標和排除內容的依據。
|
updateCorrelator
|
變更與廣告請求一併傳送的 correlator,可有效開啟新的網頁瀏覽。
|
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();
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();
-
參數 slots?: Slot[]
要清除的版位陣列。陣列為選用項目,如未指定,所有運算單元都會遭到清除。 -
傳回 boolean
如果已清除版位,則傳回true
,否則傳回false
。
clearCategoryExclusions
-
clearCategoryExclusions(): PubAdsService
-
清除所有網頁層級廣告類別排除標籤。如果您想重新整理廣告版位,這個方法就能派上用場。
-
- 範例
-
JavaScript
// Set category exclusion to exclude ads with 'AirlineAd' labels. googletag.pubads().setCategoryExclusion("AirlineAd"); // Make ad requests. No ad with 'AirlineAd' label will be returned. // Clear category exclusions so all ads can be returned. googletag.pubads().clearCategoryExclusions(); // Make ad requests. Any ad can be returned.
JavaScript (舊版)
// Set category exclusion to exclude ads with 'AirlineAd' labels. googletag.pubads().setCategoryExclusion("AirlineAd"); // Make ad requests. No ad with 'AirlineAd' label will be returned. // Clear category exclusions so all ads can be returned. googletag.pubads().clearCategoryExclusions(); // Make ad requests. Any ad can be returned.
TypeScript
// Set category exclusion to exclude ads with 'AirlineAd' labels. googletag.pubads().setCategoryExclusion("AirlineAd"); // Make ad requests. No ad with 'AirlineAd' label will be returned. // Clear category exclusions so all ads can be returned. googletag.pubads().clearCategoryExclusions(); // Make ad requests. Any ad can be returned.
- 另請參閱
-
傳回 PubAdsService
呼叫方法的服務物件。
clearTargeting
-
clearTargeting(key?: string): PubAdsService
-
清除特定鍵或所有鍵的自訂指定參數。
-
- 範例
-
JavaScript
googletag.pubads().setTargeting("interests", "sports"); googletag.pubads().setTargeting("colors", "blue"); googletag.pubads().setTargeting("fruits", "apple"); googletag.pubads().clearTargeting("interests"); // Targeting 'colors' and 'fruits' are still present, while 'interests' // was cleared. googletag.pubads().clearTargeting(); // All targeting has been cleared.
JavaScript (舊版)
googletag.pubads().setTargeting("interests", "sports"); googletag.pubads().setTargeting("colors", "blue"); googletag.pubads().setTargeting("fruits", "apple"); googletag.pubads().clearTargeting("interests"); // Targeting 'colors' and 'fruits' are still present, while 'interests' // was cleared. googletag.pubads().clearTargeting(); // All targeting has been cleared.
TypeScript
googletag.pubads().setTargeting("interests", "sports"); googletag.pubads().setTargeting("colors", "blue"); googletag.pubads().setTargeting("fruits", "apple"); googletag.pubads().clearTargeting("interests"); // Targeting 'colors' and 'fruits' are still present, while 'interests' // was cleared. googletag.pubads().clearTargeting(); // All targeting has been cleared.
- 另請參閱
-
參數 key?: string
指定參數鍵。該鍵為選用項目,如未指定,系統會將所有指定參數清除。 -
傳回 PubAdsService
呼叫方法的服務物件。
collapseEmptyDivs
-
collapseEmptyDivs(collapseBeforeAdFetch?: boolean): boolean
-
啟用版位 div 的收合功能,以免在沒有可顯示的廣告內容時,佔用網頁上的任何空間。這個模式必須在服務啟用前設定。
-
- 另請參閱
-
參數 collapseBeforeAdFetch?: boolean
是否要在擷取廣告前收合版位。這個參數為選用項目;如未提供,系統會使用false
做為預設值。 -
傳回 boolean
如果 div 收合模式已啟用,會傳回true
;如果在服務啟用後呼叫此方法,因此無法啟用收合模式,則傳回false
。
disableInitialLoad
-
disableInitialLoad(): void
-
停用在網頁載入時請求廣告,但允許透過
PubAdsService.refresh
呼叫請求廣告。啟用服務之前,請先完成這項設定。必須使用非同步模式,否則無法透過refresh
請求廣告。 -
- 另請參閱
display
-
display(adUnitPath: string, size: GeneralSize, div?: string | Element, clickUrl?: string): void
-
使用指定廣告單元路徑和大小建構及顯示廣告版位。這個方法不適用於單一請求模式。
注意:呼叫此方法時,系統會建立版位和網頁狀態的快照,以確保在傳送廣告請求及顯示回應時保持一致。在呼叫此方法後,對版位或網頁狀態所做的任何變更 (包括指定目標、隱私權設定、強制使用 SafeFrame 等) 都只會套用至後續的display()
或refresh()
要求。 -
- 範例
-
JavaScript
googletag.pubads().display("/1234567/sports", [728, 90], "div-1");
JavaScript (舊版)
googletag.pubads().display("/1234567/sports", [728, 90], "div-1");
TypeScript
googletag.pubads().display("/1234567/sports", [728, 90], "div-1");
- 另請參閱
-
參數 adUnitPath: string
要顯示的版位廣告單元路徑。size: GeneralSize
版位的寬度和高度。div?: string | Element
可以是包含版位的 div ID 或 div 元素本身。clickUrl?: string
用於這個版位的點擊網址。
enableLazyLoad
-
enableLazyLoad(config?: { fetchMarginPercent: number, mobileScaling: number, renderMarginPercent: number }): void
-
按照設定物件所定義的 GPT 啟用延遲載入功能。如需更詳細的範例,請參閱「延遲載入」範例。
注意:只有所有版位都在擷取邊界外時,SRA 中的 Lazy 擷取功能才能正常運作。 -
- 範例
-
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, });
- 另請參閱
-
參數 config?: { fetchMarginPercent: number, mobileScaling: number, renderMarginPercent: number }
設定物件可自訂延遲行為。省略的任何設定都會使用 Google 預設的設定,並且會隨時間經過調整。如要停用特定設定 (例如擷取邊界),請將值設為-1
。fetchMarginPercent
與目前可視區域的最短距離如果值為 0,表示「版位進入可視區域時」,100 表示「廣告距離 1 個可視區域時」,以此類推。renderMarginPercent
與目前可視區域的最短距離這可讓您預先擷取廣告,但等候轉譯並下載其他子資源。這個值的運作方式與fetchMarginPercent
一樣,都是在可視區域中所佔百分比。mobileScaling
套用到行動裝置邊界的調節係數。這允許行動裝置和電腦以不同的利潤幅度。舉例來說,如果值為 2.0,行動裝置上的所有邊界乘以 2,在擷取和算繪前,運算單元可設定的最小距離越小。
enableSingleRequest
-
enableSingleRequest(): boolean
-
啟用單一要求模式即可同時擷取多個廣告。如要使用此功能,您必須先定義所有發布商廣告版位並新增至 PubAdsService,才能啟用服務。啟用服務前,您必須先設定單一要求模式。
-
傳回 boolean
如果已啟用單一要求模式,則傳回true
;如果在服務啟用後呼叫該方法,導致無法啟用單一要求模式,則會傳回false
。
enableVideoAds
-
enableVideoAds(): void
-
告知 GPT 這個網頁上將會顯示影片廣告。藉此設定多媒體廣告和影片廣告的競爭排除限制。如果已知有影片內容,則呼叫
PubAdsService.setVideoContent
即可針對多媒體廣告使用內容排除功能。 -
get
-
get(key: string): null | string
-
傳回與指定鍵相關聯的 AdSense 屬性值。
-
- 範例
-
JavaScript
googletag.pubads().set("adsense_background_color", "#FFFFFF"); googletag.pubads().get("adsense_background_color"); // Returns '#FFFFFF'.
JavaScript (舊版)
googletag.pubads().set("adsense_background_color", "#FFFFFF"); googletag.pubads().get("adsense_background_color"); // Returns '#FFFFFF'.
TypeScript
googletag.pubads().set("adsense_background_color", "#FFFFFF"); googletag.pubads().get("adsense_background_color"); // Returns '#FFFFFF'.
- 另請參閱
-
參數 key: string
要尋找的屬性名稱。 -
傳回 null | string
屬性鍵目前的值;如果鍵不存在,則為null
。
getAttributeKeys
-
getAttributeKeys(): string[]
-
傳回已在這項服務上設定的屬性鍵。
-
- 範例
-
JavaScript
googletag.pubads().set("adsense_background_color", "#FFFFFF"); googletag.pubads().set("adsense_border_color", "#AABBCC"); googletag.pubads().getAttributeKeys(); // Returns ['adsense_background_color', 'adsense_border_color'].
JavaScript (舊版)
googletag.pubads().set("adsense_background_color", "#FFFFFF"); googletag.pubads().set("adsense_border_color", "#AABBCC"); googletag.pubads().getAttributeKeys(); // Returns ['adsense_background_color', 'adsense_border_color'].
TypeScript
googletag.pubads().set("adsense_background_color", "#FFFFFF"); googletag.pubads().set("adsense_border_color", "#AABBCC"); googletag.pubads().getAttributeKeys(); // Returns ['adsense_background_color', 'adsense_border_color'].
-
傳回 string[]
在此服務中設定的屬性鍵陣列。未定義順序。
getTargeting
-
getTargeting(key: string): string[]
-
傳回已設定的特定自訂服務層級指定目標參數。
-
- 範例
-
JavaScript
googletag.pubads().setTargeting("interests", "sports"); googletag.pubads().getTargeting("interests"); // Returns ['sports']. googletag.pubads().getTargeting("age"); // Returns [] (empty array).
JavaScript (舊版)
googletag.pubads().setTargeting("interests", "sports"); googletag.pubads().getTargeting("interests"); // Returns ['sports']. googletag.pubads().getTargeting("age"); // Returns [] (empty array).
TypeScript
googletag.pubads().setTargeting("interests", "sports"); googletag.pubads().getTargeting("interests"); // Returns ['sports']. googletag.pubads().getTargeting("age"); // Returns [] (empty array).
-
參數 key: string
要尋找的指定鍵。 -
傳回 string[]
與這個鍵相關聯的值,如果沒有此類鍵,則為空白陣列。
getTargetingKeys
-
getTargetingKeys(): string[]
-
傳回已設定的所有自訂服務層級指定鍵清單。
-
- 範例
-
JavaScript
googletag.pubads().setTargeting("interests", "sports"); googletag.pubads().setTargeting("colors", "blue"); googletag.pubads().getTargetingKeys(); // Returns ['interests', 'colors'].
JavaScript (舊版)
googletag.pubads().setTargeting("interests", "sports"); googletag.pubads().setTargeting("colors", "blue"); googletag.pubads().getTargetingKeys(); // Returns ['interests', 'colors'].
TypeScript
googletag.pubads().setTargeting("interests", "sports"); googletag.pubads().setTargeting("colors", "blue"); googletag.pubads().getTargetingKeys(); // Returns ['interests', 'colors'].
-
傳回 string[]
指定鍵的陣列。未定義順序。
isInitialLoadDisabled
-
isInitialLoadDisabled(): boolean
-
傳回前一次
PubAdsService.disableInitialLoad
呼叫是否成功停用廣告的初始請求。 -
-
傳回 boolean
refresh
-
refresh(slots?: null | 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 });
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 });
- 另請參閱
-
參數 slots?: null | Slot[]
要重新整理的版位。陣列為選用項目,如未指定,系統會重新整理所有運算單元。options?: { changeCorrelator: boolean }
與此重新整理呼叫相關聯的設定選項。changeCorrelator
指定是否要為擷取廣告產生新的 Correlator。我們的廣告伺服器會暫時保留這個 correlator 值 (目前為 30 秒,但隨時可能變更),因此如果非常接近一次收到使用相同 correlator 的請求,系統會將其視為一次網頁瀏覽。根據預設,每次重新整理都會產生新的 Correlator。
注意:這個選項不會影響 GPT 的長效網頁瀏覽機制,該頁面會自動反映網頁上目前的廣告,且沒有到期時間。
set
-
set(key: string, value: string): PubAdsService
-
設定 AdSense 屬性的值,該屬性值會套用到發布商廣告服務下所有廣告版位。
如果為同一個鍵重複呼叫這個方法,該鍵先前設定的值將會覆寫先前設定的值。請務必先設定所有值,再呼叫display
或refresh
。 -
- 範例
-
JavaScript
googletag.pubads().set("adsense_background_color", "#FFFFFF");
JavaScript (舊版)
googletag.pubads().set("adsense_background_color", "#FFFFFF");
TypeScript
googletag.pubads().set("adsense_background_color", "#FFFFFF");
- 另請參閱
-
參數 key: string
屬性的名稱。value: string
屬性值。 -
傳回 PubAdsService
呼叫方法的服務物件。
setCategoryExclusion
-
setCategoryExclusion(categoryExclusion: string): PubAdsService
-
針對特定標籤名稱設定網頁層級排除廣告類別。
-
- 範例
-
JavaScript
// Label = AirlineAd. googletag.pubads().setCategoryExclusion("AirlineAd");
JavaScript (舊版)
// Label = AirlineAd. googletag.pubads().setCategoryExclusion("AirlineAd");
TypeScript
// Label = AirlineAd. googletag.pubads().setCategoryExclusion("AirlineAd");
- 另請參閱
-
參數 categoryExclusion: string
要新增的廣告類別排除標籤。 -
傳回 PubAdsService
呼叫方法的服務物件。
setCentering
-
setCentering(centerAds: boolean): void
-
啟用及停用廣告水平中心。中心預設為停用。在舊版 gpt_mobile.js 中,置中預設會啟用。
由於只有在呼叫此方法後要求的廣告才會置中,才能在呼叫display
或refresh
前叫用這個方法。 -
- 範例
-
JavaScript
// Make ads centered. googletag.pubads().setCentering(true);
JavaScript (舊版)
// Make ads centered. googletag.pubads().setCentering(true);
TypeScript
// Make ads centered. googletag.pubads().setCentering(true);
-
參數 centerAds: boolean
true
:將廣告置中對齊,false
即可靠左對齊。
setForceSafeFrame
-
setForceSafeFrame(forceSafeFrame: boolean): PubAdsService
-
設定是否強制要求網頁上的所有廣告使用 SafeFrame 容器顯示。
使用此 API 時,請注意下列事項:- 只有針對個別版位送出的「後續」廣告請求,這項設定才會生效。
- 版位層級設定 (如有指定) 一律會覆寫網頁層級設定。
- 如果設為
true
(版位層級或網頁層級),則無論您在 Google Ad Manager 使用者介面中的選擇為何,系統一律會使用 SafeFrame 容器顯示廣告。 - 但是,如果設為
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");
- 另請參閱
-
參數 forceSafeFrame: boolean
true
可強制網頁上的所有廣告在 SafeFrame 中顯示,而false
則會將先前的設定變更為 false。如果先前未指定,則設為false
不會有任何變更。 -
傳回 PubAdsService
呼叫函式的服務物件。
setLocation
-
setLocation(address: string): PubAdsService
-
傳送網站的位置資訊,方便您將委刊項指定到特定位置。
-
- 範例
-
JavaScript
// Postal code: googletag.pubads().setLocation("10001,US");
JavaScript (舊版)
// Postal code: googletag.pubads().setLocation("10001,US");
TypeScript
// Postal code: googletag.pubads().setLocation("10001,US");
-
參數 address: string
任意形式的地址。 -
傳回 PubAdsService
呼叫方法的服務物件。
setPrivacySettings
-
setPrivacySettings(privacySettings: PrivacySettingsConfig): PubAdsService
-
允許使用設定物件,從單一 API 中設定所有隱私權設定。
-
- 範例
-
JavaScript
googletag.pubads().setPrivacySettings({ restrictDataProcessing: true, }); // Set multiple privacy settings at the same time. googletag.pubads().setPrivacySettings({ childDirectedTreatment: true, underAgeOfConsent: true, }); // Clear the configuration for childDirectedTreatment. googletag.pubads().setPrivacySettings({ childDirectedTreatment: null, });
JavaScript (舊版)
googletag.pubads().setPrivacySettings({ restrictDataProcessing: true, }); // Set multiple privacy settings at the same time. googletag.pubads().setPrivacySettings({ childDirectedTreatment: true, underAgeOfConsent: true, }); // Clear the configuration for childDirectedTreatment. googletag.pubads().setPrivacySettings({ childDirectedTreatment: null, });
TypeScript
googletag.pubads().setPrivacySettings({ restrictDataProcessing: true, }); // Set multiple privacy settings at the same time. googletag.pubads().setPrivacySettings({ childDirectedTreatment: true, underAgeOfConsent: true, }); // Clear the configuration for childDirectedTreatment. googletag.pubads().setPrivacySettings({ childDirectedTreatment: null, });
- 另請參閱
-
參數 privacySettings: PrivacySettingsConfig
包含隱私權設定的物件。 -
傳回 PubAdsService
呼叫函式的服務物件。
setPublisherProvidedId
-
setPublisherProvidedId(ppid: string): PubAdsService
-
為發布商提供的 ID 設定值。
-
- 範例
-
JavaScript
googletag.pubads().setPublisherProvidedId("12JD92JD8078S8J29SDOAKC0EF230337");
JavaScript (舊版)
googletag.pubads().setPublisherProvidedId("12JD92JD8078S8J29SDOAKC0EF230337");
TypeScript
googletag.pubads().setPublisherProvidedId("12JD92JD8078S8J29SDOAKC0EF230337");
- 另請參閱
-
參數 ppid: string
發布商提供的英數字元 ID。長度必須介於 32 至 150 個半形字元之間。 -
傳回 PubAdsService
呼叫方法的服務物件。
setSafeFrameConfig
-
setSafeFrameConfig(config: SafeFrameConfig): PubAdsService
-
設定 SafeFrame 設定的網頁層級偏好設定。系統會忽略設定物件中所有無法識別的鍵。如果為可識別的鍵傳遞無效值,系統會忽略整個設定。
如果指定的話,版位層級偏好設定將覆寫這些網頁層級的偏好設定。 -
- 範例
-
JavaScript
googletag.pubads().setForceSafeFrame(true); const pageConfig = { allowOverlayExpansion: true, allowPushExpansion: true, sandbox: true, }; const slotConfig = { allowOverlayExpansion: false }; googletag.pubads().setSafeFrameConfig(pageConfig); // The following slot will not allow for expansion by overlay. googletag .defineSlot("/1234567/sports", [160, 600], "div-1") .setSafeFrameConfig(slotConfig) .addService(googletag.pubads()); // The following slot will inherit the page level settings, and hence // would allow for expansion by overlay. googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads()); googletag.display("div-1"); googletag.display("div-2");
JavaScript (舊版)
googletag.pubads().setForceSafeFrame(true); var pageConfig = { allowOverlayExpansion: true, allowPushExpansion: true, sandbox: true, }; var slotConfig = { allowOverlayExpansion: false }; googletag.pubads().setSafeFrameConfig(pageConfig); // The following slot will not allow for expansion by overlay. googletag .defineSlot("/1234567/sports", [160, 600], "div-1") .setSafeFrameConfig(slotConfig) .addService(googletag.pubads()); // The following slot will inherit the page level settings, and hence // would allow for expansion by overlay. googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads()); googletag.display("div-1"); googletag.display("div-2");
TypeScript
googletag.pubads().setForceSafeFrame(true); const pageConfig = { allowOverlayExpansion: true, allowPushExpansion: true, sandbox: true, }; const slotConfig = { allowOverlayExpansion: false }; googletag.pubads().setSafeFrameConfig(pageConfig); // The following slot will not allow for expansion by overlay. googletag .defineSlot("/1234567/sports", [160, 600], "div-1")! .setSafeFrameConfig(slotConfig) .addService(googletag.pubads()); // The following slot will inherit the page level settings, and hence // would allow for expansion by overlay. googletag.defineSlot("/1234567/news", [160, 600], "div-2")!.addService(googletag.pubads()); googletag.display("div-1"); googletag.display("div-2");
- 另請參閱
-
參數 config: SafeFrameConfig
設定物件。 -
傳回 PubAdsService
呼叫方法的服務物件。
setTargeting
-
setTargeting(key: string, value: string | string[]): PubAdsService
-
設定特定鍵的自訂指定參數,並套用至所有發布商廣告服務廣告版位。如果為同一個鍵多次呼叫這個方法,系統就會覆寫舊的值。請在 Google Ad Manager 帳戶中定義這些鍵。
-
- 範例
-
JavaScript
// Example with a single value for a key. googletag.pubads().setTargeting("interests", "sports"); // Example with multiple values for a key inside in an array. googletag.pubads().setTargeting("interests", ["sports", "music"]);
JavaScript (舊版)
// Example with a single value for a key. googletag.pubads().setTargeting("interests", "sports"); // Example with multiple values for a key inside in an array. googletag.pubads().setTargeting("interests", ["sports", "music"]);
TypeScript
// Example with a single value for a key. googletag.pubads().setTargeting("interests", "sports"); // Example with multiple values for a key inside in an array. googletag.pubads().setTargeting("interests", ["sports", "music"]);
- 另請參閱
-
參數 key: string
指定參數鍵。value: string | string[]
指定參數值或值陣列。 -
傳回 PubAdsService
呼叫方法的服務物件。
setVideoContent
-
setVideoContent(videoContentId: string, videoCmsId: string): void
-
設定要與廣告請求一起傳送的影片內容資訊,做為指定目標和排除內容的依據。呼叫此方法後,影片廣告會自動啟用。如果是
videoContentId
和videoCmsId
,請使用與您提供給 Google Ad Manager 內容擷取服務的值。 -
- 另請參閱
-
參數 videoContentId: string
影片內容 ID。videoCmsId: string
影片 CMS ID。
updateCorrelator
-
updateCorrelator(): PubAdsService
-
變更隨廣告請求一併傳送的 correlator,可讓新網頁瀏覽生效。對於來自單一網頁瀏覽的所有廣告請求,以及在所有網頁檢視中不重複放送的廣告請求,Correlator 相同。僅適用於非同步模式。
注意:這不會影響 GPT 的長效網頁瀏覽機制,該頁面會自動反映廣告實際在網頁上的廣告,且沒有到期時間。 -
- 範例
-
JavaScript
// Assume that the correlator is currently 12345. All ad requests made // by this page will currently use that value. // Replace the current correlator with a new correlator. googletag.pubads().updateCorrelator(); // The correlator will now be a new randomly selected value, different // from 12345. All subsequent ad requests made by this page will use // the new value.
JavaScript (舊版)
// Assume that the correlator is currently 12345. All ad requests made // by this page will currently use that value. // Replace the current correlator with a new correlator. googletag.pubads().updateCorrelator(); // The correlator will now be a new randomly selected value, different // from 12345. All subsequent ad requests made by this page will use // the new value.
TypeScript
// Assume that the correlator is currently 12345. All ad requests made // by this page will currently use that value. // Replace the current correlator with a new correlator. googletag.pubads().updateCorrelator(); // The correlator will now be a new randomly selected value, different // from 12345. All subsequent ad requests made by this page will use // the new value.
-
傳回 PubAdsService
呼叫函式的服務物件。
googletag。ResponseInformation
代表單一廣告回應的物件。
資源摘要 | |
---|---|
advertiserId
|
廣告主的 ID。
|
campaignId
|
廣告活動的 ID。
|
creativeId
|
廣告素材的 ID。
|
creativeTemplateId
|
廣告的範本 ID。
|
lineItemId
|
委刊項的 ID。
|
advertiserId
-
advertiserId: null | number
-
廣告客戶的 ID。
-
campaignId
-
campaignId: null | number
-
廣告活動的 ID。
-
creativeId
-
creativeId: null | number
-
廣告素材的 ID。
-
creativeTemplateId
-
creativeTemplateId: null | number
-
廣告的範本 ID。
-
lineItemId
-
lineItemId: null | number
-
委刊項的 ID。
-
googletag。RewardedPayload
代表與獎勵廣告相關聯的獎勵的物件
資源摘要 | |
---|---|
amount
|
獎勵所包含的商品數量。
|
type
|
獎勵中所含的項目類型 (例如「錢幣」)。
|
- 另請參閱
amount
-
amount: number
-
獎勵隨附的商品數量。
-
type
-
type: string
-
獎勵中所含的項目類型 (例如「錢幣」)。
-
googletag。SafeFrameConfig
SafeFrame 容器的設定物件。
資源摘要 | |
---|---|
allowOverlayExpansion
|
是否允許 SafeFrame 透過重疊網頁內容的方式展開廣告素材。
|
allowPushExpansion
|
是否允許 SafeFrame 允許藉由推送網頁內容來展開廣告素材。
|
sandbox
|
指定 SafeFrame 是否應使用 HTML5 sandbox 屬性,以防止在沒有使用者互動的情況下發生頂層導覽。
|
useUniqueDomain
|
已淘汰。是否應針對預訂廣告素材使用隨機子網域。
|
allowOverlayExpansion
-
allowOverlayExpansion: boolean
-
是否允許 SafeFrame 透過重疊網頁內容的方式展開廣告素材。
-
allowPushExpansion
-
allowPushExpansion: boolean
-
是否允許 SafeFrame 以推送網頁內容的方式展開廣告素材。
-
sandbox
-
sandbox: boolean
-
指定 SafeFrame 是否應使用 HTML5 sandbox 屬性,以防止在沒有使用者互動的情況下發生頂層導覽。唯一的有效值是
true
(不得強制設為false
)。請注意,沙箱屬性會停用外掛程式 (例如 Flash)。 -
useUniqueDomain
-
useUniqueDomain: null | boolean
-
是否應針對預訂廣告素材使用隨機子網域。傳入
null
即可清除儲存的值。
注意:這項功能預設為啟用。 -
- 另請參閱
googletag。Service
基礎服務類別,其中包含所有服務通用的方法。
方法摘要 | |
---|---|
addEventListener
|
註冊事件監聽器,以便在網頁上發生特定 GPT 事件時,設定及呼叫 JavaScript 函式。
|
getSlots
|
取得與這項服務相關聯的運算單元清單。
|
removeEventListener
|
移除先前註冊的事件監聽器。
|
addEventListener
-
addEventListener<K extends keyof EventTypeMap>(eventType: K, listener: (arg: EventTypeMap[K]) => void): Service
-
註冊一個監聽器,這個接聽程式允許您在頁面上發生特定 GPT 事件時,設定及呼叫 JavaScript 函式。支援的事件如下:
系統會在呼叫時,將適當事件類型的物件傳遞到事件監聽器。 -
- 範例
-
JavaScript
// 1. Adding an event listener for the PubAdsService. googletag.pubads().addEventListener("slotOnload", (event) => { console.log("Slot has been loaded:"); console.log(event); }); // 2. Adding an event listener with slot specific logic. // Listeners operate at service level, which means that you cannot add // a listener for an event for a specific slot only. You can, however, // programmatically filter a listener to respond only to a certain ad // slot, using this pattern: const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotOnload", (event) => { if (event.slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// 1. Adding an event listener for the PubAdsService. googletag.pubads().addEventListener("slotOnload", function (event) { console.log("Slot has been loaded:"); console.log(event); }); // 2. Adding an event listener with slot specific logic. // Listeners operate at service level, which means that you cannot add // a listener for an event for a specific slot only. You can, however, // programmatically filter a listener to respond only to a certain ad // slot, using this pattern: var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotOnload", function (event) { if (event.slot === targetSlot) { // Slot specific logic. } });
TypeScript
// 1. Adding an event listener for the PubAdsService. googletag.pubads().addEventListener("slotOnload", (event) => { console.log("Slot has been loaded:"); console.log(event); }); // 2. Adding an event listener with slot specific logic. // Listeners operate at service level, which means that you cannot add // a listener for an event for a specific slot only. You can, however, // programmatically filter a listener to respond only to a certain ad // slot, using this pattern: const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotOnload", (event) => { if (event.slot === targetSlot) { // Slot specific logic. } });
- 另請參閱
-
參數 eventType: K
代表 GPT 產生事件類型的字串。事件類型須區分大小寫。listener: (arg: EventTypeMap[K]) => void
採用單一事件物件引數的函式。 -
傳回 Service
呼叫方法的服務物件。
getSlots
removeEventListener
-
removeEventListener<K extends keyof EventTypeMap>(eventType: K, listener: (event: EventTypeMap[K]) => void): void
-
移除先前註冊的事件監聽器。
-
- 範例
-
JavaScript
googletag.cmd.push(() => { // Define a new ad slot. googletag.defineSlot("/6355419/Travel", [728, 90], "div-for-slot").addService(googletag.pubads()); // Define a new function that removes itself via removeEventListener // after the impressionViewable event fires. const onViewableListener = (event) => { googletag.pubads().removeEventListener("impressionViewable", onViewableListener); setTimeout(() => { googletag.pubads().refresh([event.slot]); }, 30000); }; // Add onViewableListener as a listener for impressionViewable events. googletag.pubads().addEventListener("impressionViewable", onViewableListener); googletag.enableServices(); });
JavaScript (舊版)
googletag.cmd.push(function () { // Define a new ad slot. googletag.defineSlot("/6355419/Travel", [728, 90], "div-for-slot").addService(googletag.pubads()); // Define a new function that removes itself via removeEventListener // after the impressionViewable event fires. var onViewableListener = function (event) { googletag.pubads().removeEventListener("impressionViewable", onViewableListener); setTimeout(function () { googletag.pubads().refresh([event.slot]); }, 30000); }; // Add onViewableListener as a listener for impressionViewable events. googletag.pubads().addEventListener("impressionViewable", onViewableListener); googletag.enableServices(); });
TypeScript
googletag.cmd.push(() => { // Define a new ad slot. googletag .defineSlot("/6355419/Travel", [728, 90], "div-for-slot")! .addService(googletag.pubads()); // Define a new function that removes itself via removeEventListener // after the impressionViewable event fires. const onViewableListener = (event: googletag.events.ImpressionViewableEvent) => { googletag.pubads().removeEventListener("impressionViewable", onViewableListener); setTimeout(() => { googletag.pubads().refresh([event.slot]); }, 30000); }; // Add onViewableListener as a listener for impressionViewable events. googletag.pubads().addEventListener("impressionViewable", onViewableListener); googletag.enableServices(); });
-
參數 eventType: K
代表 GPT 產生事件類型的字串。事件類型須區分大小寫。listener: (event: EventTypeMap[K]) => void
採用單一事件物件引數的函式。
googletag。SizeMappingBuilder
大小對應規格物件的建構工具。此建構工具可協助您輕鬆建構尺寸規格。
方法摘要 | |
---|---|
addSize
|
將單一大小陣列 (代表可視區域) 的對應關係新增至代表該版位的單一或多重大小陣列。
|
build
|
根據新增到這個建構工具的對應,建構尺寸對應規格。
|
- 另請參閱
addSize
-
addSize(viewportSize: SingleSizeArray, slotSize: GeneralSize): SizeMappingBuilder
-
將單一大小陣列 (代表可視區域) 的對應新增至代表該版位的單一大小陣列或多重大小陣列。
-
- 範例
-
JavaScript
// Mapping 1 googletag .sizeMapping() .addSize([1024, 768], [970, 250]) .addSize([980, 690], [728, 90]) .addSize([640, 480], "fluid") .addSize([0, 0], [88, 31]) // All viewports < 640x480 .build(); // Mapping 2 googletag .sizeMapping() .addSize([1024, 768], [970, 250]) .addSize([980, 690], []) .addSize([640, 480], [120, 60]) .addSize([0, 0], []) .build(); // Mapping 2 will not show any ads for the following viewport sizes: // [1024, 768] > size >= [980, 690] and // [640, 480] > size >= [0, 0]
JavaScript (舊版)
// Mapping 1 googletag .sizeMapping() .addSize([1024, 768], [970, 250]) .addSize([980, 690], [728, 90]) .addSize([640, 480], "fluid") .addSize([0, 0], [88, 31]) // All viewports < 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
-
build(): null | SizeMappingArray
-
根據新增到這個建構工具的對應,建立尺寸對應規格。
如果提供了任何無效的對應,這個方法會傳回null
。否則,系統會傳回格式正確的規格,以便傳遞至Slot.defineSizeMapping
。
注意:建構工具在呼叫此方法後的行為並未定義。 -
-
傳回 null | SizeMappingArray
這個建構工具建構的結果。如果提供無效的大小對應,則可傳回空值。
googletag。Slot
版位是一種物件,代表網頁上的單一廣告版位。
方法摘要 | |
---|---|
addService
|
將
Service 新增至這個版位。
|
clearCategoryExclusions
|
清除這個版位的所有版位層級廣告類別排除標籤。
|
clearTargeting
|
清除這個版位的特定或所有自訂版位層級指定目標參數。
|
defineSizeMapping
|
針對這個版位設定對應的陣列陣列,範圍從最小可視區域大小到版位大小。
|
get
|
傳回與此版位的指定鍵相關聯的 AdSense 屬性值。
|
getAdUnitPath
|
傳回廣告單元的完整路徑,包含聯播網代碼和廣告單元路徑。
|
getAttributeKeys
|
傳回此版位設定的屬性鍵清單。
|
getCategoryExclusions
|
傳回這個版位的廣告類別排除標籤。
|
getResponseInformation
|
傳回廣告回應資訊。
|
getSlotElementId
|
傳回在定義版位時提供的版位
div ID。
|
getTargeting
|
傳回針對這個版位設定的特定自訂指定參數。
|
getTargetingKeys
|
傳回此版位設定的所有自訂指定鍵清單。
|
set
|
設定這個廣告版位的 AdSense 屬性值。
|
setCategoryExclusion
|
設定此版位的版位層級廣告類別排除標籤。
|
setClickUrl
|
設定點擊網址,使用者在按下廣告後會重新導向至哪個網址。
|
setCollapseEmptyDiv
|
設定版位
div 在版位沒有廣告時是否應隱藏。
|
setConfig
|
設定這個運算單元的一般設定選項。
|
setForceSafeFrame
|
設定是否應使用 SafeFrame 容器顯示這個版位中的廣告。
|
setSafeFrameConfig
|
設定 SafeFrame 設定的版位層級偏好設定。
|
setTargeting
|
設定這個版位的自訂指定參數。
|
updateTargetingFromMap
|
從 JSON 物件中的 key:value 對應,設定此版位的自訂指定參數。
|
addService
-
將
Service
新增至這個版位。 -
- 範例
-
JavaScript
googletag.defineSlot("/1234567/sports", [160, 600], "div").addService(googletag.pubads());
JavaScript (舊版)
googletag.defineSlot("/1234567/sports", [160, 600], "div").addService(googletag.pubads());
TypeScript
googletag.defineSlot("/1234567/sports", [160, 600], "div")!.addService(googletag.pubads());
- 另請參閱
-
參數 service: Service
要新增的服務。 -
傳回 Slot
呼叫方法的版位物件。
clearCategoryExclusions
-
clearCategoryExclusions(): Slot
-
清除此版位的所有版位層級廣告類別排除標籤。
-
- 範例
-
JavaScript
// Set category exclusion to exclude ads with 'AirlineAd' labels. const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setCategoryExclusion("AirlineAd") .addService(googletag.pubads()); // Make an ad request. No ad with 'AirlineAd' label will be returned // for the slot. // Clear category exclusions so all ads can be returned. slot.clearCategoryExclusions(); // Make an ad request. Any ad can be returned for the slot.
JavaScript (舊版)
// Set category exclusion to exclude ads with 'AirlineAd' labels. var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setCategoryExclusion("AirlineAd") .addService(googletag.pubads()); // Make an ad request. No ad with 'AirlineAd' label will be returned // for the slot. // Clear category exclusions so all ads can be returned. slot.clearCategoryExclusions(); // Make an ad request. Any ad can be returned for the slot.
TypeScript
// Set category exclusion to exclude ads with 'AirlineAd' labels. const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .setCategoryExclusion("AirlineAd") .addService(googletag.pubads()); // Make an ad request. No ad with 'AirlineAd' label will be returned // for the slot. // Clear category exclusions so all ads can be returned. slot.clearCategoryExclusions(); // Make an ad request. Any ad can be returned for the slot.
-
傳回 Slot
呼叫方法的版位物件。
clearTargeting
-
clearTargeting(key?: string): Slot
-
清除這個版位的特定或所有自訂版位層級指定目標參數。
-
- 範例
-
JavaScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setTargeting("allow_expandable", "true") .setTargeting("interests", ["sports", "music"]) .setTargeting("color", "red") .addService(googletag.pubads()); slot.clearTargeting("color"); // Targeting 'allow_expandable' and 'interests' are still present, // while 'color' was cleared. slot.clearTargeting(); // All targeting has been cleared.
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setTargeting("allow_expandable", "true") .setTargeting("interests", ["sports", "music"]) .setTargeting("color", "red") .addService(googletag.pubads()); slot.clearTargeting("color"); // Targeting 'allow_expandable' and 'interests' are still present, // while 'color' was cleared. slot.clearTargeting(); // All targeting has been cleared.
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .setTargeting("allow_expandable", "true") .setTargeting("interests", ["sports", "music"]) .setTargeting("color", "red") .addService(googletag.pubads()); slot.clearTargeting("color"); // Targeting 'allow_expandable' and 'interests' are still present, // while 'color' was cleared. slot.clearTargeting(); // All targeting has been cleared.
- 另請參閱
-
參數 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);
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .addService(googletag.pubads()); var mapping = googletag .sizeMapping() .addSize([100, 100], [88, 31]) .addSize( [320, 400], [ [320, 50], [300, 50], ] ) .build(); slot.defineSizeMapping(mapping);
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .addService(googletag.pubads()); const mapping = googletag .sizeMapping() .addSize([100, 100], [88, 31]) .addSize( [320, 400], [ [320, 50], [300, 50], ] ) .build(); slot.defineSizeMapping(mapping!);
- 另請參閱
-
參數 sizeMapping: SizeMappingArray
-
傳回 Slot
呼叫方法的版位物件。
get
-
get(key: string): null | string
-
傳回與此版位的指定鍵相關聯的 AdSense 屬性值。如要查看這個運算單元沿用的服務層級屬性,請使用
PubAdsService.get
。 -
- 範例
-
JavaScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .set("adsense_background_color", "#FFFFFF") .addService(googletag.pubads()); slot.get("adsense_background_color"); // Returns '#FFFFFF'.
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .set("adsense_background_color", "#FFFFFF") .addService(googletag.pubads()); slot.get("adsense_background_color"); // Returns '#FFFFFF'.
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .set("adsense_background_color", "#FFFFFF") .addService(googletag.pubads()); slot.get("adsense_background_color"); // Returns '#FFFFFF'.
- 另請參閱
-
參數 key: string
要尋找的屬性名稱。 -
傳回 null | string
屬性鍵目前的值;如果鍵不存在,則為null
。
getAdUnitPath
-
getAdUnitPath(): string
-
傳回廣告單元的完整路徑,包含聯播網代碼和廣告單元路徑。
-
- 範例
-
JavaScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .addService(googletag.pubads()); slot.getAdUnitPath(); // Returns '/1234567/sports'.
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .addService(googletag.pubads()); slot.getAdUnitPath(); // Returns '/1234567/sports'.
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .addService(googletag.pubads()); slot.getAdUnitPath(); // Returns '/1234567/sports'.
-
傳回 string
廣告單元路徑。
getAttributeKeys
-
getAttributeKeys(): string[]
-
傳回這個版位設定的屬性鍵清單。如要查看這個運算單元繼承的服務層級屬性金鑰,請使用
PubAdsService.getAttributeKeys
。 -
- 範例
-
JavaScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .set("adsense_background_color", "#FFFFFF") .set("adsense_border_color", "#AABBCC") .addService(googletag.pubads()); slot.getAttributeKeys(); // Returns ['adsense_background_color', 'adsense_border_color'].
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .set("adsense_background_color", "#FFFFFF") .set("adsense_border_color", "#AABBCC") .addService(googletag.pubads()); slot.getAttributeKeys(); // Returns ['adsense_background_color', 'adsense_border_color'].
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .set("adsense_background_color", "#FFFFFF") .set("adsense_border_color", "#AABBCC") .addService(googletag.pubads()); slot.getAttributeKeys(); // Returns ['adsense_background_color', 'adsense_border_color'].
-
傳回 string[]
屬性鍵的陣列。未定義順序。
getCategoryExclusions
-
getCategoryExclusions(): string[]
-
傳回這個版位的廣告類別排除標籤。
-
- 範例
-
JavaScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setCategoryExclusion("AirlineAd") .setCategoryExclusion("TrainAd") .addService(googletag.pubads()); slot.getCategoryExclusions(); // Returns ['AirlineAd', 'TrainAd'].
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setCategoryExclusion("AirlineAd") .setCategoryExclusion("TrainAd") .addService(googletag.pubads()); slot.getCategoryExclusions(); // Returns ['AirlineAd', 'TrainAd'].
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .setCategoryExclusion("AirlineAd") .setCategoryExclusion("TrainAd") .addService(googletag.pubads()); slot.getCategoryExclusions(); // Returns ['AirlineAd', 'TrainAd'].
-
傳回 string[]
此版位的廣告類別排除標籤;如果未設定任何標籤,則傳回空白陣列。
getResponseInformation
-
getResponseInformation(): null | ResponseInformation
-
傳回廣告回應資訊。這是根據版位上次的廣告回應計算得出。如果版位沒有廣告時呼叫此方法,就會傳回
null
。 -
-
傳回 null | ResponseInformation
最新的廣告回應資訊;如果版位沒有廣告,則為null
。
getSlotElementId
-
getSlotElementId(): string
-
傳回在定義版位時提供的版位
div
。 -
- 範例
-
JavaScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .addService(googletag.pubads()); slot.getSlotElementId(); // Returns 'div-1'.
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .addService(googletag.pubads()); slot.getSlotElementId(); // Returns 'div-1'.
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .addService(googletag.pubads()); slot.getSlotElementId(); // Returns 'div-1'.
-
傳回 string
版位div
ID。
getTargeting
-
getTargeting(key: string): string[]
-
傳回針對這個版位設定的特定自訂指定參數。服務層級指定目標參數未包含在內。
-
- 範例
-
JavaScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setTargeting("allow_expandable", "true") .addService(googletag.pubads()); slot.getTargeting("allow_expandable"); // Returns ['true']. slot.getTargeting("age"); // Returns [] (empty array).
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setTargeting("allow_expandable", "true") .addService(googletag.pubads()); slot.getTargeting("allow_expandable"); // Returns ['true']. slot.getTargeting("age"); // Returns [] (empty array).
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .setTargeting("allow_expandable", "true") .addService(googletag.pubads()); slot.getTargeting("allow_expandable"); // Returns ['true']. slot.getTargeting("age"); // Returns [] (empty array).
-
參數 key: string
要尋找的指定鍵。 -
傳回 string[]
與這個鍵相關聯的值,如果沒有此類鍵,則為空白陣列。
getTargetingKeys
-
getTargetingKeys(): string[]
-
傳回此版位設定的所有自訂指定鍵清單。不含服務層級指定鍵。
-
- 範例
-
JavaScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setTargeting("allow_expandable", "true") .setTargeting("interests", ["sports", "music"]) .addService(googletag.pubads()); slot.getTargetingKeys(); // Returns ['interests', 'allow_expandable'].
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .setTargeting("allow_expandable", "true") .setTargeting("interests", ["sports", "music"]) .addService(googletag.pubads()); slot.getTargetingKeys(); // Returns ['interests', 'allow_expandable'].
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .setTargeting("allow_expandable", "true") .setTargeting("interests", ["sports", "music"]) .addService(googletag.pubads()); slot.getTargetingKeys(); // Returns ['interests', 'allow_expandable'].
-
傳回 string[]
指定鍵的陣列。未定義順序。
set
-
set(key: string, value: string): Slot
-
設定此廣告版位的 AdSense 屬性值。這會覆寫該鍵在服務層級所設定的任何值。
如果為同一個鍵重複呼叫這個方法,該鍵先前設定的值將遭到覆寫。請務必先設定所有值,再呼叫display
或refresh
。 -
- 範例
-
JavaScript
// Setting an attribute on a single ad slot. googletag .defineSlot("/1234567/sports", [160, 600], "div") .set("adsense_background_color", "#FFFFFF") .addService(googletag.pubads());
JavaScript (舊版)
// Setting an attribute on a single ad slot. googletag .defineSlot("/1234567/sports", [160, 600], "div") .set("adsense_background_color", "#FFFFFF") .addService(googletag.pubads());
TypeScript
// Setting an attribute on a single ad slot. googletag .defineSlot("/1234567/sports", [160, 600], "div")! .set("adsense_background_color", "#FFFFFF") .addService(googletag.pubads());
- 另請參閱
-
參數 key: string
屬性的名稱。value: string
屬性值。 -
傳回 Slot
呼叫方法的版位物件。
setCategoryExclusion
-
setCategoryExclusion(categoryExclusion: string): Slot
-
設定此版位的版位層級廣告類別排除標籤。
-
- 範例
-
JavaScript
// Label = AirlineAd googletag .defineSlot("/1234567/sports", [160, 600], "div") .setCategoryExclusion("AirlineAd") .addService(googletag.pubads());
JavaScript (舊版)
// Label = AirlineAd googletag .defineSlot("/1234567/sports", [160, 600], "div") .setCategoryExclusion("AirlineAd") .addService(googletag.pubads());
TypeScript
// Label = AirlineAd googletag .defineSlot("/1234567/sports", [160, 600], "div")! .setCategoryExclusion("AirlineAd") .addService(googletag.pubads());
- 另請參閱
-
參數 categoryExclusion: string
要新增的廣告類別排除標籤。 -
傳回 Slot
呼叫方法的版位物件。
setClickUrl
-
setClickUrl(value: string): Slot
-
設定點擊網址,系統會將點擊廣告的使用者重新導向。
即使點擊網址已變更,Google Ad Manager 伺服器仍會記錄一次點擊。所有與放送的廣告素材相關聯的到達網頁網址,都會附加到提供的值。後續的呼叫則會覆寫這個值。這個方法僅適用於非 SRA 請求。 -
- 範例
-
JavaScript
googletag .defineSlot("/1234567/sports", [160, 600], "div") .setClickUrl("http://www.example.com?original_click_url=") .addService(googletag.pubads());
JavaScript (舊版)
googletag .defineSlot("/1234567/sports", [160, 600], "div") .setClickUrl("http://www.example.com?original_click_url=") .addService(googletag.pubads());
TypeScript
googletag .defineSlot("/1234567/sports", [160, 600], "div")! .setClickUrl("http://www.example.com?original_click_url=") .addService(googletag.pubads());
-
參數 value: string
要設定的點擊網址。 -
傳回 Slot
呼叫方法的版位物件。
setCollapseEmptyDiv
-
setCollapseEmptyDiv(collapse: boolean, collapseBeforeAdFetch?: boolean): Slot
-
設定版位
div
在版位沒有廣告時是否應隱藏。這會覆寫服務層級的設定。 -
- 範例
-
JavaScript
googletag .defineSlot("/1234567/sports", [160, 600], "div-1") .setCollapseEmptyDiv(true, true) .addService(googletag.pubads()); // The above will cause the div for this slot to be collapsed // when the page is loaded, before ads are requested. googletag .defineSlot("/1234567/sports", [160, 600], "div-2") .setCollapseEmptyDiv(true) .addService(googletag.pubads()); // The above will cause the div for this slot to be collapsed // only after GPT detects that no ads are available for the slot.
JavaScript (舊版)
googletag .defineSlot("/1234567/sports", [160, 600], "div-1") .setCollapseEmptyDiv(true, true) .addService(googletag.pubads()); // The above will cause the div for this slot to be collapsed // when the page is loaded, before ads are requested. googletag .defineSlot("/1234567/sports", [160, 600], "div-2") .setCollapseEmptyDiv(true) .addService(googletag.pubads()); // The above will cause the div for this slot to be collapsed // only after GPT detects that no ads are available for the slot.
TypeScript
googletag .defineSlot("/1234567/sports", [160, 600], "div-1")! .setCollapseEmptyDiv(true, true) .addService(googletag.pubads()); // The above will cause the div for this slot to be collapsed // when the page is loaded, before ads are requested. googletag .defineSlot("/1234567/sports", [160, 600], "div-2")! .setCollapseEmptyDiv(true) .addService(googletag.pubads()); // The above will cause the div for this slot to be collapsed // only after GPT detects that no ads are available for the slot.
- 另請參閱
-
參數 collapse: boolean
如果未傳回任何廣告,是否要收合版位。collapseBeforeAdFetch?: boolean
是否要在擷取廣告前就收合版位。如果收合不是true
欄位,系統會忽略這項設定。 -
傳回 Slot
呼叫方法的版位物件。
setConfig
-
setConfig(slotConfig: SlotSettingsConfig): void
-
設定這個運算單元的一般設定選項。
-
-
參數 slotConfig: SlotSettingsConfig
設定物件。
setForceSafeFrame
-
setForceSafeFrame(forceSafeFrame: boolean): Slot
-
設定是否要使用 SafeFrame 容器顯示這個版位中的廣告。
使用此 API 時,請注意下列事項:- 只有針對個別版位送出的「後續」廣告請求,這項設定才會生效。
- 版位層級設定 (如有指定) 一律會覆寫網頁層級設定。
- 如果設為
true
(版位層級或網頁層級),則無論您在 Google Ad Manager 使用者介面中的選擇為何,系統一律會使用 SafeFrame 容器顯示廣告。 - 但是,如果設為
false
或未指定,系統會根據廣告素材類型和 Google Ad Manager UI 中的選項,使用 SafeFrame 容器顯示廣告。 - 這個 API 使用時請小心謹慎,因為此 API 可能會影響嘗試脫離 iframe,或仰賴發布商頁面直接顯示的廣告素材行為。
-
- 範例
-
JavaScript
googletag .defineSlot("/1234567/sports", [160, 600], "div") .setForceSafeFrame(true) .addService(googletag.pubads());
JavaScript (舊版)
googletag .defineSlot("/1234567/sports", [160, 600], "div") .setForceSafeFrame(true) .addService(googletag.pubads());
TypeScript
googletag .defineSlot("/1234567/sports", [160, 600], "div")! .setForceSafeFrame(true) .addService(googletag.pubads());
- 另請參閱
-
參數 forceSafeFrame: boolean
true
可強制這個版位中的所有廣告顯示在 SafeFrame 中,而false
可停用網頁層級設定 (如果有的話)。如未在網頁層級指定這個欄位,設為false
,則不會有任何影響。 -
傳回 Slot
呼叫方法的版位物件。
setSafeFrameConfig
-
setSafeFrameConfig(config: null | SafeFrameConfig): Slot
-
設定 SafeFrame 設定的版位層級偏好設定。系統會忽略設定物件中所有無法識別的鍵。如果為可識別的鍵傳遞無效值,系統會忽略整個設定。
如果指定這些版位層級偏好設定,就會覆寫任何頁面層級的偏好設定。 -
- 範例
-
JavaScript
googletag.pubads().setForceSafeFrame(true); // The following slot will have a sandboxed safeframe that only // disallows top-level navigation. googletag .defineSlot("/1234567/sports", [160, 600], "div-1") .setSafeFrameConfig({ sandbox: true }) .addService(googletag.pubads()); // The following slot will inherit page-level settings. googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads()); googletag.display("div-1"); googletag.display("div-2");
JavaScript (舊版)
googletag.pubads().setForceSafeFrame(true); // The following slot will have a sandboxed safeframe that only // disallows top-level navigation. googletag .defineSlot("/1234567/sports", [160, 600], "div-1") .setSafeFrameConfig({ sandbox: true }) .addService(googletag.pubads()); // The following slot will inherit page-level settings. googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads()); googletag.display("div-1"); googletag.display("div-2");
TypeScript
googletag.pubads().setForceSafeFrame(true); // The following slot will have a sandboxed safeframe that only // disallows top-level navigation. googletag .defineSlot("/1234567/sports", [160, 600], "div-1")! .setSafeFrameConfig({ sandbox: true }) .addService(googletag.pubads()); // The following slot will inherit page-level settings. googletag.defineSlot("/1234567/news", [160, 600], "div-2")!.addService(googletag.pubads()); googletag.display("div-1"); googletag.display("div-2");
- 另請參閱
-
參數 config: null | SafeFrameConfig
設定物件。 -
傳回 Slot
呼叫方法的版位物件。
setTargeting
-
setTargeting(key: string, value: string | string[]): Slot
-
設定這個版位的自訂指定參數。如果為同一個鍵多次呼叫此方法,系統就會覆寫舊值。在這裡設定的值會覆寫在服務層級設定的指定目標參數。請在 Google Ad Manager 帳戶中定義這些鍵。
-
- 範例
-
JavaScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .addService(googletag.pubads()); // Example with a single value for a key. slot.setTargeting("allow_expandable", "true"); // Example with multiple values for a key inside in an array. slot.setTargeting("interests", ["sports", "music"]);
JavaScript (舊版)
var slot = googletag .defineSlot("/1234567/sports", [160, 600], "div") .addService(googletag.pubads()); // Example with a single value for a key. slot.setTargeting("allow_expandable", "true"); // Example with multiple values for a key inside in an array. slot.setTargeting("interests", ["sports", "music"]);
TypeScript
const slot = googletag .defineSlot("/1234567/sports", [160, 600], "div")! .addService(googletag.pubads()); // Example with a single value for a key. slot.setTargeting("allow_expandable", "true"); // Example with multiple values for a key inside in an array. slot.setTargeting("interests", ["sports", "music"]);
- 另請參閱
-
參數 key: string
指定參數鍵。value: string | string[]
指定參數值或值陣列。 -
傳回 Slot
呼叫方法的版位物件。
updateTargetingFromMap
-
updateTargetingFromMap(map: { [adUnitPath: string]: string | string[] }): Slot
-
從 JSON 物件中的 key:value 對應,設定此版位的自訂指定參數。這與針對物件的所有鍵值呼叫
Slot.setTargeting
相同。請在 Google Ad Manager 帳戶中定義這些鍵。
注意:- 如果覆寫,系統只會保留最後一個值。
- 如果值是陣列,系統會覆寫任何先前的值,不會合併。
- 在這裡設定的值會覆寫在服務層級設定的指定目標參數。
-
- 範例
-
JavaScript
const slot = googletag.defineSlot("/1234567/sports", [160, 600], "div"); slot.updateTargetingFromMap({ color: "red", interests: ["sports", "music", "movies"], });
JavaScript (舊版)
var slot = googletag.defineSlot("/1234567/sports", [160, 600], "div"); slot.updateTargetingFromMap({ color: "red", interests: ["sports", "music", "movies"], });
TypeScript
const slot = googletag.defineSlot("/1234567/sports", [160, 600], "div")!; slot.updateTargetingFromMap({ color: "red", interests: ["sports", "music", "movies"], });
-
參數 map: { [adUnitPath: string]: string | string[] }
指定參數鍵/值對應。 -
傳回 Slot
呼叫方法的版位物件。
googletag.config。AdExpansionConfig
控管廣告展開功能的設定。
資源摘要 | |
---|---|
enabled
|
廣告展開功能是否設為啟用或停用。
|
- 範例
-
JavaScript
// Enable ad slot expansion across the entire page. googletag.setConfig({ adExpansion: { enabled: true }, });
JavaScript (舊版)
// Enable ad slot expansion across the entire page. googletag.setConfig({ adExpansion: { enabled: true }, });
TypeScript
// Enable ad slot expansion across the entire page. googletag.setConfig({ adExpansion: { enabled: true }, });
enabled
-
enabled: boolean
-
啟用或停用廣告展開功能。
設定這個值會覆寫 Google Ad Manager 中的預設值。
googletag.config。ComponentAuctionConfig
這是一個物件,代表裝置端廣告競價中的單一元件競價。
資源摘要 | |
---|---|
auctionConfig
|
此元件競價的競價設定物件。
|
configKey
|
與此元件競價相關聯的設定金鑰。
|
auctionConfig
-
auctionConfig: null | { auctionSignals: unknown, decisionLogicUrl: string, interestGroupBuyers: string[], perBuyerExperimentGroupIds: { [buyer: string]: number }, perBuyerGroupLimits: { [buyer: string]: number }, perBuyerSignals: { [buyer: string]: unknown }, perBuyerTimeouts: { [buyer: string]: number }, seller: string, sellerExperimentGroupId: number, sellerSignals: unknown, sellerTimeout: number, trustedScoringSignalsUrl: string }
-
這項元件競價的競價設定物件。
如果將這個值設為null
,系統會刪除指定configKey
的所有現有設定。 -
- 範例
-
JavaScript
const componentAuctionConfig = { // Seller URL should be https and the same as decisionLogicUrl's origin seller: "https://testSeller.com", decisionLogicUrl: "https://testSeller.com/ssp/decision-logic.js", interestGroupBuyers: ["https://example-buyer.com"], auctionSignals: { auction_signals: "auction_signals" }, sellerSignals: { seller_signals: "seller_signals" }, perBuyerSignals: { // listed on interestGroupBuyers "https://example-buyer.com": { per_buyer_signals: "per_buyer_signals", }, }, }; const auctionSlot = googletag.defineSlot("/1234567/example", [160, 600]); // To add configKey to the component auction: auctionSlot.setConfig({ componentAuction: [ { configKey: "https://testSeller.com", auctionConfig: componentAuctionConfig, }, ], }); // To remove configKey from the component auction: auctionSlot.setConfig({ componentAuction: [ { configKey: "https://testSeller.com", auctionConfig: null, }, ], });
JavaScript (舊版)
var componentAuctionConfig = { // Seller URL should be https and the same as decisionLogicUrl's origin seller: "https://testSeller.com", decisionLogicUrl: "https://testSeller.com/ssp/decision-logic.js", interestGroupBuyers: ["https://example-buyer.com"], auctionSignals: { auction_signals: "auction_signals" }, sellerSignals: { seller_signals: "seller_signals" }, perBuyerSignals: { // listed on interestGroupBuyers "https://example-buyer.com": { per_buyer_signals: "per_buyer_signals", }, }, }; var auctionSlot = googletag.defineSlot("/1234567/example", [160, 600]); // To add configKey to the component auction: auctionSlot.setConfig({ componentAuction: [ { configKey: "https://testSeller.com", auctionConfig: componentAuctionConfig, }, ], }); // To remove configKey from the component auction: auctionSlot.setConfig({ componentAuction: [ { configKey: "https://testSeller.com", auctionConfig: null, }, ], });
TypeScript
const componentAuctionConfig = { // Seller URL should be https and the same as decisionLogicUrl's origin seller: "https://testSeller.com", decisionLogicUrl: "https://testSeller.com/ssp/decision-logic.js", interestGroupBuyers: ["https://example-buyer.com"], auctionSignals: { auction_signals: "auction_signals" }, sellerSignals: { seller_signals: "seller_signals" }, perBuyerSignals: { // listed on interestGroupBuyers "https://example-buyer.com": { per_buyer_signals: "per_buyer_signals", }, }, }; const auctionSlot = googletag.defineSlot("/1234567/example", [160, 600])!; // To add configKey to the component auction: auctionSlot.setConfig({ componentAuction: [ { configKey: "https://testSeller.com", auctionConfig: componentAuctionConfig, }, ], }); // To remove configKey from the component auction: auctionSlot.setConfig({ componentAuction: [ { configKey: "https://testSeller.com", auctionConfig: null, }, ], });
- 另請參閱
configKey
-
configKey: string
-
與這項元件競價相關聯的設定金鑰。
這個值不得留空,且不得重複。如果兩個ComponentAuctionConfig
物件共用相同的 configKey 值,則最後要設定的最後一個設定會覆寫先前的設定。 -
googletag.config。InterstitialConfig
定義單一插頁式廣告版位行為的物件。
資源摘要 | |
---|---|
triggers
|
這個插頁式廣告的插頁式廣告觸發條件設定。
|
triggers
-
triggers: Partial<Record<InterstitialTrigger, boolean>>
-
這個插頁式廣告的插頁式廣告觸發條件設定。
如果將插頁式廣告觸發條件的值設為「true
」,系統就會啟用該觸發條件,false
則會停用該觸發條件。這會覆寫在 Google Ad Manager 中設定的預設值。 -
- 範例
-
JavaScript
// Define a GPT managed web interstitial ad slot. const interstitialSlot = googletag.defineOutOfPageSlot( "/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL ); // Enable optional interstitial triggers. // Change this value to false to disable. const enableTriggers = true; interstitialSlot.setConfig({ interstitial: { triggers: { navBar: enableTriggers, unhideWindow: enableTriggers, }, }, });
JavaScript (舊版)
// Define a GPT managed web interstitial ad slot. var interstitialSlot = googletag.defineOutOfPageSlot( "/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL ); // Enable optional interstitial triggers. // Change this value to false to disable. var enableTriggers = true; interstitialSlot.setConfig({ interstitial: { triggers: { navBar: enableTriggers, unhideWindow: enableTriggers, }, }, });
TypeScript
// Define a GPT managed web interstitial ad slot. const interstitialSlot = googletag.defineOutOfPageSlot( "/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL )!; // Enable optional interstitial triggers. // Change this value to false to disable. const enableTriggers = true; interstitialSlot.setConfig({ interstitial: { triggers: { navBar: enableTriggers, unhideWindow: enableTriggers, }, }, });
- 另請參閱
googletag.config。PageSettingsConfig
頁面層級設定的主要設定介面。
可透過單一 API 呼叫設定多項功能。
下列所有屬性皆屬於範例,不會反映使用 setConfig 的實際功能。如需一組功能,請參閱下方的 PageSettingsConfig 類型欄位。
範例:
- 系統只會修改
setConfig
呼叫中指定的功能。// Configure feature alpha. googletag.setConfig({ alpha: {...} }); // Configure feature bravo. Feature alpha is unchanged. googletag.setConfig({ bravo: {...} });
- 每次呼叫
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
|
控管廣告展開功能的設定。
|
pps
|
控管發布商提供的信號 (PPS) 設定。
|
privacyTreatments
|
發布商隱私權處理方式控管設定。
|
adExpansion
-
adExpansion: null | AdExpansionConfig
-
控管廣告展開功能的設定。
-
pps
-
pps: null | PublisherProvidedSignalsConfig
-
控管發布商提供的信號 (PPS) 設定。
-
privacyTreatments
-
privacyTreatments: null | PrivacyTreatmentsConfig
-
控管發布商隱私權處理方式的設定。
-
googletag.config。PrivacyTreatmentsConfig
控管發布商隱私權處理方式的設定。
資源摘要 | |
---|---|
treatments
|
要啟用的發布商隱私權處理方式陣列。
|
treatments
-
treatments: "disablePersonalization"[]
-
要啟用的發布商隱私權處理方式陣列。
-
- 範例
-
JavaScript
// Disable personalization across the entire page. googletag.setConfig({ privacyTreatments: { treatments: ["disablePersonalization"] }, });
JavaScript (舊版)
// Disable personalization across the entire page. googletag.setConfig({ privacyTreatments: { treatments: ["disablePersonalization"] }, });
TypeScript
// Disable personalization across the entire page. googletag.setConfig({ privacyTreatments: { treatments: ["disablePersonalization"] }, });
googletag.config。PublisherProvidedSignalsConfig
發布商提供的信號 (PPS) 設定物件。
資源摘要 | |
---|---|
taxonomies
|
包含 Taxonomy 對應關係的物件。
|
- 範例
-
JavaScript
googletag.setConfig({ pps: { taxonomies: { IAB_AUDIENCE_1_1: { values: ["6", "626"] }, // '6' = 'Demographic | Age Range | 18-20' // '626' = 'Interest | Sports | Darts' IAB_CONTENT_2_2: { values: ["48", "127"] }, // '48' = 'Books and Literature | Fiction' // '127' = 'Careers | Job Search' }, }, });
JavaScript (舊版)
googletag.setConfig({ pps: { taxonomies: { IAB_AUDIENCE_1_1: { values: ["6", "626"] }, // '6' = 'Demographic | Age Range | 18-20' // '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 | 18-20' // '626' = 'Interest | Sports | Darts' IAB_CONTENT_2_2: { values: ["48", "127"] }, // '48' = 'Books and Literature | Fiction' // '127' = 'Careers | Job Search' }, }, });
- 另請參閱
taxonomies
-
taxonomies: Partial<Record<Taxonomy, TaxonomyData>>
-
包含 Taxonomy 對應關係的物件。
-
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
|
控管廣告展開功能的設定。
|
componentAuction
|
要納入裝置端廣告競價的一系列元件競價。
|
interstitial
|
控制插頁式廣告版位行為的設定。
|
adExpansion
-
adExpansion: AdExpansionConfig
-
控管廣告展開功能的設定。
-
componentAuction
-
componentAuction: ComponentAuctionConfig[]
-
要納入裝置端廣告競價的一系列元件競價。
-
interstitial
-
interstitial: InterstitialConfig
-
控制插頁式廣告版位行為的設定。
-
googletag.config。TaxonomyData
包含單一 Taxonomy 值的物件。
資源摘要 | |
---|---|
values
|
Taxonomy 值的清單。
|
values
-
values: string[]
-
Taxonomy 值的清單。
-
googletag.events。Event
所有 GPT 事件的基礎介面。以下所有 GPT 事件都會有下列欄位。
資源摘要 | |
---|---|
serviceName
|
觸發事件的服務名稱。
|
slot
|
觸發事件的版位。
|
- 另請參閱
serviceName
-
serviceName: string
-
觸發事件的服務名稱。
-
slot
-
slot: Slot
-
觸發事件的版位。
-
googletag.events。EventTypeMap
這個虛擬類型會將事件名稱對應至 Service.addEventListener
和 Service.removeEventListener
的對應事件物件類型。內容僅供參考和類型安全用途。
資源摘要 | |
---|---|
impressionViewable
|
|
rewardedSlotClosed
|
|
rewardedSlotGranted
|
|
rewardedSlotReady
|
|
slotOnload
|
|
slotRenderEnded
|
|
slotRequested
|
|
slotResponseReceived
|
|
slotVisibilityChanged
|
impressionViewable
-
impressionViewable: ImpressionViewableEvent
-
rewardedSlotClosed
-
rewardedSlotClosed: RewardedSlotClosedEvent
-
rewardedSlotGranted
-
rewardedSlotGranted: RewardedSlotGrantedEvent
-
rewardedSlotReady
-
rewardedSlotReady: RewardedSlotReadyEvent
-
slotOnload
-
slotOnload: SlotOnloadEvent
-
slotRenderEnded
-
slotRenderEnded: SlotRenderEndedEvent
-
slotRequested
-
slotRequested: SlotRequestedEvent
-
slotResponseReceived
-
slotResponseReceived: SlotResponseReceived
-
slotVisibilityChanged
-
slotVisibilityChanged: SlotVisibilityChangedEvent
-
googletag.events。ImpressionViewableEvent
擴充
根據 Active View 條件,當曝光為可視時,就會觸發此事件。
資源摘要 | |
---|---|
serviceName
|
觸發事件的服務名稱。
沿用自「
|
slot
|
觸發事件的版位。
沿用自「
|
- 範例
-
JavaScript
// This listener is called when an impression becomes viewable. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("impressionViewable", (event) => { const slot = event.slot; console.log("Impression for slot", slot.getSlotElementId(), "became viewable."); if (slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// This listener is called when an impression becomes viewable. var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("impressionViewable", function (event) { var slot = event.slot; console.log("Impression for slot", slot.getSlotElementId(), "became viewable."); if (slot === targetSlot) { // Slot specific logic. } });
TypeScript
// This listener is called when an impression becomes viewable. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("impressionViewable", (event) => { const slot = event.slot; console.log("Impression for slot", slot.getSlotElementId(), "became viewable."); if (slot === targetSlot) { // Slot specific logic. } });
- 另請參閱
googletag.events。RewardedSlotClosedEvent
擴充
使用者關閉獎勵廣告版位時,會觸發此事件。可能會在獎勵發放之前或之後觸發。如要確認是否已獲得獎勵,請改用 events.RewardedSlotGrantedEvent
。
資源摘要 | |
---|---|
serviceName
|
觸發事件的服務名稱。
沿用自「
|
slot
|
觸發事件的版位。
沿用自「
|
- 範例
-
JavaScript
// This listener is called when the user closes a rewarded ad slot. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("rewardedSlotClosed", (event) => { const slot = event.slot; console.log("Rewarded ad slot", slot.getSlotElementId(), "has been closed."); if (slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// This listener is called when the user closes a rewarded ad slot. var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("rewardedSlotClosed", function (event) { var slot = event.slot; console.log("Rewarded ad slot", slot.getSlotElementId(), "has been closed."); if (slot === targetSlot) { // Slot specific logic. } });
TypeScript
// This listener is called when the user closes a rewarded ad slot. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); 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
擴充
獲得觀看獎勵廣告的獎勵時,會觸發此事件。如果在符合獎勵條件前使用者關閉廣告,此事件就不會觸發。
資源摘要 | |
---|---|
payload
|
包含已獲得獎勵相關資訊的物件。
|
serviceName
|
觸發事件的服務名稱。
沿用自「
|
slot
|
觸發事件的版位。
沿用自「
|
- 範例
-
JavaScript
// This listener is called whenever a reward is granted for a // rewarded ad. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("rewardedSlotGranted", (event) => { const slot = event.slot; console.group("Reward granted for slot", slot.getSlotElementId(), "."); // Log details of the reward. console.log("Reward type:", event.payload?.type); console.log("Reward amount:", event.payload?.amount); console.groupEnd(); if (slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// This listener is called whenever a reward is granted for a // rewarded ad. var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("rewardedSlotGranted", function (event) { var _a, _b; var slot = event.slot; console.group("Reward granted for slot", slot.getSlotElementId(), "."); // Log details of the reward. console.log("Reward type:", (_a = event.payload) === null || _a === void 0 ? void 0 : _a.type); console.log( "Reward amount:", (_b = event.payload) === null || _b === void 0 ? void 0 : _b.amount ); console.groupEnd(); if (slot === targetSlot) { // Slot specific logic. } });
TypeScript
// This listener is called whenever a reward is granted for a // rewarded ad. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); 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: null | RewardedPayload
-
物件,內含已授予的獎勵相關資訊。
-
googletag.events。RewardedSlotReadyEvent
擴充
準備好顯示獎勵廣告時,就會觸發此事件。發布商必須負責在放送廣告前,向使用者顯示廣告觀看的選項。
資源摘要 | |
---|---|
serviceName
|
觸發事件的服務名稱。
沿用自「
|
slot
|
觸發事件的版位。
沿用自「
|
方法摘要 | |
---|---|
makeRewardedVisible
|
顯示獎勵廣告。
|
- 範例
-
JavaScript
// This listener is called when a rewarded ad slot becomes ready to be // displayed. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("rewardedSlotReady", (event) => { const slot = event.slot; console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed."); // Replace with custom logic. const userHasConsented = true; if (userHasConsented) { event.makeRewardedVisible(); } if (slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// This listener is called when a rewarded ad slot becomes ready to be // displayed. var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("rewardedSlotReady", function (event) { var slot = event.slot; console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed."); // Replace with custom logic. var userHasConsented = true; if (userHasConsented) { event.makeRewardedVisible(); } if (slot === targetSlot) { // Slot specific logic. } });
TypeScript
// This listener is called when a rewarded ad slot becomes ready to be // displayed. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("rewardedSlotReady", (event) => { const slot = event.slot; console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed."); // Replace with custom logic. const userHasConsented = true; if (userHasConsented) { event.makeRewardedVisible(); } if (slot === targetSlot) { // Slot specific logic. } });
- 另請參閱
makeRewardedVisible
-
makeRewardedVisible(): void
-
顯示獎勵廣告。除非使用者同意觀看廣告,否則請不要呼叫此方法。
-
googletag.events。SlotOnloadEvent
擴充
廣告素材的 iframe 觸發載入事件時,會觸發這個事件。在同步顯示模式中呈現互動式多媒體廣告時,系統不會使用任何 iframe,因此不會觸發任何 SlotOnloadEvent
。
資源摘要 | |
---|---|
serviceName
|
觸發事件的服務名稱。
沿用自「
|
slot
|
觸發事件的版位。
沿用自「
|
- 範例
-
JavaScript
// This listener is called when a creative iframe load event fires. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotOnload", (event) => { const slot = event.slot; console.log("Creative iframe for slot", slot.getSlotElementId(), "has loaded."); if (slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// This listener is called when a creative iframe load event fires. var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotOnload", function (event) { var slot = event.slot; console.log("Creative iframe for slot", slot.getSlotElementId(), "has loaded."); if (slot === targetSlot) { // Slot specific logic. } });
TypeScript
// This listener is called when a creative iframe load event fires. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotOnload", (event) => { const slot = event.slot; console.log("Creative iframe for slot", slot.getSlotElementId(), "has loaded."); if (slot === targetSlot) { // Slot specific logic. } });
- 另請參閱
googletag.events。SlotRenderEndedEvent
擴充
廣告素材程式碼插入版位時,會觸發這個事件。這個事件會在擷取廣告素材資源前發生,因此廣告素材可能還無法顯示。如需知道版位的所有廣告素材資源何時載入完畢,請考慮改用 events.SlotOnloadEvent
。
資源摘要 | |
---|---|
advertiserId
|
已顯示的廣告廣告主 ID。
|
campaignId
|
已顯示廣告的廣告活動 ID。
|
companyIds
|
對顯示的廣告式候補廣告出價的公司 ID。
|
creativeId
|
已顯示的預訂廣告的廣告素材 ID。
|
creativeTemplateId
|
已顯示的預訂廣告的廣告素材範本 ID。
|
isBackfill
|
廣告是否為候補廣告。
|
isEmpty
|
指出版位是否有傳回廣告。
|
labelIds
|
已顯示的廣告標籤 ID。
|
lineItemId
|
已顯示的預訂廣告的委刊項 ID。
|
serviceName
|
觸發事件的服務名稱。
沿用自「
|
size
|
表示已顯示廣告素材的像素大小。
|
slot
|
觸發事件的版位。
沿用自「
|
slotContentChanged
|
版位內容是否已隨著顯示的廣告變更。
|
sourceAgnosticCreativeId
|
所顯示的廣告預訂或候補廣告的廣告素材 ID。
|
sourceAgnosticLineItemId
|
已顯示的預訂或候補廣告的委刊項 ID。
|
yieldGroupIds
|
已顯示的廣告候補廣告的收益群組 ID。
|
- 範例
-
JavaScript
// This listener is called when a slot has finished rendering. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotRenderEnded", (event) => { const slot = event.slot; console.group("Slot", slot.getSlotElementId(), "finished rendering."); // Log details of the rendered ad. console.log("Advertiser ID:", event.advertiserId); console.log("Campaign ID:", event.campaignId); console.log("Company IDs:", event.companyIds); console.log("Creative ID:", event.creativeId); console.log("Creative Template ID:", event.creativeTemplateId); console.log("Is backfill?:", event.isBackfill); console.log("Is empty?:", event.isEmpty); console.log("Label IDs:", event.labelIds); console.log("Line Item ID:", event.lineItemId); console.log("Size:", event.size); console.log("Slot content changed?", event.slotContentChanged); console.log("Source Agnostic Creative ID:", event.sourceAgnosticCreativeId); console.log("Source Agnostic Line Item ID:", event.sourceAgnosticLineItemId); console.log("Yield Group IDs:", event.yieldGroupIds); console.groupEnd(); if (slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// This listener is called when a slot has finished rendering. var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotRenderEnded", function (event) { var slot = event.slot; console.group("Slot", slot.getSlotElementId(), "finished rendering."); // Log details of the rendered ad. console.log("Advertiser ID:", event.advertiserId); console.log("Campaign ID:", event.campaignId); console.log("Company IDs:", event.companyIds); console.log("Creative ID:", event.creativeId); console.log("Creative Template ID:", event.creativeTemplateId); console.log("Is backfill?:", event.isBackfill); console.log("Is empty?:", event.isEmpty); console.log("Label IDs:", event.labelIds); 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("Label IDs:", event.labelIds); 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: null | number
-
已顯示的廣告廣告主 ID。若
PubAdsService
以外的服務所顯示的版位、候補廣告和廣告素材是空白的,則值為null
。 -
campaignId
-
campaignId: null | number
-
已顯示廣告的廣告活動 ID。若
PubAdsService
以外的服務所顯示的版位、候補廣告和廣告素材是空白的,則值為null
。 -
companyIds
-
companyIds: null | number[]
-
對顯示的廣告式候補廣告出價的公司 ID。對於空白版位、預訂廣告和由
PubAdsService
以外服務顯示的廣告素材,其值為null
。 -
creativeId
-
creativeId: null | number
-
所顯示預訂廣告的廣告素材 ID。若
PubAdsService
以外的服務所顯示的版位、候補廣告和廣告素材是空白的,則值為null
。 -
creativeTemplateId
-
creativeTemplateId: null | number
-
所顯示預訂廣告的廣告素材範本 ID。若
PubAdsService
以外的服務所顯示的版位、候補廣告和廣告素材是空白的,則值為null
。 -
isBackfill
-
isBackfill: boolean
-
廣告是否為候補廣告。如果廣告是候補廣告,其值為
true
,否則值為false
。 -
isEmpty
-
isEmpty: boolean
-
指出版位是否有傳回廣告。如果沒有傳回任何廣告,則值為
true
,否則值為false
。 -
labelIds
-
labelIds: null | number[]
-
已顯示的廣告標籤 ID。若
PubAdsService
以外的服務所顯示的版位、候補廣告和廣告素材是空白的,則值為null
。 -
lineItemId
-
lineItemId: null | number
-
已顯示的預訂廣告的委刊項 ID。若
PubAdsService
以外的服務所顯示的版位、候補廣告和廣告素材是空白的,則值為null
。 -
size
-
size: null | string | number[]
-
代表已顯示廣告素材的像素大小。範例:
[728, 90]
。若廣告版位是空的,則值為null
。 -
slotContentChanged
-
slotContentChanged: boolean
-
指出版位內容是否已隨著顯示的廣告變更。如果內容已變更,值為
true
,否則為false
。 -
sourceAgnosticCreativeId
-
sourceAgnosticCreativeId: null | number
-
所顯示預訂或候補廣告的廣告素材 ID。如果廣告不是預訂或委刊項候補廣告,或者廣告素材由
PubAdsService
以外的服務顯示,則值為null
。 -
sourceAgnosticLineItemId
-
sourceAgnosticLineItemId: null | number
-
已顯示的預訂廣告或候補廣告的委刊項 ID。如果廣告不是預訂或委刊項候補廣告,或者廣告素材由
PubAdsService
以外的服務顯示,則值為null
。 -
yieldGroupIds
-
yieldGroupIds: null | number[]
-
已顯示的廣告候補廣告的收益群組 ID。對於空白版位、預訂廣告和由
PubAdsService
以外服務顯示的廣告素材,其值為null
。 -
googletag.events。SlotRequestedEvent
擴充
當我們要求特定版位的廣告時,就會觸發此事件。
資源摘要 | |
---|---|
serviceName
|
觸發事件的服務名稱。
沿用自「
|
slot
|
觸發事件的版位。
沿用自「
|
- 範例
-
JavaScript
// This listener is called when the specified service issues an ad // request for a slot. Each slot will fire this event, even though they // may be batched together in a single request if single request // architecture (SRA) is enabled. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotRequested", (event) => { const slot = event.slot; console.log("Slot", slot.getSlotElementId(), "has been requested."); if (slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// This listener is called when the specified service issues an ad // request for a slot. Each slot will fire this event, even though they // may be batched together in a single request if single request // architecture (SRA) is enabled. var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotRequested", function (event) { var slot = event.slot; console.log("Slot", slot.getSlotElementId(), "has been requested."); if (slot === targetSlot) { // Slot specific logic. } });
TypeScript
// This listener is called when the specified service issues an ad // request for a slot. Each slot will fire this event, even though they // may be batched together in a single request if single request // architecture (SRA) is enabled. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotRequested", (event) => { const slot = event.slot; console.log("Slot", slot.getSlotElementId(), "has been requested."); if (slot === targetSlot) { // Slot specific logic. } });
- 另請參閱
googletag.events。SlotResponseReceived
擴充
系統收到特定版位的廣告回應時,會觸發此事件。
資源摘要 | |
---|---|
serviceName
|
觸發事件的服務名稱。
沿用自「
|
slot
|
觸發事件的版位。
沿用自「
|
- 範例
-
JavaScript
// This listener is called when an ad response has been received // for a slot. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotResponseReceived", (event) => { const slot = event.slot; console.log("Ad response for slot", slot.getSlotElementId(), "received."); if (slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// This listener is called when an ad response has been received // for a slot. var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotResponseReceived", function (event) { var slot = event.slot; console.log("Ad response for slot", slot.getSlotElementId(), "received."); if (slot === targetSlot) { // Slot specific logic. } });
TypeScript
// This listener is called when an ad response has been received // for a slot. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotResponseReceived", (event) => { const slot = event.slot; console.log("Ad response for slot", slot.getSlotElementId(), "received."); if (slot === targetSlot) { // Slot specific logic. } });
- 另請參閱
googletag.events。SlotVisibilityChangedEvent
擴充
每當廣告版位區域的畫面上變化百分比時,就會觸發此事件。事件受到限制,頻率不會每 200 毫秒觸發一次。
資源摘要 | |
---|---|
inViewPercentage
|
廣告區域的可見區域百分比。
|
serviceName
|
觸發事件的服務名稱。
沿用自「
|
slot
|
觸發事件的版位。
沿用自「
|
- 範例
-
JavaScript
// This listener is called whenever the on-screen percentage of an // ad slot's area changes. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotVisibilityChanged", (event) => { const slot = event.slot; console.group("Visibility of slot", slot.getSlotElementId(), "changed."); // Log details of the event. console.log("Visible area:", `${event.inViewPercentage}%`); console.groupEnd(); if (slot === targetSlot) { // Slot specific logic. } });
JavaScript (舊版)
// This listener is called whenever the on-screen percentage of an // ad slot's area changes. var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotVisibilityChanged", function (event) { var slot = event.slot; console.group("Visibility of slot", slot.getSlotElementId(), "changed."); // Log details of the event. console.log("Visible area:", "".concat(event.inViewPercentage, "%")); console.groupEnd(); if (slot === targetSlot) { // Slot specific logic. } });
TypeScript
// This listener is called whenever the on-screen percentage of an // ad slot's area changes. const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]); googletag.pubads().addEventListener("slotVisibilityChanged", (event) => { const slot = event.slot; console.group("Visibility of slot", slot.getSlotElementId(), "changed."); // Log details of the event. console.log("Visible area:", `${event.inViewPercentage}%`); console.groupEnd(); if (slot === targetSlot) { // Slot specific logic. } });
- 另請參閱
inViewPercentage
-
inViewPercentage: number
-
廣告區域的可見區域百分比。這個值是介於 0 到 100 之間的數字。
-
googletag.secureSignals。BidderSignalProvider
傳回特定出價方的安全信號。
出價方安全信號供應商由 2 個部分組成:
- 收集器函式會傳回
Promise
,該函式會解析為安全信號。 id
,用於識別與信號相關聯的出價方。
secureSignals.PublisherSignalProvider
。
資源摘要 | |
---|---|
collectorFunction
|
。
|
id
|
與這個安全信號相關聯的收集器專屬 ID,在 Google Ad Manager 中註冊。
|
- 範例
-
JavaScript
// id is provided googletag.secureSignalProviders.push({ id: "collector123", collectorFunction: () => { // ...custom signal generation logic... return Promise.resolve("signal"); }, });
JavaScript (舊版)
// id is provided googletag.secureSignalProviders.push({ id: "collector123", collectorFunction: function () { // ...custom signal generation logic... return Promise.resolve("signal"); }, });
TypeScript
// id is provided googletag.secureSignalProviders!.push({ id: "collector123", collectorFunction: () => { // ...custom signal generation logic... return Promise.resolve("signal"); }, });
- 另請參閱
collectorFunction
-
collectorFunction: () => Promise<string>
-
id
-
id: string
-
與這個安全信號相關聯的收集器專屬 ID,在 Google Ad Manager 中註冊。
-
googletag.secureSignals。PublisherSignalProvider
傳回特定發布商的安全信號。
發布商信號供應商由 2 個部分組成:
- 收集器函式會傳回
Promise
,該函式會解析為安全信號。 networkCode
,用於識別與信號相關聯的發布商。
secureSignals.BidderSignalProvider
。
資源摘要 | |
---|---|
collectorFunction
|
。
|
networkCode
|
與此安全信號相關聯的發布商聯播網代碼 (如廣告單元路徑所示)。
|
- 範例
-
JavaScript
// networkCode is provided googletag.secureSignalProviders.push({ networkCode: "123456", collectorFunction: () => { // ...custom signal generation logic... return Promise.resolve("signal"); }, });
JavaScript (舊版)
// networkCode is provided googletag.secureSignalProviders.push({ networkCode: "123456", collectorFunction: function () { // ...custom signal generation logic... return Promise.resolve("signal"); }, });
TypeScript
// networkCode is provided googletag.secureSignalProviders!.push({ networkCode: "123456", collectorFunction: () => { // ...custom signal generation logic... return Promise.resolve("signal"); }, });
- 另請參閱
collectorFunction
-
collectorFunction: () => Promise<string>
-
networkCode
-
networkCode: string
-
與此安全信號相關聯的發布商聯播網代碼 (如廣告單元路徑所示)。
-
googletag.secureSignals。SecureSignalProvidersArray
用於管理安全信號的介面。
方法摘要 | |
---|---|
clearAllCache
|
清除本機儲存空間中的所有快取信號。
|
push
|
在信號提供者陣列中加入新的
secureSignals.SecureSignalProvider ,並開始信號產生程序。 |
clearAllCache
-
clearAllCache(): void
-
清除本機儲存空間中的所有快取信號。
-
push
-
push(provider: SecureSignalProvider): void
-
在信號供應商陣列中加入新的
secureSignals.SecureSignalProvider
,並開始信號產生程序。 -
-
參數 provider: SecureSignalProvider
要新增至陣列的secureSignals.SecureSignalProvider
物件。