欢迎在 2024 年 Google 发布商代码开发者调查问卷中分享您的想法，帮助我们改善 Google 发布商代码开发者体验。

此页面由 Cloud Translation API 翻译。

GPT 参考文档

此参考文档使用 TypeScript 表示法描述类型。下表提供了并给出示例的简要说明

类型表达式
`string`	基本字符串类型。
`string[]`	一种数组类型，其中的值只能是字符串。
`number \| string`	一种联合类型，其中值可以是数字或字符串。
`Array<number \| string>`	数组类型，其中值是复数（联合）类型。
`[number, string]`	元组类型，其值是一个双元素数组，其中必须包含数字和字符串（按顺序排列）。
`Slot`	一种对象类型，其值为 `googletag.Slot` 的实例。
`() => void`	没有已定义参数和返回值的函数类型。

要详细了解支持的类型和类型表达式，请参阅 <ph type="x-smartling-placeholder"></ph> TypeScript 手册。

类型注解

变量、参数名称、属性名称或函数签名后面的冒号表示 type 注解。类型注解描述了冒号左侧的元素的类型可以接受或退货。下表显示了您可能会在引用的内容。

类型注解
`param: string`	表示 `param` 接受或返回字符串值。此语法用于指定变量、参数、属性和返回值类型。
`param?: number \| string`	表示 `param` 是可选的，但接受数字或字符串。此语法用于参数和属性。
`...params: Array<() => void>`	表示 `params` 是一个 <ph type="x-smartling-placeholder"></ph> REST 参数，该方法可接受函数。REST 参数接受数量不限的指定的类型。

类型定义

类型
`googletag.GeneralSize`	`SingleSize \| MultiSize`
广告位的有效尺寸配置，可以是一个或多个尺寸。
`googletag.MultiSize`	`SingleSize[]`
单个有效尺寸的列表。
`googletag.NamedSize`	`"fluid" \| ["fluid"]`
广告位可以采用的已命名尺寸。在大多数情况下，尺寸是一个固定尺寸的矩形，但在某些情况下，我们需要其他类型的尺寸规范。只有以下项是有效的已命名尺寸： fluid：广告容器会占用父 div 的 100% 宽度，然后调整高度以适应广告素材内容。与页面上常规块元素的行为方式类似。用于原生广告（请参阅相关文章）。请注意，`fluid` 和 `['fluid']` 都可以是将广告位尺寸声明为自适应尺寸的形式。
`googletag.SingleSize`	`SingleSizeArray \| NamedSize`
广告位的单个有效尺寸。
`googletag.SingleSizeArray`	`[number, number]`
由两个数字组成的数组，代表 [宽度, 高度]。
`googletag.SizeMapping`	`[SingleSizeArray, GeneralSize]`
视口尺寸与广告尺寸的映射。用于自适应广告。
`googletag.SizeMappingArray`	`SizeMapping[]`
尺寸映射列表。
`googletag.config.InterstitialTrigger`	`"unhideWindow" \| "navBar"`
支持的插页式广告触发器。
`googletag.config.PrivacyTreatment`	`"disablePersonalization"`
支持的发布商隐私权处理方式。
`googletag.config.Taxonomy`	`"IAB_AUDIENCE_1_1" \| "IAB_CONTENT_2_2"`
发布商提供的信号 (PPS) 支持的类目。
`googletag.secureSignals.SecureSignalProvider`	`BidderSignalProvider \| PublisherSignalProvider`
用于为特定出价方或提供商返回安全信号的界面。必须提供 `id` 或 `networkCode` 中的一个，但不能同时提供两者。

枚举类型

枚举
`googletag.enums.OutOfPageFormat`	GPT 支持的页外格式。
`googletag.enums.TrafficSource`	GPT 支持的流量来源。

`googletag.enums.OutOfPageFormat`

GPT 支持的页外格式。
另请参阅
- defineOutOfPageSlot

值
`BOTTOM_ANCHOR`	广告位固定在视口底部的锚定格式。
`GAME_MANUAL_INTERSTITIAL`	游戏手动插页式广告格式。注意：游戏手动插页式广告是一种小范围开放使用的格式。
`INTERSTITIAL`	网站插页式广告素材格式。
`LEFT_SIDE_RAIL`	左侧边栏格式。
`REWARDED`	激励广告格式。
`RIGHT_SIDE_RAIL`	右侧边栏格式。
`TOP_ANCHOR`	广告位固定在视口顶部的锚定格式。

`googletag.enums.TrafficSource`

GPT 支持的流量来源。
另请参阅
- PrivacySettingsConfig.trafficSource

值
`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 状态。

请注意，处理异步的推荐方法是使用 googletag.cmd 将回调排入队列，等待 GPT 准备就绪。这些回调不必检查 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 相关调用。

网页上的 GPT 代码语法会将 googletag.cmd 变量初始化为空 JavaScript 数组，而 cmd.push 是标准 Array.push 方法，可在数组末尾添加元素。GPT JavaScript 加载完毕后，会遍历数组并按顺序执行所有函数。然后，脚本将 cmd 替换为 CommandArray 对象，该对象的 push 方法定义为执行传递给它的函数参数。这种机制可在异步提取 JavaScript 的同时允许浏览器继续呈现网页，从而使 GPT 能够缩短感知延迟时间。

示例

JavaScript

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

JavaScript（旧版）

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

TypeScript

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

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 的 ID。

返回
`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");

另请参阅

Google 发布商代码使用入门

参数
`adUnitPath: string`	包含广告资源网代码和单元代码的完整广告单元路径。
`size: GeneralSize`	所添加广告位的宽度和高度。如果未提供自适应尺寸映射或视口尺寸小于映射中提供的最小尺寸，则广告请求中将使用此尺寸。
`div?: string`	包含此广告单元的 div 的 ID。

返回
`Slot \| null`	新创建的槽或 `null`（如果无法创建槽）。

googletag。destroySlots

destroySlots(slots?: Slot[]): boolean
销毁指定广告位，从 GPT 中移除这些广告位的所有相关对象和引用。此 API 不支持回传广告位和随播广告位。

对广告位调用此 API 会清除广告，并从 GPT 维护的内部状态中移除广告位对象。对 slot 对象调用更多函数将导致未定义的行为。请注意，如果发布商网页维护了对该广告位的引用，则浏览器可能仍然无法释放与该广告位关联的内存。调用此 API 可使与该广告位关联的 div 可供重复使用。

具体而言，销毁广告位会从 GPT 的长期有效的网页浏览中移除广告，这样以后的请求就不会受到涉及此广告的包版或竞争排除规则的影响。如果未能在从网页中移除广告位的 div 之前调用此函数，将会导致未定义的行为。

示例

JavaScript

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

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

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

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

JavaScript（旧版）

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

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

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

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

TypeScript

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

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

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

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

参数
`slots?: Slot[]`	要销毁的槽数组。数组是可选的；如果未指定该属性，所有槽都会被销毁。

返回
`boolean`	如果槽已被销毁，则为 `true`，否则为 `false`。

googletag。disablePublisherConsole

disablePublisherConsole(): void
停用 Google 发布商控制台。
另请参阅
- Google 发布商控制台

googletag。display

display(divOrSlot: string | Element | Slot): void
指示槽服务呈现槽。每个广告位在每个网页上只能展示一次。所有广告位都必须进行定义并与某个服务相关联，然后才能显示。在该元素出现在 DOM 中之前，不得执行 display 调用。通常的做法是将其放置在方法调用中指定的 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 元素的 div 元素的 ID，或者广告位对象。如果提供 div 元素，该元素必须具有“id”属性，该 ID 与传入 `defineSlot` 的 ID 匹配。

googletag。enableServices

enableServices(): void
启用已为网页上的广告位定义的所有 GPT 服务。

googletag。getVersion

getVersion(): string
返回最新版本的 GPT。
另请参阅
- 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();

另请参阅

Google 发布商控制台

参数
`div?: string`	广告位 div ID。此值是可选的。发布商控制台（若提供）将尝试打开并显示指定广告位的详细信息。

googletag。pubads

pubads(): PubAdsService
返回对 PubAdsService 的引用。

返回
`PubAdsService`	发布商广告服务。

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

扩展 Service

随播广告服务。此服务用于视频广告来展示随播广告。

方法摘要
`addEventListener`	注册监听器，以便您设置 JavaScript 函数并在网页上发生特定 GPT 事件时调用该函数。继承自“`googletag.Service.addEventListener`”
`getSlots`	获取与此服务关联的槽列表。继承自“`googletag.Service.getSlots`”
`removeEventListener`	移除之前注册的监听器。继承自“`googletag.Service.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
允许以受限广告模式投放广告，以帮助满足发布商法规遵从需求。

您可以通过以下两种方式指示 GPT 请求受限广告：
- 自动，使用来自 IAB TCF v2.0 意见征求管理平台的信号。
- 手动将此字段的值设置为 true。
。只有在从受限广告网址加载 GPT 时，才能手动配置受限广告。如果在从标准网址加载 GPT 后尝试修改此设置，系统会显示发布商控制台警告。

请注意，在使用 CMP 时，无需手动启用受限广告。

示例

JavaScript

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

JavaScript（旧版）

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

TypeScript

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

另请参阅

展示受限广告

nonPersonalizedAds

nonPersonalizedAds: boolean
允许以非个性化广告模式投放广告，以帮助满足发布商法规遵从需求。

restrictDataProcessing

restrictDataProcessing: boolean
允许在受限处理模式下投放，以帮助满足发布商法规遵从需求。

trafficSource

trafficSource: TrafficSource
指明请求代表的是购买流量还是自然流量。此值会填充 Ad Manager 报告中的流量来源维度。如果未设置，则报告中的流量来源默认为 undefined。

示例

JavaScript

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

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

JavaScript（旧版）

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

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

TypeScript

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

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

underAgeOfConsent

underAgeOfConsent: null | boolean
指明是否将广告请求标记为来自未达到同意年龄的用户。设置为 null 即可清除此配置。

googletag。PubAdsService

扩展 Service

“发布商广告”服务此服务用于从您的 Google Ad Manager 账号提取和展示广告。

方法摘要
`addEventListener`	注册监听器，以便您设置 JavaScript 函数并在网页上发生特定 GPT 事件时调用该函数。继承自“`googletag.Service.addEventListener`”
`clear`	从指定广告位中删除广告，并将其替换为空白内容。
`clearCategoryExclusions`	清除所有网页级广告类别排除标签。
`clearTargeting`	清除特定键或所有键的自定义定位参数。
`collapseEmptyDivs`	启用广告位 div 合拢，以便在无广告内容显示时不占用网页上的任何空间。
`disableInitialLoad`	禁止在网页加载时发出广告请求，但允许通过 `PubAdsService.refresh` 调用来请求广告。
`display`	使用指定广告单元路径和尺寸构建和显示广告位。
`enableLazyLoad`	在 GPT 中启用延迟加载（如配置对象所定义）。
`enableSingleRequest`	启用单一请求模式，以便同时获取多个广告。
`enableVideoAds`	向 GPT 发出信号，表明网页上将展示视频广告。
`get`	返回与指定键相关联的 AdSense 属性的值。
`getAttributeKeys`	返回在此服务上设置的属性键。
`getSlots`	获取与此服务关联的槽列表。继承自“`googletag.Service.getSlots`”
`getTargeting`	返回已设置的特定自定义服务级定位参数。
`getTargetingKeys`	返回已设置的所有自定义服务级定位键的列表。
`isInitialLoadDisabled`	返回之前的 `PubAdsService.disableInitialLoad` 调用是否已成功停用初始广告请求。
`refresh`	为网页上的特定或所有广告位提取并展示新广告。
`removeEventListener`	移除之前注册的监听器。继承自“`googletag.Service.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 请求广告。
另请参阅
- 控制广告加载和刷新
- 控制 SRA 批处理

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 中的延迟提取仅在所有广告位都位于提取外边距时有效。

示例

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，从而增加广告位在提取和渲染之前可以实现的最小距离。

config?: { fetchMarginPercent: number, mobileScaling: number, renderMarginPercent: number }

配置对象支持自定义延迟行为。任何省略的配置都将使用 Google 设置的默认配置，并会随着时间的推移而进行调整。如需停用特定设置（例如提取外边距），请将值设置为 -1。

fetchMarginPercent

广告位与当前视口之间的最小距离，以占视口尺寸的百分比表示，然后才能提取广告。值 0 表示“当广告位进入视口时”，100 表示“当广告距离视口 1 个视口时”，以此类推。
renderMarginPercent

在呈现广告之前，广告位必须与当前视口之间的最小距离。这样一来，系统便可以预提取广告，但同时等待呈现和下载其他子资源。该值的作用类似于 fetchMarginPercent，以占视口的百分比表示。
mobileScaling

对移动设备上的利润应用了系数。这样，在移动设备和桌面设备上就可以获得不同的利润。例如，如果值为 2.0，移动设备上的所有外边距都会乘以 2，从而增加广告位在提取和渲染之前可以实现的最小距离。

enableSingleRequest

enableSingleRequest(): boolean
启用单一请求模式，以便同时获取多个广告。这要求在启用服务之前，定义所有发布商广告位并将其添加到 PubAdsService。必须先设置单一请求模式，然后才能启用服务。
另请参阅
- Google Ads 最佳实践：正确使用单一请求架构
- 控制 SRA 批处理

返回
`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'.

另请参阅

AdSense 属性

参数
`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`	如果先前对 `PubAdsService.disableInitialLoad` 的调用成功，则返回 `true`，否则返回 `false`。

refresh

refresh(slots?: null | Slot[], options?: { changeCorrelator: boolean }): void
为网页上的特定或所有广告位提取并展示新广告。仅适用于异步呈现模式。

为了确保所有浏览器上都能正常展示，在调用 refresh 之前，必须先调用 display 广告位。如果省略了对 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 的长期网页浏览没有影响，后者会自动反映网页上现有的广告，没有到期时间。

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

另请参阅

AdSense 属性

参数
`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 或未指定，则广告将使用 SafeFrame 容器呈现，具体取决于广告素材类型以及在 Google Ad Manager 界面中所做的选择。
- 使用此 API 时应谨慎，因为它可能会影响试图脱离其 iframe 或依赖于直接在发布商页面中呈现的广告素材的行为。

示例

JavaScript

googletag.pubads().setForceSafeFrame(true);

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

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

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

JavaScript（旧版）

googletag.pubads().setForceSafeFrame(true);

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

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

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

TypeScript

googletag.pubads().setForceSafeFrame(true);

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

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

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

另请参阅

使用 SafeFrame 呈现广告素材

参数
`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");

另请参阅

使用 SafeFrame 呈现广告素材

参数
`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 内容提取服务提供的值。
另请参阅
- VAST 广告代码网址参数

参数
`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。

另请参阅

Slot.getResponseInformation

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 沙盒属性来阻止无用户互动的顶层导航。
`useUniqueDomain`	已弃用。 SafeFrame 是否应为预订型广告素材使用随机子网域。

另请参阅

PubAdsService.setSafeFrameConfig

allowOverlayExpansion

allowOverlayExpansion: boolean
SafeFrame 是否应允许广告内容通过叠加在网页内容上展开。

allowPushExpansion

allowPushExpansion: boolean
SafeFrame 是否应允许通过推送网页内容来展开广告内容。

sandbox

sandbox: boolean
SafeFrame 是否应使用 HTML5 沙盒属性来阻止无用户互动的顶层导航。唯一的有效值为 true（无法强制设置为 false）。请注意，沙盒属性会停用插件（例如 Flash）。

useUniqueDomain

useUniqueDomain: null | boolean
SafeFrame 是否应为预订型广告素材使用随机子网域。传入 null 以清除存储的值。

注意：默认情况下，此功能处于启用状态。

</ph> 已弃用：无法再停用此功能。设置 useUniqueDomain 不会产生任何影响。

另请参阅
- 使用 SafeFrame 呈现广告素材

googletag。Service

基服务类，包含所有服务通用的方法。

方法摘要
`addEventListener`	注册监听器，以便您设置 JavaScript 函数并在网页上发生特定 GPT 事件时调用该函数。
`getSlots`	获取与此服务关联的槽列表。
`removeEventListener`	移除之前注册的监听器。

addEventListener

addEventListener<K extends keyof EventTypeMap>(eventType: K, listener: (arg: EventTypeMap[K]) => void): Service
注册监听器，以便您设置 JavaScript 函数并在网页上发生特定 GPT 事件时调用该函数。支持以下事件：
在调用监听器时，系统会将属于适当事件类型的对象传递给监听器。

示例

JavaScript

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

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

JavaScript（旧版）

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

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

TypeScript

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

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

另请参阅

广告事件监听器

参数
`eventType: K`	表示由 GPT 生成的事件类型的字符串。事件类型区分大小写。
`listener: (arg: EventTypeMap[K]) => void`	接受单个事件对象参数的函数。

返回
`Service`	调用方法的服务对象。

getSlots

getSlots(): Slot[]
获取与此服务关联的槽列表。

返回
`Slot[]`	槽（按照添加到服务的顺序）。

removeEventListener

removeEventListener<K extends keyof EventTypeMap>(eventType: K, listener: (event: EventTypeMap[K]) => void): void
移除之前注册的监听器。

示例

JavaScript

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

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

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

JavaScript（旧版）

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

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

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

TypeScript

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

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

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

参数
`eventType: K`	表示由 GPT 生成的事件类型的字符串。事件类型区分大小写。
`listener: (event: EventTypeMap[K]) => void`	接受单个事件对象参数的函数。

googletag。SizeMappingBuilder

尺寸映射规范对象的构建器。提供此构建器可帮助您轻松构建大小规范。

方法摘要
`addSize`	添加从单个尺寸数组（表示视口）到表示广告位的单尺寸或多尺寸数组的映射。
`build`	根据添加到此构建器的映射来构建尺寸映射规范。

另请参阅

广告尺寸：自适应广告

addSize

addSize(viewportSize: SingleSizeArray, slotSize: GeneralSize): SizeMappingBuilder
添加从单个尺寸数组（表示视口）到表示广告位的单尺寸或多尺寸数组的映射。

示例

JavaScript

// Mapping 1
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [728, 90])
  .addSize([640, 480], "fluid")
  .addSize([0, 0], [88, 31]) // All viewports < 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`	此构建器构建的结果。如果提供了无效的尺寸映射，可以为 null。

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 对象中的键值对映射设置此广告位的自定义定位参数。

addService

addService(service: Service): Slot
将 Service 添加到此槽。

示例

JavaScript

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

JavaScript（旧版）

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

TypeScript

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

另请参阅

参数
`service: Service`	要添加的服务。

返回
`Slot`	调用方法的 slot 对象。

clearCategoryExclusions

clearCategoryExclusions(): Slot
清除该广告位的所有广告位级广告类别排除标签。

示例

JavaScript

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

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

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

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

JavaScript（旧版）

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

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

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

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

TypeScript

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

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

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

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

返回
`Slot`	调用方法的 slot 对象。

clearTargeting

clearTargeting(key?: string): Slot
清除该广告位的特定或所有自定义广告位级定位参数。

示例

JavaScript

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

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

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

JavaScript（旧版）

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

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

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

TypeScript

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

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

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

另请参阅

键值对定位

参数
`key?: string`	定位参数键。键是可选的；如果未指定，所有定位参数都会被清除。

返回
`Slot`	调用方法的 slot 对象。

defineSizeMapping

defineSizeMapping(sizeMapping: SizeMappingArray): Slot
用于为此广告位设置从最小视口尺寸到广告位尺寸的映射数组。

示例

JavaScript

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

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

slot.defineSizeMapping(mapping);

JavaScript（旧版）

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

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

slot.defineSizeMapping(mapping);

TypeScript

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

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

slot.defineSizeMapping(mapping!);

另请参阅

广告尺寸：自适应广告

参数
`sizeMapping: SizeMappingArray`	尺寸映射数组。您可以使用 `SizeMappingBuilder` 来创建。每个尺寸映射都是由以下两个元素组成的数组：`SingleSizeArray` 和 `GeneralSize`。

返回
`Slot`	调用方法的 slot 对象。

get

get(key: string): 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'.

另请参阅

AdSense 属性

参数
`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 的 ID。

示例

JavaScript

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

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

JavaScript（旧版）

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

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

TypeScript

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

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

返回
`string`	广告位 `div` ID。

getTargeting

getTargeting(key: string): string[]
返回在此广告位上设置的特定自定义定位参数。不包括服务级定位参数。

示例

JavaScript

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

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

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

JavaScript（旧版）

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

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

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

TypeScript

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

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

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

参数
`key: string`	要查找的定位键。

返回
`string[]`	与此键关联的值，如果没有此键，则为空数组。

getTargetingKeys

getTargetingKeys(): string[]
返回在此广告位上设置的所有自定义定位键的列表。不包括服务级定位键。

示例

JavaScript

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

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

JavaScript（旧版）

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

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

TypeScript

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

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

返回
`string[]`	定位键数组。排序方式未定义。

set

set(key: string, value: string): Slot
设置此广告位上的 AdSense 属性的值。这会替换在服务级别为该键设置的所有值。

针对同一个键多次调用此方法会替换之前为该键设置的值。必须在调用 display 或 refresh 之前设置所有值。

示例

JavaScript

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

JavaScript（旧版）

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

TypeScript

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

另请参阅

AdSense 属性

参数
`key: string`	属性的名称。
`value: string`	属性值。

返回
`Slot`	调用方法的 slot 对象。

setCategoryExclusion

setCategoryExclusion(categoryExclusion: string): Slot
为此广告位设置一个广告位级广告类别排除标签。

示例

JavaScript

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

JavaScript（旧版）

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

TypeScript

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

另请参阅

用于屏蔽广告的自定义标签

参数
`categoryExclusion: string`	要添加的广告类别排除标签。

返回
`Slot`	调用方法的 slot 对象。

setClickUrl

setClickUrl(value: string): Slot
设置用户在点击广告后会被重定向到的点击跟踪网址。

即使替换点击跟踪网址，Google Ad Manager 服务器仍会记录点击。与所投放的广告素材相关联的所有着陆页网址都会附加到所提供的值。后续调用会覆盖该值。这仅适用于非 SRA 请求。

示例

JavaScript

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

JavaScript（旧版）

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

TypeScript

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

参数
`value: string`	要设置的点击网址。

返回
`Slot`	调用方法的 slot 对象。

setCollapseEmptyDiv

setCollapseEmptyDiv(collapse: boolean, collapseBeforeAdFetch?: boolean): Slot
设置当广告位中没有广告时是否应隐藏广告位 div。这会替换服务级设置。

示例

JavaScript

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

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

JavaScript（旧版）

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

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

TypeScript

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

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

另请参阅

参数
`collapse: boolean`	是否在未返回任何广告时合拢广告位。
`collapseBeforeAdFetch?: boolean`	是否在提取广告之前就合拢广告位。如果收起状态不是 `true`，则忽略。

返回
`Slot`	调用方法的 slot 对象。

setConfig

setConfig(slotConfig: SlotSettingsConfig): void
设置此槽的常规配置选项。

参数
`slotConfig: SlotSettingsConfig`	配置对象。

setForceSafeFrame

setForceSafeFrame(forceSafeFrame: boolean): Slot
配置是否强制使用 SafeFrame 容器呈现此广告位中的广告。

使用此 API 时，请注意以下几点：
- 此设置只会对针对相应广告位发出的后续广告请求生效。
- 广告位级设置（如果已指定）将始终覆盖网页级设置。
- 如果设为 true（在广告位级或网页级），无论在 Google Ad Manager 界面中所做的选择，广告始终会使用 SafeFrame 容器呈现。
- 不过，如果设为 false 或未指定，则广告将使用 SafeFrame 容器呈现，具体取决于广告素材类型以及在 Google Ad Manager 界面中所做的选择。
- 使用此 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());

另请参阅

使用 SafeFrame 呈现广告素材

参数
`forceSafeFrame: boolean`	`true` 会强制此广告位中的所有广告都通过 SafeFrame 呈现；`false` 则会选择停用网页级设置（如果有）。如果您未在网页级指定此字段，则将其设置为 `false` 不会产生任何变化。

返回
`Slot`	调用方法的 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");

另请参阅

使用 SafeFrame 呈现广告素材

参数
`config: null \| SafeFrameConfig`	配置对象。

返回
`Slot`	调用方法的 slot 对象。

setTargeting

setTargeting(key: string, value: string | string[]): Slot
为此广告位设置自定义定位参数。针对同一键多次调用此方法将覆盖旧值。此处设置的值将覆盖在服务级设置的定位参数。这些键在您的 Google Ad Manager 账号中定义。

示例

JavaScript

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

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

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

JavaScript（旧版）

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

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

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

TypeScript

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

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

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

另请参阅

键值对定位

参数
`key: string`	定位参数键。
`value: string \| string[]`	定位参数值或值数组。

返回
`Slot`	调用方法的 slot 对象。

updateTargetingFromMap

updateTargetingFromMap(map: { [adUnitPath: string]: string | string[] }): Slot
通过 JSON 对象中的键值对映射设置此广告位的自定义定位参数。这等同于为对象的所有键值调用 Slot.setTargeting。这些键是在 Google Ad Manager 账号中定义的。

注意：
- 如果覆盖，则仅保留最后一个值。
- 如果值为数组，则之前的所有值都将被覆盖，而不会合并。
- 此处设置的值将覆盖在服务级设置的定位参数。

示例

JavaScript

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

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

JavaScript（旧版）

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

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

TypeScript

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

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

参数
`map: { [adUnitPath: string]: string \| string[] }`	定位参数键值对映射。

返回
`Slot`	调用方法的 slot 对象。

googletagconfig。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 中配置的默认值。
另请参阅
- 在桌面设备和平板电脑上展开广告
- 在移动网站上展开广告（局部屏幕）

googletagconfig。ComponentAuctionConfig

表示设备端广告竞价中单个组成部分竞价的对象。

属性摘要
`auctionConfig`	此组成部分竞价的竞价配置对象。
`configKey`	与此组件竞价相关联的配置键。

另请参阅

Protected Audience API 卖方指南：开展广告竞价

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

另请参阅

Protected Audience API：发起设备端竞价

configKey

configKey: string
与此组件竞价关联的配置键。

此值不得为空且应是唯一的。如果两个 ComponentAuctionConfig 对象具有相同的 configKey 值，则最后设置的对象将覆盖之前的配置。

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

另请参阅

展示网站插页式广告

googletagconfig。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`	用于控制广告展开方式的设置。
`adYield`	已弃用。，了解所有最新动态。
`pps`	用于控制发布商提供的信号 (PPS) 的设置。
`privacyTreatments`	用于控制发布商隐私保护处理方式的设置。
`threadYield`	此设置用于控制 GPT 在呈现广告素材时是否应生成 JS 线程。

adExpansion

adExpansion: null | AdExpansionConfig
用于控制广告展开方式的设置。

adYield

adYield: null | "DISABLED" | "ENABLED_ALL_SLOTS"

pps

pps: null | PublisherProvidedSignalsConfig
用于控制发布商提供的信号 (PPS) 的设置。

privacyTreatments

privacyTreatments: null | PrivacyTreatmentsConfig
用于控制发布商隐私保护处理方式的设置。

threadYield

threadYield: null | "DISABLED" | "ENABLED_ALL_SLOTS"
此设置用于控制 GPT 在呈现广告素材时是否应生成 JS 线程。

只有支持 Scheduler.postTask API 的浏览器才能使用 GPT。

支持的值：
- null（默认）：GPT 会为视口之外的广告位生成 JS 线程。
- ENABLED_ALL_SLOTS：GPT 将为所有广告位生成 JS 线程，无论广告位是否在视口内。
- DISABLED：GPT 不会产生 JS 线程。

示例

JavaScript

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

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

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

JavaScript（旧版）

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

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

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

TypeScript

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

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

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

另请参阅

调度器：postTask() 方法

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

googletagconfig。PublisherProvidedSignalsConfig

发布商提供的信号 (PPS) 配置对象。

属性摘要
`taxonomies`	包含分类映射的对象。

示例

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>>
包含分类映射的对象。

googletagconfig。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
用于控制插页式广告位行为的设置。

googletagconfig。TaxonomyData

包含单个分类的值的对象。

属性摘要
`values`	分类值列表。

values

values: string[]
分类值列表。

googletagevents。Event

所有 GPT 事件的基础接口。以下所有 GPT 事件都将包含以下字段。

属性摘要
`serviceName`	触发事件的服务的名称。
`slot`	触发事件的广告位。

另请参阅

广告事件监听器

serviceName

serviceName: string
触发事件的服务的名称。

slot

slot: Slot
触发事件的广告位。

googletagevents。EventTypeMap

这是一种伪类型，可将事件名称映射到其对应的 Service.addEventListener 和 Service.removeEventListener 事件对象类型。本文档仅作参考和类型安全之用。

属性摘要
`gameManualInterstitialSlotClosed`	`events.GameManualInterstitialSlotClosedEvent` 的别名。
`gameManualInterstitialSlotReady`	`events.GameManualInterstitialSlotReadyEvent` 的别名。
`impressionViewable`	`events.ImpressionViewableEvent` 的别名。
`rewardedSlotClosed`	`events.RewardedSlotClosedEvent` 的别名。
`rewardedSlotGranted`	`events.RewardedSlotGrantedEvent` 的别名。
`rewardedSlotReady`	`events.RewardedSlotReadyEvent` 的别名。
`slotOnload`	`events.SlotOnloadEvent` 的别名。
`slotRenderEnded`	`events.SlotRenderEndedEvent` 的别名。
`slotRequested`	`events.SlotRequestedEvent` 的别名。
`slotResponseReceived`	`events.SlotResponseReceived` 的别名。
`slotVisibilityChanged`	`events.SlotVisibilityChangedEvent` 的别名。

googletagevents。GameManualInterstitialSlotClosedEvent

扩展 Event

用户关闭游戏手动插页式广告位时，会触发此事件。

注意：游戏手动插页式广告是一种访问受限的格式。

属性摘要
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.slot`”

示例

JavaScript

// This listener is called when a game manual interstial slot is closed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL
);
googletag.pubads().addEventListener("gameManualInterstitialSlotClosed", (event) => {
  const slot = event.slot;
  console.log("Game manual interstital slot", slot.getSlotElementId(), "is closed.");

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

JavaScript（旧版）

// This listener is called when a game manual interstial slot is closed.
var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL
);
googletag.pubads().addEventListener("gameManualInterstitialSlotClosed", function (event) {
  var slot = event.slot;
  console.log("Game manual interstital slot", slot.getSlotElementId(), "is closed.");

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

TypeScript

// This listener is called when a game manual interstial slot is closed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL
);
googletag.pubads().addEventListener("gameManualInterstitialSlotClosed", (event) => {
  const slot = event.slot;
  console.log("Game manual interstital slot", slot.getSlotElementId(), "is closed.");

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

另请参阅

googletagevents。GameManualInterstitialSlotReadyEvent

扩展 Event

当游戏手动插页式广告位已做好向用户展示的准备时，会触发此事件。

注意：游戏手动插页式广告是一种访问受限的格式。

属性摘要
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.slot`”

方法摘要
`makeGameManualInterstitialVisible`	向用户展示游戏手动插页式广告。

示例

JavaScript

// This listener is called when a game manual interstitial slot is ready to
// be displayed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL
);
googletag.pubads().addEventListener("gameManualInterstitialSlotReady", (event) => {
  const slot = event.slot;
  console.log("Game manual interstital slot", slot.getSlotElementId(), "is ready to be displayed.");

  //Replace with custom logic.
  const displayGmiAd = true;
  if (displayGmiAd) {
    event.makeGameManualInterstitialVisible();
  }

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

JavaScript（旧版）

// This listener is called when a game manual interstitial slot is ready to
// be displayed.
var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL
);
googletag.pubads().addEventListener("gameManualInterstitialSlotReady", function (event) {
  var slot = event.slot;
  console.log("Game manual interstital slot", slot.getSlotElementId(), "is ready to be displayed.");

  //Replace with custom logic.
  var displayGmiAd = true;
  if (displayGmiAd) {
    event.makeGameManualInterstitialVisible();
  }

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

TypeScript

// This listener is called when a game manual interstitial slot is ready to
// be displayed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL
);
googletag.pubads().addEventListener("gameManualInterstitialSlotReady", (event) => {
  const slot = event.slot;
  console.log("Game manual interstital slot", slot.getSlotElementId(), "is ready to be displayed.");

  //Replace with custom logic.
  const displayGmiAd = true;
  if (displayGmiAd) {
    event.makeGameManualInterstitialVisible();
  }

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

另请参阅

makeGameManualInterstitialVisible

makeGameManualInterstitialVisible(): void
向用户展示游戏手动插页式广告。

googletagevents。ImpressionViewableEvent

扩展 Event

根据 Active View 条件，当展示变得可见时会触发此事件。

属性摘要
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.slot`”

示例

JavaScript

// This listener is called when an impression becomes viewable.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("impressionViewable", (event) => {
  const slot = event.slot;
  console.log("Impression for slot", slot.getSlotElementId(), "became viewable.");

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

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

另请参阅

广告事件监听器

googletagevents。RewardedSlotClosedEvent

扩展 Event

用户关闭激励广告位时会触发此事件。它可能在提供奖励之前或之后触发。如需确定是否已授予奖励，请改用 events.RewardedSlotGrantedEvent。

属性摘要
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.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.
  }
});

另请参阅

googletagevents。RewardedSlotGrantedEvent

扩展 Event

当观看激励广告获得奖励时会触发此事件。如果在满足奖励条件之前关闭广告，则系统不会触发此事件。

属性摘要
`payload`	包含已授予奖励相关信息的对象。
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.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
包含已授予奖励相关信息的对象。

googletagevents。RewardedSlotReadyEvent

扩展 Event

当激励广告准备好展示时会触发此事件。发布商负责在展示广告之前向用户显示广告查看选项。

属性摘要
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.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
展示激励广告。在用户同意观看广告之前，不应调用此方法。

googletagevents。SlotOnloadEvent

扩展 Event

当广告素材的 iframe 触发其加载事件时会触发此事件。在同步呈现模式下呈现富媒体广告时，不使用 iframe，因此不会触发任何 SlotOnloadEvent。

属性摘要
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.slot`”

示例

JavaScript

// This listener is called when a creative iframe load event fires.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotOnload", (event) => {
  const slot = event.slot;
  console.log("Creative iframe for slot", slot.getSlotElementId(), "has loaded.");

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

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

另请参阅

广告事件监听器

googletagevents。SlotRenderEndedEvent

扩展 Event

在广告素材代码注入广告位时会触发此事件。此事件发生在系统抓取广告素材的资源之前，因此广告素材可能尚无法显示。如果您需要知道广告位的所有广告素材资源何时加载完毕，不妨考虑改用 events.SlotOnloadEvent。

属性摘要
`advertiserId`	所呈现广告的广告客户 ID。
`campaignId`	所呈现广告的广告系列 ID。
`companyIds`	对呈现的补余广告出价的公司 ID。
`creativeId`	所呈现的预订型广告的广告素材 ID。
`creativeTemplateId`	所呈现的预订型广告的广告素材模板 ID。
`isBackfill`	某个广告是否为补余广告。
`isEmpty`	是否针对相应广告位返回了广告。
`labelIds`	所呈现广告的标签 ID。
`lineItemId`	所呈现的预订型广告的订单项 ID。
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`size`	表示所呈现广告素材的像素尺寸。
`slot`	触发事件的广告位。继承自“`googletag.events.Event.slot`”
`slotContentChanged`	广告位内容是否随所呈现的广告一起更改。
`sourceAgnosticCreativeId`	所呈现的预订型广告或补余广告的广告素材 ID。
`sourceAgnosticLineItemId`	所呈现的预订型广告或补余广告的订单项 ID。
`yieldGroupIds`	所呈现的补余广告的收益组的 ID。

示例

JavaScript

// This listener is called when a slot has finished rendering.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotRenderEnded", (event) => {
  const slot = event.slot;
  console.group("Slot", slot.getSlotElementId(), "finished rendering.");

  // Log details of the rendered ad.
  console.log("Advertiser ID:", event.advertiserId);
  console.log("Campaign ID:", event.campaignId);
  console.log("Company IDs:", event.companyIds);
  console.log("Creative ID:", event.creativeId);
  console.log("Creative Template ID:", event.creativeTemplateId);
  console.log("Is backfill?:", event.isBackfill);
  console.log("Is empty?:", event.isEmpty);
  console.log("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。

googletagevents。SlotRequestedEvent

扩展 Event

为特定广告位请求广告时会触发此事件。

属性摘要
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.slot`”

示例

JavaScript

// This listener is called when the specified service issues an ad
// request for a slot. Each slot will fire this event, even though they
// may be batched together in a single request if single request
// architecture (SRA) is enabled.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotRequested", (event) => {
  const slot = event.slot;
  console.log("Slot", slot.getSlotElementId(), "has been requested.");

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

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

另请参阅

广告事件监听器

googletagevents。SlotResponseReceived

扩展 Event

在收到特定广告位的广告响应时会触发此事件。

属性摘要
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.slot`”

示例

JavaScript

// This listener is called when an ad response has been received
// for a slot.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotResponseReceived", (event) => {
  const slot = event.slot;
  console.log("Ad response for slot", slot.getSlotElementId(), "received.");

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

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

另请参阅

广告事件监听器

googletagevents。SlotVisibilityChangedEvent

扩展 Event

每当广告位区域区域在屏幕上的比例发生变化时，就会触发此事件。事件受到限制，触发频率不会超过每 200 毫秒一次。

属性摘要
`inViewPercentage`	广告可见区域所占的百分比。
`serviceName`	触发事件的服务的名称。继承自“`googletag.events.Event.serviceName`”
`slot`	触发事件的广告位。继承自“`googletag.events.Event.slot`”

示例

JavaScript

// This listener is called whenever the on-screen percentage of an
// ad slot's area changes.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("slotVisibilityChanged", (event) => {
  const slot = event.slot;
  console.group("Visibility of slot", slot.getSlotElementId(), "changed.");

  // Log details of the event.
  console.log("Visible area:", `${event.inViewPercentage}%`);
  console.groupEnd();

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

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 之间的数字。

googletagsecureSignals。BidderSignalProvider

为特定出价方返回安全信号。

出价方安全信号提供程序由 2 部分组成：

收集器函数，用于返回解析为安全信号的 Promise。
id，用于标识与信号相关联的出价方。

如需为发布商返回安全信号，请改用 secureSignals.PublisherSignalProvider。

属性摘要
`collectorFunction`	，了解所有最新动态。
`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
与此安全信号关联的收集器的唯一标识符（在 Google Ad Manager 中注册）。

googletagsecureSignals。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
与此安全信号相关联的发布商的广告资源网代码（如广告单元路径中所示）。

googletagsecureSignals。SecureSignalProvidersArray

用于管理安全信号的接口。

方法摘要
`clearAllCache`	从缓存中清除所有收集器的所有信号。
`push`	向信号提供程序数组添加新的 `secureSignals.SecureSignalProvider`，并开始信号生成过程。

clearAllCache

clearAllCache(): void
会从缓存中清除所有收集器的所有信号。

调用此方法可能会降低当前及日后可能的网页浏览中包含信号的可能性。因此，只有在发生有意义的状态变化（例如指示新用户（登录、退出、注册等）的事件）时，才应调用此方法。

push

push(provider: SecureSignalProvider): void
向信号提供程序数组添加新的 secureSignals.SecureSignalProvider，并开始信号生成过程。

参数
`provider: SecureSignalProvider`	要添加到数组的 `secureSignals.SecureSignalProvider` 对象。

GPT 参考文档

类型注解

类型定义

googletag.GeneralSize

googletag.MultiSize

googletag.NamedSize

googletag.SingleSize

googletag.SingleSizeArray

googletag.SizeMapping

googletag.SizeMappingArray

googletag.config.InterstitialTrigger

googletag.config.PrivacyTreatment

googletag.config.Taxonomy

googletag.secureSignals.SecureSignalProvider

枚举类型

googletag.enums.OutOfPageFormat

googletag.enums.TrafficSource

googletag

googletag。apiReady

JavaScript

JavaScript（旧版）

TypeScript

googletag。cmd

JavaScript

JavaScript（旧版）

TypeScript

googletag。pubadsReady

googletag。secureSignalProviders

JavaScript

JavaScript（旧版）

TypeScript

googletag。companionAds

googletag。defineOutOfPageSlot

JavaScript

JavaScript（旧版）

TypeScript

googletag。defineSlot

JavaScript

JavaScript（旧版）

TypeScript

googletag。destroySlots

JavaScript

JavaScript（旧版）

TypeScript

googletag。disablePublisherConsole

googletag。display

JavaScript

JavaScript（旧版）

TypeScript

googletag。enableServices

googletag。getVersion

googletag。openConsole

JavaScript

JavaScript（旧版）

TypeScript

googletag。pubads

googletag。setAdIframeTitle

JavaScript

JavaScript（旧版）

TypeScript

googletag。setConfig

googletag。sizeMapping

googletag。CommandArray

push

JavaScript

JavaScript（旧版）

TypeScript

googletag。CompanionAdsService

继承自“googletag.Service.addEventListener”

继承自“googletag.Service.getSlots”

继承自“googletag.Service.removeEventListener”

setRefreshUnfilledSlots

JavaScript

JavaScript（旧版）

TypeScript

googletag。PrivacySettingsConfig

childDirectedTreatment

limitedAds

JavaScript

JavaScript（旧版）

`googletag.GeneralSize`

`googletag.MultiSize`

`googletag.NamedSize`

`googletag.SingleSize`

`googletag.SingleSizeArray`

`googletag.SizeMapping`

`googletag.SizeMappingArray`

`googletag.config.InterstitialTrigger`

`googletag.config.PrivacyTreatment`

`googletag.config.Taxonomy`

`googletag.secureSignals.SecureSignalProvider`

`googletag.enums.OutOfPageFormat`

`googletag.enums.TrafficSource`

继承自“`googletag.Service.addEventListener`”

继承自“`googletag.Service.getSlots`”

继承自“`googletag.Service.removeEventListener`”

继承自“`googletag.Service.addEventListener`”

继承自“`googletag.Service.getSlots`”

继承自“`googletag.Service.removeEventListener`”