GPT 参考文档

本参考文档使用 TypeScript 表示法来描述类型。下表通过示例简要说明了此属性。

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

如需详细了解支持的类型和类型表达式,请参阅 TypeScript 手册

类型注解

在变量、形参名称、属性名称或函数签名后面添加冒号表示类型注解。类型注解描述了英文冒号左侧的元素可以接受或返回的类型。下表显示了您可能会在此参考文档中看到的类型注解示例。

类型注解
param: string 表示 param 接受或返回字符串值。此语法适用于变量、形参、属性和返回值类型。
param?: number | string 表示 param 是可选的,但在指定后接受数字或字符串。此语法适用于参数和属性。
...params: Array<() => void> 表示 params 是一个接受函数的 剩余参数 。Rest 参数接受指定类型的无限数量的值。

googletag

Google Publisher Tag 为其 API 使用的全局命名空间。
命名空间
config
用于网页级设置的主要配置界面。
enums
这是 GPT 为枚举类型使用的命名空间。
events
这是 GPT 为事件使用的命名空间。
secureSignals
这是 GPT 用于管理安全信号的命名空间。
接口
CommandArray
命令数组接受一系列函数,并按顺序调用它们。
CompanionAdsService
随播广告服务。
PrivacySettingsConfig
隐私设置的配置对象。
PubAdsService
发布商广告服务。
ResponseInformation
表示单个广告响应的对象。
RewardedPayload
表示与激励广告关联的奖励的对象。
SafeFrameConfig
SafeFrame 容器的配置对象。
Service
包含适用于所有服务的通用方法的基准服务类。
SizeMappingBuilder
大小映射规范对象的构建器。
Slot
广告位是表示网页上单个广告位的对象。
类型别名
GeneralSize
槽的有效尺寸配置,可以是 1 种或多种尺寸。
MultiSize
单个有效尺寸的列表。
NamedSize
槽可采用的命名大小。
SingleSize
相应槽的单个有效尺寸。
SingleSizeArray
一个包含两个数字的数组,表示 [width, height]。
SizeMapping
将视口大小映射到广告尺寸。
SizeMappingArray
尺寸映射列表。
变量
apiReady
用于指示 GPT API 已加载且可以调用的标志。
cmd
对全局命令队列的引用,用于异步执行与 GPT 相关的调用。
pubadsReady
此标志表示 PubAdsService 已启用、已加载且完全可用。
secureSignalProviders
对安全信号提供商数组的引用。
函数
companionAds
返回对 CompanionAdsService 的引用。
defineOutOfPageSlot
使用指定的广告单元路径构建页外广告位。
defineSlot
使用指定的广告单元路径和尺寸构建广告位,并将其与网页上将包含广告的 div 元素的 ID 相关联。
destroySlots
销毁给定的槽,从 GPT 中移除所有相关对象和这些槽的引用。
disablePublisherConsole
停用 Google 发布商控制台。
display
指示槽服务呈现槽。
enableServices
启用为网页上的广告位定义的所有 GPT 服务。
getVersion
返回 GPT 的当前版本。
openConsole
打开 Google 发布商控制台。
pubads
返回对 PubAdsService 的引用。
setAdIframeTitle
从此时起,为 PubAdsService 创建的所有广告容器 iframe 设置标题。
setConfig
设置页面的常规配置选项。
sizeMapping
创建新的 SizeMappingBuilder

类型别名


GeneralSize

    GeneralSize: SingleSize | MultiSize

    槽的有效尺寸配置,可以是 1 种或多种尺寸。


MultiSize

    MultiSize: SingleSize[]

    单个有效尺寸的列表。


NamedSize

    NamedSize: "fluid" | ["fluid"]

    槽可采用的命名大小。在大多数情况下,尺寸是固定大小的矩形,但在某些情况下,我们需要其他类型的尺寸规范。只有以下命名尺寸有效:

    • 自适应:广告容器占据父 div 的 100% 宽度,然后调整其高度以适应广告素材内容。类似于网页上的常规块元素的行为方式。用于原生广告(请参阅相关文章)。请注意,fluid['fluid'] 均可用于将槽大小声明为流体。


SingleSize


SingleSizeArray

    SingleSizeArray: [number, number]

    一个包含两个数字的数组,表示 [width, height]。


SizeMapping


SizeMappingArray

变量


Const apiReady

    apiReady: boolean | undefined

    用于指示 GPT API 已加载且可以调用的标志。在 API 准备就绪之前,此属性将仅为 undefined

    请注意,处理异步的推荐方法是使用 googletag.cmd 将回调加入队列,以便在 GPT 准备就绪时执行回调。这些回调无需检查 googletag.apiReady,因为它们在 API 设置完毕后一定会执行。


Const cmd

    cmd: ((this: typeof globalThis) => void)[] | CommandArray

    对全局命令队列的引用,用于异步执行与 GPT 相关的调用。

    googletag.cmd 变量由网页上的 GPT 代码语法初始化为空 JavaScript 数组,cmd.push 是用于向数组末尾添加元素的标准 Array.push 方法。GPT JavaScript 加载后,会浏览数组并依次执行所有函数。然后,脚本会将 cmd 替换为 CommandArray 对象,其 push 方法定义为执行传递给它的函数实参。借助此机制,GPT 可以异步提取 JavaScript,同时允许浏览器继续渲染页面,从而缩短感知延迟时间。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

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

Const pubadsReady

    pubadsReady: boolean | undefined

    此标志表示 PubAdsService 已启用、已加载且完全可用。在调用 enableServices 并加载并初始化 PubAdsService 之前,此属性将仅为 undefined


secureSignalProviders

    secureSignalProviders: SecureSignalProvider[] | SecureSignalProvidersArray | undefined

    对安全信号提供程序数组的引用。

    安全信号提供程序数组接受一系列信号生成函数,并按顺序调用这些函数。它旨在替换用于将信号生成函数加入队列的标准数组,以便在 GPT 加载后调用这些函数。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

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

函数


companionAds


defineOutOfPageSlot

    defineOutOfPageSlot(adUnitPath: string, div?: string | OutOfPageFormat): Slot | null

    使用指定的广告单元路径构建页外广告位。

    对于自定义页外广告,div 是将包含广告的 div 元素的 ID。如需了解详情,请参阅页外广告素材一文。

    对于 GPT 管理的页外广告,div 是一种受支持的 OutOfPageFormat

    示例

    JavaScript

    // Define a custom out-of-page ad slot.
    googletag.defineOutOfPageSlot("/1234567/sports", "div-1");
    
    // Define a GPT managed web interstitial ad slot.
    googletag.defineOutOfPageSlot("/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL);
    

    JavaScript(旧版)

    // Define a custom out-of-page ad slot.
    googletag.defineOutOfPageSlot("/1234567/sports", "div-1");
    
    // Define a GPT managed web interstitial ad slot.
    googletag.defineOutOfPageSlot("/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL);
    

    TypeScript

    // Define a custom out-of-page ad slot.
    googletag.defineOutOfPageSlot("/1234567/sports", "div-1");
    
    // Define a GPT managed web interstitial ad slot.
    googletag.defineOutOfPageSlot("/1234567/sports", googletag.enums.OutOfPageFormat.INTERSTITIAL);
    
    另请参阅
    参数
    adUnitPath: string包含广告资源网代码和广告单元代码的完整广告单元路径
    Optional div: string | OutOfPageFormat将包含此广告单元或 OutOfPageFormat 的 div 的 ID。
    返回结果
    Slot | null新创建的槽;如果无法创建槽,则返回 null


defineSlot

    defineSlot(adUnitPath: string, size: GeneralSize, div?: string): Slot | null

    使用指定的广告单元路径和尺寸构建广告位,并将其与网页上将包含广告的 div 元素的 ID 相关联。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
    
    另请参阅
    参数
    adUnitPath: string包含广告资源网代码和单元代码的完整广告单元路径
    size: GeneralSize添加的槽的宽度和高度。如果未提供自适应大小映射,或者视口大小小于映射中提供的最小尺寸,则广告请求中会使用此尺寸。
    Optional div: string将包含此广告单元的 div 的 ID。
    返回结果
    Slot | null新创建的槽;如果无法创建槽,则返回 null


destroySlots

    destroySlots(slots?: Slot[]): boolean

    销毁给定的槽,从 GPT 中移除所有相关对象和这些槽的引用。此 API 不支持回传广告位和随播广告位。

    对广告位调用此 API 会清除广告,并从 GPT 维护的内部状态中移除广告位对象。对槽对象调用任何其他函数都会导致未定义行为。请注意,如果发布商页面维护了对该槽的引用,浏览器可能仍不会释放与该槽关联的内存。调用此 API 会使与该广告位关联的 div 可供重复使用。

    具体而言,销毁广告位会将广告从 GPT 的长时段网页浏览中移除,因此未来的请求不会受到涉及此广告的拦截或竞争排除的影响。如果未在从页面中移除槽的 div 之前调用此函数,则会导致未定义的行为。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // The calls to construct an ad and display contents.
    const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1")!;
    googletag.display("div-1");
    const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2")!;
    googletag.display("div-2");
    
    // This call to destroy only slot1.
    googletag.destroySlots([slot1]);
    
    // This call to destroy both slot1 and slot2.
    googletag.destroySlots([slot1, slot2]);
    
    // This call to destroy all slots.
    googletag.destroySlots();
    
    参数
    Optional slots: Slot[]要销毁的槽的数组。数组是可选项;如果未指定,则所有槽都会被销毁。
    返回结果
    boolean如果槽位已被销毁,则为 true;否则为 false


disablePublisherConsole


显示

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

    指示槽服务呈现槽。每个广告位在每个网页上都应只展示一次。所有槽都必须先定义并与服务相关联,然后才能显示。在元素出现在 DOM 中之前,不得发生显示调用。通常,实现此目的的方法是将其放置在方法调用中命名的 div 元素内的脚本块中。

    如果使用的是单一请求架构 (SRA),则系统会在调用此方法时一次提取所有未提取的广告位。若要强制不显示广告展示位置,必须移除整个 div。

    另请参阅
    参数
    divOrSlot: string | Element | Slot包含广告展示位置的 div 元素的 ID、div 元素或广告位对象。如果提供了 div 元素,则其“id”属性必须与传入 defineSlot 的 ID 一致。


enableServices

    enableServices(): void

    启用为网页上的广告位定义的所有 GPT 服务。


getVersion

    getVersion(): string

    返回 GPT 的当前版本。

    另请参阅
    返回结果
    string当前正在执行的 GPT 版本字符串。


openConsole

    openConsole(div?: string): void

    打开 Google 发布商控制台。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // Calling with div ID.
    googletag.openConsole("div-1");
    
    // Calling without div ID.
    googletag.openConsole();
    
    另请参阅
    参数
    Optional div: string广告位 div ID。此值为可选值。在提供该参数后,发布商控制台会尝试打开,并显示指定广告展示位置的详细信息。


pubads


setAdIframeTitle

    setAdIframeTitle(title: string): void

    从此时起,为 PubAdsService 创建的所有广告容器 iframe 设置标题。

    示例

    JavaScript

    googletag.setAdIframeTitle("title");
    

    JavaScript(旧版)

    googletag.setAdIframeTitle("title");
    

    TypeScript

    googletag.setAdIframeTitle("title");
    
    参数
    title: string所有广告容器 iframe 的新标题。


setConfig


sizeMapping


googletag.CommandArray

命令数组接受一系列函数,并按顺序调用它们。它旨在替换用于将函数加入队列的标准数组,以便在 GPT 加载后调用这些函数。
方法
push
按顺序执行参数中指定的函数序列。

方法


推送

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

    按顺序执行参数中指定的函数序列。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.cmd.push(() => {
      googletag.defineSlot("/1234567/sports", [160, 600])!.addService(googletag.pubads());
    });
    
    参数
    Rest ...f: ((this: typeof globalThis) => void)[]要执行的 JavaScript 函数。运行时绑定始终为 globalThis。考虑传递箭头函数以保留封闭词法上下文的 this 值。
    返回结果
    number到目前为止处理的命令数量。这与 Array.push 的返回值(数组的当前长度)兼容。


googletag.CompanionAdsService

扩展了 Service
随播广告服务。视频广告会使用此服务来展示随播广告。
方法
addEventListener
注册监听器,以便您在网页上发生特定 GPT 事件时设置和调用 JavaScript 函数。
getSlots
获取与此服务关联的槽位列表。
removeEventListener
移除之前注册的监听器。
setRefreshUnfilledSlots
设置是否自动补充尚未填充的随播广告位。
另请参阅

方法


setRefreshUnfilledSlots

    setRefreshUnfilledSlots(value: boolean): void

    设置是否自动补充未填充的随播广告位。

    此方法可以在网页生命周期内多次调用,以启用和停用回填功能。只有同时注册到 PubAdsService 的广告位才会被补充。由于政策限制,此方法无法在投放 Ad Exchange 视频时填充空的随播广告展示位置。

    示例

    JavaScript

    googletag.companionAds().setRefreshUnfilledSlots(true);
    

    JavaScript(旧版)

    googletag.companionAds().setRefreshUnfilledSlots(true);
    

    TypeScript

    googletag.companionAds().setRefreshUnfilledSlots(true);
    
    参数
    value: booleantrue 表示自动回填未填充的槽位,false 表示保持不变。


googletag.PrivacySettingsConfig

隐私设置的配置对象。
属性
childDirectedTreatment?
指示相应网页是否应视为面向儿童的内容
limitedAds?
启用受限广告模式,以便满足发布商的法规遵从需求。
nonPersonalizedAds?
启用非个性化广告模式,以帮助发布商满足法规遵从要求。
restrictDataProcessing?
使广告投放在受限处理模式下运行,以帮助发布商满足监管合规性要求。
trafficSource?
指明请求是代表付费流量还是自然流量。
underAgeOfConsent?
指示是否将广告请求标记为来自未达到法定承诺年龄的用户。
另请参阅

属性


Optional childDirectedTreatment


Optional 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,
    });
    
    另请参阅

Optional nonPersonalizedAds

    nonPersonalizedAds?: boolean

    启用非个性化广告模式,以帮助发布商满足法规遵从要求。


Optional restrictDataProcessing

    restrictDataProcessing?: boolean

    使广告投放在受限处理模式下运行,以帮助发布商满足监管合规性要求。


Optional trafficSource

    trafficSource?: TrafficSource

    指明请求是代表付费流量还是自然流量。此值用于填充 Ad Manager 报告中的流量来源维度。如果未设置,则在报告中流量来源默认为 undefined

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

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

Optional underAgeOfConsent

    underAgeOfConsent?: null | boolean

    指示是否将广告请求标记为来自未达到法定承诺年龄的用户。设置为 null 可清除配置。


googletag.PubAdsService

扩展了 Service
发布商广告服务。此服务用于提取并展示您 Google Ad Manager 账号中的广告。
方法
addEventListener
注册监听器,以便您在网页上发生特定 GPT 事件时设置和调用 JavaScript 函数。
clear
从给定槽中移除广告,并将其替换为空白内容。
clearCategoryExclusions
清除所有网页级广告类别排除标签。
clearTargeting
清除特定键或所有键的自定义定位参数。
collapseEmptyDivs
启用广告位 div 的合拢功能,以便在没有要显示的广告内容时,这些 div 不会占用网页上的任何空间。
disableInitialLoad
在网页加载时停用广告请求,但允许通过 PubAdsService.refresh 调用请求广告。
display
使用指定的广告单元路径和尺寸构建并显示广告位。
enableLazyLoad
启用配置对象中定义的 GPT 中的延迟加载。
enableSingleRequest
启用单个请求模式,以便同时提取多个广告。
enableVideoAds
向 GPT 发出信号,指示网页上将展示视频广告。
get
返回与给定键关联的 AdSense 属性的值。
getAttributeKeys
返回已在此服务上设置的属性键。
getSlots
获取与此服务关联的槽位列表。
getTargeting
返回已设置的特定自定义服务级定位参数。
getTargetingKeys
返回已设置的所有自定义服务级定位键的列表。
isInitialLoadDisabled
返回之前的 PubAdsService.disableInitialLoad 调用是否成功停用了广告的初始请求。
refresh
为网页上的特定广告位或所有广告位提取并显示新广告。
removeEventListener
移除之前注册的监听器。
set
为适用于发布商广告服务下的所有广告位的 AdSense 属性设置值。
setCategoryExclusion
为指定的标签名称设置页面级广告类别排除。
setCentering
启用和停用横向居中显示广告。
setForceSafeFrame
配置是否应强制使用 SafeFrame 容器呈现网页上的所有广告。
setLocation
传递网站的位置信息,以便您将订单项地理位置定位到特定位置。
setPrivacySettings
允许使用配置对象通过单个 API 配置所有隐私设置。
setPublisherProvidedId
为发布商提供的 ID 设置值。
setSafeFrameConfig
为 SafeFrame 配置设置页面级偏好设置。
setTargeting
为给定键设置自定义定位参数,这些参数适用于所有发布商广告服务广告位。
setVideoContent
设置要随广告请求一起发送的视频内容信息,以便进行定位和内容排除。
updateCorrelator
更改随广告请求一起发送的相关方,从而有效地开始新的网页浏览。

方法


清除

    clear(slots?: Slot[]): boolean

    从给定槽中移除广告,并将其替换为空白内容。这些槽位将被标记为未提取。

    具体而言,清除槽位会将广告从 GPT 的长时段网页浏览中移除,因此未来的请求不会受到涉及此广告的拦截或竞争排除的影响。

    示例

    JavaScript

    const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
    googletag.display("div-1");
    const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2");
    googletag.display("div-2");
    
    // This call to clear only slot1.
    googletag.pubads().clear([slot1]);
    
    // This call to clear both slot1 and slot2.
    googletag.pubads().clear([slot1, slot2]);
    
    // This call to clear all slots.
    googletag.pubads().clear();
    

    JavaScript(旧版)

    var slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
    googletag.display("div-1");
    var slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2");
    googletag.display("div-2");
    
    // This call to clear only slot1.
    googletag.pubads().clear([slot1]);
    
    // This call to clear both slot1 and slot2.
    googletag.pubads().clear([slot1, slot2]);
    
    // This call to clear all slots.
    googletag.pubads().clear();
    

    TypeScript

    const slot1 = googletag.defineSlot("/1234567/sports", [728, 90], "div-1")!;
    googletag.display("div-1");
    const slot2 = googletag.defineSlot("/1234567/news", [160, 600], "div-2")!;
    googletag.display("div-2");
    
    // This call to clear only slot1.
    googletag.pubads().clear([slot1]);
    
    // This call to clear both slot1 and slot2.
    googletag.pubads().clear([slot1, slot2]);
    
    // This call to clear all slots.
    googletag.pubads().clear();
    
    参数
    Optional slots: Slot[]要清除的槽的数组。数组是可选的;如果未指定,则会清除所有槽位。
    返回结果
    boolean如果槽位已清除,则返回 true;否则返回 false


clearCategoryExclusions

    clearCategoryExclusions(): PubAdsService

    清除所有网页级广告类别排除标签。如果您想刷新槽,这会非常有用。

    示例

    JavaScript

    // Set category exclusion to exclude ads with 'AirlineAd' labels.
    googletag.pubads().setCategoryExclusion("AirlineAd");
    
    // Make ad requests. No ad with 'AirlineAd' label will be returned.
    
    // Clear category exclusions so all ads can be returned.
    googletag.pubads().clearCategoryExclusions();
    
    // Make ad requests. Any ad can be returned.
    

    JavaScript(旧版)

    // Set category exclusion to exclude ads with 'AirlineAd' labels.
    googletag.pubads().setCategoryExclusion("AirlineAd");
    
    // Make ad requests. No ad with 'AirlineAd' label will be returned.
    
    // Clear category exclusions so all ads can be returned.
    googletag.pubads().clearCategoryExclusions();
    
    // Make ad requests. Any ad can be returned.
    

    TypeScript

    // Set category exclusion to exclude ads with 'AirlineAd' labels.
    googletag.pubads().setCategoryExclusion("AirlineAd");
    
    // Make ad requests. No ad with 'AirlineAd' label will be returned.
    
    // Clear category exclusions so all ads can be returned.
    googletag.pubads().clearCategoryExclusions();
    
    // Make ad requests. Any ad can be returned.
    
    另请参阅
    返回结果
    PubAdsService调用该方法的服务对象。


clearTargeting

    clearTargeting(key?: string): PubAdsService

    清除特定键或所有键的自定义定位参数。

    示例

    JavaScript

    googletag.pubads().setTargeting("interests", "sports");
    googletag.pubads().setTargeting("colors", "blue");
    googletag.pubads().setTargeting("fruits", "apple");
    
    googletag.pubads().clearTargeting("interests");
    // Targeting 'colors' and 'fruits' are still present, while 'interests'
    // was cleared.
    
    googletag.pubads().clearTargeting();
    // All targeting has been cleared.
    

    JavaScript(旧版)

    googletag.pubads().setTargeting("interests", "sports");
    googletag.pubads().setTargeting("colors", "blue");
    googletag.pubads().setTargeting("fruits", "apple");
    
    googletag.pubads().clearTargeting("interests");
    // Targeting 'colors' and 'fruits' are still present, while 'interests'
    // was cleared.
    
    googletag.pubads().clearTargeting();
    // All targeting has been cleared.
    

    TypeScript

    googletag.pubads().setTargeting("interests", "sports");
    googletag.pubads().setTargeting("colors", "blue");
    googletag.pubads().setTargeting("fruits", "apple");
    
    googletag.pubads().clearTargeting("interests");
    // Targeting 'colors' and 'fruits' are still present, while 'interests'
    // was cleared.
    
    googletag.pubads().clearTargeting();
    // All targeting has been cleared.
    
    另请参阅
    参数
    Optional key: string定位参数键。此键是可选的;如果未指定,系统会清除所有定位参数。
    返回结果
    PubAdsService调用该方法的服务对象。


collapseEmptyDivs

    collapseEmptyDivs(collapseBeforeAdFetch?: boolean): boolean

    启用广告位 div 的合拢功能,以便在没有要显示的广告内容时,这些 div 不会占用网页上的任何空间。必须先设置此模式,然后才能启用该服务。

    另请参阅
    参数
    Optional collapseBeforeAdFetch: boolean是否在获取广告之前收起广告位。此参数是可选参数;如果未提供,系统将使用 false 作为默认值。
    返回结果
    boolean如果已启用 div 收起模式,则返回 true;如果由于在启用服务后调用了此方法而无法启用收起模式,则返回 false


disableInitialLoad


显示

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

    使用指定的广告单元路径和尺寸构建并显示广告位。此方法不适用于单个请求模式。

    注意:调用此方法时,系统会创建槽和页面状态的快照,以确保在发送广告请求和呈现响应时保持一致性。调用此方法后对槽或页面状态所做的任何更改(包括定位、隐私设置、强制使用 SafeFrame 等)都只会应用于后续的 display()refresh() 请求。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.pubads().display("/1234567/sports", [728, 90], "div-1");
    
    另请参阅
    参数
    adUnitPath: string要呈现的广告位的广告单元路径
    size: GeneralSize槽的宽度和高度。
    Optional div: string | Element包含槽的 div 的 ID 或 div 元素本身。
    Optional clickUrl: string要在此广告位上使用的点击后到达网址。


enableLazyLoad

    enableLazyLoad(config?: {
      fetchMarginPercent?: number;
      mobileScaling?: number;
      renderMarginPercent?: number;
    }): void

    启用配置对象定义的 GPT 中的延迟加载。如需查看更详细的示例,请参阅延迟加载示例。

    注意:只有当所有槽都超出提取边距时,SRA 中的延迟提取才会起作用。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.pubads().enableLazyLoad({
      // Fetch slots within 5 viewports.
      fetchMarginPercent: 500,
      // Render slots within 2 viewports.
      renderMarginPercent: 200,
      // Double the above values on mobile.
      mobileScaling: 2.0,
    });
    
    另请参阅
    参数
    Optional config: {
      fetchMarginPercent?: number;
      mobileScaling?: number;
      renderMarginPercent?: number;
    }
    配置对象允许自定义延迟行为。所有省略的配置都将使用 Google 设置的默认配置,该配置会随着时间的推移进行调整。如需停用特定设置(例如提取边距),请将值设置为 -1
    • fetchMarginPercent

      广告位距离当前视口的最小距离(以视口大小的百分比表示),在达到此距离之前,我们不会提取广告。值为 0 表示“广告位进入视口时”,100 表示“广告距离视口 1 个视口时”,以此类推。
    • renderMarginPercent

      广告位必须距离当前视口的最小距离,我们才会呈现广告。这样可以预加载广告,但会等待呈现和下载其他子资源。此值的运作方式与 fetchMarginPercent 相同,表示视口的百分比。
    • mobileScaling

      应用于移动设备上边距的乘数。这样一来,您就可以在移动设备和桌面设备上设置不同的边距。例如,如果值为 2.0,则会在移动设备上将所有边距乘以 2,从而增加槽在提取和呈现之前的最小距离。


enableSingleRequest

    enableSingleRequest(): boolean

    启用单个请求模式,以便同时提取多个广告。为此,您需要先定义所有发布商广告位并将其添加到 PubAdsService,然后才能启用该服务。必须先设置单次请求模式,然后才能启用该服务。

    另请参阅
    返回结果
    boolean如果已启用单一请求模式,则返回 true;如果由于在启用服务后调用了该方法而无法启用单一请求模式,则返回 false


enableVideoAds

    enableVideoAds(): void

    向 GPT 发出信号,指示网页上将展示视频广告。这样,就可以对展示广告和视频广告启用竞争排除限制。如果已知视频内容,请调用 PubAdsService.setVideoContent,以便对展示广告使用内容排除功能。


get

    get(key: string): null | string

    返回与给定键关联的 AdSense 属性的值。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.pubads().set("adsense_background_color", "#FFFFFF");
    googletag.pubads().get("adsense_background_color");
    // Returns '#FFFFFF'.
    
    另请参阅
    参数
    key: string要查找的属性的名称。
    返回结果
    null | string属性键的当前值,如果不存在该键,则为 null


getAttributeKeys

    getAttributeKeys(): string[]

    返回已在此服务上设置的属性键。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.pubads().set("adsense_background_color", "#FFFFFF");
    googletag.pubads().set("adsense_border_color", "#AABBCC");
    googletag.pubads().getAttributeKeys();
    // Returns ['adsense_background_color', 'adsense_border_color'].
    
    返回结果
    string[]在此服务上设置的属性键的数组。顺序未定义。


getTargeting

    getTargeting(key: string): string[]

    返回已设置的特定自定义服务级定位参数。

    示例

    JavaScript

    googletag.pubads().setTargeting("interests", "sports");
    
    googletag.pubads().getTargeting("interests");
    // Returns ['sports'].
    
    googletag.pubads().getTargeting("age");
    // Returns [] (empty array).
    

    JavaScript(旧版)

    googletag.pubads().setTargeting("interests", "sports");
    
    googletag.pubads().getTargeting("interests");
    // Returns ['sports'].
    
    googletag.pubads().getTargeting("age");
    // Returns [] (empty array).
    

    TypeScript

    googletag.pubads().setTargeting("interests", "sports");
    
    googletag.pubads().getTargeting("interests");
    // Returns ['sports'].
    
    googletag.pubads().getTargeting("age");
    // Returns [] (empty array).
    
    参数
    key: string要查找的定位键。
    返回结果
    string[]与此键关联的值;如果没有此类键,则返回一个空数组。


getTargetingKeys

    getTargetingKeys(): string[]

    返回已设置的所有自定义服务级定位键的列表。

    示例

    JavaScript

    googletag.pubads().setTargeting("interests", "sports");
    googletag.pubads().setTargeting("colors", "blue");
    
    googletag.pubads().getTargetingKeys();
    // Returns ['interests', 'colors'].
    

    JavaScript(旧版)

    googletag.pubads().setTargeting("interests", "sports");
    googletag.pubads().setTargeting("colors", "blue");
    
    googletag.pubads().getTargetingKeys();
    // Returns ['interests', 'colors'].
    

    TypeScript

    googletag.pubads().setTargeting("interests", "sports");
    googletag.pubads().setTargeting("colors", "blue");
    
    googletag.pubads().getTargetingKeys();
    // Returns ['interests', 'colors'].
    
    返回结果
    string[]定位键数组。顺序未定义。


isInitialLoadDisabled


刷新

    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 });
    
    另请参阅
    参数
    Optional slots: null | Slot[]要刷新的槽。数组是可选项;如果未指定,则会刷新所有槽位。
    Optional options: {
      changeCorrelator: boolean;
    }
    与此刷新调用关联的配置选项。
    • changeCorrelator

      指定是否要为提取广告生成新的相关器。我们的广告服务器会短暂地保留此 Correlator 值(目前为 30 秒,但可能会发生变化),因此收到时间非常靠近且具有相同 Correlator 值的请求会被视为一次网页浏览。默认情况下,系统会为每次刷新生成一个新的相关器。

      注意:此选项对 GPT 的长时段网页浏览没有影响,后者会自动反映网页上当前显示的广告,并且没有到期时间。


set

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

    为适用于发布商广告服务下的所有广告位的 AdSense 属性设置值。

    如果对同一键多次调用此方法,系统会覆盖之前为该键设置的值。必须先设置所有值,然后才能调用 displayrefresh

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.pubads().set("adsense_background_color", "#FFFFFF");
    
    另请参阅
    参数
    key: string属性的名称。
    value: string属性值。
    返回结果
    PubAdsService调用该方法的服务对象。


setCategoryExclusion

    setCategoryExclusion(categoryExclusion: string): PubAdsService

    为指定的标签名称设置页面级广告类别排除。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // Label = AirlineAd.
    googletag.pubads().setCategoryExclusion("AirlineAd");
    
    另请参阅
    参数
    categoryExclusion: string要添加的广告类别排除标签。
    返回结果
    PubAdsService调用该方法的服务对象。


setCentering

    setCentering(centerAds: boolean): void

    启用和停用广告的水平居中。居中功能默认处于停用状态。在旧版 gpt_mobile.js 中,居中显示默认处于启用状态。

    应先调用此方法,然后再调用 displayrefresh,因为只有在调用此方法后请求的广告才会居中显示。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // Make ads centered.
    googletag.pubads().setCentering(true);
    
    参数
    centerAds: booleantrue 表示居中放置广告,false 表示左对齐广告。


setForceSafeFrame

    setForceSafeFrame(forceSafeFrame: boolean): PubAdsService

    配置是否应强制使用 SafeFrame 容器呈现网页上的所有广告。

    使用此 API 时,请注意以下事项:

    • 此设置仅适用于针对相应广告位发出的后续广告请求。
    • 广告位级设置(如果指定)始终会替换网页级设置。
    • 如果设置为 true(在广告位一级或网页一级),系统将始终使用 SafeFrame 容器呈现广告,无论 Google Ad Manager 界面中做出了什么选择。
    • 不过,如果将其设置为 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");
    
    另请参阅
    参数
    forceSafeFrame: booleantrue 以强制在 SafeFrames 中呈现网页上的所有广告,false 则会将之前的设置更改为 false。如果之前未指定此值,将其设为 false 不会改变任何内容。
    返回结果
    PubAdsService调用函数的服务对象。


setLocation

    setLocation(address: string): PubAdsService

    传递网站的位置信息,以便您将订单项地理位置定位到特定位置。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // Postal code:
    googletag.pubads().setLocation("10001,US");
    
    参数
    address: string不限格式的地址。
    返回结果
    PubAdsService调用该方法的服务对象。


setPrivacySettings

    setPrivacySettings(privacySettings: PrivacySettingsConfig): PubAdsService

    允许使用配置对象通过单个 API 配置所有隐私设置。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.pubads().setPrivacySettings({
      restrictDataProcessing: true,
    });
    
    // Set multiple privacy settings at the same time.
    googletag.pubads().setPrivacySettings({
      childDirectedTreatment: true,
      underAgeOfConsent: true,
    });
    
    // Clear the configuration for childDirectedTreatment.
    googletag.pubads().setPrivacySettings({
      childDirectedTreatment: null,
    });
    
    另请参阅
    参数
    privacySettings: PrivacySettingsConfig包含隐私设置配置的对象。
    返回结果
    PubAdsService调用函数的服务对象。


setPublisherProvidedId

    setPublisherProvidedId(ppid: string): PubAdsService

    为发布商提供的 ID 设置值。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.pubads().setPublisherProvidedId("12JD92JD8078S8J29SDOAKC0EF230337");
    
    另请参阅
    参数
    ppid: string发布商提供的一个由字母和数字组成的 ID。长度必须介于 32 到 150 个字符之间。
    返回结果
    PubAdsService调用该方法的服务对象。


setSafeFrameConfig

    setSafeFrameConfig(config: SafeFrameConfig): PubAdsService

    为 SafeFrame 配置设置页面级偏好设置。配置对象中的所有无法识别的键都会被忽略。如果为已识别的键传递无效值,系统会忽略整个配置。

    这些网页级偏好设置将被槽级偏好设置(如果指定)替换。

    示例

    JavaScript

    googletag.pubads().setForceSafeFrame(true);
    
    const pageConfig = {
      allowOverlayExpansion: true,
      allowPushExpansion: true,
      sandbox: true,
    };
    
    const slotConfig = { allowOverlayExpansion: false };
    
    googletag.pubads().setSafeFrameConfig(pageConfig);
    
    // The following slot will not allow for expansion by overlay.
    googletag
      .defineSlot("/1234567/sports", [160, 600], "div-1")
      .setSafeFrameConfig(slotConfig)
      .addService(googletag.pubads());
    
    // The following slot will inherit the page level settings, and hence
    // would allow for expansion by overlay.
    googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads());
    
    googletag.display("div-1");
    googletag.display("div-2");
    

    JavaScript(旧版)

    googletag.pubads().setForceSafeFrame(true);
    
    var pageConfig = {
      allowOverlayExpansion: true,
      allowPushExpansion: true,
      sandbox: true,
    };
    
    var slotConfig = { allowOverlayExpansion: false };
    
    googletag.pubads().setSafeFrameConfig(pageConfig);
    
    // The following slot will not allow for expansion by overlay.
    googletag
      .defineSlot("/1234567/sports", [160, 600], "div-1")
      .setSafeFrameConfig(slotConfig)
      .addService(googletag.pubads());
    
    // The following slot will inherit the page level settings, and hence
    // would allow for expansion by overlay.
    googletag.defineSlot("/1234567/news", [160, 600], "div-2").addService(googletag.pubads());
    
    googletag.display("div-1");
    googletag.display("div-2");
    

    TypeScript

    googletag.pubads().setForceSafeFrame(true);
    
    const pageConfig = {
      allowOverlayExpansion: true,
      allowPushExpansion: true,
      sandbox: true,
    };
    
    const slotConfig = { allowOverlayExpansion: false };
    
    googletag.pubads().setSafeFrameConfig(pageConfig);
    
    // The following slot will not allow for expansion by overlay.
    googletag
      .defineSlot("/1234567/sports", [160, 600], "div-1")!
      .setSafeFrameConfig(slotConfig)
      .addService(googletag.pubads());
    
    // The following slot will inherit the page level settings, and hence
    // would allow for expansion by overlay.
    googletag.defineSlot("/1234567/news", [160, 600], "div-2")!.addService(googletag.pubads());
    
    googletag.display("div-1");
    googletag.display("div-2");
    
    另请参阅
    参数
    config: SafeFrameConfig配置对象。
    返回结果
    PubAdsService调用该方法的服务对象。


setTargeting

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

    为给定键设置自定义定位参数,这些参数适用于所有发布商广告服务广告位。针对同一键多次调用此方法会覆盖旧值。这些键是在您的 Google Ad Manager 账号中定义的。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // Example with a single value for a key.
    googletag.pubads().setTargeting("interests", "sports");
    
    // Example with multiple values for a key inside in an array.
    googletag.pubads().setTargeting("interests", ["sports", "music"]);
    
    另请参阅
    参数
    key: string定位参数键。
    value: string | string[]定位参数值或值数组。
    返回结果
    PubAdsService调用该方法的服务对象。


setVideoContent

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

    设置要随广告请求一起发送的视频内容信息,以便进行定位和内容排除。调用此方法时,系统会自动启用视频广告。对于 videoContentIdvideoCmsId,请使用提供给 Google Ad Manager 内容提取服务的值。

    另请参阅
    参数
    videoContentId: string视频内容 ID。
    videoCmsId: string视频 CMS ID。


updateCorrelator

    updateCorrelator(): PubAdsService

    更改随广告请求一起发送的协调 ID,从而有效地开始新的网页浏览。来自一次网页浏览的所有广告请求具有相同的 Correlator 值,并且针对每次网页浏览,这个值都是独一无二的。仅适用于异步模式。

    注意:这对 GPT 的长时段网页浏览没有影响,后者会自动反映网页上实际显示的广告,并且没有到期时间。

    示例

    JavaScript

    // Assume that the correlator is currently 12345. All ad requests made
    // by this page will currently use that value.
    
    // Replace the current correlator with a new correlator.
    googletag.pubads().updateCorrelator();
    
    // The correlator will now be a new randomly selected value, different
    // from 12345. All subsequent ad requests made by this page will use
    // the new value.
    

    JavaScript(旧版)

    // Assume that the correlator is currently 12345. All ad requests made
    // by this page will currently use that value.
    
    // Replace the current correlator with a new correlator.
    googletag.pubads().updateCorrelator();
    
    // The correlator will now be a new randomly selected value, different
    // from 12345. All subsequent ad requests made by this page will use
    // the new value.
    

    TypeScript

    // Assume that the correlator is currently 12345. All ad requests made
    // by this page will currently use that value.
    
    // Replace the current correlator with a new correlator.
    googletag.pubads().updateCorrelator();
    
    // The correlator will now be a new randomly selected value, different
    // from 12345. All subsequent ad requests made by this page will use
    // the new value.
    
    返回结果
    PubAdsService调用函数的服务对象。


googletag.ResponseInformation

表示单个广告响应的对象。
属性
advertiserId
广告客户的 ID。
campaignId
广告系列的 ID。
creativeId
广告素材的 ID。
creativeTemplateId
广告的模板 ID。
lineItemId
订单项的 ID。
另请参阅

属性


advertiserId

    advertiserId: null | number

    广告客户的 ID。


campaignId

    campaignId: null | number

    广告系列的 ID。


creativeId

    creativeId: null | number

    广告素材的 ID。


creativeTemplateId

    creativeTemplateId: null | number

    广告的模板 ID。


lineItemId

    lineItemId: null | number

    订单项的 ID。


googletag.RewardedPayload

表示与激励广告关联的奖励的对象
属性
amount
奖励中包含的项的数量。
type
奖励中包含的项的类型(例如“coin”)。
另请参阅

属性


金额

    amount: number

    奖励中包含的项的数量。


type

    type: string

    奖励中包含的项的类型(例如“coin”)。


googletag.SafeFrameConfig

SafeFrame 容器的配置对象。
属性
allowOverlayExpansion?
SafeFrame 是否应允许广告内容通过叠加网页内容进行展开。
allowPushExpansion?
SafeFrame 是否应允许广告内容通过推送网页内容进行展开。
sandbox?
SafeFrame 是否应使用 HTML5 沙盒属性来阻止在无用户互动的情况下进行顶级导航。
useUniqueDomain?
已废弃。 SafeFrame 是否应为预订型广告素材使用随机子网域。
另请参阅

属性


Optional allowOverlayExpansion

    allowOverlayExpansion?: boolean

    SafeFrame 是否应允许广告内容通过叠加网页内容进行展开。


Optional allowPushExpansion

    allowPushExpansion?: boolean

    SafeFrame 是否应允许广告内容通过推送网页内容进行展开。


Optional 沙盒

    sandbox?: boolean

    SafeFrame 是否应使用 HTML5 沙盒属性来阻止在无用户互动的情况下进行顶级导航。唯一的有效值为 true(无法强制设为 false)。请注意,沙盒属性会停用插件(例如 Flash)。


Optional useUniqueDomain

    useUniqueDomain?: null | boolean

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

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

    另请参阅

googletag.Service

包含适用于所有服务的通用方法的基准服务类。
方法
addEventListener
注册监听器,以便您在网页上发生特定 GPT 事件时设置和调用 JavaScript 函数。
getSlots
获取与此服务关联的槽位列表。
removeEventListener
移除之前注册的监听器。

方法


addEventListener

    addEventListener<K extends keyof EventTypeMap>(eventType: K, listener: ((arg: EventTypeMap[K]) => void)): Service

    注册监听器,以便您在网页上发生特定 GPT 事件时设置和调用 JavaScript 函数。支持以下事件:

    调用监听器时,系统会将相应事件类型的对象传递给监听器。
    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // 1. Adding an event listener for the PubAdsService.
    googletag.pubads().addEventListener("slotOnload", (event) => {
      console.log("Slot has been loaded:");
      console.log(event);
    });
    
    // 2. Adding an event listener with slot specific logic.
    // Listeners operate at service level, which means that you cannot add
    // a listener for an event for a specific slot only. You can, however,
    // programmatically filter a listener to respond only to a certain ad
    // slot, using this pattern:
    const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
    googletag.pubads().addEventListener("slotOnload", (event) => {
      if (event.slot === targetSlot) {
        // Slot specific logic.
      }
    });
    
    另请参阅
    参数
    eventType: K表示 GPT 生成的事件类型的字符串。事件类型区分大小写。
    listener: ((arg: EventTypeMap[K]) => void)接受单个事件对象参数的函数。
    返回结果
    Service调用该方法的服务对象。


getSlots

    getSlots(): Slot[]

    获取与此服务关联的槽位列表。

    返回结果
    Slot[]槽,按添加到服务中的顺序。


removeEventListener

    removeEventListener<K extends keyof EventTypeMap>(eventType: K, listener: ((event: EventTypeMap[K]) => void)): void

    移除之前注册的监听器。

    示例

    JavaScript

    googletag.cmd.push(() => {
      // Define a new ad slot.
      googletag.defineSlot("/6355419/Travel", [728, 90], "div-for-slot").addService(googletag.pubads());
    
      // Define a new function that removes itself via removeEventListener
      // after the impressionViewable event fires.
      const onViewableListener = (event) => {
        googletag.pubads().removeEventListener("impressionViewable", onViewableListener);
        setTimeout(() => {
          googletag.pubads().refresh([event.slot]);
        }, 30000);
      };
    
      // Add onViewableListener as a listener for impressionViewable events.
      googletag.pubads().addEventListener("impressionViewable", onViewableListener);
      googletag.enableServices();
    });
    

    JavaScript(旧版)

    googletag.cmd.push(function () {
      // Define a new ad slot.
      googletag.defineSlot("/6355419/Travel", [728, 90], "div-for-slot").addService(googletag.pubads());
    
      // Define a new function that removes itself via removeEventListener
      // after the impressionViewable event fires.
      var onViewableListener = function (event) {
        googletag.pubads().removeEventListener("impressionViewable", onViewableListener);
        setTimeout(function () {
          googletag.pubads().refresh([event.slot]);
        }, 30000);
      };
    
      // Add onViewableListener as a listener for impressionViewable events.
      googletag.pubads().addEventListener("impressionViewable", onViewableListener);
      googletag.enableServices();
    });
    

    TypeScript

    googletag.cmd.push(() => {
      // Define a new ad slot.
      googletag
        .defineSlot("/6355419/Travel", [728, 90], "div-for-slot")!
        .addService(googletag.pubads());
    
      // Define a new function that removes itself via removeEventListener
      // after the impressionViewable event fires.
      const onViewableListener = (event: googletag.events.ImpressionViewableEvent) => {
        googletag.pubads().removeEventListener("impressionViewable", onViewableListener);
        setTimeout(() => {
          googletag.pubads().refresh([event.slot]);
        }, 30000);
      };
    
      // Add onViewableListener as a listener for impressionViewable events.
      googletag.pubads().addEventListener("impressionViewable", onViewableListener);
      googletag.enableServices();
    });
    
    参数
    eventType: K表示 GPT 生成的事件类型的字符串。事件类型区分大小写。
    listener: ((event: EventTypeMap[K]) => void)接受单个事件对象参数的函数。


googletag.SizeMappingBuilder

尺寸映射规范对象的构建器。此构建器旨在帮助您轻松构建尺寸规范。
方法
addSize
添加从单尺寸数组(表示视口)到表示槽的单尺寸或多尺寸数组的映射。
build
根据添加到此构建器的映射构建尺寸映射规范。
另请参阅

方法


addSize

    addSize(viewportSize: SingleSizeArray, slotSize: GeneralSize): SizeMappingBuilder

    添加从单尺寸数组(表示视口)到表示槽的单尺寸或多尺寸数组的映射。

    示例

    JavaScript

    // Mapping 1
    googletag
      .sizeMapping()
      .addSize([1024, 768], [970, 250])
      .addSize([980, 690], [728, 90])
      .addSize([640, 480], "fluid")
      .addSize([0, 0], [88, 31]) // All viewports &lt; 640x480
      .build();
    
    // Mapping 2
    googletag
      .sizeMapping()
      .addSize([1024, 768], [970, 250])
      .addSize([980, 690], [])
      .addSize([640, 480], [120, 60])
      .addSize([0, 0], [])
      .build();
    
    // Mapping 2 will not show any ads for the following viewport sizes:
    // [1024, 768] > size >= [980, 690] and
    // [640, 480] > size >= [0, 0]
    

    JavaScript(旧版)

    // Mapping 1
    googletag
      .sizeMapping()
      .addSize([1024, 768], [970, 250])
      .addSize([980, 690], [728, 90])
      .addSize([640, 480], "fluid")
      .addSize([0, 0], [88, 31]) // All viewports &lt; 640x480
      .build();
    
    // Mapping 2
    googletag
      .sizeMapping()
      .addSize([1024, 768], [970, 250])
      .addSize([980, 690], [])
      .addSize([640, 480], [120, 60])
      .addSize([0, 0], [])
      .build();
    
    // Mapping 2 will not show any ads for the following viewport sizes:
    // [1024, 768] > size >= [980, 690] and
    // [640, 480] > size >= [0, 0]
    

    TypeScript

    // Mapping 1
    googletag
      .sizeMapping()
      .addSize([1024, 768], [970, 250])
      .addSize([980, 690], [728, 90])
      .addSize([640, 480], "fluid")
      .addSize([0, 0], [88, 31]) // All viewports &lt; 640x480
      .build();
    
    // Mapping 2
    googletag
      .sizeMapping()
      .addSize([1024, 768], [970, 250])
      .addSize([980, 690], [])
      .addSize([640, 480], [120, 60])
      .addSize([0, 0], [])
      .build();
    
    // Mapping 2 will not show any ads for the following viewport sizes:
    // [1024, 768] > size >= [980, 690] and
    // [640, 480] > size >= [0, 0]
    
    参数
    viewportSize: SingleSizeArray此映射条目的视口大小。
    slotSize: GeneralSize此映射条目的槽大小。
    返回结果
    SizeMappingBuilder对此构建器的引用。


build

    build(): null | SizeMappingArray

    根据添加到此构建器的映射构建尺寸映射规范。

    如果提供了任何无效的映射,此方法将返回 null。否则,它会返回格式正确的规范,以便传递给 Slot.defineSizeMapping

    注意:调用此方法后,构建器的行为未定义。

    返回结果
    null | SizeMappingArray此构建器构建的结果。如果提供的尺寸映射无效,则可以为 null。


googletag.Slot

广告位是表示网页上单个广告位的对象。
方法
addService
向此槽添加服务
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

    向此槽添加服务

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.defineSlot("/1234567/sports", [160, 600], "div")!.addService(googletag.pubads());
    
    另请参阅
    参数
    service: Service要添加的服务。
    返回结果
    Slot调用该方法的槽对象。


clearCategoryExclusions

    clearCategoryExclusions(): Slot

    清除此广告位的所有广告位级广告类别排除标签。

    示例

    JavaScript

    // Set category exclusion to exclude ads with 'AirlineAd' labels.
    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")
      .setCategoryExclusion("AirlineAd")
      .addService(googletag.pubads());
    
    // Make an ad request. No ad with 'AirlineAd' label will be returned
    // for the slot.
    
    // Clear category exclusions so all ads can be returned.
    slot.clearCategoryExclusions();
    
    // Make an ad request. Any ad can be returned for the slot.
    

    JavaScript(旧版)

    // Set category exclusion to exclude ads with 'AirlineAd' labels.
    var slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")
      .setCategoryExclusion("AirlineAd")
      .addService(googletag.pubads());
    
    // Make an ad request. No ad with 'AirlineAd' label will be returned
    // for the slot.
    
    // Clear category exclusions so all ads can be returned.
    slot.clearCategoryExclusions();
    
    // Make an ad request. Any ad can be returned for the slot.
    

    TypeScript

    // Set category exclusion to exclude ads with 'AirlineAd' labels.
    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .setCategoryExclusion("AirlineAd")
      .addService(googletag.pubads());
    
    // Make an ad request. No ad with 'AirlineAd' label will be returned
    // for the slot.
    
    // Clear category exclusions so all ads can be returned.
    slot.clearCategoryExclusions();
    
    // Make an ad request. Any ad can be returned for the slot.
    
    返回结果
    Slot调用该方法的槽对象。


clearTargeting

    clearTargeting(key?: string): Slot

    清除此广告位的特定或所有自定义广告位级定位参数。

    示例

    JavaScript

    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")
      .setTargeting("allow_expandable", "true")
      .setTargeting("interests", ["sports", "music"])
      .setTargeting("color", "red")
      .addService(googletag.pubads());
    
    slot.clearTargeting("color");
    // Targeting 'allow_expandable' and 'interests' are still present,
    // while 'color' was cleared.
    
    slot.clearTargeting();
    // All targeting has been cleared.
    

    JavaScript(旧版)

    var slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")
      .setTargeting("allow_expandable", "true")
      .setTargeting("interests", ["sports", "music"])
      .setTargeting("color", "red")
      .addService(googletag.pubads());
    
    slot.clearTargeting("color");
    // Targeting 'allow_expandable' and 'interests' are still present,
    // while 'color' was cleared.
    
    slot.clearTargeting();
    // All targeting has been cleared.
    

    TypeScript

    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .setTargeting("allow_expandable", "true")
      .setTargeting("interests", ["sports", "music"])
      .setTargeting("color", "red")
      .addService(googletag.pubads());
    
    slot.clearTargeting("color");
    // Targeting 'allow_expandable' and 'interests' are still present,
    // while 'color' was cleared.
    
    slot.clearTargeting();
    // All targeting has been cleared.
    
    另请参阅
    参数
    Optional key: string定位参数键。此键是可选的;如果未指定,系统会清除所有定位参数。
    返回结果
    Slot调用该方法的槽对象。


defineSizeMapping

    defineSizeMapping(sizeMapping: SizeMappingArray): Slot

    为此槽设置从最小视口大小到槽大小的映射数组。

    示例

    JavaScript

    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")
      .addService(googletag.pubads());
    
    const mapping = googletag
      .sizeMapping()
      .addSize([100, 100], [88, 31])
      .addSize(
        [320, 400],
        [
          [320, 50],
          [300, 50],
        ],
      )
      .build();
    
    slot.defineSizeMapping(mapping);
    

    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 创建它。每个尺寸映射都是由两个元素组成的数组:SingleSizeArrayGeneralSize
    返回结果
    Slot调用该方法的槽对象。


get

    get(key: string): null | string

    返回与此广告位的给定键关联的 AdSense 属性的值。如需查看此广告位继承的服务级属性,请使用 PubAdsService.get

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .set("adsense_background_color", "#FFFFFF")
      .addService(googletag.pubads());
    
    slot.get("adsense_background_color");
    // Returns '#FFFFFF'.
    
    另请参阅
    参数
    key: string要查找的属性的名称。
    返回结果
    null | string属性键的当前值,如果不存在该键,则为 null


getAdUnitPath

    getAdUnitPath(): string

    返回广告单元的完整路径,其中包含广告资源网代码和广告单元路径。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .addService(googletag.pubads());
    
    slot.getAdUnitPath();
    // Returns '/1234567/sports'.
    
    返回结果
    string广告单元路径。


getAttributeKeys

    getAttributeKeys(): string[]

    返回在此槽上设置的属性键的列表。如需查看此广告位继承的服务级属性的键,请使用 PubAdsService.getAttributeKeys

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .set("adsense_background_color", "#FFFFFF")
      .set("adsense_border_color", "#AABBCC")
      .addService(googletag.pubads());
    
    slot.getAttributeKeys();
    // Returns ['adsense_background_color', 'adsense_border_color'].
    
    返回结果
    string[]属性键的数组。顺序未定义。


getCategoryExclusions

    getCategoryExclusions(): string[]

    返回此广告位的广告类别排除标签。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .setCategoryExclusion("AirlineAd")
      .setCategoryExclusion("TrainAd")
      .addService(googletag.pubads());
    
    slot.getCategoryExclusions();
    // Returns ['AirlineAd', 'TrainAd'].
    
    返回结果
    string[]此广告位的广告类别排除标签;如果未设置任何标签,则返回空数组。


getResponseInformation

    getResponseInformation(): null | ResponseInformation

    返回广告响应信息。此值基于相应广告位的上一个广告响应。如果在广告位没有广告时调用此方法,则会返回 null

    返回结果
    null | ResponseInformation最新的广告响应信息,如果广告位没有广告,则为 null


getSlotElementId

    getSlotElementId(): string

    返回在定义槽时提供的槽 div 的 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'.
    
    返回结果
    stringdiv 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 属性设置值。这会替换为此键在服务级别设置的所有值。

    如果针对同一键多次调用此方法,则会替换之前为该键设置的值。必须先设置所有值,然后才能调用 displayrefresh

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // Setting an attribute on a single ad slot.
    googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .set("adsense_background_color", "#FFFFFF")
      .addService(googletag.pubads());
    
    另请参阅
    参数
    key: string属性的名称。
    value: string属性值。
    返回结果
    Slot调用该方法的槽对象。


setCategoryExclusion

    setCategoryExclusion(categoryExclusion: string): Slot

    为此广告位设置广告位级广告类别排除标签。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // Label = AirlineAd
    googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .setCategoryExclusion("AirlineAd")
      .addService(googletag.pubads());
    
    另请参阅
    参数
    categoryExclusion: string要添加的广告类别排除标签。
    返回结果
    Slot调用该方法的槽对象。


setClickUrl

    setClickUrl(value: string): Slot

    设置用户点击广告后会被重定向到的点击网址。

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

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .setClickUrl("http://www.example.com?original_click_url=")
      .addService(googletag.pubads());
    
    参数
    value: string要设置的点击网址。
    返回结果
    Slot调用该方法的槽对象。


setCollapseEmptyDiv

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

    设置当广告位 div 中没有广告时,是否应隐藏该广告位。这会替换服务级设置。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag
      .defineSlot("/1234567/sports", [160, 600], "div-1")!
      .setCollapseEmptyDiv(true, true)
      .addService(googletag.pubads());
    // The above will cause the div for this slot to be collapsed
    // when the page is loaded, before ads are requested.
    
    googletag
      .defineSlot("/1234567/sports", [160, 600], "div-2")!
      .setCollapseEmptyDiv(true)
      .addService(googletag.pubads());
    // The above will cause the div for this slot to be collapsed
    // only after GPT detects that no ads are available for the slot.
    
    另请参阅
    参数
    collapse: boolean是否在未返回任何广告时收起广告位。
    Optional collapseBeforeAdFetch: boolean是否在获取广告之前收起广告位。如果 collapse 不为 true,则会被忽略。
    返回结果
    Slot调用该方法的槽对象。


setConfig


setForceSafeFrame

    setForceSafeFrame(forceSafeFrame: boolean): Slot

    配置是否应强制使用 SafeFrame 容器呈现此广告位中的广告。

    使用此 API 时,请注意以下事项:

    • 此设置仅适用于针对相应广告位发出的后续广告请求。
    • 广告位级设置(如果指定)始终会替换网页级设置。
    • 如果设置为 true(在广告位一级或网页一级),系统将始终使用 SafeFrame 容器呈现广告,无论 Google Ad Manager 界面中做出了什么选择。
    • 不过,如果将其设置为 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());
    
    另请参阅
    参数
    forceSafeFrame: booleantrue 用于强制在此广告位中将所有广告呈现于 SafeFrame 中,false 用于停用网页级设置(如果有)。如果未在页面级别指定,将此值设为 false 不会产生任何变化。
    返回结果
    Slot调用该方法的槽对象。


setSafeFrameConfig

    setSafeFrameConfig(config: null | SafeFrameConfig): Slot

    为 SafeFrame 配置设置槽级偏好设置。配置对象中的所有无法识别的键都会被忽略。如果为已识别的键传递无效值,系统会忽略整个配置。

    如果指定了这些槽级偏好设置,它们将覆盖所有网页级偏好设置。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    googletag.pubads().setForceSafeFrame(true);
    
    // The following slot will have a sandboxed safeframe that only
    // disallows top-level navigation.
    googletag
      .defineSlot("/1234567/sports", [160, 600], "div-1")!
      .setSafeFrameConfig({ sandbox: true })
      .addService(googletag.pubads());
    
    // The following slot will inherit page-level settings.
    googletag.defineSlot("/1234567/news", [160, 600], "div-2")!.addService(googletag.pubads());
    
    googletag.display("div-1");
    googletag.display("div-2");
    
    另请参阅
    参数
    config: null | SafeFrameConfig配置对象。
    返回结果
    Slot调用该方法的槽对象。


setTargeting

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

    为此槽位设置自定义定位参数。针对同一键多次调用此方法会覆盖旧值。此处设置的值将覆盖在服务级别设置的定位参数。这些键是在您的 Google Ad Manager 账号中定义的。

    示例

    JavaScript

    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")
      .addService(googletag.pubads());
    
    // Example with a single value for a key.
    slot.setTargeting("allow_expandable", "true");
    
    // Example with multiple values for a key inside in an array.
    slot.setTargeting("interests", ["sports", "music"]);
    

    JavaScript(旧版)

    var slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")
      .addService(googletag.pubads());
    
    // Example with a single value for a key.
    slot.setTargeting("allow_expandable", "true");
    
    // Example with multiple values for a key inside in an array.
    slot.setTargeting("interests", ["sports", "music"]);
    

    TypeScript

    const slot = googletag
      .defineSlot("/1234567/sports", [160, 600], "div")!
      .addService(googletag.pubads());
    
    // Example with a single value for a key.
    slot.setTargeting("allow_expandable", "true");
    
    // Example with multiple values for a key inside in an array.
    slot.setTargeting("interests", ["sports", "music"]);
    
    另请参阅
    参数
    key: string定位参数键。
    value: string | string[]定位参数值或值数组。
    返回结果
    Slot调用该方法的槽对象。


updateTargetingFromMap

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

    根据 JSON 对象中的键值对映射,为此广告位设置自定义定位参数。这与针对对象的所有键值调用 Slot.setTargeting 相同。这些键是在您的 Google Ad Manager 账号中定义的。

    注意

    • 如果发生覆盖,系统只会保留最后一个值。
    • 如果值为数组,则系统会覆盖所有之前的值,而不是合并这些值。
    • 此处设置的值将覆盖在服务级别设置的定位参数。
    示例

    JavaScript

    const slot = googletag.defineSlot("/1234567/sports", [160, 600], "div");
    
    slot.updateTargetingFromMap({
      color: "red",
      interests: ["sports", "music", "movies"],
    });
    

    JavaScript(旧版)

    var slot = googletag.defineSlot("/1234567/sports", [160, 600], "div");
    
    slot.updateTargetingFromMap({
      color: "red",
      interests: ["sports", "music", "movies"],
    });
    

    TypeScript

    const slot = googletag.defineSlot("/1234567/sports", [160, 600], "div")!;
    
    slot.updateTargetingFromMap({
      color: "red",
      interests: ["sports", "music", "movies"],
    });
    
    参数
    map: {
      [adUnitPath: string]: string | string[];
    }
    定位参数键值对映射。
    返回结果
    Slot调用该方法的槽对象。


googletag.config

用于网页级设置的主要配置界面。
接口
AdExpansionConfig
用于控制广告展开的设置。
ComponentAuctionConfig
表示设备端广告竞价中的单个组件竞价的对象。
InterstitialConfig
用于定义单个插页式广告位行为的对象。
PageSettingsConfig
用于网页级设置的主要配置界面。
PrivacyTreatmentsConfig
用于控制发布商隐私权处理设置。
PublisherProvidedSignalsConfig
发布商提供的信号 (PPS) 配置对象。
SlotSettingsConfig
用于槽级设置的主要配置界面。
TaxonomyData
一个对象,包含单个分类的值。
类型别名
InterstitialTrigger
支持的插页式广告触发器。
PrivacyTreatment
支持的发布商隐私保护处理措施。
Taxonomy

类型别名


InterstitialTrigger

    InterstitialTrigger: "unhideWindow" | "navBar"

    支持的插页式广告触发器。


PrivacyTreatment

    PrivacyTreatment: "disablePersonalization"

    支持的发布商隐私保护措施。


分类


googletag.config.AdExpansionConfig

用于控制广告展开的设置。
属性
enabled?
广告展开功能是处于启用还是停用状态。
示例

JavaScript

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

JavaScript(旧版)

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

TypeScript

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

属性


Optional 已启用


googletag.config.ComponentAuctionConfig

表示设备端广告竞价中的单个组件竞价的对象。
属性
auctionConfig
此组件竞价的竞价配置对象。
configKey
与此组件竞价关联的配置键。
另请参阅

属性


auctionConfig

    auctionConfig: null | {
      auctionSignals?: unknown;
      decisionLogicUrl: string;
      interestGroupBuyers?: string[];
      perBuyerExperimentGroupIds?: {
        [buyer: string]: number;
      };
      perBuyerGroupLimits?: {
        [buyer: string]: number;
      };
      perBuyerSignals?: {
        [buyer: string]: unknown;
      };
      perBuyerTimeouts?: {
        [buyer: string]: number;
      };
      seller: string;
      sellerExperimentGroupId?: number;
      sellerSignals?: unknown;
      sellerTimeout?: number;
      trustedScoringSignalsUrl?: string;
    }

    此组件竞价的竞价配置对象。

    如果此值设为 null,系统会删除指定 configKey 的所有现有配置。

    示例

    JavaScript

    const componentAuctionConfig = {
      // Seller URL should be https and the same as decisionLogicUrl's origin
      seller: "https://testSeller.com",
      decisionLogicUrl: "https://testSeller.com/ssp/decision-logic.js",
      interestGroupBuyers: ["https://example-buyer.com"],
      auctionSignals: { auction_signals: "auction_signals" },
      sellerSignals: { seller_signals: "seller_signals" },
      perBuyerSignals: {
        // listed on interestGroupBuyers
        "https://example-buyer.com": {
          per_buyer_signals: "per_buyer_signals",
        },
      },
    };
    
    const auctionSlot = googletag.defineSlot("/1234567/example", [160, 600]);
    
    // To add configKey to the component auction:
    auctionSlot.setConfig({
      componentAuction: [
        {
          configKey: "https://testSeller.com",
          auctionConfig: componentAuctionConfig,
        },
      ],
    });
    
    // To remove configKey from the component auction:
    auctionSlot.setConfig({
      componentAuction: [
        {
          configKey: "https://testSeller.com",
          auctionConfig: null,
        },
      ],
    });
    

    JavaScript(旧版)

    var componentAuctionConfig = {
      // Seller URL should be https and the same as decisionLogicUrl's origin
      seller: "https://testSeller.com",
      decisionLogicUrl: "https://testSeller.com/ssp/decision-logic.js",
      interestGroupBuyers: ["https://example-buyer.com"],
      auctionSignals: { auction_signals: "auction_signals" },
      sellerSignals: { seller_signals: "seller_signals" },
      perBuyerSignals: {
        // listed on interestGroupBuyers
        "https://example-buyer.com": {
          per_buyer_signals: "per_buyer_signals",
        },
      },
    };
    
    var auctionSlot = googletag.defineSlot("/1234567/example", [160, 600]);
    
    // To add configKey to the component auction:
    auctionSlot.setConfig({
      componentAuction: [
        {
          configKey: "https://testSeller.com",
          auctionConfig: componentAuctionConfig,
        },
      ],
    });
    
    // To remove configKey from the component auction:
    auctionSlot.setConfig({
      componentAuction: [
        {
          configKey: "https://testSeller.com",
          auctionConfig: null,
        },
      ],
    });
    

    TypeScript

    const componentAuctionConfig = {
      // Seller URL should be https and the same as decisionLogicUrl's origin
      seller: "https://testSeller.com",
      decisionLogicUrl: "https://testSeller.com/ssp/decision-logic.js",
      interestGroupBuyers: ["https://example-buyer.com"],
      auctionSignals: { auction_signals: "auction_signals" },
      sellerSignals: { seller_signals: "seller_signals" },
      perBuyerSignals: {
        // listed on interestGroupBuyers
        "https://example-buyer.com": {
          per_buyer_signals: "per_buyer_signals",
        },
      },
    };
    
    const auctionSlot = googletag.defineSlot("/1234567/example", [160, 600])!;
    
    // To add configKey to the component auction:
    auctionSlot.setConfig({
      componentAuction: [
        {
          configKey: "https://testSeller.com",
          auctionConfig: componentAuctionConfig,
        },
      ],
    });
    
    // To remove configKey from the component auction:
    auctionSlot.setConfig({
      componentAuction: [
        {
          configKey: "https://testSeller.com",
          auctionConfig: null,
        },
      ],
    });
    
    另请参阅

configKey

    configKey: string

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

    此值不得为空,且应唯一。如果两个 ComponentAuctionConfig 对象共享相同的 configKey 值,则最后设置的值会覆盖之前的配置。


googletag.config.InterstitialConfig

用于定义单个插页式广告位行为的对象。
属性
requireStorageAccess?
是否需要征得用户同意才能使用本地存储空间来展示此插页式广告。
triggers?
此插页式广告的插页式广告触发器配置。

属性


Optional requireStorageAccess

    requireStorageAccess?: null | boolean

    是否需要用户同意使用本地存储空间才能展示此插页式广告。

    GPT 会使用本地存储空间来强制控制插页式广告的展示频次上限。不过,未提供本地存储空间使用同意声明的用户仍有资格看到插页式广告。将此属性设置为 true 可停用默认行为,并确保仅向已同意使用本地存储空间的用户展示插页式广告。

    示例

    JavaScript

    // Opt out of showing interstitials to users
    // without local storage consent.
    const interstitialSlot = googletag.defineOutOfPageSlot(
      "/1234567/sports",
      googletag.enums.OutOfPageFormat.INTERSTITIAL,
    );
    
    interstitialSlot.setConfig({
      interstitial: {
        requireStorageAccess: true, // defaults to false
      },
    });
    

    JavaScript(旧版)

    // Opt out of showing interstitials to users
    // without local storage consent.
    var interstitialSlot = googletag.defineOutOfPageSlot(
      "/1234567/sports",
      googletag.enums.OutOfPageFormat.INTERSTITIAL,
    );
    
    interstitialSlot.setConfig({
      interstitial: {
        requireStorageAccess: true, // defaults to false
      },
    });
    

    TypeScript

    // Opt out of showing interstitials to users
    // without local storage consent.
    const interstitialSlot = googletag.defineOutOfPageSlot(
      "/1234567/sports",
      googletag.enums.OutOfPageFormat.INTERSTITIAL,
    )!;
    
    interstitialSlot.setConfig({
      interstitial: {
        requireStorageAccess: true, // defaults to false
      },
    });
    
    另请参阅

Optional 触发器

    triggers?: null | Partial<Record<InterstitialTrigger, boolean>>

    此插页式广告的插页式广告触发器配置。

    将插页式广告触发器的值设置为 true 会启用该触发器,将其设置为 false 会停用该触发器。这将覆盖在 Google Ad Manager 中配置的默认值。

    示例

    JavaScript

    // Define a GPT managed web interstitial ad slot.
    const interstitialSlot = googletag.defineOutOfPageSlot(
      "/1234567/sports",
      googletag.enums.OutOfPageFormat.INTERSTITIAL,
    );
    
    // Enable optional interstitial triggers.
    // Change this value to false to disable.
    const enableTriggers = true;
    
    interstitialSlot.setConfig({
      interstitial: {
        triggers: {
          navBar: enableTriggers,
          unhideWindow: enableTriggers,
        },
      },
    });
    

    JavaScript(旧版)

    // Define a GPT managed web interstitial ad slot.
    var interstitialSlot = googletag.defineOutOfPageSlot(
      "/1234567/sports",
      googletag.enums.OutOfPageFormat.INTERSTITIAL,
    );
    
    // Enable optional interstitial triggers.
    // Change this value to false to disable.
    var enableTriggers = true;
    
    interstitialSlot.setConfig({
      interstitial: {
        triggers: {
          navBar: enableTriggers,
          unhideWindow: enableTriggers,
        },
      },
    });
    

    TypeScript

    // Define a GPT managed web interstitial ad slot.
    const interstitialSlot = googletag.defineOutOfPageSlot(
      "/1234567/sports",
      googletag.enums.OutOfPageFormat.INTERSTITIAL,
    )!;
    
    // Enable optional interstitial triggers.
    // Change this value to false to disable.
    const enableTriggers = true;
    
    interstitialSlot.setConfig({
      interstitial: {
        triggers: {
          navBar: enableTriggers,
          unhideWindow: enableTriggers,
        },
      },
    });
    
    另请参阅

googletag.config.PageSettingsConfig

用于网页级设置的主要配置界面。

允许通过单个 API 调用设置多个功能。

下面列出的所有属性均为示例,并不反映实际使用 setConfig 的功能。如需了解这组功能,请参阅下文中 PageSettingsConfig 类型中的字段。

示例:
  • 只有 googletag.setConfig 调用中指定的功能会被修改。
      // Configure feature alpha.
      googletag.setConfig({
          alpha: {...}
      });
    
      // Configure feature bravo. Feature alpha is unchanged.
      googletag.setConfig({
         bravo: {...}
      });
    
  • 每次调用 googletag.setConfig 时,都会更新给定功能的所有设置。
      // Configure feature charlie to echo = 1, foxtrot = true.
      googletag.setConfig({
          charlie: {
              echo: 1,
              foxtrot: true,
          }
      });
    
      // Update feature charlie to echo = 2. Since foxtrot was not specified,
      // the value is cleared.
      googletag.setConfig({
          charlie: {
              echo: 2
          }
      });
    
  • 通过传递 null,可以清除功能的所有设置。
      // Configure features delta, golf, and hotel.
      googletag.setConfig({
          delta: {...},
          golf: {...},
          hotel: {...},
      });
    
      // Feature delta and hotel are cleared, but feature golf remains set.
      googletag.setConfig({
          delta: null,
          hotel: null,
      });
    
属性
adExpansion?
用于控制广告展开的设置。
adYield?
已废弃。 
pps?
用于控制发布商提供的信号 (PPS) 的设置。
privacyTreatments?
用于控制发布商隐私权处理设置。
threadYield?
用于控制 GPT 在呈现广告素材时是否应让出 JS 线程的设置。

属性


Optional adExpansion


Optional adYield

    adYield?: null | "DISABLED" | "ENABLED_ALL_SLOTS"


Optional pps


Optional privacyTreatments


Optional threadYield

    threadYield?: null | "DISABLED" | "ENABLED_ALL_SLOTS"

    用于控制 GPT 在呈现广告素材时是否应让出 JS 线程的设置。

    GPT 仅会针对支持 Scheduler.postTask 或 Scheduler.yield API 的浏览器让出线程。

    支持的值:

    • null(默认):GPT 将为视口之外的广告位让出 JS 线程。
    • ENABLED_ALL_SLOTS:GPT 会为所有槽让出 JS 线程,无论槽是否位于视口内。
    • DISABLED:GPT 不会让出 JS 线程。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

    // Disable yielding.
    googletag.setConfig({ threadYield: "DISABLED" });
    
    // Enable yielding for all slots.
    googletag.setConfig({ threadYield: "ENABLED_ALL_SLOTS" });
    
    // Enable yielding only for slots outside of the viewport (default).
    googletag.setConfig({ threadYield: null });
    
    另请参阅

googletag.config.PrivacyTreatmentsConfig

用于控制发布商隐私权处理设置。
属性
treatments
要启用的发布商隐私保护处理措施的数组。

属性


处理组

    treatments: null | "disablePersonalization"[]

    要启用的发布商隐私保护处理措施的数组。

    示例

    JavaScript

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

    JavaScript(旧版)

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

    TypeScript

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

googletag.config.PublisherProvidedSignalsConfig

发布商提供的信号 (PPS) 配置对象。
属性
taxonomies
包含分类法映射的对象。
示例

JavaScript

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

JavaScript(旧版)

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

TypeScript

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

属性


分类法


googletag.config.SlotSettingsConfig

用于槽级设置的主要配置界面。

允许通过单个 API 调用为单个槽设置多个功能。

下面列出的所有属性均为示例,并不反映实际使用 setConfig 的功能。如需了解这组功能,请参阅下文中 SlotSettingsConfig 类型中的字段。

示例:
  • 只有 Slot.setConfig 调用中指定的功能会被修改。
      const slot = googletag.defineSlot("/1234567/example", [160, 600]);
    
      // Configure feature alpha.
      slot.setConfig({
          alpha: {...}
      });
    
      // Configure feature bravo. Feature alpha is unchanged.
      slot.setConfig({
         bravo: {...}
      });
    
  • 每次调用 Slot.setConfig 时,都会更新给定功能的所有设置。
      // Configure feature charlie to echo = 1, foxtrot = true.
      slot.setConfig({
          charlie: {
              echo: 1,
              foxtrot: true,
          }
      });
    
      // Update feature charlie to echo = 2. Since foxtrot was not specified,
      // the value is cleared.
      slot.setConfig({
          charlie: {
              echo: 2
          }
      });
    
  • 通过传递 null,可以清除功能的所有设置。
      // Configure features delta, golf, and hotel.
      slot.setConfig({
          delta: {...},
          golf: {...},
          hotel: {...},
      });
    
      // Feature delta and hotel are cleared, but feature golf remains set.
      slot.setConfig({
          delta: null,
          hotel: null,
      });
    
属性
adExpansion?
用于控制广告展开的设置。
componentAuction?
要包含在设备端广告竞价中的一系列组件竞价。
interstitial?
用于控制插页式广告位行为的设置。

属性


Optional adExpansion


Optional componentAuction

    componentAuction?: null | ComponentAuctionConfig[]

    要包含在设备端广告竞价中的一系列组件竞价。


Optional 插页式广告


googletag.config.TaxonomyData

一个对象,包含单个分类的值。
属性
values
分类值的列表。

属性


    values: string[]

    分类值的列表。


googletag.enums

这是 GPT 为枚举类型使用的命名空间。
枚举
OutOfPageFormat
GPT 支持的页外广告格式。
TrafficSource
GPT 支持的流量来源

枚举


OutOfPageFormat

    OutOfPageFormat

    GPT 支持的页外广告格式。

    另请参阅
    枚举成员
    BOTTOM_ANCHOR
    锚定格式,广告位会固定在视口底部。
    GAME_MANUAL_INTERSTITIAL
    游戏手动插页式广告格式。

    注意:游戏手动插页式广告是一种访问受限的广告格式。
    INTERSTITIAL
    网站插页式广告素材格式。
    LEFT_SIDE_RAIL
    左侧边栏广告格式。
    REWARDED
    激励广告格式。
    RIGHT_SIDE_RAIL
    右侧边栏广告格式。
    TOP_ANCHOR
    锚定格式,广告位会固定在视口顶部。

TrafficSource

    TrafficSource

    GPT 支持的流量来源

    另请参阅
    枚举成员
    ORGANIC
    直接网址输入、网站搜索或应用下载。
    PURCHASED
    从非自有媒体资源重定向的流量(已收购的媒体资源或其他利诱性质的活动)。

googletag.events

这是 GPT 为事件使用的命名空间。您的代码可以使用 Service.addEventListener 响应这些事件。
接口
Event
所有 GPT 事件的基础接口。
EventTypeMap
这是一种伪类型,用于将事件名称映射到 Service.addEventListenerService.removeEventListener 对应的事件对象类型。
GameManualInterstitialSlotClosedEvent
当用户关闭游戏手册插页式广告位时,系统会触发此事件。
GameManualInterstitialSlotReadyEvent
当游戏手动插页式广告位准备好向用户展示时,系统会触发此事件。
ImpressionViewableEvent
当某次展示根据 Active View 标准变为可见时,系统会触发此事件。
RewardedSlotClosedEvent
当用户关闭激励广告展示位置时,系统会触发此事件。
RewardedSlotGrantedEvent
在用户观看激励广告后获得奖励时,系统会触发此事件。
RewardedSlotReadyEvent
激励广告准备好展示时,系统会触发此事件。
SlotOnloadEvent
当广告素材的 iframe 触发其 load 事件时,系统会触发此事件。
SlotRenderEndedEvent
在广告素材代码注入到槽中时,系统会触发此事件。
SlotRequestedEvent
在为特定广告位请求广告时,系统会触发此事件。
SlotResponseReceived
当系统收到特定广告位对应的广告响应时,系统会触发此事件。
SlotVisibilityChangedEvent
每当广告展示位置区域的屏幕百分比发生变化时,都会触发此事件。

googletag.events.Event

所有 GPT 事件的基础接口。以下所有 GPT 事件都将包含以下字段。
属性
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
另请参阅

属性


serviceName

    serviceName: string

    触发事件的服务的名称。


    slot: Slot

    触发事件的槽。


googletag.events.EventTypeMap

这是一种伪类型,用于将事件名称映射到 Service.addEventListenerService.removeEventListener 对应的事件对象类型。我们记录这些信息只是为了提供参考和类型安全性。
属性
gameManualInterstitialSlotClosed
gameManualInterstitialSlotReady
impressionViewable
rewardedSlotClosed
rewardedSlotGranted
rewardedSlotReady
slotOnload
slotRenderEnded
slotRequested
slotResponseReceived
slotVisibilityChanged

属性


gameManualInterstitialSlotClosed


gameManualInterstitialSlotReady


impressionViewable


rewardedSlotClosed


rewardedSlotGranted


rewardedSlotReady


slotOnload


slotRenderEnded


slotRequested


slotResponseReceived


slotVisibilityChanged


googletag.events.GameManualInterstitialSlotClosedEvent

扩展了 Event
当用户关闭游戏手动插页式广告位时,系统会触发此事件。

注意:游戏手动插页式广告是一种访问受限格式。
属性
serviceName
触发事件的服务的名称。
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.
  }
});
另请参阅

googletag.events.GameManualInterstitialSlotReadyEvent

扩展了 Event
当游戏手动插页式广告位准备好向用户展示时,系统会触发此事件。

注意:游戏手动插页式广告是一种访问受限格式。
属性
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
方法
makeGameManualInterstitialVisible
向用户展示游戏手册插页式广告。
示例

JavaScript

// This listener is called when a game manual interstitial slot is ready to
// be displayed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);
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

    向用户展示游戏手册插页式广告。


googletag.events.ImpressionViewableEvent

扩展了 Event
当某次展示根据 Active View 标准变为可见时,系统会触发此事件。
属性
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
示例

JavaScript

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

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

JavaScript(旧版)

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

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

TypeScript

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

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另请参阅

googletag.events.RewardedSlotClosedEvent

扩展了 Event
当用户关闭激励广告展示位置时,系统会触发此事件。此事件可以在奖励授予之前或之后触发。如需确定是否已授予奖励,请改用 events.RewardedSlotGrantedEvent
属性
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
示例

JavaScript

// This listener is called when the user closes a rewarded ad slot.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("rewardedSlotClosed", (event) => {
  const slot = event.slot;
  console.log("Rewarded ad slot", slot.getSlotElementId(), "has been closed.");

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

JavaScript(旧版)

// This listener is called when the user closes a rewarded ad slot.
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("rewardedSlotClosed", function (event) {
  var slot = event.slot;
  console.log("Rewarded ad slot", slot.getSlotElementId(), "has been closed.");

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

TypeScript

// This listener is called when the user closes a rewarded ad slot.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("rewardedSlotClosed", (event) => {
  const slot = event.slot;
  console.log("Rewarded ad slot", slot.getSlotElementId(), "has been closed.");

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另请参阅

googletag.events.RewardedSlotGrantedEvent

扩展了 Event
在用户观看激励广告后获得奖励时,系统会触发此事件。如果用户在满足奖励发放条件之前关闭广告,系统不会触发此事件。
属性
payload
一个包含已授予的奖励的相关信息的对象。
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
示例

JavaScript

// This listener is called whenever a reward is granted for a
// rewarded ad.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("rewardedSlotGranted", (event) => {
  const slot = event.slot;
  console.group("Reward granted for slot", slot.getSlotElementId(), ".");

  // Log details of the reward.
  console.log("Reward type:", event.payload?.type);
  console.log("Reward amount:", event.payload?.amount);
  console.groupEnd();

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

JavaScript(旧版)

// This listener is called whenever a reward is granted for a
// rewarded ad.
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("rewardedSlotGranted", function (event) {
  var _a, _b;
  var slot = event.slot;
  console.group("Reward granted for slot", slot.getSlotElementId(), ".");

  // Log details of the reward.
  console.log("Reward type:", (_a = event.payload) === null || _a === void 0 ? void 0 : _a.type);
  console.log(
    "Reward amount:",
    (_b = event.payload) === null || _b === void 0 ? void 0 : _b.amount,
  );
  console.groupEnd();

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

TypeScript

// This listener is called whenever a reward is granted for a
// rewarded ad.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("rewardedSlotGranted", (event) => {
  const slot = event.slot;
  console.group("Reward granted for slot", slot.getSlotElementId(), ".");

  // Log details of the reward.
  console.log("Reward type:", event.payload?.type);
  console.log("Reward amount:", event.payload?.amount);
  console.groupEnd();

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另请参阅

属性


载荷

    payload: null | RewardedPayload

    一个包含已授予的奖励的相关信息的对象。


googletag.events.RewardedSlotReadyEvent

扩展了 Event
激励广告准备好展示时,系统会触发此事件。发布商负责在展示广告之前向用户提供观看广告的选项。
属性
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
方法
makeRewardedVisible
展示激励广告。
示例

JavaScript

// This listener is called when a rewarded ad slot becomes ready to be
// displayed.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("rewardedSlotReady", (event) => {
  const slot = event.slot;
  console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed.");

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

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

JavaScript(旧版)

// This listener is called when a rewarded ad slot becomes ready to be
// displayed.
var targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("rewardedSlotReady", function (event) {
  var slot = event.slot;
  console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed.");

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

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

TypeScript

// This listener is called when a rewarded ad slot becomes ready to be
// displayed.
const targetSlot = googletag.defineSlot("/1234567/example", [160, 600]);
googletag.pubads().addEventListener("rewardedSlotReady", (event) => {
  const slot = event.slot;
  console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed.");

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

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另请参阅

方法


makeRewardedVisible

    makeRewardedVisible(): void

    展示激励广告。在用户同意观看广告之前,不应调用此方法。


googletag.events.SlotOnloadEvent

扩展了 Event
当广告素材的 iframe 触发其 load 事件时,系统会触发此事件。在同步呈现模式下呈现富媒体广告时,系统不会使用 iframe,因此不会触发 SlotOnloadEvent
属性
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
示例

JavaScript

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

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

JavaScript(旧版)

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

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

TypeScript

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

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另请参阅

googletag.events.SlotRenderEndedEvent

扩展了 Event
当广告素材代码注入到槽中时,系统会触发此事件。此事件会在提取广告素材资源之前发生,因此广告素材可能尚未显示。如果您需要了解某个广告位的所有广告素材资源何时加载完毕,请改用 events.SlotOnloadEvent
属性
advertiserId
所呈现广告的广告客户 ID。
campaignId
所呈现广告的广告系列 ID。
companyIds
对所呈现的补余广告出价的公司的 ID。
creativeId
呈现的预订广告的广告素材 ID。
creativeTemplateId
所呈现的预订广告的广告素材模板 ID。
isBackfill
广告是否为补余广告。
isEmpty
是否为该广告位返回了广告。
labelIds
已废弃。 
lineItemId
所呈现的预订型广告的订单项 ID。
serviceName
触发事件的服务的名称。
size
表示呈现的广告素材的像素尺寸。
slot
触发事件的槽。
slotContentChanged
广告位内容是否随所呈现的广告而更改。
sourceAgnosticCreativeId
呈现的预订广告或补余广告的广告素材 ID。
sourceAgnosticLineItemId
所呈现的预订广告或补余广告的订单项 ID。
yieldGroupIds
所呈现回填广告的收益组的 ID。
示例

JavaScript

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

  // Log details of the rendered ad.
  console.log("Advertiser ID:", event.advertiserId);
  console.log("Campaign ID:", event.campaignId);
  console.log("Company IDs:", event.companyIds);
  console.log("Creative ID:", event.creativeId);
  console.log("Creative Template ID:", event.creativeTemplateId);
  console.log("Is backfill?:", event.isBackfill);
  console.log("Is empty?:", event.isEmpty);
  console.log("Line Item ID:", event.lineItemId);
  console.log("Size:", event.size);
  console.log("Slot content changed?", event.slotContentChanged);
  console.log("Source Agnostic Creative ID:", event.sourceAgnosticCreativeId);
  console.log("Source Agnostic Line Item ID:", event.sourceAgnosticLineItemId);
  console.log("Yield Group IDs:", event.yieldGroupIds);
  console.groupEnd();

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

JavaScript(旧版)

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

  // Log details of the rendered ad.
  console.log("Advertiser ID:", event.advertiserId);
  console.log("Campaign ID:", event.campaignId);
  console.log("Company IDs:", event.companyIds);
  console.log("Creative ID:", event.creativeId);
  console.log("Creative Template ID:", event.creativeTemplateId);
  console.log("Is backfill?:", event.isBackfill);
  console.log("Is empty?:", event.isEmpty);
  console.log("Line Item ID:", event.lineItemId);
  console.log("Size:", event.size);
  console.log("Slot content changed?", event.slotContentChanged);
  console.log("Source Agnostic Creative ID:", event.sourceAgnosticCreativeId);
  console.log("Source Agnostic Line Item ID:", event.sourceAgnosticLineItemId);
  console.log("Yield Group IDs:", event.yieldGroupIds);
  console.groupEnd();

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

TypeScript

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

  // Log details of the rendered ad.
  console.log("Advertiser ID:", event.advertiserId);
  console.log("Campaign ID:", event.campaignId);
  console.log("Company IDs:", event.companyIds);
  console.log("Creative ID:", event.creativeId);
  console.log("Creative Template ID:", event.creativeTemplateId);
  console.log("Is backfill?:", event.isBackfill);
  console.log("Is empty?:", event.isEmpty);
  console.log("Line Item ID:", event.lineItemId);
  console.log("Size:", event.size);
  console.log("Slot content changed?", event.slotContentChanged);
  console.log("Source Agnostic Creative ID:", event.sourceAgnosticCreativeId);
  console.log("Source Agnostic Line Item ID:", event.sourceAgnosticLineItemId);
  console.log("Yield Group IDs:", event.yieldGroupIds);
  console.groupEnd();

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另请参阅

属性


advertiserId

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


lineItemId

    lineItemId: null | number

    所呈现的预订型广告的订单项 ID。对于空广告位、回填广告和由 PubAdsService 以外的服务呈现的广告素材,此值为 null


size

    size: null | string | number[]

    表示呈现的广告素材的像素尺寸。示例:[728, 90]。对于空白广告位,此值为 null


slotContentChanged

    slotContentChanged: boolean

    广告位内容是否随所呈现的广告而更改。如果内容已更改,则值为 true;否则值为 false


sourceAgnosticCreativeId

    sourceAgnosticCreativeId: null | number

    呈现的预订广告或补余广告的广告素材 ID。如果广告不是预订型广告或订单项回填广告,或者广告素材由 PubAdsService 以外的服务呈现,则值为 null


sourceAgnosticLineItemId

    sourceAgnosticLineItemId: null | number

    所呈现的预订广告或补余广告的订单项 ID。如果广告不是预订型广告或订单项回填广告,或者广告素材由 PubAdsService 以外的服务呈现,则值为 null


yieldGroupIds

    yieldGroupIds: null | number[]

    所呈现回填广告的收益组的 ID。对于空槽、预订广告和由 PubAdsService 以外的服务呈现的广告素材,值为 null


googletag.events.SlotRequestedEvent

扩展了 Event
在为特定广告位请求广告时,系统会触发此事件。
属性
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
示例

JavaScript

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

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

JavaScript(旧版)

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

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

TypeScript

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

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另请参阅

googletag.events.SlotResponseReceived

扩展了 Event
当系统收到特定广告位对应的广告响应时,系统会触发此事件。
属性
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
示例

JavaScript

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

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

JavaScript(旧版)

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

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

TypeScript

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

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另请参阅

googletag.events.SlotVisibilityChangedEvent

扩展了 Event
每当广告展示位置区域的屏幕百分比发生变化时,都会触发此事件。此事件会受到节流限制,触发频率不会超过每 200 毫秒一次。
属性
inViewPercentage
广告可见区域所占的百分比。
serviceName
触发事件的服务的名称。
slot
触发事件的槽。
示例

JavaScript

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

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

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

JavaScript(旧版)

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

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

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

TypeScript

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

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

  if (slot === targetSlot) {
    // Slot specific logic.
  }
});
另请参阅

属性


inViewPercentage

    inViewPercentage: number

    广告可见区域所占的百分比。值为 0 到 100 之间的数字。


googletag.secureSignals

这是 GPT 用于管理安全信号的命名空间。
接口
BidderSignalProvider
返回特定出价方的安全信号。
PublisherSignalProvider
返回特定发布商的安全信号。
SecureSignalProvidersArray
用于管理安全信号的接口。
类型别名
SecureSignalProvider
用于为特定出价方或提供商返回安全信号的接口。

类型别名


SecureSignalProvider


googletag.secureSignals.BidderSignalProvider

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

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

  1. 收集器函数,用于返回解析为安全信号的 Promise
  2. id,用于标识与信号关联的出价方。
如需为发布商返回安全信号,请改用 secureSignals.PublisherSignalProvider
属性
collectorFunction
一个函数,用于返回解析为安全信号的 Promise
id
与此安全信号关联的收集器的唯一标识符(已在 Google Ad Manager 中注册)。
示例

JavaScript

// id is provided
googletag.secureSignalProviders.push({
  id: "collector123",
  collectorFunction: () => {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});

JavaScript(旧版)

// id is provided
googletag.secureSignalProviders.push({
  id: "collector123",
  collectorFunction: function () {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});

TypeScript

// id is provided
googletag.secureSignalProviders!.push({
  id: "collector123",
  collectorFunction: () => {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});
另请参阅

属性


collectorFunction

    collectorFunction: (() => Promise<string>)

    一个函数,用于返回解析为安全信号的 Promise


id

    id: string

    与此安全信号关联的收集器的唯一标识符(已在 Google Ad Manager 中注册)。


googletag.secureSignals.PublisherSignalProvider

返回特定发布商的安全信号。

发布商信号提供程序由 2 部分组成:

  1. 收集器函数,用于返回解析为安全信号的 Promise
  2. networkCode,用于标识与信号关联的发布商。
如需为出价方返回安全信号,请改用 secureSignals.BidderSignalProvider
属性
collectorFunction
一个函数,用于返回解析为安全信号的 Promise
networkCode
与此安全信号关联的发布商的广告联盟代码(如广告单元路径中所示)。
示例

JavaScript

// networkCode is provided
googletag.secureSignalProviders.push({
  networkCode: "123456",
  collectorFunction: () => {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});

JavaScript(旧版)

// networkCode is provided
googletag.secureSignalProviders.push({
  networkCode: "123456",
  collectorFunction: function () {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});

TypeScript

// networkCode is provided
googletag.secureSignalProviders!.push({
  networkCode: "123456",
  collectorFunction: () => {
    // ...custom signal generation logic...
    return Promise.resolve("signal");
  },
});
另请参阅

属性


collectorFunction

    collectorFunction: (() => Promise<string>)

    一个函数,用于返回解析为安全信号的 Promise


networkCode

    networkCode: string

    与此安全信号关联的发布商的广告联盟代码(如广告单元路径中所示)。


googletag.secureSignals.SecureSignalProvidersArray

用于管理安全信号的接口。
方法
clearAllCache
从缓存中清除所有收集器的所有信号。
push
向信号提供程序数组添加新的 secureSignals.SecureSignalProvider,并开始信号生成流程。

方法


clearAllCache

    clearAllCache(): void

    从缓存中清除所有收集器的所有信号。

    调用此方法可能会降低信号包含在当前网页浏览(以及可能之后的网页浏览)的广告请求中的可能性。因此,只有在发生有意义的状态更改时(例如指示有新用户的事件,例如登录、退出、注册等),才应调用此方法。


推送