DFP Small Business

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

cmd

Reference to the global command queue for asynchronous execution of GPT-related calls.

companionAds()

Returns a reference to the companion ads service.

content()

Returns a reference to the content service.

defineOutOfPageSlot(unitName, divId)

Constructs an out of page (interstitial) ad slot with the given ad unit name. divId is the ID of the div element that will contain the ad.

definePassback (unitName, size)

When called in a DFP ad tag given to a third-party ad server, passes the tag back to DFP when no matching ad is available on the third-party ad server.

defineSlot(unitName, size, divId)

Constructs an ad slot with the given ad unit name and size. divId is the ID of the div element that will contain this ad slot.

display(divId)

Indicates where on the page the ad slot contents should be displayed.

enableServices()

Enables all Google Publisher Tag services that have been associated with ad slots on the page.

pubads()

Returns a reference to the publisher ads service.

API for configuring the DFP publisher ads service. The publisher ads service is the main service used to request ads from Google.

collapseEmptyDivs()

Collapses empty div elements on the page when there is no ad content to display. This must be called before enableServices() for it to have any effect.

disableInitialLoad()

Disables the initial fetch of ads from Google when the page is first loaded. Calls to refresh() can still be used to fetch ads.

display(unitName, size, divId)

Constructs an ad slot with the specified parameters and associates it with the publisher service. Equivalent to defineSlot() followed by addService(pubads). Note that using this method does not allow you to use single request mode.

enableAsyncRendering()

Instructs the service to fetch ads asynchronously using iframes in the publisher's domain.

enableSingleRequest()

Requests all ad slot contents in a single request.

enableSyncRendering()

Instructs the service to wait for each ad request to complete before continuing with rendering the page.

noFetch()

Processes the JavaScript but does not make any HTTP calls for ad slot contents.

refresh(slots)

(Async mode only) Refreshes the specified array of slots on the page with new ads.

set(key, value)

Sets values for AdSense parameters that apply to all pubService ad slots.

setTargeting(key, value)

Sets values for targeting keys that apply to all pubService ad slots.

API for configuring the DFP companion ads service.

enableSyncLoading()

Enables the service implementation to be loaded synchronously.

setRefreshUnfilledSlots(value)

Enables or disables the automatic refresh of companion slots that have not been filled.

API for configuring the DFP content service. The content service gives you control over an ad slot to display other ads before a companion ad is requested.

setContent(slot, content)

Fills a slot with the given contents. If the slot is not yet rendered (or does not have an associated div), the contents are stored and the slot is filled when the div is created.

API for configuring a specific ad slot on the page.

addService(service)

Adds the ad slot to the specified Google tag service.

set(key, value)

Sets values for AdSense parameters on a particular ad slot.

setClickUrl(url)

Sets the redirect URL for a click on an ad in a particular slot. The DoubleClick 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.

setTargeting(key, value)

Sets values for targeting keys on a particular ad slot.

API for queueing GPT function calls for execution when ready.

push(JsFunction)

JsFunction will be queued for execution pending the loading of gpt.js.

Returns a reference to the companion ads service.

Returns:

companionAdsService - A reference to the companion ads service.

content

Returns a reference to the content service.

Returns:

contentService - A reference to the content service.

defineOutOfPageSlot

googletag.defineOutOfPageSlot(unitName, divId)

Constructs an out of page (interstitial) ad slot with the given ad unit name. divId is the ID of the div element that will contain the ad.

Parameters:

string unitName: Full path of the ad unit with the network code and unit name.

string divId: Publisher-specified ID for the div element containing the ad.

Returns:

adSlot: The newly created ad slot.

Example:

// Ad unit = "/networkCode/unitName"
googletag.defineOutOfPageSlot("1234567/outofpage", "div-gpt-ad-1");

definePassback

googletag.pubads().definePassback(unitName, size)

When called in a DFP ad tag given to a third-party ad server, passes the tag back to DFP when no matching ad is available on the third-party ad server.

Parameters:

string unitName: Full path of the ad unit with the network code and unit name.

number size: Width and height of the ad unit within brackets and separated by a comma.

Returns:

passbackSlot: The newly created passback ad slot.

Example:

// Ad unit = "/networkCode/unitName"; size = [width, height]
googletag.pubads().definePassback("/1234567/leaderboard", [728, 90]);

defineSlot

Constructs an ad slot with a given ad unit name and size and associates it with the ID of a div element on the page that will contain the ad.

Parameters:

string unitName - Full path of the ad unit with the network code and unit name.

number sizes - Width and height of the ad unit within brackets and separated by a comma. You can specify more than one size using this syntax: [[width1, height1], [width2, height2]]

string divId - Publisher-specified ID for the div element containing the ad.

Returns:

adSlot - The newly created ad slot.

Example:

// Ad unit = "/networkCode/unitName"; sizes = [[width1, height1], [width2, height2]]
googletag.defineSlot("/1234567/leaderboard", [[468, 60], [728, 90]], "div-1");

disablePublisherConsole

Disables the Google Publisher Console.

display

Indicates where on the page the ad slot contents should be displayed. 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 appear in a script block within the div element named in the function call (this restriction is required to seamlessly support the synchronous ad rendering mode).

Parameters:

string divId - ID of the div element containing the ad slot.

Example:

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

enableServices

Enables all Google Publisher Tag services that have been defined for ad slots on the page. This is only needed once per page but including it multiple times will not cause any harm.

pubads

Returns a reference to the publisher ads service.

Returns:

pubService - A reference to the publisher ads service.

collapseEmptyDivs

Collapses empty div elements on a page when there is no ad content to display. This must be called before enableServices() for it to have any effect.

disableInitialLoad

Disables the initial fetch of ads from Google when the page is first loaded. Calls to refresh() can still be used to fetch ads.

display

Constructs an ad slot with the specified parameters and associates it with the publisher service. Equivalent to defineSlot() followed by addService(pubads). Note that using this method does not allow you to use single request mode.

Parameters:

string unitName - Full path of the ad slot with the network code and unit name.

string size - Width and height of the unit (within brackets, and separated by a comma).

string divId - Publisher-specified ID for the div element containing the ad.

Example:

// Ad unit = "/networkCode/unitName"; size = [width, height]

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

enableAsyncRendering

Directs the publisher ads service to use the asynchronous rendering mode. In asynchronous rendering, ad requests are made using iframes in the publisher domain (friendly iframes) and the response is written into another friendly iframe. Since the service uses asynchronous rendering by default, publishers would only need to use this method to override a previous setting. As with most service-level settings, this should be called prior to enabling the service.

enableSingleRequest

Directs the publisher ads service to make a single request when fetching content for multiple ad slots. This should be called prior to enabling the service.

enableSyncRendering

Directs the publisher ads service to use synchronous rendering mode. In synchronous rendering, both the ad requests and the rendering of the responses are done directly on the publisher's page in a blocking fashion. While this may increase the latency of the page, it makes available certain types of ad creatives that are not iframe-friendly. This should be called prior to enabling the service. Synchronous rendering also requires that the GPT JavaScript be fetched synchronously.

noFetch

Processes the JavaScript but does not make any HTTP calls for ad slot contents.

refresh

(Async mode only) Refreshes the specified array of slots on the page with new ads.

Parameters:

array slots - Optional array of slots to refresh. If not supplied, all ad slots are refreshed.

Example:

var slot1 = googletag.defineUnit("/1234567/leaderboard", [728, 90], "div-1").addService(googletag.pubads());
var slot2 = googletag.defineUnit("/1234567/skyscraper", [160, 600], "div-2").addService(googletag.pubads());

// The call to refresh fetches a new ad for each slot
googletag.pubads().refresh([slot1, slot2]);

set

Sets values for AdSense parameters that apply to all ad slots under the publisher ads service. Calling this more than once for the same key will override previously set values for that key. All values must be set before the first display call.

Parameters:

string key - Key name of the parameter for which to set a value.

string value - Value of the key.

Example:

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

Available keys:

New parameter	Legacy parameter	Example	Allowed values
adsense_channel_ids	google_ad_channel	271828183+314159265	valid AdSense channel IDs, separated by '+'
adsense_ad_types	google_ad_type	text_image	text, image, text_image
adsense_ad_format	google_ad_format	250x250_as	468x60_as, 234x60_as, 125x125_as, 120x600_as, 160x600_as, 180x150_as, 120x240_as, 200x200_as, 250x250_as, 300x250_as, 336x280_as, 728x90_as
adsense_background_color	google_color_bg	#000000	hexadecimal colors
adsense_border_color	google_color_border	#000000	hexadecimal colors
adsense_link_color	google_color_link	#000000	hexadecimal colors
adsense_text_color	google_color_text	#000000	hexadecimal colors
adsense_url_color	google_color_url	#000000	hexadecimal colors
adsense_ui_features	google_ui_features	rc:10	rc:10 for very rounded corners, rc:6 for slightly rounded corners, rc:0 for square corners (default)

setTargeting

Sets values for targeting keys that apply to all pubService ad slots. These keys are defined by an administrator in the DFP application. Calling this function 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 - Key name of the parameter for which to set a value.

string value - Value of the key.

Example:

// example with a single value for a key
googletag.pubads().setTargeting("interests", "sports");

// example with multiple values for a key inside of brackets
googletag.pubads().setTargeting("interests", ["sports","music","movies"]);

enableSyncLoading

Enables the service implementation to be loaded synchronously. As with most service-level settings, this should be called prior to enabling the service.

setRefreshUnfilledSlots

Enables or disables the automatic refresh of companion slots that have not been filled.

Parameters:

boolean value - If true, enables the automatic refresh of unfilled slots.

Example:

googletag.companionAds.setRefreshUnfilledSlots(true);

setContent

contentService.setContent(slot, content)

Fills a slot with the given contents. If the slot is not yet rendered (or does not have an associated div element), the contents are stored and the slot is filled when the div is created..

Parameters:

slot - The slot to be filled.

string - The HTML content for the slot.

Example:

var slot = googletag.defineSlot('/1234567/leaderboard', [728, 90], 'div-1');
var content = '<a href="www.mydestinationsite.com"><img src="www.mysite.com/img.png"></img></a>';
googletag.content().setContent(slot, content);

addService

Adds the ad slot to the specified Google tag service.

Parameters:

pubService service - Reference to the publisher tag service.

Returns:

adSlot - The ad slot on which the function was called.

Example:

adSlot.addService(googletag.pubads());

set

Sets values for AdSense parameters on a particular ad slot. This will override any values set at the service level for this key. See the set table above for a list of available keys and values. Calling this function 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 - Key name of the parameter for which to set a value.

string value - Value of the key.

Example:

// setting targeting on a single ad slot
var slot = googletag.defineSlot("/1234567/skyscraper", [160, 600]).addService(googletag.pubads());
slot.set("adsense_background_color", "#FFFFFF");

setClickUrl

Sets the redirect URL for a click on an ad in a particular slot. The DoubleClick 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.

Parameters:

string url - The click URL.

Example:

googletag.defineSlot("/1234567/skyscraper", [160, 600])
  .setClickUrl("http://www.example.com")
  .addService(googletag.pubads());

setTargeting

Sets values for targeting keys and slot parameters on a particular ad slot. This function will override any values set at the service level for this key. These keys are defined by an administrator in the DFP application. Calling this function 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 - Key name of the parameter for which to set a value.

string value - Value of the key.

Example:

var slot=googletag.defineSlot("/1234567/skyscraper", [160, 600]).addService(googletag.pubads());

// example with a single value for a key
slot.setTargeting("allow_expandable", "true");

// example with multiple values for a key inside of brackets
slot.setTargeting("interests", ["sports","music","movies"]);

push

The googletag.cmd variable is initialized to an empty JavaScript Array by the publisher as part of the tags, and cmd.push is the standard Array.push function that adds an element to the end of the array. When the main GPT JavaScript is loaded, it looks through the array and executes all the functions in order. The script then replaces cmd with an internal object whose push function is defined to immediately execute the function argument passed to it. This mechanism allows GPT to reduce perceived latency by fetching the initial JavaScript asynchronously while allowing the browser to continue rendering the page. If the initial JS file is fetched synchronously, calling cmd.push with a function definition is equivalent to calling the function directly.

Example:

googletag.cmd.push(function() {
  googletag.defineSlot("/1234567/ca-pub-12345678912/skyscraper", [160, 600]).
       addService(googletag.pubads());
});