Companion Ads

You may want to associate your in-page HTML ad slots with video or overlay ad slots. This relationship between associated ad slots is referred to as the master/companion relationship.

In addition to requesting video and overlay master ads, the IMA SDK can be used to display companion HTML ads. These ads are displayed within an HTML environment.

Using companion ads

To use companion ads, perform the steps described below:

1. Book your companion ads

You must first book the companion ads that you want to display with your master ads. Companion ads can be trafficked in DFP. You can serve up to six companion ads per master ad. This technique, when a single buyer controls all ads on the page, is also known as roadblocking.

2. Request your companion ads

By default, companion ads are enabled for each ad request.

3. Displaying companion ads

There are two ways to render companion ads:

  • Automatically using the Google Publisher Tag (GPT)
    If you're using GPTs to implement your companion ads, they will be displayed automatically as long as there are companion ad slots declared on the HTML page and these ads are registered with the API (that is, the div ID in the JavaScript and HTML must match). Some benefits of using GPTs are:
    • Companion slot awareness
    • Companion backfill from the publisher's network, if the VAST response contains fewer companion ads than there are defined slots on the HTML page
    • Companion autofill if a video ad is missing
    • Preloaded companion ad slots for click-to-play video players
    • Automated companion rendering, including HTMLResource and iFrameResource
  • Manually using the Ad API.

Using companion ads with Google Publisher Tag

The Google Publisher Tag (GPT) automates the display 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 must 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 section explains how to declare companion ads in HTML using GPT and provides sample code for different scenarios. For the HTML5 SDK, you need to add some JavaScript to your HTML page and declare the companion ad slots.

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

Using companion ads with the Ad API

This section describes how to display companion ads using the Ad API.

Displaying companion ads

To display companion ads, first get a reference to an Ad object through any of the AdEvent events dispatched from the AdsManager. We recommend using the AdEvent.STARTED event, as displaying companion ads should coincide with displaying the master ad.

Next, use this Ad object to call getCompanionAds() to get an array of CompanionAd objects. Here you have the option of specifying CompanionAdSelectionSettings, which allows you to set filters on the companion ads for creative type, near fit percentage, resource type, and size criteria. For more information on these settings, see the HTML5 API documentation.

The CompanionAd objects returned by getCompanionAds can now be used to display the companion ads on the page using these guidelines:

  1. Create a companion ad slot <div> of the required size on the page.
  2. In your event handler for the STARTED event, retrieve the Ad object by calling getAd().
  3. Use getCompanionAds() to get a list of companion ads that match both the companion ad slot size and CompanionAdSelectionSettings and have the same sequence number as the master creative. Creatives with a missing sequence attribute are treated as having sequence number 0.
  4. Get the content from a CompanionAd instance and set it as the inner HTMl of that ad slot's <div>.

Sample code


<div id="companion-ad-300-250" width="300" height="250"></div>

<script type="text/javascript">

  // Listen to the STARTED event.
  adsManager.addEventListener(
    google.ima.AdEvent.Type.STARTED,
    onAdEvent);

  function onAdEvent(adEvent) {
    switch (adEvent.type) {
      case google.ima.AdEvent.Type.STARTED:
        // Get the ad from the event.
        var ad = adEvent.getAd();
        var selectionCriteria = new google.ima.CompanionAdSelectionSettings();
        selectionCriteria.resourceType = google.ima.CompanionAdSelectionSettings.ResourceType.STATIC;
        selectionCriteria.creativeType = google.ima.CompanionAdSelectionSettings.CreativeType.IMAGE;
        selectionCriteria.sizeCriteria = google.ima.CompanionAdSelectionSettings.SizeCriteria.IGNORE;
        // Get a list of companion ads for an ad slot size and CompanionAdSelectionSettings
        var companionAds = ad.getCompanionAds(300, 250, selectionCriteria);
        var companionAd = companionAds[0];
        // Get HTML content from the companion ad.
        var content = companionAd.getContent();
        // Write the content to the companion ad slot.
        var div = document.getElementById('companion-ad-300-250');
        div.innerHTML = content;
        break;
    }
  }
</script>

Send feedback about...

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