GPT Reference

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
number	The number of commands processed so far. This is compatible with Array.push's return value (the current length of the array).

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: boolean	true to automatically backfill unfilled slots, false to leave them unchanged.

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

• Display a limited ad

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.

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
boolean	Returns 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

• Custom labels to block ads

Returns
PubAdsService	The 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

• Key-value targeting

Parameters
Optional key: string	Targeting parameter key. The key is optional; all targeting parameters will be cleared if it is unspecified.

Returns
PubAdsService	The 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

• Collapse empty ad slots
• Minimize layout shift

Parameters
Optional collapseBeforeAdFetch: boolean	Whether 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
boolean	Returns 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

• Control ad loading and refresh
• Control SRA batching

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

• Display a test ad
• Control ad loading and refresh

Parameters
adUnitPath: string	The ad unit path of slot to be rendered.
size: GeneralSize	Width and height of the slot.
Optional div: string | Element	Either the ID of the div containing the slot or the div element itself.
Optional clickUrl: string	The 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

• Ads best practices: Prioritize "important" ad slots
• Lazy loading

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

• Ads best practices: Use Single Request Architecture correctly
• Control SRA batching

Returns
boolean	Returns 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

• AdSense Attributes

Parameters
key: string	Name of the attribute to look for.

Returns
null | string	Current 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: string	The 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
boolean	Returns 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

• Control ad loading and refresh
• Refresh ad slots

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

• AdSense Attributes

Parameters
key: string	The name of the attribute.
value: string	Attribute value.

Returns
PubAdsService	The 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

• Custom labels to block ads

Parameters
categoryExclusion: string	The ad category exclusion label to add.

Returns
PubAdsService	The 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: boolean	true 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

• Render creatives using SafeFrame

Parameters
forceSafeFrame: boolean	true 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
PubAdsService	The 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: string	Freeform address.

Returns
PubAdsService	The 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

• Configure privacy settings
• Display a limited ad

Parameters
privacySettings: PrivacySettingsConfig	Object containing privacy settings config.

Returns
PubAdsService	The 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

• About publisher provided identifiers

Parameters
ppid: string	An alphanumeric ID provided by the publisher. Must be between 32 and 150 characters.

Returns
PubAdsService	The 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

• Render creatives using SafeFrame

Parameters
config: SafeFrameConfig	The configuration object.

Returns
PubAdsService	The 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

• Key-value targeting

Parameters
key: string	Targeting parameter key.
value: string | string[]	Targeting parameter value or array of values.

Returns
PubAdsService	The 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

• VAST ad tag URL parameters

Parameters
videoContentId: string	The video content ID.
videoCmsId: string	The 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
PubAdsService	The service object on which the function was called.

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.

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

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

• Render creatives using SafeFrame

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:

• events.GameManualInterstitialSlotClosedEvent
• events.GameManualInterstitialSlotReadyEvent
• events.ImpressionViewableEvent
• events.RewardedSlotClosedEvent
• events.RewardedSlotGrantedEvent
• events.RewardedSlotReadyEvent
• events.SlotOnloadEvent
• events.SlotRenderEndedEvent
• events.SlotRequestedEvent
• events.SlotResponseReceived
• events.SlotVisibilityChangedEvent
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

• Ad event listeners

Parameters
eventType: K	A 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
Service	The 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: K	A 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.

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 < 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 < 640x480
  .build();

// Mapping 2
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [])
  .addSize([640, 480], [120, 60])
  .addSize([0, 0], [])
  .build();

// Mapping 2 will not show any ads for the following viewport sizes:
// [1024, 768] > size >= [980, 690] and
// [640, 480] > size >= [0, 0]

TypeScript

// Mapping 1
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [728, 90])
  .addSize([640, 480], "fluid")
  .addSize([0, 0], [88, 31]) // All viewports < 640x480
  .build();

// Mapping 2
googletag
  .sizeMapping()
  .addSize([1024, 768], [970, 250])
  .addSize([980, 690], [])
  .addSize([640, 480], [120, 60])
  .addSize([0, 0], [])
  .build();

// Mapping 2 will not show any ads for the following viewport sizes:
// [1024, 768] > size >= [980, 690] and
// [640, 480] > size >= [0, 0]

Parameters
viewportSize: SingleSizeArray	The size of the viewport for this mapping entry.
slotSize: GeneralSize	The sizes of the slot for this mapping entry.

Returns
SizeMappingBuilder	A 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 | SizeMappingArray	The result built by this builder. Can be null if invalid size mappings were supplied.

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

• Get Started with Google Publisher Tags
• Display a test ad

Parameters
service: Service	The service to be added.

Returns
Slot	The 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
Slot	The 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

• Key-value targeting

Parameters
Optional key: string	Targeting parameter key. The key is optional; all targeting parameters will be cleared if it is unspecified.

Returns
Slot	The 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

• Ad sizes: Responsive ads

Parameters
sizeMapping: SizeMappingArray	Array of size mappings. You can use SizeMappingBuilder to create it. Each size mapping is an array of two elements: SingleSizeArray and GeneralSize.

Returns
Slot	The 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

• AdSense Attributes

Parameters
key: string	Name of the attribute to look for.

Returns
null | string	Current 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
string	Ad 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 | ResponseInformation	The 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
string	Slot 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: string	The 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

• AdSense Attributes

Parameters
key: string	The name of the attribute.
value: string	Attribute value.

Returns
Slot	The 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

• Custom labels to block ads

Parameters
categoryExclusion: string	The ad category exclusion label to add.

Returns
Slot	The 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: string	The click URL to set.

Returns
Slot	The 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

• Collapse empty ad slots
• Minimize layout shift

Parameters
collapse: boolean	Whether to collapse the slot if no ad is returned.
Optional collapseBeforeAdFetch: boolean	Whether to collapse the slot even before an ad is fetched. Ignored if collapse is not true.

Returns
Slot	The slot object on which the method was called.

setConfig

setConfig(slotConfig: SlotSettingsConfig): void

Sets general configuration options for this slot.

Parameters
slotConfig: SlotSettingsConfig	The 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

• Render creatives using SafeFrame

Parameters
forceSafeFrame: boolean	true 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
Slot	The 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

• Render creatives using SafeFrame

Parameters
config: null | SafeFrameConfig	The configuration object.

Returns
Slot	The 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

• Key-value targeting

Parameters
key: string	Targeting parameter key.
value: string | string[]	Targeting parameter value or array of values.

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

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

• IAB Audience Taxonomy 1.1
• IAB Content Taxonomy 2.2

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

See also

• Protected Audience API Seller guide: run ad auctions

Properties

Properties

Properties

Properties

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

• About publisher provided signals (Beta)
• IAB Audience Taxonomy 1.1
• IAB Content Taxonomy 2.2

Properties

Properties

Properties

OutOfPageFormat

OutOfPageFormat

Out-of-page formats supported by GPT.

See also

• defineOutOfPageSlot

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

• PrivacySettingsConfig.trafficSource

Enumeration Members
ORGANIC	Direct URL entry, site search, or app download.
PURCHASED	Traffic redirected from properties other than owned (acquired or otherwise incentivized activity).

See also

• Ad event listeners

Properties

Properties

Example

JavaScript

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

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

JavaScript (legacy)

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

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

TypeScript

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

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

See also

• Ad event listeners
• Display a game manual interstitial ad

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,
);
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,
);
googletag.pubads().addEventListener("gameManualInterstitialSlotReady", function (event) {
  var slot = event.slot;
  console.log("Game manual interstital slot", slot.getSlotElementId(), "is ready to be displayed.");

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

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

TypeScript

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

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

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

See also

• Ad event listeners
• Display a game manual interstitial ad

Methods

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

• Ad event listeners

Example

JavaScript

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

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

JavaScript (legacy)

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

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

TypeScript

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

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

See also

• Ad event listeners
• Display a rewarded ad

Example

JavaScript

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

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

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

JavaScript (legacy)

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

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

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

TypeScript

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

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

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

See also

• Ad event listeners
• Display a rewarded ad

Properties