In our getting started and basic concept examples, the Google Publisher Tag
(GPT) library's display()
method is used
to register and display an ad slot. However, there are times when it may be
preferrable or even necessary to separate these actions, in order to more
precisely control when ad content is loaded. For example, when working with a
consent management platform or requesting ad content as the result of a user
action.
In this guide we'll explore the mechanisms provided by GPT to control the loading of ad content and fetch new ad content on demand. Full code for this example can be found on the event based requests sample page.
Control ad loading
By default, the behavior of the display()
method is to
register, request, and render ad content into an ad slot. The automatic
requesting and rendering of ad content can be disabled via the
PubAdsService.disableInitialLoad()
method.
With initial load disabled, calls to display()
will only register the ad slot.
No ad content will be loaded until a second action is taken. This allows you to
precisely control when ad requests are made.
To avoid making unintentional ad requests, disableInitialLoad()
must be called
before enabling the service and before calling display()
.
<!doctype html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="description" content="Request GPT ads based on events." /> <title>Event-based ad requests</title> <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js" crossorigin="anonymous" ></script> <script> window.googletag = window.googletag || { cmd: [] }; googletag.cmd.push(() => { // Define the ad slot. googletag .defineSlot("/6355419/Travel", [728, 90], "div-for-slot") .setTargeting("test", "event") .addService(googletag.pubads()); // Disable initial load. // This prevents GPT from automatically fetching ads when display is called. googletag.pubads().disableInitialLoad(); googletag.enableServices(); }); </script> <style></style> </head> <body> <div id="div-for-slot" style="width: 300px; height: 250px"></div> <script> googletag.cmd.push(() => { // Register the ad slot. // An ad will not be fetched until refresh is called. googletag.display("div-for-slot"); // Register click event handler. document.getElementById("showAdButton").addEventListener("click", () => { googletag.cmd.push(() => { googletag.pubads().refresh(); }); }); }); </script> </body> </html>
In this example, initial load is disabled ensuring that no ad request is made
and no ad content is rendered when display()
is called. The slot is ready to
accept and display an ad, but an ad request won't be made until the slot is
refreshed.
Refresh
The PubAdsService.refresh()
method is used to populate a
slot or slots with new ad content. This method can be used on slots that have
yet to load any content (due to disableInitialLoad()
), or to replace the
contents of an already populated slot. However, only slots which have been
registered by calling display()
are eligible to be refreshed.
<!doctype html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="description" content="Request GPT ads based on events." /> <title>Event-based ad requests</title> <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js" crossorigin="anonymous" ></script> <script> window.googletag = window.googletag || { cmd: [] }; googletag.cmd.push(() => { // Define the ad slot. googletag .defineSlot("/6355419/Travel", [728, 90], "div-for-slot") .setTargeting("test", "event") .addService(googletag.pubads()); // Disable initial load. // This prevents GPT from automatically fetching ads when display is called. googletag.pubads().disableInitialLoad(); googletag.enableServices(); }); </script> <style></style> </head> <body> <div id="div-for-slot" style="width: 300px; height: 250px"></div> <button id="showAdButton">Show/Refresh Ad</button> <script> googletag.cmd.push(() => { // Register the ad slot. // An ad will not be fetched until refresh is called. googletag.display("div-for-slot"); // Register click event handler. document.getElementById("showAdButton").addEventListener("click", () => { googletag.cmd.push(() => { googletag.pubads().refresh(); }); }); }); </script> </body> </html>
In this modified example, when a user clicks the "Show/Refresh Ad" button, the
refresh()
method is called. This triggers a request to fetch new ad content
and load it into the registered slot, overwriting any pre-existing content.
Note that in the above example the refresh()
method is called with no
parameters, which has the effect of refreshing all registered ad slots.
However, it's also possible to refresh specific ad slots by passing an array of
slots to the refresh()
method. See the Refresh ad slots
sample for an example of this.
Best practices
When working with refresh()
, there are some best practices that should be
adhered to.
Don't refresh too quickly.
Refreshing ad slots too quickly may cause your ad requests to be throttled. To prevent this, avoid refreshing slots more frequently than once every 30 seconds.
Don't call
clear()
unnecessarilyWhen refreshing an ad slot, do not call
PubAdsService.clear()
first. This is unnecessary, sincerefresh()
replaces the contents of the specified slot, regardless of whether any ad content was previously loaded. Callingclear()
immediately before callingrefresh()
will only increase the amount of time a blank slot is visible to the user.Only refresh viewable ad slots
Using
refresh()
to replace the contents of ad slots that are never viewable can significatly lower your ActiveView rate. The ImpressionViewableEvent can be used to determine when an ad slot has become viewable, as in the example below.googletag.cmd.push(function() { var REFRESH_KEY = 'refresh'; var REFRESH_VALUE = 'true'; googletag.defineSlot('/6355419/Travel',[728, 90], 'div-for-slot') .setTargeting(REFRESH_KEY, REFRESH_VALUE) .setTargeting('test', 'event') .addService(googletag.pubads()); // Number of seconds to wait after the slot becomes viewable. var SECONDS_TO_WAIT_AFTER_VIEWABILITY = 60; googletag.pubads().addEventListener('impressionViewable', function(event) { var slot = event.slot; if (slot.getTargeting(REFRESH_KEY).indexOf(REFRESH_VALUE) > -1) { setTimeout(function() { googletag.pubads().refresh([slot]); }, SECONDS_TO_WAIT_AFTER_VIEWABILITY * 1000); } }); googletag.enableServices(); });