Working with VAST 2.0 External Companion Ads

The VAST 2.0 specification offers a way to traffic together video ads and traditional HTML companions ads such as iFrames, banners, and HTML or JavaScript code. When this kind of VAST template is trafficked against a Video Cloud player, these companion ads are meant to be added to the HTML container and be displayed alongside the Video Cloud player. That is, they are external companion ads to the Video Cloud video player.

The XML structure of a VAST 2.0 template that contains video ad information and companion ads looks like this:

VAST
  Ad
    Inline
      Creatives
        Creative
          Linear
          TrackingEvents
          VideoClicks
          ClickThrough
          MediaFiles
            MediaFile // Video ad to be displayed in the Video Cloud player.
        Creative
          CompanionAds // HTML companion ads to be displayed alongside the player.
            Companion
              StaticResource || HTMLResource || IFrameResource
              TrackingEvents
                Tracking
              CompanionClickThrough

You can find several VAST 2.0 XML examples  in the IAB page.

Following  is an example of a  CompanionAds XML node, which would be nested inside the VAST, Ad, Inline, Creatives, and Creative nodes:

<Creative>
   <CompanionAds>
      <Companion id="banner" width="728" height="90">
         <TrackingEvents>
            <Tracking event="start">
                <![CDATA[http://my.adserver.com/start?]]>
            </Tracking>
          </TrackingEvents>
          <StaticResource creativeType="image/jpeg">
                <![CDATA[http://my.adserver.com/banner_728x90_orange.jpg]]>
          </StaticResource>
          <CompanionClickThrough>
                <![CDATA[http://my.adserver.com/?clickThrough=banner728x90_VAST_jpg]]>
          </CompanionClickThrough>
       </Companion>
       <Companion id="expanding_banner" width="0" height="0" expandedWidth="300" expandedHeight="250">
           <TrackingEvents>
              <Tracking event="start">
                  <![CDATA[http://my.adserver.com/trackPoint=trackstart;]]>
              </Tracking>
           </TrackingEvents>
           <StaticResource creativeType="image/jpeg">
                <![CDATA[my.adserver.com/expanded_300x250.jpg]]>
           </StaticResource>
           <CompanionClickThrough>
                <![CDATA[http://my.adserver.com/?clickThrough=banner468x60_VAST_expandingBanner]]>
           </CompanionClickThrough>
        </Companion>
        <Companion id="rich media banner" width="468" height="60">
            <HTMLResource>
               <![CDATA[
               <!-- HTML inline banner -->
               <img alt="impression" src="http://my.adserver.com/trackPoint=start;" />
               <a href="http://my.adserver.com?params&amp;creative=banner&amp;resourceType=html&amp;">
               <img alt="creative" src="http://my.adserver.com/banner_468x60.gif?creative=banner;resourceType=html" />
               </a>
               ]]>
             </HTMLResource>
          </Companion>
    </CompanionAds>
</Creative>

The video ad portion of this ad response is played automatically by the Video Cloud player; the information about external companion ads is passed to a JavaScript method named bcsyncroadblock. A string with the information about the companion ads is passed to this method. Companions will be wrapped in a XML root node named CompanionAds, which is the same name as the one in the VAST specification. If you want to access those companion ads, you need to write a bcsyncroadblock method and include it in the HTML container. The bcsyncroadblock method needs to take the adXML ad response, parse the CompanionAds node, and add the ads to the HTML page.

Note: Many ad sources handle ad responses using their own software libraries, in which case Brightcove's bcsyncroadblock() function would not be triggered. For example, DFP IMA handles all HTML companions using the methods included in this article. In the event that bcsyncroadblock() is not triggered by your VAST ads, please contact your ad provider for details on companion handling with your given ad source.

For example, the adXML ad response might contain a CompanionAds node like this:

<CompanionAds>
     <Companion id="expanding_banner" width="0" height="0" expandedWidth="300" expandedHeight="250">
         <TrackingEvents>
            <Tracking event="start">
                <![CDATA[http://my.adserver.com/trackPoint=trackstart;]]>
            </Tracking>
         </TrackingEvents>
         <StaticResource creativeType="image/jpeg">
              <![CDATA[http://my.adserver.com/expanded_300x250.jpg]]>
         </StaticResource>
         <CompanionClickThrough>
              <![CDATA[http://my.adserver.com/?clickThrough=banner468x60_VAST_expandingBanner]]>
         </CompanionClickThrough> 
     </Companion>
</CompanionAds> 

Here is a JavaScript snippet that adds the bcsyncroadblock method:

<script language="JavaScript">
    // This JS function is called by the Video Cloud Player when it encounters Companion Ads
    // in a VAST response
    function bcsyncroadblock(adXML){
     // 1. Parse adXML
     // 2. Add companion ads to the page ( DIV, Iframe, etc)
    }
</script>

When you are working with the adXML ad response, you need to remember that it is passed as a string. You will probably need to cast this to XML in the browser for easy manipulation. In the examples below, the getXMLDoc method shows how to do that.

If you're dealing with multiple ad server providers, it is always a good idea to get familiar with the VAST XML response that you will be working with. There might be slightly differences in what information is contained in the XML nodes by each provider.

In addition, you might be able to use VAST ad formats such as Video Pods that contain companion banners and traffick them to players such as the Single Video Player that do not support banners natively. You can then get access to those companion banners and display them as external companion ads (see Example 2 below). If a banner is included in a VAST response and its size is not supported by a specific player, the banner then will be available as external companion ad and will be passed to the bcsyncroadblock method.

Next we show two examples that demonstrate how to handle the adXML string that is passed to bcsyncroadblock. These examples are meant to illustrate a basic workflow of receiving the adXML string, parsing it, and adding its content to the HTML container. In our experience, more validations will be needed for production environments. For example, these examples do not handle cases where an ad response is returned with a different structure from the one that is expected.

Example 1: Playing a VAST external companion ad alongside a Single Video Player

The following example parses the CompanionAds node, extracts an Iframe companion ad, and places it right next to a Single Video Player as a companion ad.

CompanionAds VAST Response

This example assumes that the CompanionAds XML node in the VAST response looks like this:

<CompanionAds>
     <Companion id="expanding_banner" width="468" height="60">
         <TrackingEvents>
            <Tracking event="start">
                <![CDATA[http://my.adserver.com/trackPoint=trackstart;]]>
            </Tracking>
         </TrackingEvents>
         <IFrameResource>
              <![CDATA[http://ad.server.com;ord=2135789343?]]>
         </IFrameResource>
         <CompanionClickThrough>
              <![CDATA[http://my.adserver.com/?clickThrough=banner468x60]]>
         </CompanionClickThrough> 
     </Companion>
</CompanionAds>

JavaScript

Here is the HTML and JavaScript, which includes the bcsyncroadblock method, the Video Cloud player publishing code for a Single Video Player, and an HTML <div> element to receive the companion ad:

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>VAST 2.0 Video Ad with external companion ad example</title>
        <script language="JavaScript" src="http://admin.brightcove.com/js/BrightcoveExperiences.js"></script>
        <script language="JavaScript" src="http://admin.brightcove.com/js/APIModules_all.js"></script>
        <script language="JavaScript"> 
    // This JS function is called by the Video Cloud Player when it encounters Companion Ads
    // in a VAST 2.0 response
    function bcsyncroadblock(adXML){
        var companionAds = getXMLDoc(adXML);
        //Get the Iframe snippet
        var companionAd = companionAds.getElementsByTagName('Companion')[0];
        var iFrameAd = companionAd.getElementsByTagName('IFrameResource')[0].firstChild.nodeValue;
        var companionAdDiv = document.getElementById("companionAd");

        // Add the IFrame to the page
        companionAdDiv.innerHTML = '<iframe src="' + iFrameAd + '"></iframe>';
     }

       // Loads adXML as XML.
       function getXMLDoc(pXML){
            var adXML;
            if (window.ActiveXObject){ //parses the XML for IE browsers
               adXML = new ActiveXObject("Microsoft.XMLDOM");
               adXML.async = false; adXML.loadXML(pXML);
            } else //parses the XML for Mozilla browsers
            if (window.XMLHttpRequest) {
                adXML = (new DOMParser()).parseFromString(pXML, "text/xml");
            }
            return adXML;
        }
    </script>
 
    <style type="text/css">
    // CSS is used to place the Ad right next to the player.
    #companionAd {
    position:absolute;
    top:120px;
    left:520px;
    width:300px;
    height:250px;
    border:dotted; }
    </style>
  </head>
<body>

<!-- Start of Brightcove Player -->

<p>VAST video ad with an external companion Ad.</p>
<div style="display:none"> </div>
<!-- By use of this code snippet, I agree to the Brightcove Publisher T and C
found at http://corp.brightcove.com/legal/terms_publisher.cfm. -->

<object id="myExperience" class="BrightcoveExperience">
<param name="bgcolor" value="#FFFFFF" />
<param name="width" value="486" />
<param name="height" value="412" />
<param name="playerID" value="yourPlayerID" />
<param name="@videoPlayer" value="yourVideoID" />
<param name="publisherID" value="yourPublisherID"/>
<param name="isVid" value="true" /> </object>
<!-- End of Brightcove Player -->
<div id='companionAd'> An Ad will display here</div>
<!-- End of Brightcove Player -->
</body>
</html>

Example 2. Play a collapsed and expanded banner with click-through alongside a Single Video Player

Collapsed and expanded banners are usually trafficked in combination with video ads in the Compact and Tabbed players. If they are trafficked to a Single Video Player, the banners in the VAST response are ignored. However, if you still want to access those banners to display them alongside the Single Video player as HTML banners, you can, by using also the bcsyncroadblock method. This example shows how to parse this kind of ad response and shows how to add the click-through URLs to the HTML banners. This example shows how to display the companion banners of a VAST Synched 728x90 banner trafficked to a single video player. Since the collapsed and expanded banner are not supported by the single video player, both are treated as external companion ads. All banners haver click through enabled as well.

CompanionAds VAST response

This example assumes that the CompanionAds portion of the VAST response looks like this:

<CompanionAds>
     <Companion id="banner" width="728" height="90" >
         <StaticResource creativeType="image/jpeg">
              <![CDATA[http://ads.example.com/banner_728x90.jpg]]>
         </StaticResource>
         <CompanionClickThrough>
             <![CDATA[http://track.example.com/?clickThrough=banner728x90_VAST_jpg]]>
         </CompanionClickThrough>
     </Companion>
     <Companion id="expanding_banner" width="0" height="0" expandedWidth="300" expandedHeight="250" >
        <StaticResource creativeType="application/x-shockwave-flash">
             <![CDATA[http://ads.example.com/expanded_300x250.swf]]>
        </StaticResource>
        <CompanionClickThrough>
             <![CDATA[http://track.example.com/?clickThrough=expandingBanner300x250]]>
        </CompanionClickThrough>
     </Companion>
</CompanionAds>

JavaScript

Here is the HTML and JavaScript, which includes the bcsyncroadblock method, the Video Cloud player publishing code for a Single Video Player, and two HTML <div> elements, one for the collapsed banner and the other for the expanded banner:

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <title>VAST 2.0 Video Ad with external companion Ad example</title>
        <script language="JavaScript" src="http://admin.brightcove.com/js/BrightcoveExperiences.js"></script>
        <script language="JavaScript" src="http://admin.brightcove.com/js/APIModules_all.js"></script>
        <script language="JavaScript"> 
    // This JS function is called by the Video Cloud Player when
    // it encounters Companion Ads in a VAST 2.0 response
    function bcsyncroadblock(adXML){
        var companionAds = getXMLDoc(adXML);
        //Get the Companion snippet
        var expandedBannerAd = companionAds.getElementsByTagName('Companion')[0];
        var collapsedBannerAd = companionAds.getElementsByTagName('Companion')[1];
        // Get the banner creative URL
        var expandedBannerAdSnippet = expandedBannerAd.getElementsByTagName('StaticResource')[0].firstChild.nodeValue;
        var collapsedBannerAdSnippet = collapsedBannerAd.getElementsByTagName('StaticResource')[0].firstChild.nodeValue;
        // Get clickthrough information for the banners from the StaticResource node
        var expandedBannerClickURL = expandedBannerAd.getElementsByTagName('CompanionClickThrough')[0].firstChild.nodeValue;
        var collapsedBannerClickURL = collapsedBannerAd.getElementsByTagName('CompanionClickThrough')[0].firstChild.nodeValue;
        
        // Display banners.
        var companionAdDiv = document.getElementById("companionBanner");
        
        // Add the expanded banner to the page
        companionAdDiv.innerHTML = "<a target='_blank' href='" + expandedBannerClickURL + "'> <img src='" +
        expandedBannerAdSnippet + "' border='0' /></a>";
        var collapsedAdDiv = document.getElementById("collapsedBanner");

        // Add the collapsed banner to the page
        collapsedAdDiv.innerHTML = "<a target='_blank' href='" + collapsedBannerClickURL + "'> <img src='" +
        collapsedBannerAdSnippet + "' border='0' /></a>";
    }

    // Loads adXML as XML.
    function getXMLDoc(pXML){
        var adXML; 
        if (window.ActiveXObject) {
        //parses the XML for IE browsers
        adXML = new ActiveXObject("Microsoft.XMLDOM");
        adXML.async = false; adXML.loadXML(pXML);
        } else //parses the XML for Mozilla browsers
        if (window.XMLHttpRequest) {
        adXML = (new DOMParser()).parseFromString(pXML, "text/xml"); }
        return adXML;
    }
  </script>
  <style type="text/css">
    #companionBanner {
    position:absolute;
    top:280px;
    left:520px;
    width:300px;
    height:250px;
    border:dotted;
    }
    #collapsedBanner {
    position:absolute;
    top:110px;
    left:40px;
    width:728px;
    height:90px;
    border:dotted;
    }
  </style>
</head>
<body>
    <!-- Start of Brightcove Player -->
    <p>VAST video ad with an external companion Ad. </p>
    <div style="display:none"> </div>
    <!-- By use of this code snippet, I agree to the
    Brightcove Publisher T and C found at http://corp.brightcove.com/legal/terms_publisher.cfm. -->
    <div id='bcplayer'>
    <object id="myExperience" class="BrightcoveExperience">
    <param name="bgcolor" value="#FFFFFF"/>
    <param name="width" value="486"/>
    <param name="height" value="412"/>
    <param name="playerID" value="yourPlayerID"/>
    <param name="@videoPlayer" value="yourVideoID"/>
    <param name="publisherID" value="yourPublisherID"/>
    <param name="isVid" value="true" />
    </object>
    </div>
    <!-- Companion Ads placeholders -->
    <div id='collapsedBanner'></div>
    <div id='companionBanner'></div>
    <!-- End of Brightcove Player -->
</body>
</html>

Many ad sources handle ad responses using their own software libraries, in which case Brightcove's bcsyncroadblock() function would not be triggered. For example, DFP IMA handles all HTML companions using the methods included in this article. In the event that bcsyncroadblock() is not triggered by your VAST ads, please contact your ad provider for details on companion handling with your given ad source.