Homepage Handleidingen Referentie

GPT Reference

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>

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

Parameters
string adUnitPath
Full path of the ad unit with the network code and ad unit code.
string= opt_div
ID of the div that will contain this ad unit.

Returns
googletag.Slot
The newly created slot.

Example:
googletag.defineOutOfPageSlot('/1234567/sports', 'div-1');

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 path of the ad unit 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
enableSyncLoading()
Enables the service implementation to be loaded synchronously.
setRefreshUnfilledSlots(value)
Sets whether companion slots that have not been filled will be automatically backfilled.

enableSyncLoading()

Enables the service implementation to be loaded synchronously. This needs to be called before googletag.enableServices().
Note: this call can be only used if gpt.js is also loaded synchronously, for example, by using a script element. If called when GPT is loaded asynchronously, the outcome of the loading is undefined.

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

Specialized slot similar to googletag.Slot, but only including those properties that are relevant to passback slots. See the article on passbacks for more details.

Method Summary
display()
Initiates rendering of this slot.
get(key)
Returns the value for the AdSense attribute associated with the given key.
set(key, value)
Sets the value for an AdSense attribute on the passback slot.
setClickUrl(url)
Sets a click URL as a prefix to the clickthrough URL from the DFP ad server (the landing page associated with the creative).
setForceSafeFrame(forceSafeFrame)
Configures whether ads in this slot should be forced to be rendered using a SafeFrame container.
setTagForChildDirectedTreatment(value)
Configures whether the passback slot should be tagged for child-directed treatment.
setTagForUnderAgeOfConsent(value)
Configures whether to mark the passback slot as coming from a user under the age of consent.
setTargeting(key, value)
Sets a custom targeting parameter for this slot.
updateTargetingFromMap(map)
Sets custom targeting parameters for this passback slot, from a key:value map in a JSON object.

display()

Initiates rendering of this slot.
Example:
googletag.pubads().definePassback('/1234567/sports', [468, 60]).display();

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

!googletag.PassbackSlot set(key, value)

Sets the value for an AdSense attribute on the passback slot. 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.

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

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

!googletag.PassbackSlot setClickUrl(url)

Sets a click URL as a prefix to the clickthrough URL from the DFP ad server (the landing page associated with the creative). The example below shows a DFP click macro being used, and this passback tag could be served as a creative by DFP. This configuration would record a click before redirecting the user to the landing page. Users will be redirected after clicking on the ad to a combination of these values. Subsequent calls overwrite the value.

Parameters
string url
The click URL to set.

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

Example:
googletag.pubads().definePassback('/1234567/sports', [468, 60]).
    setClickUrl('%%CLICK_URL_UNESC%%').
    display();

!googletag.PassbackSlot 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 DFP FE.
  • 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 DFP FE (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.PassbackSlot
The slot object on which the method was called.

Example:
googletag.pubads().definePassback('/1234567/sports', [468, 60]).
    setForceSafeFrame(true).
    display();

!googletag.PassbackSlot setTagForChildDirectedTreatment(value)

Configures whether the passback slot should be tagged for child-directed treatment. Although in general TFCD is treated as a page-level setting, passbacks operate in a separate context, so for a passback, this is a slot-level setting.
See the TFCD article for more details.

Parameters
number value
The child-directed treatment tag status to set. See the article for supported values.

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

Example:
googletag.pubads().definePassback('/1234567/sports', [468, 60]).
    setTagForChildDirectedTreatment(1).
    display();

!googletag.PassbackSlot setTagForUnderAgeOfConsent(value)

Configures whether to mark the passback slot as coming from a user under the age of consent. Although in general TFUA is treated as a page-level setting, passbacks operate in a separate context, so for a passback, this is a slot-level setting.

Parameters
number value
The under age tag status to set. 0 and 1 are the only valid values.

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

Example:
// Mark the passback slot as coming from a user under the age of consent.
googletag.pubads().definePassback('/1234567/sports', [468, 60]).
    setTagForUnderAgeOfConsent(1).
    display();

!googletag.PassbackSlot setTargeting(key, value)

Sets a custom targeting parameter for this slot. Calling this multiple times for the same key will overwrite old values. Values set here will overwrite targeting parameters set on the service that this slot uses.

Parameters
string key
Targeting parameter key.
string|!Array<string> value
Targeting parameter value or list of values.

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

Example:
googletag.pubads().definePassback('/1234567/sports', [468, 60]).
    setTargeting('color', 'red').
    setTargeting('sport', ['rugby', 'rowing']).
    display();

!googletag.PassbackSlot updateTargetingFromMap(map)

Sets custom targeting parameters for this passback slot, from a key:value map in a JSON object. A badly formatted input will be rejected. This is the same as calling passbackSlot.setTargeting(key,value) for all the key values of the object. In case of overwriting, only the last value will be kept. Values set here will overwrite targeting parameters set on service level. These keys are defined in your DFP account.

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

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

Example:
var slot = googletag.definePassback('/1234567/sports', [160, 600]).
  updateTargetingFromMap({'color':'red',
                          'interests', ['sports','music','movies']}).
  display();

googletag.PrivacySettingsConfig

Configuration object for privacy settings.

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

boolean restrictDataProcessing

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

googletag.PubAdsService

Extends googletag.Service.

Publisher Ads service. This service is used to fetch and show ads from your DFP 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.
clearTagForChildDirectedTreatment()
Clears the configuration for whether the page should be treated as child-directed.
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.
defineOutOfPagePassback(adUnitPath)
Constructs an out-of-page passback slot.
definePassback(adUnitPath, size)
Constructs a passback slot.
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/disables centering of ads.
setCookieOptions(options)
Sets options for ignoring DFP 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(latitudeOrAddress, opt_longitude, opt_radius)
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.
setTagForChildDirectedTreatment(value)
Configures whether the page should be treated as child-directed.
setTagForUnderAgeOfConsent(opt_value)
Configures whether to mark ad requests as coming from users under the age of consent.
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 clearTagForChildDirectedTreatment()

Clears the configuration for whether the page should be treated as child-directed.
See the TFCD article for more details.

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

Example:
// Mark ad requests as child-directed.
googletag.pubads().setTagForChildDirectedTreatment(1);

// Clear child-directed setting and return to initial not-set value.
googletag.pubads().clearTagForChildDirectedTreatment();

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

googletag.PassbackSlot defineOutOfPagePassback(adUnitPath)

Constructs an out-of-page passback slot. A passback is where a GPT snippet is used as a creative in an ad serving system. The ad serving system could be DFP or a third party.
Use of this method is discouraged, since it behaves synchronously and may be blocked by certain browsers. See the help center article on passbacks for an alternative.

Parameters
string adUnitPath
The ad unit path of the slot to use as a passback.

Returns
googletag.PassbackSlot
The new passback object or null if the method was called with invalid arguments.

Example:
<script src="//www.googletagservices.com/tag/js/gpt.js">
  googletag.pubads().defineOutOfPagePassback('/1234567/sports').display();
</script>

googletag.PassbackSlot definePassback(adUnitPath, size)

Constructs a passback slot. A passback is where a GPT snippet is used as a creative in an ad serving system. The ad serving system could be DFP or a third party.
Use of this method is discouraged, since it behaves synchronously and may be blocked by certain browsers. See the help center article on passbacks for an alternative.

Parameters
string adUnitPath
The ad unit path of the slot to use as a passback.
!googletag.GeneralSize size
The size of the slot.

Returns
googletag.PassbackSlot
The new passback object or null if the method was called with invalid arguments.

Example:
<script src="//www.googletagservices.com/tag/js/gpt.js">
  googletag.pubads().definePassback('/1234567/sports', [468,
60]).display(); </script>

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
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 in the Help Center.
Notes:
  • Lazy loading only works if using async rendering.
  • Lazy fetching in SRA only works if all slots are outside the fetching margin.
  • Lazy fetching does not currently work with collapseEmptyDivs.

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.

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
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/disables centering of ads. This mode must be set before the service is enabled. Centering is disabled by default. In legacy gpt_mobile.js, centering is enabled by default.

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

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

!googletag.PubAdsService setCookieOptions(options)

Sets options for ignoring DFP cookies on the current page.

Parameters
number options
The cookie options to set. Possible values are:
  • 0: Enables DFP cookies on ad requests on the page. This option is set by default.
  • 1: Ignores DFP 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 DFP 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 DFP FE.
  • 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 DFP FE (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:
<script src="//www.googletagservices.com/tag/js/gpt.js">
  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();
</script>

!googletag.PubAdsService setLocation(latitudeOrAddress, opt_longitude, opt_radius)

Passes location information from websites so you can geo-target line items to specific locations. DFP will not use location data unless this feature has been enabled for your network. To enable this feature, please contact your account manager.

Parameters
string|number latitudeOrAddress
Latitude or freeform address.
number= opt_longitude
The longitude (if a latitude was provided as first argument).
number= opt_radius
The radius in millimeters. Will be rounded to closest integer. Only used when passing the latitude and longitude.

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

Example:
// Latitude, longitude:
googletag.pubads().setLocation(34, -45.12);

// Latitude, longitude, and precision in millimeters:
googletag.pubads().setLocation(34, -45.12, 10000);

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

!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 overriden 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:
<script src="//www.googletagservices.com/tag/js/gpt.js">
  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();
</script>

!googletag.PubAdsService setTagForChildDirectedTreatment(value)

Configures whether the page should be treated as child-directed.
See the TFCD article for more details.

Parameters
number value
The child-directed treatment tag status to set. See the article for supported values.

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

Example:
// Mark ad requests as child-directed.
googletag.pubads().setTagForChildDirectedTreatment(1);

!googletag.PubAdsService setTagForUnderAgeOfConsent(opt_value)

Configures whether to mark ad requests as coming from users under the age of consent.

Parameters
number= opt_value
The user under the age of consent tag to set. The value is optional; the tag value is cleared if it is unspecified. 0 for ad requests that are not from users under the age of consent, and 1 for ad requests that are from users under the age of consent.

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

Example:
// Mark ad requests as coming from users under the age of consent.
googletag.pubads().setTagForUnderAgeOfConsent(1);

// Mark ad requests as not coming from users under the age of consent.
googletag.pubads().setTagForUnderAgeOfConsent(0);

// Clear the tag value that configures whether to mark ad requests as
// coming from users under the age of consent.
googletag.pubads().setTagForUnderAgeOfConsent();

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

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.

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: 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. Slot requested listener.
// The listener will be called when pubads service actually sends 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.
googletag.pubads().addEventListener('slotRequested', function(event) {
  console.log('Slot has been requested:');
  console.log(event);
});

// 2. Slot render ended listener.
// The listener will be called only when the pubads service renders a slot.
// To listen to companion ads, add a similar listener to
// googletag.companionAds().
googletag.pubads().addEventListener('slotRenderEnded', function(event) {
  console.log('Slot has been rendered:');
  console.log(event);
});

// 3. Slot render ended listener, slot specific logic.
// Listeners operate at service level, which means that you cannot add a
// listener for a slotRenderEnded 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('slotRenderEnded', function(event) {
  if (event.slot === targetSlot) {
    // Slot specific logic.
  }
});

// 4. Impression viewable listener, slot specific logic.
// The listener will be called when the impression is considered viewable.
// This event also operates at service level, but, as above, you can filter
// to respond only to a certain ad slot by using this pattern:
googletag.pubads().addEventListener('impressionViewable', 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 DFP servers still record a click even if the click URL is replaced, but any landing page URL associated with the creative that is served is overridden. 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').
    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 DFP FE.
  • 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 DFP FE (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:
<script src="//www.googletagservices.com/tag/js/gpt.js">
  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();
</script>

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

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.

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. The event is fired by the service that rendered the slot. Example: To listen to companion ads, add a listener to the companion ads service, not the pubads service. Note: If you need to know when the creative has fired its load event, consider the SlotOnloadEvent.

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.

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

googletag.events.SlotResponseReceived

Extends googletag.events.Event.

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

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.

number inViewPercentage

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