Control ad loading and refresh

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"></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"></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() unnecessarily

When refreshing an ad slot, do not call PubAdsService.clear() first. This is unnecessary, since refresh() replaces the contents of the specified slot, regardless of whether any ad content was previously loaded. Calling clear() immediately before calling refresh() 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();
});