Click here to see your recently viewed pages and most viewed pages.
Hide
Google Interactive Media Ads

Companion Ads with Google Publisher Tag

The use of the Google Publisher Tag (GPT) automates the displaying of HTML companion ads on your site. We recommend that most publishers use the GPT.

This quick start guide covers the following topics when displaying GPT companion ads in the IMA Flash SDK:

Prerequisites

  • Flash video player with the IMA Flash SDK integrated. If you don't have one, check out our quick start guide.
  • The Flash player must be embedded with allowscriptaccess="always".
  • A video tag URL that returns a VAST XML document with <CompanionAds> defined. [Sample tag]

Helpful primers

  • GPT docs - more detailed information on using GPT.
  • IAB VAST spec - You can read about the <CompanionAds> element and its attributes and child nodes.

Visitor disclosure

Script access

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.

Displaying GPT companion ads with the IMA Flash SDK

The IMA SDK will look for companion slots on the current page. You'll declare these companion slots via JavaScript on your HTML page, as demonstrated in the following examples.

Note: In each of the examples below, be sure to supply a valid network and unit-path in the googletag.defineSlot method call.

Example 1: Basic ad slot

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.

<html>
  ...
  <body>
  ...
    <!-- Load tagging library -->
    <script type="text/javascript"
            src="http://www.googletagservices.com/tag/js/gpt.js">
    </script>

    <script type="text/javascript">
      // Register your companion slots.
      // Supply YOUR_NETWORK and YOUR_UNIT_PATH.
      adSlot1 = googletag.defineUnit(
          '/YOUR_NETWORK/YOUR_UNIT_PATH',
          [728, 90],
          'companionDiv1');
      adSlot1.addService(googletag.companionAds());
      adSlot1.addService(googletag.pubads());
      // Load companion ads service synchronously.
      googletag.companionAds().enableSyncLoading();
      googletag.enableServices();
    </script>
    <!-- Declare a div where you want the companion to appear. Use
          googletag.display() to make sure the ad is displayed. -->
    <div id="companionDiv1" style="width:728px; height:90px;">
      <script type="text/javascript">
        // The unit will not actually display now - it will display when
        // the video player is displaying the ads.
        googletag.cmd.push(function() { googletag.display('companionDiv1'); });
      </script>
    </div>
    ...
    <!-- IMA-integrated Flash player embed code -->
    ...
  <body>
</html>
 

Example 2: Dynamic ad slot

If you don't know how many ad slots you will have on a page until the content is rendered, you can register the ad slot in the same div where the ad will be rendered.

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>
  ...
  <body>
  ...
    <!-- Load tagging library -->
    <script type="text/javascript"
            src="http://www.googletagservices.com/tag/js/gpt.js">
    </script>

    <!-- Declare a div where you want the companion to appear. Use
          googletag.display() to make sure the ad is displayed. -->
    <div id="companionDiv1" 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], 'companionDiv1')
              .addService(googletag.companionAds())
              .addService(googletag.pubads());
          googletag.companionAds().setRefreshUnfilledSlots(true);
          googletag.pubads().enableVideoAds();
          googletag.enableServices();
          googletag.display('companionDiv1');
        });
      </script>
    </div>
    ...
    <!-- IMA-integrated Flash player embed code -->
    ...
  <body>
</html>
 

Example 3: Pre-load a companion slot with a display ad

You can also display a standard web ad in the companion slot which gets replaced with companion ads once your video ad starts playing. 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 otherwise the same Example 1 except you provide the ad network and unit path of your preload ad instead of your video ad unit and call setRefreshUnfilledSlots(true);

Here's an example of the implementation just described:

adSlot1 = googletag.defineUnit( '/YOUR_NETWORK/YOUR_UNIT_PATH', [728, 90], 'companionDiv1'); adSlot1.addService(googletag.companionAds()); adSlot1.addService(googletag.pubads()); // Load companion ads service synchronously. googletag.companionAds().enableSyncLoading(); googletag.enableServices();
  ...
     // Supply YOUR_PRELOAD_NETWORK and YOUR_PRELOAD_UNIT_PATH.
     adSlot1 = googletag.defineUnit(
          '/YOUR_PRELOAD_NETWORK/YOUR_PRELOAD_UNIT_PATH',
          [728, 90],
          'companionDiv1');
     adSlot1.addService(googletag.companionAds())
     adSlot1.addService(googletag.pubads());
     googletag.companionAds().setRefreshUnfilledSlots(true);
     googletag.pubads().enableVideoAds();
     googletag.enableServices();
   });
  ...

Example 4: Pre-load a companion slot with static content

This example shows the use of static content (such as HTML) as a pre-load for your ad slot.

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.

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

Set up Backfill for Companion Ads

AdSense for video publishers can use backfill to request and display unrelated companion banner ads to fill a companion slot. Note that this is for AdSense users only. If you enable backfill, a banner ad can be served in a companion slot if the master ad is returned without its companion ad. Otherwise, if backfill is not enabled, the companion slots will remain empty. Audio master ads are returned with companion ads by default and do not require any backfill.

Here's an example that shows how to enable backfilling:

    ...
     <!-- 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());
         adSlot.set("backfill", "true");
         googletag.companionAds().setRefreshUnfilledSlots(true);
         googletag.pubads().enableVideoAds();
         googletag.enableServices();
       });
     </script>
    ...

Note that companion backfill can be filled with eligible display ads from the DFP network's directly sold inventory or Ad Exchange/AdSense backfill.

Back to top