Companion Ads in DFP Premium (Deprecated)

HTML Companion Ads

Follow the steps below to implement HTML companion ads in your website.

  1. Book HTML Companion Ads
  2. Request Companion Ads from Flash
  3. Declare Companion Ad Slots in HTML

Additional Topics:

Book HTML Companion Ads

To set up companion ad slots in DFP Premium, create a new ad unit on the Inventory tab. Expand the Video (VAST) sizes option, then enter companion ad sizes in the Companion sizes field. For complete documentation, visit the Help Center.

Request Companion Ads using the SDK

By default, companions ads are enabled for each ad request. Companion ads will be requested and displayed automatically as long as there are companion ad slots declared on the HTML page.

If you want to disable HTML companion ads, set adsRequest.disableCompanionAds to true. Refer to the Disabling Companion Ads section of this page for an example.

Declare Companion Ad Slots in HTML

For a companion banner to work, the Flash player must be embedded on the HTML page with allowscriptaccess="always", which enables the Flash code to access the companion ad slots declared in JavaScript. Just before the video player shows the companions, it looks for companion slots in the current page.

You need to add some JavaScript to your HTML page and declare companion ad slots. This section describes various examples and provides example code and demos. Click the Demo link after each code snippet to go to the demo. You can inspect the demo to see the exact implementation in action.

Example 1: Basic ad slot implementation

The code example below shows how to include a gpt.js file in your HTML page and declare two ad slots. One of them is 728x90 and the other is 300x250. After ad slots have been declared, the googletag.display() function can render them anywhere on the page where it is called. Because the slots are companion slots, they will not be displayed right away, but at the video ad display time.

The following example reflects a scenario in which the video ad plays automatically and companion ad backfill has been enabled. To enable Click-to-play, refer to the code modifications described under Enable Click-to-play

 <html>
  <head>

    <!-- HEAD part -->
    <!-- Initialize the tagging library -->
    <script type="text/javascript">
      // Define the command queue to be able to issue tagging commands
      // before the actual JavaScript library loads.
      var googletag = googletag || {};
      googletag.cmd = googletag.cmd || [];

      // Load the library, asynchronously.
      (function() {
      var gads = document.createElement('script');
      gads.async = true;
      gads.type = 'text/javascript';
      var useSSL = 'https:' == document.location.protocol;
      gads.src = (useSSL ? 'https:' : 'http:') +
          '//www.googletagservices.com/tag/js/gpt.js';
      var node = document.getElementsByTagName('script')[0];
      node.parentNode.insertBefore(gads, node);
      })();
    </script>

    <script type="text/javascript">
      // Add a command to the command queue
      googletag.cmd.push(function() {
        // Use googletag.defineSlot() to create ad slots.
        // Specify size and div id to identify the ad placement.
        // Attach the slot to the companion ads service.
        var adSlot1 = googletag.defineSlot(
            '/%network%/%unit-path%',
            [728, 90],
            'companionDiv1');
        // Attach the slot to the companion ads service.
        adSlot1.addService(googletag.companionAds());
        // Attach to the publisher ads service in order to support backfill.
        adSlot1.addService(googletag.pubads());
        var adSlot2 = googletag.defineSlot(
            '/%network%/%unit-path%',
            [300, 250],
            'companionDiv2');
        adSlot2.addService(googletag.companionAds());
        adSlot2.addService(googletag.pubads());
        googletag.pubads().disableInitialLoad();
        googletag.pubads().enableAsyncRendering();
        googletag.companionAds().setRefreshUnfilledSlots(true);
        // Enable the companion ads service.
        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="companionDiv1" style="width:728px; height:90px;">
      <script type="text/javascript">
        // Still 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('companionDiv1'); });
      </script>
    </div>
  ...
    <div id="companionDiv2" style="width:300px; height:250px;">
      <script type="text/javascript">
        googletag.cmd.push(function() { googletag.display('companionDiv2'); });
      </script>
    </div>

  </body>
 </html>
 
Enable Click-to-Play

In certain circumstances, a companion ad may only load after the user has clicked a Click-to-Play video. In that scenario, you would 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 set standard web ads to display in the companion slot (ensure that the web ads are targeted to the companion slots).

To enable the Click-to-Play option, to pre-load the ad slots, remove googletag.pubads().disableInitialLoad(); from the Basic ad slot implementation example above.

Disable Backfill

If you wish to disable backfill on companion ads, change the value passed to the googletag.companionAds().setRefreshUnfilledSlots(true); function in the Basic ad slot implementation example above to false.

Demo

Back to top

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. This example shows how to define ad slots while the page renders.

The example is identical to Example #1 except for defining the ad slots where they will be displayed.

Note: The Flash player will ask for the slots when it's about to show the ads. Please make sure the slots are defined before the player shows the ads.

 <html>
  <head>
    <!-- HEAD part -->
    <!-- Initialize the tagging library -->
    <script type="text/javascript">
      // Define the command queue to be able to issue tagging commands
      // before the actual JavaScript library loads.
      var googletag = googletag || {};
      googletag.cmd = googletag.cmd || [];

      // Load the library, asynchronously.
      (function() {
      var gads = document.createElement('script');
      gads.async = true;
      gads.type = 'text/javascript';
      var useSSL = 'https:' == document.location.protocol;
      gads.src = (useSSL ? 'https:' : 'http:') +
          '//www.googletagservices.com/tag/js/gpt.js';
      var node = document.getElementsByTagName('script')[0];
      node.parentNode.insertBefore(gads, node);
      })();
    </script>
  </head>
  <body>
    ...
    <div id="companionDiv1" style="width:728px; height:90px;">
    <script type="text/javascript">
      // Add a command to the command queue
      googletag.cmd.push(function() {
        // Define the unit
        var adSlot1 = googletag.defineSlot(
            '/%network%/%unit-path%',
            [728, 90],
            'companionDiv1');
        adSlot1.addService(googletag.companionAds());
        // Attach to the publisher ads service in order to preload the ads.
        adSlot1.addService(googletag.pubads());
        // Enable the companion ads service.
        googletag.pubads().disableInitialLoad();
        googletag.pubads().enableAsyncRendering();
        googletag.companionAds().setRefreshUnfilledSlots(true);
        googletag.enableServices();
        // Immediately signal to show it.
        googletag.display('companionDiv1');
      });
    </script>
    </div>

  </body>
 </html>
 

Disabling Companion Ads

This example shows an AdSense For Video request that is explicitly disabling companions.

 // Create AdsLoader
 var adsLoader:AdsLoader = new AdsLoader();

 // Create AdsRequest
 var adsRequest:AdsRequest = new AdsRequest();
 adsRequest.adSlotWidth = 300;
 adsRequest.adSlotHeight = 250;
 adsRequest.publisherId = "ca-video-mypubid";
 adsRequest.adType = AdsRequestType.VIDEO;
 adsRequest.contentId = "unique-content-identifier";

 // Disable companion ads (optional)
 adsRequest.disableCompanionAds = true;

 // Request ads
 adsLoader.requestAds(adsRequest);
 

Custom Targeting for Backfilled Companions

When backfilling companions, it is possible to provide custom per-page or per-slot targeting similar to that used in non-companion ad slots.

In this example, page-level targeting has been set to sports=baseball or sports=basketball and the ad slot-specific targeting has been set to gender=male:

  <script type="text/javascript">
    ...
    var adSlot1 = googletag.defineSlot(
            '/%network%/%unit-path%',
            [728, 90],
            'companionDiv1');
    adSlot1.addService(googletag.companionAds()).addService(googletag.pubads());
    // Set per-slot targeting.
    adSlot1.setTargeting('gender', 'male');
    // Set per-page targeting - applies to all slots.
    googletag.pubads().setTargeting('sports', ['baseball', 'basketball']);
    ...
    googletag.enableServices();
  </script>

For more information, see Setting Targeting and Sizes with GPT in the Help Center.

Back to top

Setting 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. When you enable backfill, a banner ad can be served in a companion slot if the master ad is returned without its companion ad. Otherwise, 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 a backfill:

  adSlot = googletag.defineSlot(
      '/%network%/%unit-path%',
      [300, 250],
      'companionDiv1');
  adSlot.set("backfill", "true");
  adSlot.addService(googletag.companionAds());

Back to top

Send feedback about...

Interactive Media Ads SDKs
Need help? Visit our support page.