GPT Reference

This reference uses TypeScript notation to describe types. The following table provides a brief explanation by example.

Type expression
string The primitive string type.
string[] An array type, where values may only be strings.
number | string A union type, where the value may be either a number or a string.
Array<number | string> An array type, where values are a complex (union) type.
[number, string] A tuple type, where the value is a two-element array that must contain a number and a string in that order.
Slot An object type, where the value is an instance of googletag.Slot.
() => void A function type with no defined arguments and no return value.

To learn more about supported types and type expressions, refer to the TypeScript Handbook .

Type annotations

A colon after a variable, parameter name, property name, or function signature denotes a type annotation. Type annotations describe the types the element to the left of the colon can accept or return. The following table shows examples of type annotations you may see in this reference.

Type annotation
param: string Indicates that param accepts or returns a string value. This syntax is used for variables, parameters, properties, and return types.
param?: number | string Indicates that param is optional, but accepts either a number or a string when specified. This syntax is used for parameters and properties.
...params: Array<() => void> Indicates that params is a rest parameter that accepts functions. Rest parameters accept an unbounded number of values of the specified type.

googletag

The global namespace the Google Publisher Tag uses for its API.
Namespaces
config
Main configuration interface for page-level settings.
enums
This is the namespace that GPT uses for enum types.
events
This is the namespace that GPT uses for Events.
secureSignals
This is the namespace that GPT uses for managing secure signals.
Interfaces
CommandArray
The command array accepts a sequence of functions and invokes them in order.
CompanionAdsService
Companion Ads service.
PrivacySettingsConfig
Configuration object for privacy settings.
PubAdsService
Publisher Ads service.
ResponseInformation
An object representing a single ad response.
RewardedPayload
An object representing the reward associated with a rewarded ad.
SafeFrameConfig
Configuration object for SafeFrame containers.
Service
Base service class that contains methods common for all services.
SizeMappingBuilder
Builder for size mapping specification objects.
Slot
Slot is an object representing a single ad slot on a page.
Type Aliases
GeneralSize
A valid size configuration for a slot, which can be one or multiple sizes.
MultiSize
A list of single valid sizes.
NamedSize
Named sizes that a slot can have.
SingleSize
A single valid size for a slot.
SingleSizeArray
Array of two numbers representing [width, height].
SizeMapping
A mapping of viewport size to ad sizes.
SizeMappingArray
A list of size mappings.
Variables
apiReady
Flag indicating that the GPT API is loaded and ready to be called.
cmd
Reference to the global command queue for asynchronous execution of GPT-related calls.
pubadsReady
Flag indicating that PubAdsService is enabled, loaded and fully operational.
secureSignalProviders
Reference to the secure signal providers array.
Functions
companionAds
Returns a reference to the CompanionAdsService.
defineOutOfPageSlot
Constructs an out-of-page ad slot with the given ad unit path.
defineSlot
Constructs an ad slot with a given ad unit path and size and associates it with the ID of a div element on the page that will contain the ad.
destroySlots
Destroys the given slots, removing all related objects and references of those slots from GPT.
disablePublisherConsole
Disables the Google Publisher Console.
display
Instructs slot services to render the slot.
enableServices
Enables all GPT services that have been defined for ad slots on the page.
getVersion
Returns the current version of GPT.
openConsole
Opens the Google Publisher Console.
pubads
Returns a reference to the PubAdsService.
setAdIframeTitle
Sets the title for all ad container iframes created by PubAdsService, from this point onwards.
setConfig
Sets general configuration options for the page.
sizeMapping
Creates a new SizeMappingBuilder.

Type Aliases

GeneralSize

GeneralSize: SingleSize | MultiSize
A valid size configuration for a slot, which can be one or multiple sizes.

MultiSize

MultiSize: SingleSize[]
A list of single valid sizes.

NamedSize

NamedSize: "fluid" | ["fluid"]
Named sizes that a slot can have. In most cases size is a fixed-size rectangle but there are some cases when we need other kinds of size specifications. Only the following are valid named sizes:
  • fluid: the ad container takes 100% width of parent div and then resizes its height to fit creative content. Similar to how regular block elements on a page behave. Used for native ads (see related article). Note that both fluid and ['fluid'] are acceptable forms to declare a slot size as fluid.

SingleSize

A single valid size for a slot.

SingleSizeArray

SingleSizeArray: [number, number]
Array of two numbers representing [width, height].

SizeMapping

A mapping of viewport size to ad sizes. Used for responsive ads.

SizeMappingArray

SizeMappingArray: SizeMapping[]
A list of size mappings.

Variables

Const apiReady

apiReady: boolean | undefined
Flag indicating that the GPT API is loaded and ready to be called. This property will be simply undefined until the API is ready.

Note that the recommended way of handling async is to use googletag.cmd to queue callbacks for when GPT is ready. These callbacks do not have to check googletag.apiReady as they are guaranteed to execute once the API is set up.

Const cmd

cmd: ((this: typeof globalThis) => void)[] | CommandArray
Reference to the global command queue for asynchronous execution of GPT-related calls.

The googletag.cmd variable is initialized to an empty JavaScript array by the GPT tag syntax on the page, and cmd.push is the standard Array.push method that adds an element to the end of the array. When the GPT JavaScript is loaded, it looks through the array and executes all the functions in order. The script then replaces cmd with a CommandArray object whose push method is defined to execute the function argument passed to it. This mechanism allows GPT to reduce perceived latency by fetching the JavaScript asynchronously while allowing the browser to continue rendering the page.
Example

JavaScript

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

JavaScript (legacy)

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
Flag indicating that PubAdsService is enabled, loaded and fully operational. This property will be simply undefined until enableServices is called and PubAdsService is loaded and initialized.

secureSignalProviders

secureSignalProviders: SecureSignalProvider[] | SecureSignalProvidersArray | undefined
Reference to the secure signal providers array.

The secure signal providers array accepts a sequence of signal-generating functions and invokes them in order. It is intended to replace a standard array that is used to enqueue signal-generating functions to be invoked once GPT is loaded.
Example

JavaScript

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

JavaScript (legacy)

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

Functions

companionAds

companionAds(): CompanionAdsService
Returns a reference to the CompanionAdsService.
Returns
CompanionAdsServiceThe Companion Ads service.

defineOutOfPageSlot

defineOutOfPageSlot(adUnitPath: string, div?: string | OutOfPageFormat): Slot | null
Constructs an out-of-page ad slot with the given ad unit path.

For custom out-of-page ads, div is the ID of the div element that will contain the ad. See the article on out-of-page creatives for more details.

For GPT managed out-of-page ads, div is a supported OutOfPageFormat.
Example

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

// 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);
See also
Parameters
adUnitPath: stringFull ad unit path with the network code and ad unit code.
Optional div: string | OutOfPageFormatID of the div that will contain this ad unit or OutOfPageFormat.
Returns
Slot | nullThe newly created slot, or null if a slot cannot be created.

defineSlot

defineSlot(adUnitPath: string, size: GeneralSize, div?: string): Slot | null
Constructs an ad slot with a given ad unit path and size and associates it with the ID of a div element on the page that will contain the ad.
Example

JavaScript

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

JavaScript (legacy)

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

TypeScript

googletag.defineSlot("/1234567/sports", [728, 90], "div-1");
See also
Parameters
adUnitPath: stringFull ad unit path with the network code and unit code.
size: GeneralSizeWidth and height of the added slot. This is the size that is used in the ad request if no responsive size mapping is provided or the size of the viewport is smaller than the smallest size provided in the mapping.
Optional div: stringID of the div that will contain this ad unit.
Returns
Slot | nullThe newly created slot, or null if a slot cannot be created.

destroySlots

destroySlots(slots?: Slot[]): boolean
Destroys the given slots, removing all related objects and references of those slots from GPT. This API does not support passback slots and companion slots.

Calling this API on a slot clears the ad and removes the slot object from the internal state maintained by GPT. Calling any more functions on the slot object will result in undefined behavior. Note the browser may still not free the memory associated with that slot if a reference to it is maintained by the publisher page. Calling this API makes the div associated with that slot available for reuse.

In particular, destroying a slot removes the ad from GPT's long-lived pageview, so future requests will not be influenced by roadblocks or competitive exclusions involving this ad. Failure to call this function before removing a slot's div from the page will result in undefined behavior.
Example

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

// 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();
Parameters
Optional slots: Slot[]The array of slots to destroy. Array is optional; all slots will be destroyed if it is unspecified.
Returns
booleantrue if slots have been destroyed, false otherwise.

disablePublisherConsole

disablePublisherConsole(): void
Disables the Google Publisher Console.
See also

display

display(divOrSlot: string | Element | Slot): void
Instructs slot services to render the slot. Each ad slot should only be displayed once per page. All slots must be defined and have a service associated with them before being displayed. The display call must not happen until the element is present in the DOM. The usual way to achieve that is to place it within a script block within the div element named in the method call.

If single request architecture (SRA) is being used, all unfetched ad slots at the time this method is called will be fetched at once. To force an ad slot not to display, the entire div must be removed.
See also
Parameters
divOrSlot: string | Element | SlotEither the ID of the div element containing the ad slot or the div element, or the slot object. If a div element is provided, it must have an 'id' attribute which matches the ID passed into defineSlot.

enableServices

enableServices(): void
Enables all GPT services that have been defined for ad slots on the page.

getVersion

getVersion(): string
Returns the current version of GPT.
See also
Returns
stringThe currently executing GPT version string.

openConsole

openConsole(div?: string): void
Opens the Google Publisher Console.
Example

JavaScript

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

// Calling without div ID.
googletag.openConsole();

JavaScript (legacy)

// 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();
See also
Parameters
Optional div: stringAn ad slot div ID. This value is optional. When provided, the Publisher Console will attempt to open with details of the specified ad slot in view.

pubads

pubads(): PubAdsService
Returns a reference to the PubAdsService.
Returns
PubAdsServiceThe Publisher Ads service.

setAdIframeTitle

setAdIframeTitle(title: string): void
Sets the title for all ad container iframes created by PubAdsService, from this point onwards.
Example

JavaScript

googletag.setAdIframeTitle("title");

JavaScript (legacy)

googletag.setAdIframeTitle("title");

TypeScript

googletag.setAdIframeTitle("title");
Parameters
title: stringThe new title for all ad container iframes.

setConfig

setConfig(config: PageSettingsConfig): void
Sets general configuration options for the page.
Parameters
config: PageSettingsConfig

sizeMapping

sizeMapping(): SizeMappingBuilder
Creates a new SizeMappingBuilder.
See also
Returns
SizeMappingBuilderA new builder.

googletag.CommandArray

The command array accepts a sequence of functions and invokes them in order. It is intended to replace a standard array that is used to enqueue functions to be invoked once GPT is loaded.
Methods
push
Executes the sequence of functions specified in the arguments in order.

Methods

push

push(...f: ((this: typeof globalThis) => void)[]): number
Executes the sequence of functions specified in the arguments in order.
Example

JavaScript

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

JavaScript (legacy)

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());
});
Parameters
Rest ...f: ((this: typeof globalThis) => void)[]A JavaScript function to be executed. The runtime binding will always be globalThis. Consider passing an arrow function to retain the this value of the enclosing lexical context.
Returns
numberThe number of commands processed so far. This is compatible with Array.push's return value (the current length of the array).

googletag.CompanionAdsService

Extends Service
Companion Ads service. This service is used by video ads to show companion ads.
Methods
addEventListener
Registers a listener that allows you to set up and call a JavaScript function when a specific GPT event happens on the page.
getSlots
Get the list of slots associated with this service.
removeEventListener
Removes a previously registered listener.
setRefreshUnfilledSlots
Sets whether companion slots that have not been filled will be automatically backfilled.
See also

Methods

setRefreshUnfilledSlots

setRefreshUnfilledSlots(value: boolean): void
Sets whether companion slots that have not been filled will be automatically backfilled.

This method can be called multiple times during the page's lifetime to turn backfill on and off. Only slots that are also registered with the PubAdsService will be backfilled. Due to policy restrictions, this method is not designed to fill empty companion slots when an Ad Exchange video is served.
Example

JavaScript

googletag.companionAds().setRefreshUnfilledSlots(true);

JavaScript (legacy)

googletag.companionAds().setRefreshUnfilledSlots(true);

TypeScript

googletag.companionAds().setRefreshUnfilledSlots(true);
Parameters
value: booleantrue to automatically backfill unfilled slots, false to leave them unchanged.

googletag.PrivacySettingsConfig

Configuration object for privacy settings.
Properties
childDirectedTreatment?
Indicates whether the page should be treated as child-directed.
limitedAds?
Enables serving to run in limited ads mode to aid in publisher regulatory compliance needs.
nonPersonalizedAds?
Enables serving to run in non-personalized ads mode to aid in publisher regulatory compliance needs.
restrictDataProcessing?
Enables serving to run in restricted processing mode to aid in publisher regulatory compliance needs.
trafficSource?
Indicates whether requests represent purchased or organic traffic.
underAgeOfConsent?
Indicates whether to mark ad requests as coming from users under the age of consent.
See also

Properties

Optional childDirectedTreatment

childDirectedTreatment?: null | boolean
Indicates whether the page should be treated as child-directed. Set to null to clear the configuration.

Optional limitedAds

limitedAds?: boolean
Enables serving to run in limited ads mode to aid in publisher regulatory compliance needs.

You can instruct GPT to request limited ads in two ways:
  • Automatically, by using a signal from an IAB TCF v2.0 consent management platform.
  • Manually, by setting the value of this field to true.
Manually configuring limited ads is only possible when GPT is loaded from the limited ads URL. Attempting to modify this setting when GPT has been loaded from the standard URL will generate a Publisher Console warning.

Note that it is not necessary to manually enable limited ads when a CMP is in use.
Example

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

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

Optional nonPersonalizedAds

nonPersonalizedAds?: boolean
Enables serving to run in non-personalized ads mode to aid in publisher regulatory compliance needs.

Optional restrictDataProcessing

restrictDataProcessing?: boolean
Enables serving to run in restricted processing mode to aid in publisher regulatory compliance needs.

Optional trafficSource

trafficSource?: TrafficSource
Indicates whether requests represent purchased or organic traffic. This value populates the Traffic source dimension in Ad Manager reporting. If not set, traffic source defaults to undefined in reporting.
Example

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

// 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
Indicates whether to mark ad requests as coming from users under the age of consent. Set to null to clear the configuration.

googletag.PubAdsService

Extends Service
Publisher Ads service. This service is used to fetch and show ads from your Google Ad Manager account.
Methods
addEventListener
Registers a listener that allows you to set up and call a JavaScript function when a specific GPT event happens on the page.
clear
Removes the ads from the given slots and replaces them with blank content.
clearCategoryExclusions
Clears all page-level ad category exclusion labels.
clearTargeting
Clears custom targeting parameters for a specific key or for all keys.
collapseEmptyDivs
Enables collapsing of slot divs so that they don't take up any space on the page when there is no ad content to display.
disableInitialLoad
Disables requests for ads on page load, but allows ads to be requested with a PubAdsService.refresh call.
display
Constructs and displays an ad slot with the given ad unit path and size.
enableLazyLoad
Enables lazy loading in GPT as defined by the config object.
enableSingleRequest
Enables single request mode for fetching multiple ads at the same time.
enableVideoAds
Signals to GPT that video ads will be present on the page.
get
Returns the value for the AdSense attribute associated with the given key.
getAttributeKeys
Returns the attribute keys that have been set on this service.
getSlots
Get the list of slots associated with this service.
getTargeting
Returns a specific custom service-level targeting parameter that has been set.
getTargetingKeys
Returns the list of all custom service-level targeting keys that have been set.
isInitialLoadDisabled
Returns whether or not initial requests for ads was successfully disabled by a previous PubAdsService.disableInitialLoad call.
refresh
Fetches and displays new ads for specific or all slots on the page.
removeEventListener
Removes a previously registered listener.
set
Sets values for AdSense attributes that apply to all ad slots under the Publisher Ads service.
setCategoryExclusion
Sets a page-level ad category exclusion for the given label name.
setCentering
Enables and disables horizontal centering of ads.
setForceSafeFrame
Configures whether all ads on the page should be forced to be rendered using a SafeFrame container.
setLocation
Passes location information from websites so you can geo-target line items to specific locations.
setPrivacySettings
Allows configuration of all privacy settings from a single API using a config object.
setPublisherProvidedId
Sets the value for the publisher-provided ID.
setSafeFrameConfig
Sets the page-level preferences for SafeFrame configuration.
setTargeting
Sets custom targeting parameters for a given key that apply to all Publisher Ads service ad slots.
setVideoContent
Sets the video content information to be sent along with the ad requests for targeting and content exclusion purposes.
updateCorrelator
Changes the correlator that is sent with ad requests, effectively starting a new page view.

Methods

clear

clear(slots?: Slot[]): boolean
Removes the ads from the given slots and replaces them with blank content. The slots will be marked as unfetched.

In particular, clearing a slot removes the ad from GPT's long-lived pageview, so future requests will not be influenced by roadblocks or competitive exclusions involving this ad.
Example

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

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();
Parameters
Optional slots: Slot[]The array of slots to clear. Array is optional; all slots will be cleared if it is unspecified.
Returns
booleanReturns true if slots have been cleared, false otherwise.

clearCategoryExclusions

clearCategoryExclusions(): PubAdsService
Clears all page-level ad category exclusion labels. This is useful if you want to refresh the slot.
Example

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

// 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.
See also
Returns
PubAdsServiceThe service object on which the method was called.

clearTargeting

clearTargeting(key?: string): PubAdsService
Clears custom targeting parameters for a specific key or for all keys.
Example

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

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.
See also
Parameters
Optional key: stringTargeting parameter key. The key is optional; all targeting parameters will be cleared if it is unspecified.
Returns
PubAdsServiceThe service object on which the method was called.

collapseEmptyDivs

collapseEmptyDivs(collapseBeforeAdFetch?: boolean): boolean
Enables collapsing of slot divs so that they don't take up any space on the page when there is no ad content to display. This mode must be set before the service is enabled.
See also
Parameters
Optional collapseBeforeAdFetch: booleanWhether to collapse the slots even before the ads are fetched. This parameter is optional; if not provided, false will be used as the default value.
Returns
booleanReturns true if div collapse mode was enabled and false if it is impossible to enable collapse mode because the method was called after the service was enabled.

disableInitialLoad

disableInitialLoad(): void
Disables requests for ads on page load, but allows ads to be requested with a PubAdsService.refresh call. This should be set prior to enabling the service. Async mode must be used; otherwise it will be impossible to request ads using refresh.
See also

display

display(adUnitPath: string, size: GeneralSize, div?: string | Element, clickUrl?: string): void
Constructs and displays an ad slot with the given ad unit path and size. This method does not work with single request mode.

Note: When this method is called, a snapshot of the slot and page state is created to ensure consistency when sending the ad request and rendering the response. Any changes that are made to the slot or page state after this method is called (including targeting, privacy settings, force SafeFrame, etc.) will only apply to subsequent display() or refresh() requests.
Example

JavaScript

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

JavaScript (legacy)

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

TypeScript

googletag.pubads().display("/1234567/sports", [728, 90], "div-1");
See also
Parameters
adUnitPath: stringThe ad unit path of slot to be rendered.
size: GeneralSizeWidth and height of the slot.
Optional div: string | ElementEither the ID of the div containing the slot or the div element itself.
Optional clickUrl: stringThe click URL to use on this slot.

enableLazyLoad

enableLazyLoad(config?: {
  fetchMarginPercent?: number;
  mobileScaling?: number;
  renderMarginPercent?: number;
}): void
Enables lazy loading in GPT as defined by the config object. For more detailed examples, see the Lazy loading sample.

Note: Lazy fetching in SRA only works if all slots are outside the fetching margin.
Example

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

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,
});
See also
Parameters
Optional config: {
  fetchMarginPercent?: number;
  mobileScaling?: number;
  renderMarginPercent?: number;
}		Configuration object allows customization of lazy behavior. Any omitted configurations will use a default set by Google that will be tuned over time. To disable a particular setting, such as a fetching margin, set the value to -1.
  • fetchMarginPercent

    The minimum distance from the current viewport a slot must be before we fetch the ad as a percentage of viewport size. A value of 0 means "when the slot enters the viewport", 100 means "when the ad is 1 viewport away", and so on.
  • renderMarginPercent

    The minimum distance from the current viewport a slot must be before we render an ad. This allows for prefetching the ad, but waiting to render and download other subresources. The value works just like fetchMarginPercent as a percentage of viewport.
  • mobileScaling

    A multiplier applied to margins on mobile devices. This allows varying margins on mobile vs. desktop. For example, a value of 2.0 will multiply all margins by 2 on mobile devices, increasing the minimum distance a slot can be before fetching and rendering.

enableSingleRequest

enableSingleRequest(): boolean
Enables single request mode for fetching multiple ads at the same time. This requires all Publisher Ads slots to be defined and added to the PubAdsService prior to enabling the service. Single request mode must be set before the service is enabled.
See also
Returns
booleanReturns true if single request mode was enabled and false if it is impossible to enable single request mode because the method was called after the service was enabled.

enableVideoAds

enableVideoAds(): void
Signals to GPT that video ads will be present on the page. This enables competitive exclusion constraints on display and video ads. If the video content is known, call PubAdsService.setVideoContent in order to be able to use content exclusion for display ads.

get

get(key: string): null | string
Returns the value for the AdSense attribute associated with the given key.
Example

JavaScript

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

JavaScript (legacy)

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'.
See also
Parameters
key: stringName of the attribute to look for.
Returns
null | stringCurrent value for the attribute key, or null if the key is not present.

getAttributeKeys

getAttributeKeys(): string[]
Returns the attribute keys that have been set on this service.
Example

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

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'].
Returns
string[]Array of attribute keys set on this service. Ordering is undefined.

getTargeting

getTargeting(key: string): string[]
Returns a specific custom service-level targeting parameter that has been set.
Example

JavaScript

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

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

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

JavaScript (legacy)

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).
Parameters
key: stringThe targeting key to look for.
Returns
string[]The values associated with this key, or an empty array if there is no such key.

getTargetingKeys

getTargetingKeys(): string[]
Returns the list of all custom service-level targeting keys that have been set.
Example

JavaScript

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

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

JavaScript (legacy)

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'].
Returns
string[]Array of targeting keys. Ordering is undefined.

isInitialLoadDisabled

isInitialLoadDisabled(): boolean
Returns whether or not initial requests for ads was successfully disabled by a previous PubAdsService.disableInitialLoad call.
Returns
booleanReturns true if a previous call to PubAdsService.disableInitialLoad was successful, false otherwise.

refresh

refresh(slots?: null | Slot[], options?: {
  changeCorrelator: boolean;
}): void
Fetches and displays new ads for specific or all slots on the page. Works only in asynchronous rendering mode.

For proper behavior across all browsers, calling refresh must be preceded by a call to display the ad slot. If the call to display is omitted, refresh may behave unexpectedly. If desired, the PubAdsService.disableInitialLoad method can be used to stop display from fetching an ad.

Refreshing a slot removes the old ad from GPT's long-lived pageview, so future requests will not be influenced by roadblocks or competitive exclusions involving that ad.
Example

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

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 });
See also
Parameters
Optional slots: null | Slot[]The slots to refresh. Array is optional; all slots will be refreshed if it is unspecified.
Optional options: {
  changeCorrelator: boolean;
}		Configuration options associated with this refresh call.
  • changeCorrelator

    Specifies whether or not a new correlator is to be generated for fetching ads. Our ad servers maintain this correlator value briefly (currently for 30 seconds, but subject to change), such that requests with the same correlator received close together will be considered a single page view. By default a new correlator is generated for every refresh.

    Note: this option has no effect on GPT's long-lived pageview, which automatically reflects the ads currently on the page and has no expiration time.

set

set(key: string, value: string): PubAdsService
Sets values for AdSense attributes that apply to all ad slots under the Publisher Ads service.

Calling this more than once for the same key will override previously set values for that key. All values must be set before calling display or refresh.
Example

JavaScript

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

JavaScript (legacy)

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

TypeScript

googletag.pubads().set("adsense_background_color", "#FFFFFF");
See also
Parameters
key: stringThe name of the attribute.
value: stringAttribute value.
Returns
PubAdsServiceThe service object on which the method was called.

setCategoryExclusion

setCategoryExclusion(categoryExclusion: string): PubAdsService
Sets a page-level ad category exclusion for the given label name.
Example

JavaScript

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

JavaScript (legacy)

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

TypeScript

// Label = AirlineAd.
googletag.pubads().setCategoryExclusion("AirlineAd");
See also
Parameters
categoryExclusion: stringThe ad category exclusion label to add.
Returns
PubAdsServiceThe service object on which the method was called.

setCentering

setCentering(centerAds: boolean): void
Enables and disables horizontal centering of ads. Centering is disabled by default. In legacy gpt_mobile.js, centering is enabled by default.

This method should be invoked before calling display or refresh because only ads that are requested after calling this method will be centered.
Example

JavaScript

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

JavaScript (legacy)

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

TypeScript

// Make ads centered.
googletag.pubads().setCentering(true);
Parameters
centerAds: booleantrue to center ads, false to left-align them.

setForceSafeFrame

setForceSafeFrame(forceSafeFrame: boolean): PubAdsService
Configures whether all ads on the page should be forced to be rendered using a SafeFrame container.

Please keep the following things in mind while using this API:
  • This setting will only take effect for subsequent ad requests made for the respective slots.
  • The slot level setting, if specified, will always override the page level setting.
  • If set to true (at slot-level or page level), the ad will always be rendered using a SafeFrame container independent of the choice made in the Google Ad Manager UI.
  • However, if set to false or left unspecified, the ad will be rendered using a SafeFrame container depending on the type of creative and the selection made in the Google Ad Manager UI.
  • This API should be used with caution as it could impact the behaviour of creatives that attempt to break out of their iFrames or rely on them being rendered directly in a publishers page.
Example

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

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");
See also
Parameters
forceSafeFrame: booleantrue to force all ads on the page to be rendered in SafeFrames and false to change the previous setting to false. Setting this to false when unspecified earlier, won't change anything.
Returns
PubAdsServiceThe service object on which the function was called.

setLocation

setLocation(address: string): PubAdsService
Passes location information from websites so you can geo-target line items to specific locations.
Example

JavaScript

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

JavaScript (legacy)

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

TypeScript

// Postal code:
googletag.pubads().setLocation("10001,US");
Parameters
address: stringFreeform address.
Returns
PubAdsServiceThe service object on which the method was called.

setPrivacySettings

setPrivacySettings(privacySettings: PrivacySettingsConfig): PubAdsService
Allows configuration of all privacy settings from a single API using a config object.
Example

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

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,
});
See also
Parameters
privacySettings: PrivacySettingsConfigObject containing privacy settings config.
Returns
PubAdsServiceThe service object on which the function was called.

setPublisherProvidedId

setPublisherProvidedId(ppid: string): PubAdsService
Sets the value for the publisher-provided ID.
Example

JavaScript

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

JavaScript (legacy)

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

TypeScript

googletag.pubads().setPublisherProvidedId("12JD92JD8078S8J29SDOAKC0EF230337");
See also
Parameters
ppid: stringAn alphanumeric ID provided by the publisher. Must be between 32 and 150 characters.
Returns
PubAdsServiceThe service object on which the method was called.

setSafeFrameConfig

setSafeFrameConfig(config: SafeFrameConfig): PubAdsService
Sets the page-level preferences for SafeFrame configuration. Any unrecognized keys in the config object will be ignored. The entire config will be ignored if an invalid value is passed for a recognized key.

These page-level preferences will be overridden by slot-level preferences, if specified.
Example

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

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");
See also
Parameters
config: SafeFrameConfigThe configuration object.
Returns
PubAdsServiceThe service object on which the method was called.

setTargeting

setTargeting(key: string, value: string | string[]): PubAdsService
Sets custom targeting parameters for a given key that apply to all Publisher Ads service ad slots. Calling this multiple times for the same key will overwrite old values. These keys are defined in your Google Ad Manager account.
Example

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

// 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"]);
See also
Parameters
key: stringTargeting parameter key.
value: string | string[]Targeting parameter value or array of values.
Returns
PubAdsServiceThe service object on which the method was called.

setVideoContent

setVideoContent(videoContentId: string, videoCmsId: string): void
Sets the video content information to be sent along with the ad requests for targeting and content exclusion purposes. Video ads will be automatically enabled when this method is called. For videoContentId and videoCmsId, use the values that are provided to the Google Ad Manager content ingestion service.
See also
Parameters
videoContentId: stringThe video content ID.
videoCmsId: stringThe video CMS ID.

updateCorrelator

updateCorrelator(): PubAdsService
Changes the correlator that is sent with ad requests, effectively starting a new page view. The correlator is the same for all the ad requests coming from one page view, and unique across page views. Only applies to async mode.

Note: this has no effect on GPT's long-lived pageview, which automatically reflects the ads actually on the page and has no expiration time.
Example

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

// 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.
Returns
PubAdsServiceThe service object on which the function was called.

googletag.ResponseInformation

An object representing a single ad response.
Properties
advertiserId
The ID of the advertiser.
campaignId
The ID of the campaign.
creativeId
The ID of the creative.
creativeTemplateId
The template ID of the ad.
lineItemId
The ID of the line item.
See also

Properties

advertiserId

advertiserId: null | number
The ID of the advertiser.

campaignId

campaignId: null | number
The ID of the campaign.

creativeId

creativeId: null | number
The ID of the creative.

creativeTemplateId

creativeTemplateId: null | number
The template ID of the ad.

lineItemId

lineItemId: null | number
The ID of the line item.

googletag.RewardedPayload

An object representing the reward associated with a rewarded ad
Properties
amount
The number of items included in the reward.
type
The type of item included in the reward (for example, "coin").
See also

Properties

amount

amount: number
The number of items included in the reward.

type

type: string
The type of item included in the reward (for example, "coin").

googletag.SafeFrameConfig

Configuration object for SafeFrame containers.
Properties
allowOverlayExpansion?
Whether SafeFrame should allow ad content to expand by overlaying page content.
allowPushExpansion?
Whether SafeFrame should allow ad content to expand by pushing page content.
sandbox?
Whether SafeFrame should use the HTML5 sandbox attribute to prevent top level navigation without user interaction.
useUniqueDomain?
Deprecated. Whether SafeFrame should use randomized subdomains for Reservation creatives.
See also

Properties

Optional allowOverlayExpansion

allowOverlayExpansion?: boolean
Whether SafeFrame should allow ad content to expand by overlaying page content.

Optional allowPushExpansion

allowPushExpansion?: boolean
Whether SafeFrame should allow ad content to expand by pushing page content.

Optional sandbox

sandbox?: boolean
Whether SafeFrame should use the HTML5 sandbox attribute to prevent top level navigation without user interaction. The only valid value is true (cannot be forced to false). Note that the sandbox attribute disables plugins (e.g. Flash).

Optional useUniqueDomain

useUniqueDomain?: null | boolean
Whether SafeFrame should use randomized subdomains for Reservation creatives. Pass in null to clear the stored value.

Note: this feature is enabled by default.
See also

googletag.Service

Base service class that contains methods common for all services.
Methods
addEventListener
Registers a listener that allows you to set up and call a JavaScript function when a specific GPT event happens on the page.
getSlots
Get the list of slots associated with this service.
removeEventListener
Removes a previously registered listener.

Methods

addEventListener

addEventListener<K extends keyof EventTypeMap>(eventType: K, listener: ((arg: EventTypeMap[K]) => void)): Service
Registers a listener that allows you to set up and call a JavaScript function when a specific GPT event happens on the page. The following events are supported: An object of the appropriate event type is passed to the listener when it is called.
Example

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

// 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.
  }
});
See also
Parameters
eventType: KA string representing the type of event generated by GPT. Event types are case sensitive.
listener: ((arg: EventTypeMap[K]) => void)Function that takes a single event object argument.
Returns
ServiceThe service object on which the method was called.

getSlots

getSlots(): Slot[]
Get the list of slots associated with this service.
Returns
Slot[]Slots in the order in which they were added to the service.

removeEventListener

removeEventListener<K extends keyof EventTypeMap>(eventType: K, listener: ((event: EventTypeMap[K]) => void)): void
Removes a previously registered listener.
Example

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

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();
});
Parameters
eventType: KA string representing the type of event generated by GPT. Event types are case sensitive.
listener: ((event: EventTypeMap[K]) => void)Function that takes a single event object argument.

googletag.SizeMappingBuilder

Builder for size mapping specification objects. This builder is provided to help easily construct size specifications.
Methods
addSize
Adds a mapping from a single-size array (representing the viewport) to a single- or multi-size array representing the slot.
build
Builds a size map specification from the mappings added to this builder.
See also

Methods

addSize

addSize(viewportSize: SingleSizeArray, slotSize: GeneralSize): SizeMappingBuilder
Adds a mapping from a single-size array (representing the viewport) to a single- or multi-size array representing the slot.
Example

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

// 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]
Parameters
viewportSize: SingleSizeArrayThe size of the viewport for this mapping entry.
slotSize: GeneralSizeThe sizes of the slot for this mapping entry.
Returns
SizeMappingBuilderA reference to this builder.

build

build(): null | SizeMappingArray
Builds a size map specification from the mappings added to this builder.

If any invalid mappings have been supplied, this method will return null. Otherwise it returns a specification in the correct format to pass to Slot.defineSizeMapping.

Note: the behavior of the builder after calling this method is undefined.
Returns
null | SizeMappingArrayThe result built by this builder. Can be null if invalid size mappings were supplied.

googletag.Slot

Slot is an object representing a single ad slot on a page.
Methods
addService
Adds a Service to this slot.
clearCategoryExclusions
Clears all slot-level ad category exclusion labels for this slot.
clearTargeting
Clears specific or all custom slot-level targeting parameters for this slot.
defineSizeMapping
Sets an array of mappings from a minimum viewport size to slot size for this slot.
get
Returns the value for the AdSense attribute associated with the given key for this slot.
getAdUnitPath
Returns the full path of the ad unit, with the network code and ad unit path.
getAttributeKeys
Returns the list of attribute keys set on this slot.
getCategoryExclusions
Returns the ad category exclusion labels for this slot.
getResponseInformation
Returns the ad response information.
getSlotElementId
Returns the ID of the slot div provided when the slot was defined.
getTargeting
Returns a specific custom targeting parameter set on this slot.
getTargetingKeys
Returns the list of all custom targeting keys set on this slot.
set
Sets a value for an AdSense attribute on this ad slot.
setCategoryExclusion
Sets a slot-level ad category exclusion label on this slot.
setClickUrl
Sets the click URL to which users will be redirected after clicking on the ad.
setCollapseEmptyDiv
Sets whether the slot div should be hidden when there is no ad in the slot.
setConfig
Sets general configuration options for this slot.
setForceSafeFrame
Configures whether ads in this slot should be forced to be rendered using a SafeFrame container.
setSafeFrameConfig
Sets the slot-level preferences for SafeFrame configuration.
setTargeting
Sets a custom targeting parameter for this slot.
updateTargetingFromMap
Sets custom targeting parameters for this slot, from a key:value map in a JSON object.

Methods

addService

addService(service: Service): Slot
Adds a Service to this slot.
Example

JavaScript

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

JavaScript (legacy)

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

TypeScript

googletag.defineSlot("/1234567/sports", [160, 600], "div")!.addService(googletag.pubads());
See also
Parameters
service: ServiceThe service to be added.
Returns
SlotThe slot object on which the method was called.

clearCategoryExclusions

clearCategoryExclusions(): Slot
Clears all slot-level ad category exclusion labels for this slot.
Example

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

// 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.
Returns
SlotThe slot object on which the method was called.

clearTargeting

clearTargeting(key?: string): Slot
Clears specific or all custom slot-level targeting parameters for this slot.
Example

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

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.
See also
Parameters
Optional key: stringTargeting parameter key. The key is optional; all targeting parameters will be cleared if it is unspecified.
Returns
SlotThe slot object on which the method was called.

defineSizeMapping

defineSizeMapping(sizeMapping: SizeMappingArray): Slot
Sets an array of mappings from a minimum viewport size to slot size for this slot.
Example

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

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!);
See also
Parameters
sizeMapping: SizeMappingArrayArray of size mappings. You can use SizeMappingBuilder to create it. Each size mapping is an array of two elements: SingleSizeArray and GeneralSize.
Returns
SlotThe slot object on which the method was called.

get

get(key: string): null | string
Returns the value for the AdSense attribute associated with the given key for this slot. To see service-level attributes inherited by this slot, use PubAdsService.get.
Example

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

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'.
See also
Parameters
key: stringName of the attribute to look for.
Returns
null | stringCurrent value for the attribute key, or null if the key is not present.

getAdUnitPath

getAdUnitPath(): string
Returns the full path of the ad unit, with the network code and ad unit path.
Example

JavaScript

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

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

JavaScript (legacy)

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'.
Returns
stringAd unit path.

getAttributeKeys

getAttributeKeys(): string[]
Returns the list of attribute keys set on this slot. To see the keys of service-level attributes inherited by this slot, use PubAdsService.getAttributeKeys.
Example

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

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'].
Returns
string[]Array of attribute keys. Ordering is undefined.

getCategoryExclusions

getCategoryExclusions(): string[]
Returns the ad category exclusion labels for this slot.
Example

JavaScript

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

slot.getCategoryExclusions();
// Returns ['AirlineAd', 'TrainAd'].

JavaScript (legacy)

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'].
Returns
string[]The ad category exclusion labels for this slot, or an empty array if none have been set.

getResponseInformation

getResponseInformation(): null | ResponseInformation
Returns the ad response information. This is based on the last ad response for the slot. If this is called when the slot has no ad, null will be returned.
Returns
null | ResponseInformationThe latest ad response information, or null if the slot has no ad.

getSlotElementId

getSlotElementId(): string
Returns the ID of the slot div provided when the slot was defined.
Example

JavaScript

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

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

JavaScript (legacy)

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'.
Returns
stringSlot div ID.

getTargeting

getTargeting(key: string): string[]
Returns a specific custom targeting parameter set on this slot. Service-level targeting parameters are not included.
Example

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

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).
Parameters
key: stringThe targeting key to look for.
Returns
string[]The values associated with this key, or an empty array if there is no such key.

getTargetingKeys

getTargetingKeys(): string[]
Returns the list of all custom targeting keys set on this slot. Service-level targeting keys are not included.
Example

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

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'].
Returns
string[]Array of targeting keys. Ordering is undefined.

set

set(key: string, value: string): Slot
Sets a value for an AdSense attribute on this ad slot. This will override any values set at the service level for this key.

Calling this method more than once for the same key will override previously set values for that key. All values must be set before calling display or refresh.
Example

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

// 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());
See also
Parameters
key: stringThe name of the attribute.
value: stringAttribute value.
Returns
SlotThe slot object on which the method was called.

setCategoryExclusion

setCategoryExclusion(categoryExclusion: string): Slot
Sets a slot-level ad category exclusion label on this slot.
Example

JavaScript

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

JavaScript (legacy)

// 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());
See also
Parameters
categoryExclusion: stringThe ad category exclusion label to add.
Returns
SlotThe slot object on which the method was called.

setClickUrl

setClickUrl(value: string): Slot
Sets the click URL to which users will be redirected after clicking on the ad.

The Google Ad Manager servers still record a click even if the click URL is replaced. Any landing page URL associated with the creative that is served is appended to the provided value. Subsequent calls overwrite the value. This works only for non-SRA requests.
Example

JavaScript

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

JavaScript (legacy)

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());
Parameters
value: stringThe click URL to set.
Returns
SlotThe slot object on which the method was called.

setCollapseEmptyDiv

setCollapseEmptyDiv(collapse: boolean, collapseBeforeAdFetch?: boolean): Slot
Sets whether the slot div should be hidden when there is no ad in the slot. This overrides the service-level settings.
Example

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

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.
See also
Parameters
collapse: booleanWhether to collapse the slot if no ad is returned.
Optional collapseBeforeAdFetch: booleanWhether to collapse the slot even before an ad is fetched. Ignored if collapse is not true.
Returns
SlotThe slot object on which the method was called.

setConfig

setConfig(slotConfig: SlotSettingsConfig): void
Sets general configuration options for this slot.
Parameters
slotConfig: SlotSettingsConfigThe configuration object.

setForceSafeFrame

setForceSafeFrame(forceSafeFrame: boolean): Slot
Configures whether ads in this slot should be forced to be rendered using a SafeFrame container.

Please keep the following things in mind while using this API:
  • This setting will only take effect for subsequent ad requests made for the respective slots.
  • The slot level setting, if specified, will always override the page level setting.
  • If set to true (at slot-level or page level), the ad will always be rendered using a SafeFrame container independent of the choice made in the Google Ad Manager UI.
  • However, if set to false or left unspecified, the ad will be rendered using a SafeFrame container depending on the type of creative and the selection made in the Google Ad Manager UI.
  • This API should be used with caution as it could impact the behaviour of creatives that attempt to break out of their iFrames or rely on them being rendered directly in a publishers page.
Example

JavaScript

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

JavaScript (legacy)

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());
See also
Parameters
forceSafeFrame: booleantrue to force all ads in this slot to be rendered in SafeFrames and false to opt-out of a page-level setting (if present). Setting this to false when not specified at the page-level won't change anything.
Returns
SlotThe slot object on which the method was called.

setSafeFrameConfig

setSafeFrameConfig(config: null | SafeFrameConfig): Slot
Sets the slot-level preferences for SafeFrame configuration. Any unrecognized keys in the config object will be ignored. The entire config will be ignored if an invalid value is passed for a recognized key.

These slot-level preferences, if specified, will override any page-level preferences.
Example

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

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");
See also
Parameters
config: null | SafeFrameConfigThe configuration object.
Returns
SlotThe slot object on which the method was called.

setTargeting

setTargeting(key: string, value: string | string[]): Slot
Sets a custom targeting parameter for this slot. Calling this method multiple times for the same key will overwrite old values. Values set here will overwrite targeting parameters set at the service-level. These keys are defined in your Google Ad Manager account.
Example

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

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"]);
See also
Parameters
key: stringTargeting parameter key.
value: string | string[]Targeting parameter value or array of values.
Returns
SlotThe slot object on which the method was called.

updateTargetingFromMap

updateTargetingFromMap(map: {
  [adUnitPath: string]: string | string[];
}): Slot
Sets custom targeting parameters for this slot, from a key:value map in a JSON object. This is the same as calling Slot.setTargeting for all the key values of the object. These keys are defined in your Google Ad Manager account.

Notes:
  • In case of overwriting, only the last value will be kept.
  • If the value is an array, any previous value will be overwritten, not merged.
  • Values set here will overwrite targeting parameters set at the service-level.
Example

JavaScript

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

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

JavaScript (legacy)

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"],
});
Parameters
map: {
  [adUnitPath: string]: string | string[];
}		Targeting parameter key:value map.
Returns
SlotThe slot object on which the method was called.

googletag.config

Main configuration interface for page-level settings.
Interfaces
AdExpansionConfig
Settings to control ad expansion.
ComponentAuctionConfig
An object representing a single component auction in a on-device ad auction.
InterstitialConfig
An object which defines the behavior of a single interstitial ad slot.
PageSettingsConfig
Main configuration interface for page-level settings.
PrivacyTreatmentsConfig
Settings to control publisher privacy treatments.
PublisherProvidedSignalsConfig
Publisher provided signals (PPS) configuration object.
SlotSettingsConfig
Main configuration interface for slot-level settings.
TaxonomyData
An object containing the values for a single Taxonomy.
Type Aliases
InterstitialTrigger
Supported interstitial ad triggers.
PrivacyTreatment
Supported publisher privacy treatments.
Taxonomy
Supported taxonomies for publisher provided signals (PPS).

Type Aliases

InterstitialTrigger

InterstitialTrigger: "unhideWindow" | "navBar"
Supported interstitial ad triggers.

PrivacyTreatment

PrivacyTreatment: "disablePersonalization"
Supported publisher privacy treatments.

Taxonomy

Taxonomy: "IAB_AUDIENCE_1_1" | "IAB_CONTENT_2_2"
Supported taxonomies for publisher provided signals (PPS).
See also

googletag.config.AdExpansionConfig

Settings to control ad expansion.
Properties
enabled?
Whether ad expansion is enabled or disabled.
Example

JavaScript

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

JavaScript (legacy)

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

Properties

Optional enabled

enabled?: null | boolean
Whether ad expansion is enabled or disabled.

Setting this value overrides the default configured in Google Ad Manager.
See also

googletag.config.ComponentAuctionConfig

An object representing a single component auction in a on-device ad auction.
Properties
auctionConfig
An auction configuration object for this component auction.
configKey
The configuration key associated with this component auction.
See also

Properties

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;
}
An auction configuration object for this component auction.

If this value is set to null, any existing configuration for the specified configKey will be deleted.
Example

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

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

configKey

configKey: string
The configuration key associated with this component auction.

This value must be non-empty and should be unique. If two ComponentAuctionConfig objects share the same configKey value, the last to be set will overwrite prior configurations.

googletag.config.InterstitialConfig

An object which defines the behavior of a single interstitial ad slot.
Properties
requireStorageAccess?
Whether local storage consent is required to display this interstitial ad.
triggers?
The interstitial trigger configuration for this interstitial ad.

Properties

Optional requireStorageAccess

requireStorageAccess?: null | boolean
Whether local storage consent is required to display this interstitial ad.

GPT uses local storage to enforce a frequency cap for interstitial ads. However, users who have not provided local storage consent are still eligible to be served interstitial ads. Setting this property to true opts out of the default behavior, and ensures interstial ads are only shown to users who have provided local storage consent.
Example

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

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

Optional triggers

triggers?: null | Partial<Record<InterstitialTrigger, boolean>>
The interstitial trigger configuration for this interstitial ad.

Setting the value of an interstitial trigger to true will enable it and false will disable it. This will override the default values configured in Google Ad Manager.
Example

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

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

googletag.config.PageSettingsConfig

Main configuration interface for page-level settings.

Allows setting multiple features with a single API call.

All properties listed below are examples and do not reflect actual features that utilize setConfig. For the set of features, see fields within the PageSettingsConfig type below.

Examples:
  • Only features specified in the googletag.setConfig call are modified. 
      // Configure feature alpha.
  googletag.setConfig({
      alpha: {...}
  });

  // Configure feature bravo. Feature alpha is unchanged.
  googletag.setConfig({
     bravo: {...}
  });
  • All settings for a given feature are updated with each call to 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
      }
  });
  • All settings for a feature can be cleared by passing 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,
  });
Properties
adExpansion?
Settings to control ad expansion.
adYield?
Deprecated. 
pps?
Settings to control publisher provided signals (PPS).
privacyTreatments?
Settings to control publisher privacy treatments.
threadYield?
Setting to control whether GPT should yield the JS thread when rendering creatives.

Properties

Optional adExpansion

adExpansion?: null | AdExpansionConfig
Settings to control ad expansion.

Optional adYield

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

Optional pps

Settings to control publisher provided signals (PPS).

Optional privacyTreatments

privacyTreatments?: null | PrivacyTreatmentsConfig
Settings to control publisher privacy treatments.

Optional threadYield

threadYield?: null | "DISABLED" | "ENABLED_ALL_SLOTS"
Setting to control whether GPT should yield the JS thread when rendering creatives.

GPT will yield only for browsers that support the Scheduler.postTask or Scheduler.yield API.

Supported values:
  • null (default): GPT will yield the JS thread for slots outside of the viewport.
  • ENABLED_ALL_SLOTS: GPT will yield the JS thread for all slots regardless of whether the slot is within the viewport.
  • DISABLED: GPT will not yield the JS thread.
Example

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

// 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 });
See also

googletag.config.PrivacyTreatmentsConfig

Settings to control publisher privacy treatments.
Properties
treatments
An array of publisher privacy treatments to enable.

Properties

treatments

treatments: null | "disablePersonalization"[]
An array of publisher privacy treatments to enable.
Example

JavaScript

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

JavaScript (legacy)

// 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

Publisher provided signals (PPS) configuration object.
Properties
taxonomies
An object containing Taxonomy mappings.
Example

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

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

Properties

taxonomies

taxonomies: Partial<Record<Taxonomy, TaxonomyData>>
An object containing Taxonomy mappings.

googletag.config.SlotSettingsConfig

Main configuration interface for slot-level settings.

Allows setting multiple features with a single API call for a single slot.

All properties listed below are examples and do not reflect actual features that utilize setConfig. For the set of features, see fields within the SlotSettingsConfig type below.

Examples:
  • Only features specified in the Slot.setConfig call are modified. 
      const slot = googletag.defineSlot("/1234567/example", [160, 600]);

  // Configure feature alpha.
  slot.setConfig({
      alpha: {...}
  });

  // Configure feature bravo. Feature alpha is unchanged.
  slot.setConfig({
     bravo: {...}
  });
  • All settings for a given feature are updated with each call to 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
      }
  });
  • All settings for a feature can be cleared by passing 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,
  });
Properties
adExpansion?
Settings to control ad expansion.
componentAuction?
An array of component auctions to be included in an on-device ad auction.
interstitial?
Settings that control interstitial ad slot behavior.

Properties

Optional adExpansion

adExpansion?: null | AdExpansionConfig
Settings to control ad expansion.

Optional componentAuction

componentAuction?: null | ComponentAuctionConfig[]
An array of component auctions to be included in an on-device ad auction.

Optional interstitial

interstitial?: null | InterstitialConfig
Settings that control interstitial ad slot behavior.

googletag.config.TaxonomyData

An object containing the values for a single Taxonomy.
Properties
values
A list of Taxonomy values.

Properties

values

values: string[]
A list of Taxonomy values.

googletag.enums

This is the namespace that GPT uses for enum types.
Enumerations
OutOfPageFormat
Out-of-page formats supported by GPT.
TrafficSource
Traffic sources supported by GPT.

Enumerations

OutOfPageFormat

OutOfPageFormat
Out-of-page formats supported by GPT.
See also
Enumeration Members
BOTTOM_ANCHOR
Anchor format where slot sticks to the bottom of the viewport.
GAME_MANUAL_INTERSTITIAL
Game manual interstitial format.

Note: Game manual interstitial is a limited-access format.
INTERSTITIAL
Web interstitial creative format.
LEFT_SIDE_RAIL
Left side rail format.
REWARDED
Rewarded format.
RIGHT_SIDE_RAIL
Right side rail format.
TOP_ANCHOR
Anchor format where slot sticks to the top of the viewport.

TrafficSource

TrafficSource
Traffic sources supported by GPT.
See also
Enumeration Members
ORGANIC
Direct URL entry, site search, or app download.
PURCHASED
Traffic redirected from properties other than owned (acquired or otherwise incentivized activity).

googletag.events

This is the namespace that GPT uses for Events. Your code can react to these events using Service.addEventListener.
Interfaces
Event
Base Interface for all GPT events.
EventTypeMap
This is a pseudo-type that maps an event name to its corresponding event object type for Service.addEventListener and Service.removeEventListener.
GameManualInterstitialSlotClosedEvent
This event is fired when a game manual interstitial slot has been closed by the user.
GameManualInterstitialSlotReadyEvent
This event is fired when a game manual interstitial slot is ready to be shown to the user.
ImpressionViewableEvent
This event is fired when an impression becomes viewable, according to the Active View criteria.
RewardedSlotClosedEvent
This event is fired when a rewarded ad slot is closed by the user.
RewardedSlotGrantedEvent
This event is fired when a reward is granted for viewing a rewarded ad.
RewardedSlotReadyEvent
This event is fired when a rewarded ad is ready to be displayed.
SlotOnloadEvent
This event is fired when the creative's iframe fires its load event.
SlotRenderEndedEvent
This event is fired when the creative code is injected into a slot.
SlotRequestedEvent
This event is fired when an ad has been requested for a particular slot.
SlotResponseReceived
This event is fired when an ad response has been received for a particular slot.
SlotVisibilityChangedEvent
This event is fired whenever the on-screen percentage of an ad slot's area changes.

googletag.events.Event

Base Interface for all GPT events. All GPT events below will have the following fields.
Properties
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
See also

Properties

serviceName

serviceName: string
Name of the service that triggered the event.

slot

slot: Slot
The slot that triggered the event.

googletag.events.EventTypeMap

This is a pseudo-type that maps an event name to its corresponding event object type for Service.addEventListener and Service.removeEventListener. It is documented for reference and type safety purposes only.
Properties
gameManualInterstitialSlotClosed
gameManualInterstitialSlotReady
impressionViewable
rewardedSlotClosed
rewardedSlotGranted
rewardedSlotReady
slotOnload
slotRenderEnded
slotRequested
slotResponseReceived
slotVisibilityChanged

Properties

gameManualInterstitialSlotClosed

gameManualInterstitialSlotReady

impressionViewable

rewardedSlotClosed

rewardedSlotGranted

rewardedSlotReady

slotOnload

slotRenderEnded

slotRequested

slotResponseReceived

slotResponseReceived: SlotResponseReceived
Alias for events.SlotResponseReceived.

slotVisibilityChanged

googletag.events.GameManualInterstitialSlotClosedEvent

Extends Event
This event is fired when a game manual interstitial slot has been closed by the user.

Note: Game manual interstitial is a limited-access format.
Properties
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Example

JavaScript

// This listener is called when a game manual interstitial slot is closed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotClosed", (event) => {
    const slot = event.slot;
    console.log("Game manual interstital slot", slot.getSlotElementId(), "is closed.");

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

JavaScript (legacy)

// This listener is called when a game manual interstitial slot is closed.
var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotClosed", 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 interstitial slot is closed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotClosed", (event) => {
    const slot = event.slot;
    console.log("Game manual interstital slot", slot.getSlotElementId(), "is closed.");

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

googletag.events.GameManualInterstitialSlotReadyEvent

Extends Event
This event is fired when a game manual interstitial slot is ready to be shown to the user.

Note: Game manual interstitial is a limited-access format.
Properties
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Methods
makeGameManualInterstitialVisible
Displays the game manual interstitial ad to the user.
Example

JavaScript

// This listener is called when a game manual interstitial slot is ready to
// be displayed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.GAME_MANUAL_INTERSTITIAL,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotReady", (event) => {
    const slot = event.slot;
    console.log(
      "Game manual interstital slot",
      slot.getSlotElementId(),
      "is ready to be displayed.",
    );

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

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

JavaScript (legacy)

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

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotReady", 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,
);

// Slot returns null if the page or device does not support game manual interstitial ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  googletag.pubads().addEventListener("gameManualInterstitialSlotReady", (event) => {
    const slot = event.slot;
    console.log(
      "Game manual interstital slot",
      slot.getSlotElementId(),
      "is ready to be displayed.",
    );

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

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

Methods

makeGameManualInterstitialVisible

makeGameManualInterstitialVisible(): void
Displays the game manual interstitial ad to the user.

googletag.events.ImpressionViewableEvent

Extends Event
This event is fired when an impression becomes viewable, according to the Active View criteria.
Properties
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Example

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

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

googletag.events.RewardedSlotClosedEvent

Extends Event
This event is fired when a rewarded ad slot is closed by the user. It may fire either before or after a reward has been granted. To determine whether a reward has been granted, use events.RewardedSlotGrantedEvent instead.
Properties
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Example

JavaScript

const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

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

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

JavaScript (legacy)

var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

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

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

TypeScript

const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

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

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

googletag.events.RewardedSlotGrantedEvent

Extends Event
This event is fired when a reward is granted for viewing a rewarded ad. If the ad is closed before the criteria for granting a reward is met, this event will not fire.
Properties
payload
An object containing information about the reward that was granted.
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Example

JavaScript

const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

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

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

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

JavaScript (legacy)

var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotGranted", 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

const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

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

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

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

Properties

payload

payload: null | RewardedPayload
An object containing information about the reward that was granted.

googletag.events.RewardedSlotReadyEvent

Extends Event
This event is fired when a rewarded ad is ready to be displayed. The publisher is responsible for presenting the user an option to view the ad before displaying it.
Properties
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Methods
makeRewardedVisible
Displays the rewarded ad.
Example

JavaScript

// This listener is called when a rewarded ad slot becomes ready to be
// displayed.
const targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotReady", (event) => {
    const slot = event.slot;
    console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed.");

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

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

JavaScript (legacy)

// This listener is called when a rewarded ad slot becomes ready to be
// displayed.
var targetSlot = googletag.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotReady", 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.defineOutOfPageSlot(
  "/1234567/example",
  googletag.enums.OutOfPageFormat.REWARDED,
);

// Slot returns null if the page or device does not support rewarded ads.
if (targetSlot) {
  targetSlot.addService(googletag.pubads());

  // This listener is called whenever a reward is granted for a
  // rewarded ad.
  googletag.pubads().addEventListener("rewardedSlotReady", (event) => {
    const slot = event.slot;
    console.log("Rewarded ad slot", slot.getSlotElementId(), "is ready to be displayed.");

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

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

Methods

makeRewardedVisible

makeRewardedVisible(): void
Displays the rewarded ad. This method should not be called until the user has consented to view the ad.

googletag.events.SlotOnloadEvent

Extends Event
This event is fired when the creative's iframe fires its load event. When rendering rich media ads in sync rendering mode, no iframe is used so no SlotOnloadEvent will be fired.
Properties
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Example

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

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

googletag.events.SlotRenderEndedEvent

Extends Event
This event is fired when the creative code is injected into a slot. This event will occur before the creative's resources are fetched, so the creative may not be visible yet. If you need to know when all creative resources for a slot have finished loading, consider the events.SlotOnloadEvent instead.
Properties
advertiserId
Advertiser ID of the rendered ad.
campaignId
Campaign ID of the rendered ad.
companyIds
IDs of the companies that bid on the rendered backfill ad.
creativeId
Creative ID of the rendered reservation ad.
creativeTemplateId
Creative template ID of the rendered reservation ad.
isBackfill
Whether an ad was a backfill ad.
isEmpty
Whether an ad was returned for the slot.
labelIds
Deprecated. 
lineItemId
Line item ID of the rendered reservation ad.
serviceName
Name of the service that triggered the event.
size
Indicates the pixel size of the rendered creative.
slot
The slot that triggered the event.
slotContentChanged
Whether the slot content was changed with the rendered ad.
sourceAgnosticCreativeId
Creative ID of the rendered reservation or backfill ad.
sourceAgnosticLineItemId
Line item ID of the rendered reservation or backfill ad.
yieldGroupIds
IDs of the yield groups for the rendered backfill ad.
Example

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

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

Properties

advertiserId

advertiserId: null | number
Advertiser ID of the rendered ad. Value is null for empty slots, backfill ads, and creatives rendered by services other than PubAdsService.

campaignId

campaignId: null | number
Campaign ID of the rendered ad. Value is null for empty slots, backfill ads, and creatives rendered by services other than PubAdsService.

companyIds

companyIds: null | number[]
IDs of the companies that bid on the rendered backfill ad. Value is null for empty slots, reservation ads, and creatives rendered by services other than PubAdsService.

creativeId

creativeId: null | number
Creative ID of the rendered reservation ad. Value is null for empty slots, backfill ads, and creatives rendered by services other than PubAdsService.

creativeTemplateId

creativeTemplateId: null | number
Creative template ID of the rendered reservation ad. Value is null for empty slots, backfill ads, and creatives rendered by services other than PubAdsService.

isBackfill

isBackfill: boolean
Whether an ad was a backfill ad. Value is true if the ad was a backfill ad, false otherwise.

isEmpty

isEmpty: boolean
Whether an ad was returned for the slot. Value is true if no ad was returned, false otherwise.

labelIds

labelIds: null | number[]

lineItemId

lineItemId: null | number
Line item ID of the rendered reservation ad. Value is null for empty slots, backfill ads, and creatives rendered by services other than PubAdsService.

size

size: null | string | number[]
Indicates the pixel size of the rendered creative. Example: [728, 90]. Value is null for empty ad slots.

slotContentChanged

slotContentChanged: boolean
Whether the slot content was changed with the rendered ad. Value is true if the content was changed, false otherwise.

sourceAgnosticCreativeId

sourceAgnosticCreativeId: null | number
Creative ID of the rendered reservation or backfill ad. Value is null if the ad is not a reservation or line item backfill, or the creative is rendered by services other than PubAdsService.

sourceAgnosticLineItemId

sourceAgnosticLineItemId: null | number
Line item ID of the rendered reservation or backfill ad. Value is null if the ad is not a reservation or line item backfill, or the creative is rendered by services other than PubAdsService.

yieldGroupIds

yieldGroupIds: null | number[]
IDs of the yield groups for the rendered backfill ad. Value is null for empty slots, reservation ads, and creatives rendered by services other than PubAdsService.

googletag.events.SlotRequestedEvent

Extends Event
This event is fired when an ad has been requested for a particular slot.
Properties
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Example

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

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

googletag.events.SlotResponseReceived

Extends Event
This event is fired when an ad response has been received for a particular slot.
Properties
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Example

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

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

googletag.events.SlotVisibilityChangedEvent

Extends Event
This event is fired whenever the on-screen percentage of an ad slot's area changes. The event is throttled and will not fire more often than once every 200ms.
Properties
inViewPercentage
The percentage of the ad's area that is visible.
serviceName
Name of the service that triggered the event.
slot
The slot that triggered the event.
Example

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

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

Properties

inViewPercentage

inViewPercentage: number
The percentage of the ad's area that is visible. Value is a number between 0 and 100.

googletag.secureSignals

This is the namespace that GPT uses for managing secure signals.
Interfaces
BidderSignalProvider
Returns a secure signal for a specific bidder.
PublisherSignalProvider
Returns a secure signal for a specific publisher.
SecureSignalProvidersArray
An interface for managing secure signals.
Type Aliases
SecureSignalProvider
Interface for returning a secure signal for a specific bidder or provider.

Type Aliases

SecureSignalProvider

Interface for returning a secure signal for a specific bidder or provider. One of id or networkCode must be provided, but not both.

googletag.secureSignals.BidderSignalProvider

Returns a secure signal for a specific bidder.

A bidder secure signal provider consists of 2 parts:

  1. A collector function, which returns a Promise that resolves to a secure signal.
  2. An id which identifies the bidder associated with the signal.
To return a secure signal for a publisher, use secureSignals.PublisherSignalProvider instead.
Properties
collectorFunction
A function which returns a Promise that resolves to a secure signal.
id
A unique identifier for the collector associated with this secure signal, as registered in Google Ad Manager.
Example

JavaScript

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

JavaScript (legacy)

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

Properties

collectorFunction

collectorFunction: (() => Promise<string>)
A function which returns a Promise that resolves to a secure signal.

id

id: string
A unique identifier for the collector associated with this secure signal, as registered in Google Ad Manager.

googletag.secureSignals.PublisherSignalProvider

Returns a secure signal for a specific publisher.

A publisher signal provider consists of 2 parts:

  1. A collector function, which returns a Promise that resolves to a secure signal.
  2. A networkCode which identifies the publisher associated with the signal.
To return a secure signal for a bidder, use secureSignals.BidderSignalProvider instead.
Properties
collectorFunction
A function which returns a Promise that resolves to a secure signal.
networkCode
The network code (as seen in the ad unit path) for the publisher associated with this secure signal.
Example

JavaScript

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

JavaScript (legacy)

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

Properties

collectorFunction

collectorFunction: (() => Promise<string>)
A function which returns a Promise that resolves to a secure signal.

networkCode

networkCode: string
The network code (as seen in the ad unit path) for the publisher associated with this secure signal.

googletag.secureSignals.SecureSignalProvidersArray

An interface for managing secure signals.
Methods
clearAllCache
Clears all signals for all collectors from cache.
push
Adds a new secureSignals.SecureSignalProvider to the signal provider array and begins the signal generation process.

Methods

clearAllCache

clearAllCache(): void
Clears all signals for all collectors from cache.

Calling this method may reduce the likelihood of signals being included in ad requests for the current and potentially later page views. Due to this, it should only be called when meaningful state changes occur, such as events that indicate a new user (log in, log out, sign up, etc.).

push

push(provider: SecureSignalProvider): void
Adds a new secureSignals.SecureSignalProvider to the signal provider array and begins the signal generation process.
Parameters
provider: SecureSignalProviderThe secureSignals.SecureSignalProvider object to be added to the array.