VAST 2.0 Survey Example: Working with the AD_RECEIVED event

Note: The steps outlined in this topic are for Flash based players and will not work in HTML5 players and may prevent HTML5 players from functioning.

Ads served under the Video Ad Serving Template (VAST) standard can include information not only about media ads but also about companion elements such as surveys that while not ads, could be linked to an advertising experience. While you have access to the ad properties of the current ad by calling the getCurrentAdProperties() method in the Advertising Module API, elements such as Survey in VAST are parsed out before the Brightcove Player plays an ad and are not available through this API. To get access to the original ad XML as returned by the ad server, you can use the AD_RECEIVED event available in the Player API (Advertising Module).

This example demonstrates how to use the AD_RECEIVED event to read a VAST 2.0 response and look for the Survey element as soon as the ad response is available. Then, it displays the survey when the user pauses the ad and removes it when the video ad playback is resumed. The VAST 2.0 XML used in this example does not contain a real script for a survey but instead a static image. We do that to simplify things. In a real VAST Survey ad, you should expect a URL to some JavaScript that adds an interactive survey to the HTML page.

The JavaScript jQuery library is used to parse the ad XML and extract the survey data (which in this simplified example is just the image location) and to add and remove the image of the survey to the HTML page. Pure JavaScript can also be used.

How the AD_RECEIVED event works

This event is fired immediately after the ad response is received from the ad server and happens before the AD_START event. In other words:

1. The ad response is received.
2. The AD_RECEIVED event is fired.
3. The Video Cloud player parses the ad response and extracts information about ads.
4. Then, the ad is played and the AD_START event is fired.

An event object is passed to the listener associated with the AD_RECEIVED event which has a property named ad. The value of this property is a string containing the original ad XML, which can then be parsed to extract any of the XML nodes.

Here is an example of adding a listener for this event and then reading the ad property.

// called when template loads, we use this to store a reference
// to the player and modules and add event listeners AD_RECEIVED

function onTemplateLoaded(experienceID) {

    // 'experienceID' is equivalent to the HTML object id (ie: "myExperience")
    player= brightcove.getExperience(experienceID);

    // Get a reference to the Ad Module API
    adModule = player.getModule(APIModules.ADVERTISING);

    // Add a callback function for the ad Received event
    adModule.addEventListener(BCAdvertisingEvent.AD_RECEIVED, onAdReceived);
    }
      
// Called when the ad server returns an ad XML.

function onAdReceived(evt) {       
   // evt.ad contains the entire ad XML as received from the ad server.
   // Create an XML doc with the ad XML sent by the ad server
   var vastAdXML = getXMLDoc(evt.ad);
   }

Working with the Survey

In a real world application, a survey is displayed when the user interacts with the video player and meets some conditions. In this example, we display the survey when the user pauses the video ad, and we hide it when the user resumes video ad playback. You can find the live example here. To see it working, play the video. The player has pre-roll ad requests set; in response to the ad request, it is loading the VAST 2.0 XML that you can find here. Once the video ad starts playing, click the player's pause button. You will see an image of a survey appearing to the right of the player. If that was a real world survey, you could click on the close button or respond to it. In this case, it is only a static image. To remove it, click the play button.

Below, we show the relevant code that listens for the AD_RECEIVED, the AD_PAUSE and the AD_START events to read the original VAST XML, display, and hide the survey, respectively. Once the AD_RECEIVED event is fired and the callback onAdReceived method is called, we store the survey URL (in this case, the image URL) in a JavaScript variable to be used when the ad is paused. You can download a zip file that includes the entire source code together with the VAST XML used in the example.

When the video ad is paused, the onAdPause method is called, which uses JavaScript to display the HTML <div> element where the image tag has been added and then display it. Then, when the video ad is resumed; the onAdResume method is called which hides the <div> containing the survey. Both methods use jQuery to animate showing and hiding the survey. But again, this can be done with pure JavaScript.

var player;
var adModule;
var adPolicy;

// The Survey content url.

var adSurveyContentURL;

// called when template loads, we use this to store a reference
// to the player and modules and add event listeners AD_RECEIVED

function onTemplateLoaded(experienceID) {
    // 'experienceID' is equivalent to the HTML object id (ie: "myExperience")
    player= brightcove.getExperience(experienceID);

    // Get a reference to the Ad Module API
    adModule = player.getModule(APIModules.ADVERTISING);

    // Add a callback function for the Ad Received. Ad Pause and Ad Start events
    adModule.addEventListener(BCAdvertisingEvent.AD_RECEIVED, onAdReceived);
    adModule.addEventListener(BCAdvertisingEvent.AD_PAUSE, onAdPause);
    adModule.addEventListener(BCAdvertisingEvent.AD_RESUME, onAdResume);   

}

// Called when the ad server returns an Ad XML.

function onAdReceived(evt) {
           
// In this specific example, evt.ad contains the entire ad XML
// as received from the ad server.

    // Create an XML doc with the ad XML sent by the ad server

    var domAdXML = getXMLDoc(evt.ad);
    var $domAdXML = $(domAdXML); 

    // Get the Survey content from the VAST Survey XML node.
    // find() is a method provide by jQuery.
    // In this example, it is a simple PNG image.
    // But usually these URL points to a JS script.  

    adSurveyContentURL = "<img src='"
        + $domAdXML.find('Survey').text()
        + "' />"       

    }
    // Show the Survey if the user pauses the video ad

    function onAdPause(evt){
       showSurvey();
    }

   // Hide the Survey when the video ad resumes playback

   function onAdResume(evt){
      hideSurvey();
   }

   // Show the survey. Uses a jQuery animation.

   function showSurvey(){        
      $("#surveyDiv").html(adSurveyContentURL).show(500);
   }

   // Hide the survey. Uses a jQuery animation.

   function hideSurvey() {
      $("#surveyDiv").html(adSurveyContentURL).hide(1000);        
   }

Using this example

If you want to set up this example using your own player, you can download a zip file that includes the source code, replace the player id, publisher id, and video id in the HTML file with the ones from your Video Cloud account, and deploy that HTML file to a web server.

You can download the VAST XML and save it to a web server, too. Then you can use its URL location as the ad server URL in the Video Cloud Studio Advertising module. Make sure to add a question mark at the end of the Ad Server URL so the Video Cloud player recognizes it as the URL of an ad server. For example, if you make the ad XML available at http://mysandbox.adserver.com/vastSurvey.xml, set the ad server URL in the Advertising module to: http://mysandbox.adserver.com/vastSurvey.xml?