Using Companion Ads with Google Publisher Tag

The Google Publisher Tag (GPT) automates the displaying of HTML companion ads on your site. We recommend that most publishers use the GPT. The HTML5 SDK recognizes GPT slots if GPT is loaded on the main web page (not in an IFrame). You can find more detailed information on using GPT with the IMA SDK in the GPT docs.

If you host the HTML5 SDK within an IFrame...

If you meet both of the following criteria, you need to include an extra proxy script in order for your GPT companions to display correctly:

  1. Load the HTML5 SDK in an IFrame.
  2. Load GPT on the main web page (outside the IFrame).

To get your companions to display in this scenario, you need to load the GPT proxy script before loading the SDK:

  <script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/gpt_proxy.js"></script>

Important things to keep in mind:

  • There should be no GPT loaded inside the IFrame loading the SDK.
  • GPT must be loaded on the top page, not in another IFrame.
  • The proxy script must be loaded in the same frame as GPT (that is, on the main page).

Declare companion ad slots in HTML

This page explains how to declare companion ads in HTML using GPT and provides sample code and demos for different scenarios. For a companion banner to function properly with the Flash SDK, the Flash player must be embedded on the HTML page with allowscriptaccess="always". This setting enables the Flash code to access the companion ad slots declared in JavaScript. As a result, just before the video player displays the companions, it will look for companion slots in the current page. For both the Flash and HTML5 SDKs, you need to add some JavaScript to your HTML page and declare the companion ad slots. Click the Demo link (where provided) after each code snippet to view the demo. Though the demos are only provided in Flash, an HTML5 implementation of the code will behave the same way. You can inspect the demo to see the exact implementation in action.

Note: In each of the examples below, be sure to supply a valid network and unit-path in the googletag.defineSlot method call (located in the <head> or <body> tag, depending on the actual example you are using).

Example 1: Basic ad slot implementation

The sample code below shows how to include the gpt.js file in your HTML page and declare an ad slot. The declared ad slot is 728x90px. After the ad slots have been declared, the googletag.display() function can render them wherever it is called on the page. Because the slots are companion slots, ads will not be displayed immediately. Instead they will appear alongside the master video ad.

Here's an example of the implementation just described:

 <html>
   <head>
     <!-- Uncomment the line below for the HTML5 SDK caveat proxy -->
     <!-- <script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/gpt_proxy.js"></script>-->
     <!-- HEAD part -->
     <!-- Initialize the tagging library -->
     <script type='text/javascript'>
       var googletag = googletag || {};
       googletag.cmd = googletag.cmd || [];
       (function() {
         var gads = document.createElement('script');
         gads.async = true;
         gads.type = 'text/javascript';
         gads.src = '//www.googletagservices.com/tag/js/gpt.js';
         var node = document.getElementsByTagName('script')[0];
         node.parentNode.insertBefore(gads, node);
       })();
     </script>

     <!-- Register your companion slots -->
     <script type='text/javascript'>
       googletag.cmd.push(function() {
         // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
         googletag.defineSlot('/YOUR_NETWORK/YOUR_UNIT_PATH', [728, 90], 'companionDiv')
             .addService(googletag.companionAds())
             .addService(googletag.pubads());
         googletag.companionAds().setRefreshUnfilledSlots(true);
         googletag.pubads().enableVideoAds();
         googletag.enableServices();
       });
     </script>
   </head>

   <body>
     <!-- BODY part -->
     <!-- Declare a div where you want the companion to appear. Use
          googletag.display() to make sure the ad is displayed. -->
     <div id="companionDiv" style="width:728px; height:90px;">
       <script type="text/javascript">
         // Using the command queue to enable asynchronous loading.
         // The unit will not actually display now - it will display when
         // the video player is displaying the ads.
         googletag.cmd.push(function() { googletag.display('companionDiv'); });
       </script>
     </div>
   <body>
 </html>
 

Try it out

You can see a working implementation below.

Example 2: Dynamic ad slot implementation

Sometimes you might not know how many ad slots you have on a page until the page content is rendered. The sample code below shows how to define ad slots while the page renders. This example is identical to Example 1 except that in this example we register the ad slots where they will actually be displayed.

Note: The video player will ask for the slots when it's about to display the ads. Ensure that the slots are defined before the player displays the ads.

 <html>
   <head>
     <!-- Uncomment the line below for the HTML5 SDK caveat proxy -->
     <!-- <script type="text/javascript" src="https://imasdk.googleapis.com/js/sdkloader/gpt_proxy.js"></script> -->
     <!-- HEAD part -->
     <!-- Initialize the tagging library -->
     <script type='text/javascript'>
       var googletag = googletag || {};
       googletag.cmd = googletag.cmd || [];
       (function() {
         var gads = document.createElement('script');
         gads.async = true;
         gads.type = 'text/javascript';
         gads.src = '//www.googletagservices.com/tag/js/gpt.js';
         var node = document.getElementsByTagName('script')[0];
         node.parentNode.insertBefore(gads, node);
       })();
     </script>
   </head>

   <body>
     <!-- BODY part -->
     <!-- Declare a div where you want the companion to appear. Use
          googletag.display() to make sure the ad is displayed. -->
     <div id="companionDiv" style="width:728px; height:90px;">
       <script type="text/javascript">
         // Using the command queue to enable asynchronous loading.
         // The unit will not actually display now - it will display when
         // the video player is displaying the ads.
         googletag.cmd.push(function() {
           // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
           googletag.defineSlot('/YOUR_NETWORK/YOUR_UNIT_PATH', [728, 90], 'companionDiv')
               .addService(googletag.companionAds())
               .addService(googletag.pubads());
           googletag.companionAds().setRefreshUnfilledSlots(true);
           googletag.pubads().enableVideoAds();
           googletag.enableServices();
           googletag.display('companionDiv');
         });
       </script>
     </div>
   <body>
 </html>
 

Try it out

You can see a working implementation below.

Example 3: Pre-loaded ad slots

In certain cases, you may need to display something in the ad slot before the companion ad is requested. Companion ads are usually requested along with a video ad or Flash-in-Flash ad. This request could occur after the page loads. For example, a companion ad may load only after the user clicks a click-to-play video. In such a case, you need the ability to request a regular ad to fill the ad slot before the companion ad is requested. To support this use case, you can display standard web ads in the companion slot. Ensure the web ads are targeted to the companion slots. You can target the companion slots in the same way as you would target standard web ad slots.

Note: The sample code below is exactly the same as that provided for Example 1 with the exception of the section that is bolded. In this case, you provide the ad network and unit path of your preload ad instead of your video ad unit.

Here's an example of the implementation just described:

 <html>
   <head>
     ...
     <!-- Register your companion slots -->
     <script type='text/javascript'>
       googletag.cmd.push(function() {
         // Supply YOUR_PRELOAD_NETWORK and YOUR_PRELOAD_UNIT_PATH.
         googletag.defineSlot('/YOUR_PRELOAD_NETWORK/YOUR_PRELOAD_UNIT_PATH', [728, 90], 'companionDiv')
             .addService(googletag.companionAds())
             .addService(googletag.pubads());
         googletag.companionAds().setRefreshUnfilledSlots(true);
         googletag.pubads().enableVideoAds();
         googletag.enableServices();
       });
     </script>
   </head>
   ...
 </html>

Try it out

You can see a working implementation below.

Example 4: Static content

This example shows the use of static content as a pre-load for your ad slot. The content service allows you to directly set content for an empty companion slot. Using this service, you can pre-populate your companion ad slots with any HTML.

Note: Content can be only set in empty slots. If a companion ad is already displayed in the slot, the content service will ignore the command.

Here's an example of the implementation just described:

 <html>
   <head>
    ...
     <!-- Register your companion slots -->
     <script type='text/javascript'>
       googletag.cmd.push(function() {
         // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
         var adSlot = googletag.defineSlot('/YOUR_NETWORK/YOUR_UNIT_PATH', [728, 90], 'companionDiv')
             .addService(googletag.companionAds())
             .addService(googletag.pubads())
             .addService(googletag.content());
         googletag.content().setContent(adSlot,
             '<h2>Custom content in ad slot.</h2>');
         googletag.companionAds().setRefreshUnfilledSlots(true);
         googletag.pubads().enableVideoAds();
         googletag.enableServices();
       });
     </script>
   </head>
   ...
 </html>

Try it out

You can see a working implementation below.

Send feedback about...

IMA SDK for HTML5
Need help? Visit our support page.