GPT Reference

This reference uses google-closure type annotations. Here is a brief explanation by example:

boolean: JavaScript boolean type.
googletag.Slot: Object of class googletag.Slot.
number|string: Union type. The value is either number or string.
?string: Indicates that a value is type string or null. string, number and boolean types are not nullable by default.
!googletag.Slot: Indicates that a value is type googletag.Slot and not null. All object types are nullable by default.
Array<string>: An array of strings.
!Array<!googletag.Slot>: An array of googletag.Slot objects. Each object is not null. Array itself is not null.
number=: Indicates that the argument described by this type is optional. A function call can omit an optional argument. An optional parameter cannot precede a non-optional parameter in the parameter list.

Find more detailed information in Google Closure docs.

Type Definitions

Types
`googletag.GeneralSize`	`(googletag.SingleSize\|googletag.MultiSize)`
`googletag.MultiSize`	`Array<!googletag.SingleSize>`
`googletag.NamedSize`	`string\|Array<string>`
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.
`googletag.SingleSize`	`googletag.SingleSizeArray\|googletag.NamedSize`
`googletag.SingleSizeArray`	`Array<number>`
Array of two numbers representing [width, height].
`googletag.SizeMapping`	`Array<!googletag.GeneralSize>`
`googletag.SizeMappingArray`	`Array<!googletag.SizeMapping>`

Enum Types

Enums
`googletag.enums.OutOfPageFormat`	Out of page formats supported by GPT.

`googletag.enums.OutOfPageFormat`

Values
`googletag.enums.OutOfPageFormat.INTERSTITIAL`	Web interstitial creative format.

googletag

This is the global namespace that the Google Publisher Tag uses for its API.

Field Summary
`googletag.apiReady`	Flag indicating that GPT API is loaded and ready to be called.
`googletag.cmd`	Reference to the global command queue for asynchronous execution of GPT-related calls.
`googletag.enums`	This is the namespace that GPT uses for enum types.
`googletag.events`	This is the namespace that GPT uses for Events.
`googletag.pubadsReady`	Flag indicating that Pubads service is enabled, loaded and fully operational.

Method Summary
`googletag.companionAds()`	Returns a reference to the companion ads service.
`googletag.content()`	Returns a reference to the content service.
`googletag.defineOutOfPageSlot(adUnitPath, opt_div)`	Constructs an out-of-page (interstitial) ad slot with the given ad unit path.
`googletag.defineSlot(adUnitPath, size, opt_div)`	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.
`googletag.destroySlots(opt_slots)`	Destroys the given slots, removing all related objects and references of those slots from GPT.
`googletag.disablePublisherConsole()`	Disables the Google Publisher Console.
`googletag.display(divOrSlot)`	Instructs slot services to render the slot.
`googletag.enableServices()`	Enables all GPT services that have been defined for ad slots on the page.
`googletag.getVersion()`	Returns the current version of GPT.
`googletag.openConsole(opt_div)`	Opens the Google Publisher Console.
`googletag.pubads()`	Returns a reference to the pubads service.
`googletag.setAdIframeTitle(title)`	Sets that title for all ad container iframes created by pubads service, from this point onwards.
`googletag.sizeMapping()`	Creates a new SizeMappingBuilder.

`boolean|undefined googletag.apiReady`

Flag indicating that 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.

Example:

 <script>
 if (window.googletag && googletag.apiReady) {
   // GPT API can be called safely.
 }
 </script>

`!Array<function()>|!googletag.CommandArray googletag.cmd`

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 googletag.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:

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

`googletag.enums`

This is the namespace that GPT uses for enum types.

`googletag.events`

This is the namespace that GPT uses for Events. Your code can react to these events using Service.addEventListener.

`boolean|undefined googletag.pubadsReady`

Flag indicating that Pubads service is enabled, loaded and fully operational. This property will be simply undefined until

 googletag.enableServices()

is called and Pubads service is loaded and initialized.

`!googletag.CompanionAdsService googletag.companionAds()`

Returns a reference to the companion ads service.

Returns
`!googletag.CompanionAdsService`	Instance of the companion ads service.

`!googletag.ContentService googletag.content()`

Returns a reference to the content service.

Returns
`!googletag.ContentService`	Instance of the content service.

`googletag.Slot googletag.defineOutOfPageSlot(adUnitPath, opt_div)`

Constructs an out-of-page (interstitial) ad slot with the given ad unit path.

For custom out-of-page ads, opt_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, opt_div is a supported OutOfPageFormat. See the article on web interstitials for more details.

Parameters
`string adUnitPath`	Full ad unit path with the network code and ad unit code.
`string\|googletag.enums.OutOfPageFormat= opt_div`	ID of the div that will contain this ad unit or OutOfPageFormat.

Returns
`googletag.Slot`	The newly created slot.

Example:

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

`googletag.Slot googletag.defineSlot(adUnitPath, size, opt_div)`

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.

Parameters
`string adUnitPath`	Full ad unit path with the network code and unit code.
`googletag.GeneralSize size`	Width 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.
`string= opt_div`	ID of the div that will contain this ad unit.

Returns
`googletag.Slot`	The newly created slot.

Example:

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

`boolean googletag.destroySlots(opt_slots)`

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 behaviour. 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.

Parameters
`Array<!googletag.Slot>= opt_slots`	The array of slots to destroy. Array is optional; all slots will be destroyed if it is unspecified.

Returns
`boolean`	true if slots have been destroyed, false otherwise.

Example:

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

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

`googletag.disablePublisherConsole()`

Disables the Google Publisher Console.
See the article on Publisher Console for more details.

`googletag.display(divOrSlot)`

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 moment display is called will be fetched in a single instance of googletag.display(). To force an ad slot not to display, the entire div must be removed.

Parameters
`string\|!Element\|!googletag.Slot divOrSlot`	Either 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 `googletag.defineSlot()`.

Example:

<div id="div-1" style="width: 728px; height: 90px">
  <script type="text/javascript">
    googletag.cmd.push(function() {
      googletag.display('div-1');
    });
  </script>
</div>

`googletag.enableServices()`

Enables all GPT services that have been defined for ad slots on the page.

`string googletag.getVersion()`

Returns the current version of GPT.

Returns
`string`	Version string.

`googletag.openConsole(opt_div)`

Opens the Google Publisher Console.

Parameters
`string= opt_div`	ID of the div element containing the ad slot.

Example:

// Calling with div id
googletag.openConsole('div-1');

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

`!googletag.PubAdsService googletag.pubads()`

Returns a reference to the pubads service.

Returns
`!googletag.PubAdsService`	Instance of the pubads service.

`googletag.setAdIframeTitle(title)`

Sets that title for all ad container iframes created by pubads service, from this point onwards.

Parameters
`string title`	The title to set.

Example:

googletag.setAdIframeTitle('title');

`!googletag.SizeMappingBuilder googletag.sizeMapping()`

Creates a new SizeMappingBuilder.
See the article on responsive design for more details.

Returns
`!googletag.SizeMappingBuilder`	A 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.

Method Summary
`push(f)`	Executes the sequence of functions specified in the arguments in order.

`number push(f)`

Executes the sequence of functions specified in the arguments in order.

Parameters
`function() f`	A JavaScript function to be executed.

Returns
`number`	The number of commands processed so far. This is compatible with `Array.push`'s return value (the current length of the array).

Example:

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

googletag.CompanionAdsService

Extends googletag.Service.

Companion Ads service. This service is used by video ads to show companion ads. See the article on companion ads for video for more details.

Method Summary
`setRefreshUnfilledSlots(value)`	Sets whether companion slots that have not been filled will be automatically backfilled.

`setRefreshUnfilledSlots(value)`

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 pubads service will be backfilled. Due to policy restrictions, this method is not designed to fill empty companion slots when an Ad Exchange video is served.

Parameters
`boolean value`	true to automatically backfill unfilled slots, false to leave them unchanged.

Example:

googletag.companionAds().setRefreshUnfilledSlots(true);

googletag.ContentService

Extends googletag.Service.

The content service. This service is used to set the content of a slot manually.

Method Summary
`setContent(slot, content)`	Fills a slot with the given content.

`setContent(slot, content)`

Fills a slot with the given content. If services are not yet enabled, stores the content and fills it in when services are enabled.

Parameters
`!googletag.Slot slot`	The slot to be filled.
`string content`	The HTML content for the slot.

Example:

var slot = googletag.defineSlot('/1234567/sports', [728, 90], 'div-1').
    addService(googletag.content());
googletag.enableServices();

var content = '<a href="www.mydestinationsite.com"><img src="www.mysite.com/img.png"></img></a>';
googletag.content().setContent(slot, content);

googletag.PrivacySettingsConfig

Configuration object for privacy settings.

Field Summary
`childDirectedTreatment`	childDirectedTreatment configuration indicates whether the page should be treated as child-directed.
`limitedAds`	limitedAds configuration enables serving to run in limited ads mode to aid in publisher regulatory compliance needs.
`restrictDataProcessing`	restrictDataProcessing configuration enables serving to run in restricted processing mode to aid in publisher regulatory compliance needs.
`underAgeOfConsent`	underAgeOfConsent configuration indicates whether to mark ad requests as coming from users under the age of consent.

`?boolean childDirectedTreatment`

childDirectedTreatment configuration indicates whether the page should be treated as child-directed. Set to null to clear the configuration.

`boolean limitedAds`

limitedAds configuration enables serving to run in limited ads mode to aid in publisher regulatory compliance needs. When enabled, the GPT library itself may optionally be requested from a cookie-less, limited ads URL.

`boolean restrictDataProcessing`

restrictDataProcessing configuration enables serving to run in restricted processing mode to aid in publisher regulatory compliance needs.

`?boolean underAgeOfConsent`

underAgeOfConsent configuration 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 googletag.Service.

Publisher Ads service. This service is used to fetch and show ads from your Google Ad Manager account.

Method Summary
`clear(opt_slots)`	Removes the ads from the given slots and replaces them with blank content.
`clearCategoryExclusions()`	Clears all page-level ad category exclusion labels.
`clearTargeting(opt_key)`	Clears custom targeting parameters for a specific key or for all keys.
`collapseEmptyDivs(opt_collapseBeforeAdFetch)`	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 `googletag.pubads().refresh()` call.
`display(adUnitPath, size, opt_div, opt_clickUrl)`	Constructs and displays an ad slot with the given ad unit path and size.
`enableLazyLoad(opt_config)`	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(key)`	Returns the value for the AdSense attribute associated with the given key.
`getAttributeKeys()`	Returns the attribute keys that have been set on this service.
`getTargeting(key)`	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 `disableInitialLoad` call.
`refresh(opt_slots, opt_options)`	Fetches and displays new ads for specific or all slots on the page.
`set(key, value)`	Sets values for AdSense attributes that apply to all ad slots under the publisher ads service.
`setCategoryExclusion(categoryExclusion)`	Sets a page-level ad category exclusion for the given label name.
`setCentering(centerAds)`	Enables and disables horizontal centering of ads.
`setCookieOptions(options)`	Sets options for ignoring Google Ad Manager cookies on the current page.
`setForceSafeFrame(forceSafeFrame)`	Configures whether all ads on the page should be forced to be rendered using a SafeFrame container.
`setLocation(address)`	Passes location information from websites so you can geo-target line items to specific locations.
`setPrivacySettings(privacySettings)`	Allows configuration of all privacy settings from a single API using a config object.
`setPublisherProvidedId(ppid)`	Sets the value for the publisher-provided ID.
`setRequestNonPersonalizedAds(nonPersonalizedAds)`	Configures whether the page should request personalized or non-personalized ads.
`setSafeFrameConfig(config)`	Sets the page-level preferences for SafeFrame configuration.
`setTargeting(key, value)`	Sets custom targeting parameters for a given key that apply to all pubads service ad slots.
`setVideoContent(videoContentId, videoCmsId)`	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.

`boolean clear(opt_slots)`

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.

Parameters
`Array<!googletag.Slot>= opt_slots`	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.

Example:

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

`!googletag.PubAdsService clearCategoryExclusions()`

Clears all page-level ad category exclusion labels. This is useful if you want to refresh the slot.

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

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

`!googletag.PubAdsService clearTargeting(opt_key)`

Clears custom targeting parameters for a specific key or for all keys.

Parameters
`string= opt_key`	Targeting parameter key. The key is optional; all targeting parameters will be cleared if it is unspecified.

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

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.

`boolean collapseEmptyDivs(opt_collapseBeforeAdFetch)`

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 the article on collapsing empty divs for more details.

Parameters
`boolean= opt_collapseBeforeAdFetch`	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()`

Disables requests for ads on page load, but allows ads to be requested with a googletag.pubads().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.

`display(adUnitPath, size, opt_div, opt_clickUrl)`

Constructs and displays an ad slot with the given ad unit path and size. This method does not work with single request mode.

Parameters
`string adUnitPath`	The ad unit path of slot to be rendered.
`!googletag.GeneralSize size`	Width and height of the slot.
`(string\|!Element)= opt_div`	Either the ID of the div containing the slot or the div element itself.
`string= opt_clickUrl`	The click URL to use on this slot.

Example:

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

`enableLazyLoad(opt_config)`

Enables lazy loading in GPT as defined by the config object. For more detailed examples, see the Lazy Loading example here.
Notes:

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

Parameters

Parameters
`{ fetchMarginPercent: number, renderMarginPercent: number, mobileScaling: number } opt_config`	Configuration object allows customization of lazy loading 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 is the minimum distance from the current viewport a slot must be before we fetch the ad as a percentage of viewport size. 0 means "when the slot enters the viewport", 100 means "when the ad is 1 viewport away", and so on. renderMarginPercent is 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 is a multiplier applied to margins on mobile devices. This allows varying margins on mobile vs. desktop. For example, a mobileScaling of 2.0 will multiply all margins by 2 on mobile devices, increasing the minimum distance a slot can be before fetching and rendering.


              
                {
    fetchMarginPercent: number,
    renderMarginPercent: number,
    mobileScaling: number
}
              
              opt_config

Configuration object allows customization of lazy loading 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 is the minimum distance from the current viewport a slot must be before we fetch the ad as a percentage of viewport size. 0 means "when the slot enters the viewport", 100 means "when the ad is 1 viewport away", and so on.

renderMarginPercent is 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 is a multiplier applied to margins on mobile devices. This allows varying margins on mobile vs. desktop. For example, a mobileScaling of 2.0 will multiply all margins by 2 on mobile devices, increasing the minimum distance a slot can be before fetching and rendering.

Example:

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

`boolean enableSingleRequest()`

Enables single request mode for fetching multiple ads at the same time. This requires all pubads slots to be defined and added to the pubads service prior to enabling the service. Single request mode must be set before the service is enabled.

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

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 setVideoContent in order to be able to use content exclusion for display ads.

`?string get(key)`

Returns the value for the AdSense attribute associated with the given key.

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

Returns
`?string`	Current value for the attribute key, or null if the key is not present.

Example:

googletag.pubads().set('adsense_background_color', '#FFFFFF');
var color = googletag.pubads().get('adsense_background_color');
// color == '#FFFFFF'.

`!Array<string> getAttributeKeys()`

Returns the attribute keys that have been set on this service.

Returns
`!Array<string>`	Array of attribute keys set on this service. Ordering is undefined.

Example:

googletag.pubads().set('adsense_background_color', '#FFFFFF');
googletag.pubads().set('adsense_border_color', '#AABBCC');
var keys = googletag.pubads().getAttributeKeys();
// Keys are ['adsense_background_color', 'adsense_border_color'].

`!Array<string> getTargeting(key)`

Returns a specific custom service-level targeting parameter that has been set.

Parameters
`string key`	The targeting key to look for.

Returns
`!Array<string>`	The values associated with this key, or an empty array if there is no such key.

Example:

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

var param = googletag.pubads().getTargeting('interests');
// param is ['sports']

var param = googletag.pubads().getTargeting('age');
// param is [] (empty array)

`!Array<string> getTargetingKeys()`

Returns the list of all custom service-level targeting keys that have been set.

Returns
`!Array<string>`	Array of targeting keys. Ordering is undefined.

Example:

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

var keys = googletag.pubads().getTargetingKeys();
// keys are ['interests', 'colors'].

`boolean isInitialLoadDisabled()`

Returns whether or not initial requests for ads was successfully disabled by a previous disableInitialLoad call.

Returns
`boolean`

`refresh(opt_slots, opt_options)`

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

Parameters

Parameters
`Array<!googletag.Slot>= opt_slots`	The slots to refresh. Array is optional; all slots will be refreshed if it is unspecified.
`{changeCorrelator: boolean}= opt_options`	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 that 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.


              
                Array<!googletag.Slot>=
              
              opt_slots

The slots to refresh. Array is optional; all slots will be refreshed if it is unspecified.


              
                {changeCorrelator: boolean}=
              
              opt_options

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 that 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.

Example:

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

`!googletag.PubAdsService set(key, value)`

Sets values for AdSense attributes that apply to all ad slots under the publisher ads service. See AdSense Attributes for a list of available keys and values. Calling this more than once for the same key will override previously set values for that key. All values must be set before the first display call.

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

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

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

`!googletag.PubAdsService setCategoryExclusion(categoryExclusion)`

Sets a page-level ad category exclusion for the given label name.
See the article on ad exclusion for more details.

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

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

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

`setCentering(centerAds)`

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.

Parameters
`boolean centerAds`	true to center ads, false to left-align them.

Example:

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

`!googletag.PubAdsService setCookieOptions(options)`

Sets options for ignoring Google Ad Manager cookies on the current page.

Parameters

The cookie options to set. Possible values are:

0: Enables Google Ad Manager cookies on ad requests on the page. This option is set by default.
1: Ignores Google Ad Manager cookies on subsequent ad requests and prevents cookies from being created on the page. Note that cookies will not be ignored on certain pingbacks and that this option will disable features that rely on cookies, such as dynamic allocation.

See the article about cookie options for more details.

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

// Ignores Google Ad Manager cookies.
googletag.pubads().setCookieOptions(1);

`!googletag.PubAdsService setForceSafeFrame(forceSafeFrame)`

Configures whether all ads on the page should be forced to be rendered using a SafeFrame container. For more details, please see the article on rendering creatives using safeframe.
Please keep the following things in mind while using this API:

Note that 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 (see related article).
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.

Parameters
`boolean forceSafeFrame`	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
`!googletag.PubAdsService`	The service object on which the function was called.

Example:

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

`!googletag.PubAdsService setLocation(address)`

Passes location information from websites so you can geo-target line items to specific locations.

Parameters
`string address`	Freeform address.

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

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

`!googletag.PubAdsService setPrivacySettings(privacySettings)`

Allows configuration of all privacy settings from a single API using a config object.

Parameters
`!googletag.PrivacySettingsConfig privacySettings`	Object containing privacy settings config.

Returns
`!googletag.PubAdsService`	The service object on which the function was called.

Example:

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

`!googletag.PubAdsService setPublisherProvidedId(ppid)`

Sets the value for the publisher-provided ID. See the article on PPID for more details.

Parameters
`string ppid`	An alphanumeric ID provided by the publisher with a recommended maximum of 150 characters.

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

googletag.pubads().setPublisherProvidedId('AB123456789');

`!googletag.PubAdsService setRequestNonPersonalizedAds(nonPersonalizedAds)`

Configures whether the page should request personalized or non-personalized ads. Personalized ads served by default.

Parameters
`number nonPersonalizedAds`	0 for personalized ads, 1 for non-personalized ads.

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

// Mark ad requests to request non-personalized ads.
googletag.pubads().setRequestNonPersonalizedAds(1);

`!googletag.PubAdsService setSafeFrameConfig(config)`

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. For more details, please refer to the help center article.

Parameters
`googletag.SafeFrameConfig config`	The configuration object.

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

googletag.pubads().setForceSafeFrame(true);

var pageConfig = {
  allowOverlayExpansion: true,
  allowPushExpansion: true,
  sandbox: true,
  useUniqueDomain: 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();

`!googletag.PubAdsService setTargeting(key, value)`

Sets custom targeting parameters for a given key that apply to all pubads 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.

Parameters
`string key`	Targeting parameter key.
`string\|!Array<string> value`	Targeting parameter value or array of values.

Returns
`!googletag.PubAdsService`	The service object on which the method was called.

Example:

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

`setVideoContent(videoContentId, videoCmsId)`

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 the article on video content for more details.

Parameters
`string videoContentId`	The video content ID.
`string videoCmsId`	The video CMS ID.

`!googletag.PubAdsService updateCorrelator()`

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.

Returns
`!googletag.PubAdsService`	The service object on which the function was called.

Example:

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

googletag.ResponseInformation

Public interface for ResponseInformation.

Field Summary
`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.

`advertiserId`

The ID of the advertiser.

`campaignId`

The ID of the campaign.

`?number creativeId`

The ID of the creative.

`?number creativeTemplateId`

The template id of the ad.

`?number lineItemId`

The ID of the line item.

googletag.SafeFrameConfig

Configuration object for SafeFrame containers.

Field Summary
`allowOverlayExpansion`	true to allow expansion by overlay and false otherwise.
`allowPushExpansion`	true to allow expansion by push and false otherwise.
`sandbox`	true if SafeFrame should use the HTML5 sandbox attribute to prevent top level navigation.
`useUniqueDomain`	Whether to use a unique subdomain for SafeFrame for Reservation creatives.

`boolean allowOverlayExpansion`

true to allow expansion by overlay and false otherwise.

`boolean allowPushExpansion`

true to allow expansion by push and false otherwise.

`boolean sandbox`

true if SafeFrame should use the HTML5 sandbox attribute to prevent top level navigation. The only valid value is true (cannot be forced to false). Note that the sandbox attribute disables plugins (e.g. Flash) and creatives that attempt to navigate the top level page instead of opening in a new window.

`?boolean useUniqueDomain`

Whether to use a unique subdomain for SafeFrame for Reservation creatives. Pass in null to clear the stored value.

googletag.Service

Base service class that contains methods common for all services.

Method Summary
`addEventListener(eventType, listener)`	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.

`!googletag.Service addEventListener(eventType, listener)`

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:

googletag.events.ImpressionViewableEvent
googletag.events.SlotOnloadEvent
googletag.events.SlotRenderEndedEvent
googletag.events.SlotRequestedEvent
googletag.events.SlotResponseReceived
googletag.events.SlotVisibilityChangedEvent

An object of the appropriate event type is passed to the listener when it is called.

Parameters
`string eventType`	A string representing the type of event generated by GPT. Event types are case sensitive.
`function(?Object) listener`	Function that takes a single event object argument.

Returns
`!googletag.Service`	The service object on which the method was called.

Example:

// 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.pubads().addEventListener('slotOnload', function(event) {
  if (event.slot === targetSlot) {
    // Slot specific logic.
  }
});

`!Array<!googletag.Slot> getSlots()`

Get the list of slots associated with this service.

Returns
`!Array<!googletag.Slot>`	Slots in the order in which they were added to the service.

googletag.SizeMappingBuilder

Builder for size mapping specification objects. This builder is provided to help easily construct size specifications.
See the article on responsive design for more details.

Method Summary
`addSize(viewportSize, slotSize)`	Adds a mapping from a single-size array representing the viewport to either a single-size array or a multi-size array representing the slot.
`build()`	Builds a size map specification from the mappings added to this builder.

`!googletag.SizeMappingBuilder addSize(viewportSize, slotSize)`

Adds a mapping from a single-size array representing the viewport to either a single-size array or a multi-size array representing the slot.

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

Returns
`!googletag.SizeMappingBuilder`	A reference to this builder.

Example:

var mapping1 = googletag.sizeMapping().
    addSize([1024, 768], [970, 250]).
    addSize([980, 690], [728, 90]).
    addSize([640, 480], 'fluid').
    addSize([0, 0], [88, 31]). // Fits browsers of any size smaller than 640x480.
    build();
var mapping2 = googletag.sizeMapping().
    addSize([1024, 768], [970, 250]).
    addSize([980, 690], []).
    addSize([640, 480], [120, 60]).
    addSize([0, 0], []).
    build();

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

`googletag.SizeMappingArray build()`

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 googletag.Slot.defineSizeMapping(). The behavior of the builder after calling build() is undefined.

Returns
`googletag.SizeMappingArray`	The result built by this builder. Can be null if invalid size mappings were supplied.

googletag.Slot

Slot is an object representing single ad slot on a page.

Method Summary
`addService(service)`	Adds a service to this slot.
`clearCategoryExclusions()`	Clears all slot-level ad category exclusion labels for this slot.
`clearTargeting(opt_key)`	Clears specific or all custom slot-level targeting parameters for this slot.
`defineSizeMapping(sizeMapping)`	Sets an array of mappings from a minimum viewport size to slot size for this slot.
`get(key)`	Returns the value for the AdSense attribute associated with the given key.
`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 element provided when the slot was defined.
`getTargeting(key)`	Returns a specific custom targeting parameter set on this slot.
`getTargetingKeys()`	Returns the list of all custom targeting keys set on this slot.
`set(key, value)`	Sets a value for an AdSense attribute on a particular ad slot.
`setCategoryExclusion(categoryExclusion)`	Sets a slot-level ad category exclusion label on this slot.
`setClickUrl(value)`	Sets the click URL to which users will be redirected after clicking on the ad.
`setCollapseEmptyDiv(collapse, opt_collapseBeforeAdFetch)`	Sets whether the slot div should be hidden when there is no ad in the slot.
`setForceSafeFrame(forceSafeFrame)`	Configures whether ads in this slot should be forced to be rendered using a SafeFrame container.
`setSafeFrameConfig(config)`	Sets the slot-level preferences for SafeFrame configuration.
`setTargeting(key, value)`	Sets a custom targeting parameter for this slot.
`updateTargetingFromMap(map)`	Sets custom targeting parameters for this slot, from a key:value map in a JSON object.

`!googletag.Slot addService(service)`

Adds a service to this slot.

Parameters
`!googletag.Service service`	The service to be added.

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

Example:

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

`!googletag.Slot clearCategoryExclusions()`

Clears all slot-level ad category exclusion labels for this slot.

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

Example:

// Set category exclusion to exclude ads with 'AirlineAd' labels.
var slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div-1').
    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.

`!googletag.Slot clearTargeting(opt_key)`

Clears specific or all custom slot-level targeting parameters for this slot.

Parameters
`string= opt_key`	Targeting parameter key. The key is optional; all targeting parameters will be cleared if it is unspecified.

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

Example:

var slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div-1').
    setTargeting('allow_expandable', 'true').
    setTargeting('interests', ['sports','music','movies']).
    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.

`!googletag.Slot defineSizeMapping(sizeMapping)`

Sets an array of mappings from a minimum viewport size to slot size for this slot.
See the article on responsive design for more details.

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

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

Example:

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

`?string get(key)`

Returns the value for the AdSense attribute associated with the given key. Note that if you intend to see service-level attributes inherited by this slot, you have to use the googletag.PubAdsService.get(key) API.

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

Returns
`?string`	Current value for the attribute key, or null if the key is not present.

Example:

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

var color = googletag.pubads().get('adsense_background_color');
// color == '#FFFFFF'.

`string getAdUnitPath()`

Returns the full path of the ad unit, with the network code and ad unit path.

Returns
`string`	Ad unit path.

Example:

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

var path = slot.getAdUnitPath();
// path is '/1234567/sports'

`!Array<string> getAttributeKeys()`

Returns the list of attribute keys set on this slot. If you intend to see the keys of service-level attributes inherited by this slot, you have to use the googletag.PubAdsService.getAttributeKeys() API.

Returns
`!Array<string>`	Array of attribute keys. Ordering is undefined.

Example:

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

var keys = googletag.pubads().getAttributeKeys();
// Keys are ['adsense_background_color', 'adsense_border_color'].

`!Array<string> getCategoryExclusions()`

Returns the ad category exclusion labels for this slot.

Returns
`!Array<string>`	The ad category exclusion labels for this slot.

Example:

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

var exclusions = slot.getCategoryExclusions();
// exclusions are ['AirlineAd', 'TrainAd']

`?googletag.ResponseInformation getResponseInformation()`

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
`?googletag.ResponseInformation`

`string getSlotElementId()`

Returns the id of the slot element provided when the slot was defined.

Returns
`string`	Slot element id.

Example:

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

var slotElementId = slot.getSlotElementId();
// slotElementId is 'div-1'

`!Array<string> getTargeting(key)`

Returns a specific custom targeting parameter set on this slot. Service-level targeting parameters are not included.

Parameters
`string key`	The targeting key to look for.

Returns
`!Array<string>`	The values associated with this key, or an empty array if there is no such key.

Example:

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

var param = slot.getTargeting('allow_expandable');
// param is ['true']

var param = slot.getTargeting('age');
// param is [] (empty array)

`!Array<string> getTargetingKeys()`

Returns the list of all custom targeting keys set on this slot. Service-level targeting keys are not included.

Returns
`!Array<string>`	Array of targeting keys. Ordering is undefined.

Example:

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

var keys = slot.getTargetingKeys();
// keys are ['interests', 'allow_expandable'].

`!googletag.Slot set(key, value)`

Sets a value for an AdSense attribute on a particular ad slot. This will override any values set at the service level for this key. See the AdSense Attributes for a list of available keys and values. Calling this method more than once for the same key will override previously set values for that key. All values must be set before any display call.

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

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

Example:

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

`!googletag.Slot setCategoryExclusion(categoryExclusion)`

Sets a slot-level ad category exclusion label on this slot.
See the article on ad exclusion for more details.

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

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

Example:

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

`!googletag.Slot setClickUrl(value)`

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.

Parameters
`string value`	The click URL to set.

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

Example:

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

`!googletag.Slot setCollapseEmptyDiv(collapse, opt_collapseBeforeAdFetch)`

Sets whether the slot div should be hidden when there is no ad in the slot. This overrides the service-level settings.

Parameters
`boolean collapse`	Whether to collapse the slot if no ad is returned.
`boolean= opt_collapseBeforeAdFetch`	Whether to collapse the slot even before an ad is fetched. Ignored if collapse is not true.

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

Example:

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.

`!googletag.Slot setForceSafeFrame(forceSafeFrame)`

Configures whether ads in this slot should be forced to be rendered using a SafeFrame container. For more details, please see the article on rendering creatives using safeframe.
Please keep the following things in mind while using this API:

Note that this setting will only take effect for subsequent ad requests made for the given slot.
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 (see related article).
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 your page.

Parameters
`boolean forceSafeFrame`	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 page-level, won't change anything.

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

Example:

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

`!googletag.Slot setSafeFrameConfig(config)`

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. For more details, please refer to the help center article.

Parameters
`googletag.SafeFrameConfig config`	The configuration object.

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

Example:

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

googletag.defineSlot('/1234567/news', [160, 600], 'div-2').
  addService(googletag.pubads());

googletag.display();

`!googletag.Slot setTargeting(key, value)`

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 on service level. These keys are defined in your Google Ad Manager account.

Parameters
`string key`	Targeting parameter key.
`string\|!Array<string> value`	Targeting parameter value or array of values.

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

Example:

var slot = googletag.defineSlot('/1234567/sports', [160, 600], 'div-1').
    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','movies']);

`!googletag.Slot updateTargetingFromMap(map)`

Sets custom targeting parameters for this slot, from a key:value map in a JSON object. A badly formatted input will be rejected. This is the same as calling slot.setTargeting(key,value) for all the key values of the object. 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 on service level. These keys are defined in your Google Ad Manager account.

Parameters
`!Object<string,string\|!Array<string>> map`	Targeting parameter key:value map.

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

Example:

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

googletag.events.Event

Base Interface for all GPT events. All GPT events below will have the following fields.

Field Summary
`serviceName`	Name of the service that triggered the event.
`slot`	The slot that triggered the event.

`string serviceName`

Name of the service that triggered the event.

`!googletag.Slot slot`

The slot that triggered the event.

googletag.events.ImpressionViewableEvent

Extends googletag.events.Event.

This event is fired when an impression becomes viewable, according to the Active View criteria.

Example:

// This listener will be called when an impression becomes viewable.
var targetSlot = ...;
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.
  }
});

googletag.events.SlotOnloadEvent

Extends googletag.events.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.

Example:

// This listener will be called when a creative iframe load event fires.
var targetSlot = ...;
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.
  }
});

googletag.events.SlotRenderEndedEvent

Extends googletag.events.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 SlotOnloadEvent instead.

Field Summary
`advertiserId`	Advertiser ID of the rendered ad.
`campaignId`	Campaign ID of the rendered ad.
`creativeId`	Creative ID of the rendered reservation ad.
`isEmpty`	true if no ad was returned for the slot, false otherwise.
`lineItemId`	Line item ID of the rendered reservation ad.
`size`	Indicates the pixel size of the rendered creative.
`sourceAgnosticCreativeId`	Creative ID of the rendered reservation or backfill ad.
`sourceAgnosticLineItemId`	Line item ID of the rendered reservation or backfill ad.

Example:

// This listener will be called when a slot has finished rendering.
var targetSlot = ...;
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('Creative ID: ', event.creativeId);
  console.log('Is empty?:', event.isEmpty);
  console.log('Line Item ID:', event.lineItemId);
  console.log('Size:', event.size);
  console.log(
      'Source Agnostic Creative ID:', event.sourceAgnosticCreativeId);
  console.log(
      'Source Agnostic Line Item ID:', event.sourceAgnosticLineItemId);
  console.groupEnd();

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

`?number advertiserId`

Advertiser ID of the rendered ad. Value is null for empty slots, backfill ads or creatives rendered by services other than pubads service.

`?number campaignId`

Campaign ID of the rendered ad. Value is null for empty slots, backfill ads or creatives rendered by services other than pubads service.

`?number creativeId`

Creative ID of the rendered reservation ad. Value is null for empty slots, backfill ads or creatives rendered by services other than pubads service.

`boolean isEmpty`

true if no ad was returned for the slot, false otherwise.

`?number lineItemId`

Line item ID of the rendered reservation ad. Value is null for empty slots, backfill ads or creatives rendered by services other than pubads service.

`Array<number>|string size`

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

`?number sourceAgnosticCreativeId`

Creative ID of the rendered reservation or backfill ad. Value is null if the ad is not a reservation or line item backfill or a creative rendered by services other than pubads service.

`?number sourceAgnosticLineItemId`

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 a creative rendered by services other than pubads service.

googletag.events.SlotRequestedEvent

Extends googletag.events.Event.

This event is fired when an ad has been requested for a particular slot.

Example:

// This listener will be 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.pubads().addEventListener('slotRequested', function(event) {
  var slot = event.slot;
  console.log('Slot', slot.getSlotElementId(), 'has been requested.');

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

googletag.events.SlotResponseReceived

Extends googletag.events.Event.

This event is fired when an ad response has been received for a particular slot.

Example:

// This listener will be called when an ad response has been received for
   // a slot.
var targetSlot = ...;
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.
      }
  }
);

googletag.events.SlotVisibilityChangedEvent

Extends googletag.events.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.

Field Summary
`inViewPercentage`	The percentage (0-100) of the ad's area that is visible.

Example:

// This listener will be called whenever the on-screen percentage of an ad
// slot's area changes.
var targetSlot = ...;
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:', event.inViewPercentage + '%');
      console.groupEnd();

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

`number inViewPercentage`

The percentage (0-100) of the ad's area that is visible.