Companion Ads

What are Companion Ads?

Zype's web player supports standard VAST 3.0 companion ads, pending proper configuration of your ad tag. Companion ads typically come in two varieties:

1) Video player overlay banner ads that appear on top of the player (usually as a lower third banner)

2) Web page banner ads displayed on a web page outside of the video player (outside of the player surface)

How do I start using Companion Ads?

The following provides a high-level outline of steps needed in order to begin using VAST 3.0 companion ads. Note, steps may vary from ad server to server, and website to website. Please work with your ad ops team and developers to properly configure your ad tags and site to serve companion ads. If you are using Google IMA companion ads, please refer to the IMA documentation provided by Google.

How to set up Video Player Overlay Banner Ads

1. Ensure your ad tag is configured to return the overlay banner image companion ads as part of its response whenever requests are generated.

Companion ads must be configured within your ad server. Please consult your ad server documentation to determine the best method for configuring companion ads. If you use Google Ad Server, this may be a helpful starting point for documentation.

2. Configure your ad tag in Zype admin to support companion ads.

The last general step is to configure your ad tag in Zype admin to enable serving of companion ads.

• Visit Zype's ad tag manager page
• Click into the ad tag you're interested in configuring to support companion ads, or create a new ad tag if you don't have one yet
• You may need to limit targeting of this ad tag to Web only, in case companion ads in the response create conflicts with other devices where your linear video ads are being served
• Toggle ON the 'COMPANION' option and save your ad tag.

After completing this setup process, you should be ready to start serving companion ads! Please make sure to test on your video player to ensure overlay ads are being displayed during playback.

How to set up Web Page Banner Ads

1. Ensure your ad tag is configured to return the overlay banner image companion ads as part of its response whenever requests are generated.

Companion ads must be configured within your ad server. Please consult your ad server documentation to determine the best method for configuring companion ads. If you use Google Ad Server, this may be a helpful starting point for documentation.

2. Configure your website / webpage to display companion ads.

You must add some configuration code to your web page in order to display companion ads in your HTML. This code can be added to a script tag in the body, or as an external JS file. 

An event listener must be attached to the video player to listen for when an ad begins. This event listener takes a function as a parameter that will handle setting up the companion ads and then displays them on the page.

Before adding an event listener to the page, you must wait for the player to load. A complete example code snippet is shown below. *Note: We are currently implementing custom Zype player events for customers to hook in to, but for now, you must wait for the player via interval checking.

Here's example code used on a webpage typical with a VAST companion ad implementation:

/* interval to wait for the player
** check for the player on the page every 200ms
*/
var playerCheck = setInterval(checkForPlayer, 200); 

/* checkForPlayer()
** check for player object, clear interval if it exists, and setup companion ads
*/
function checkForPlayer() {
  /* if the player object is not equal to undefined,
  ** then continue setting up companion ads
  */
  if(typeof theoplayer.ads != 'undefined') {
    // stop the player check interval
    clearInterval(playerCheck);

    // setup the companion ads
    setupCompanionAds();
  }
}

/* setupCompanionAds()
** Add an event listener to the player to listen to when an ad begins
** When the event handler is fired, select the div element to put
** the companion ad into.
** If there is an ad, and if it does have companion ads, loop
** through the array of companion ads adding them to the DOM
*/
function setupCompanionAds() {
  theoplayer.ads.addEventListener('adbegin', function(data) {
  // find your ad container(s)
  var adContainer = document.querySelector('#companion-ad-container');
  // if ad exists
  if(data.ad) {
  // if ad has companion ads
    if(data.ad.companions.length > 0) {
      // loop through array of companion ads
      for (var i = 0; i < data.ad.companions.length; i++) {
        // add companion ad to selected ad container(s)
        adContainer.innerHTML = data.ad.companions[i].contentHTML;
      }
    }
   }
  });
}

3. Configure your ad tag in Zype admin to support companion ads.

The last general step is to configure your ad tag in Zype admin to enable serving of companion ads.

• Visit Zype's ad tag manager page
• Click into the ad tag you're interested in configuring to support companion ads, or create a new ad tag if you don't have one yet
• You may need to limit targeting of this ad tag to Web only, in case companion ads in the response create conflicts with other devices where your linear video ads are being served
• Toggle ON the 'COMPANION' option and save your ad tag.

After completing this setup process, you should be ready to start serving companion ads! Please make sure to test on a web page to ensure companion ads are being requested and rendered as expected.