Dynamic Ad Policies using the setAdPolicy API

This topic describes how to change a player's ad policy on the fly, using ActionScript.

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. For use of the Smart Player API version of setAdPolicy, which will work for both Flash and HTML players, see Using the Smart Player API setAdPolicy() Method

In Video Cloud 3.3, we added a new method to the Flash-only Player API's Advertising Module, setAdPolicy(), that allows you to alter the player's ad policy programmatically. You can read more about this API here.  With this new API, you can control many of the aspects of ad delivery for your Video Cloud players dynamically. For example, some of our publishers control the rate of ad delivery based on the user's video watching habits, based on the user's geography, or based on the length of the video the user has selected to view. If you have a one hour video, perhaps you want to deliver a mid-roll video ad every 15 minutes. However, if the video is only 15 minutes long, perhaps you want to deliver a mid-roll ad at 8 minutes. You can also set the Ad Server URL dynamically, so you could configure one player that requests ads from different ad servers or ad networks, depending on where it is published. If the player is published on your web domain, perhaps you request ads from your ad server but if the player is published virally on someone else's website, perhaps you want to request ads from an ad network.

This article shows how you can modify the player's ad policy depending on the ad format. For example, say you want to deliver both video ads and overlay ads in your player. You may want to run a pre-roll video ad every second video, and then run an overlay ad every video. You may also want to change how often you run the pre-roll ad, so that at first you run a pre-roll ad every 2 videos, but after the user watches 5 videos, you then want to run a pre-roll ad every 3 videos.

The sample code shows how to read a Player-level key/value pair (KVP) to look for "frequency=(some number)." That number is then used as a variable to determine how often a pre-roll video ad will be played. To spice things up a bit, every video is set to display a mid-roll overlay ad. So, for example, if "frequency=2", then a pre-roll video ad will be played every two videos, and every video will continue to play an overlay ad.

Setting up the ad insertion points

Before you begin, you will need to set up a couple things in Video Cloud Studio's Advertising module:

  1. Edit the player to enable ad insertion on player load and add a key/value pair like the following: "frequency=2" (use any number you want).
  2. Turn off all pre-roll, mid-roll, or post-roll ad insertion points in the player.
  3. Add a cue point shortly after the start (for example, 2 seconds into the video) for all the videos in the player's playlist. You can do this using the Advertising module or using the Media API.
  4. In the Publishing module, make sure to enable the ActionScript/JavaScript APIs for the player.

Code

You can download a zip file that includes the ActionScript code for this example. The following outlines the main parts of the code:

  1. Make global variables out of the Player and the Player API's  Ad, Video Player, and Experience Modules.
private var bcp:BrightcovePlayer = new BrightcovePlayer();
private var player:BrightcovePlayerWrapper;
private var adModule:Object;
private var videoPlayerModule:Object;
private var experienceModule:Object;
  1. Make a reference to the current ad policy of the player to get the KVP of the player. Do this by creating an Object named currentAdPolicy.
  2. Assign the current ad policy of the player to that object using the advertising module API:
    CurrentAdPolicy = adModule.getAdPolicy();
  3. Assign a new local variable to the player KVP of mCurrentAdPolicy.
  4. Store the index of the instance of the string "frequency" in the player KVP:
    index = playerAdKeys.indexOf("frequency");
  5. Store the index of the delimiter in the same way:
    indexOfDelimiter = playerAdKeys.indexOf(";", index + 8); 
    where semi-colon is the delimiter.  (You can change the delimiter to whatever character your particular ad server or ad translator uses.)
  6. Add a check to see if the frequency KVP is the only one in the player KVP.
  7. Parse the frequency KVP to get the number at the end and store it as a number:
    frequency = playerAdKeys.substring(index + 10, indexOfDelimiter) as Number;
  8. Once the template is ready, set the initial ad policy to be a pre-roll video ad and a mid-roll overlay ad.
  9. In the Media Change event, use a number variable to keep track of how many videos have played and then increment that number every time the video changes (either because the viewer watched the video to the end or by changing the video in the middle of playback).
  10. Divide the counter by the frequency in the player KVP. If it divides evenly, play the pre-roll video ad, then a mid-roll overlay. Otherwise, play an overlay ad: 
        if (videoCounter % frequency != 0){
                setOverlayAds();
            }
            else {
                setPreRollAds();
           }
  1. Create the setPreRollAds and setOverlayAds helper functions which set the ad policy.

Here's the complete example:

package {
  import com.brightcove.api.APIModules;
  import com.brightcove.api.BrightcovePlayerWrapper;
  import com.brightcove.api.events.ExperienceEvent;
  import com.brightcove.api.events.MediaEvent;
  import com.brightcove.api.modules.AdvertisingModule;
  import com.brightcove.api.modules.ExperienceModule;
  import com.brightcove.api.modules.VideoPlayerModule;
  import com.brightcove.bcplayer.BrightcovePlayer;
	
  import flash.display.Sprite;
  import flash.display.StageAlign;
  import flash.display.StageScaleMode;
  import flash.events.Event;
  /*
   * This class reads a KVP set in the Ad Module to know when to use a certain ad policy. 
   * So if "frequency=2" it will use the ad policy which has a video ad and an overlay; 
   * otherwise, just an overlay. This is accomplished using the Ad API setAdPolicy();
   */
  public class CustomAdPolicyPlayer extends Sprite
  {
  	private var bcp:BrightcovePlayer = new BrightcovePlayer();
	private var player:BrightcovePlayerWrapper;
	private var adModule:Object;
	private var videoPlayerModule:Object;
	private var experienceModule:Object;
	private var currentAdPolicy:Object;
	private var frequency:Number;
	private var videoCounter:Number;
		
        public function CustomAdPolicyPlayer()
	{
             stage.scaleMode = StageScaleMode.NO_SCALE;
             stage.align = StageAlign.TOP_LEFT;
             player = new BrightcovePlayerWrapper(bcp);
             addChild(player);
             player.addEventListener("templateLoaded", onTemplateLoaded);
             // set to -1 so the video counter does not start incrementing
             // until after the first video
             videoCounter = -1;
        }
		
        public function onTemplateLoaded(evt:Event):void {    
             // Get a reference to the Advertising API
             adModule = player.getModule(APIModules.ADVERTISING) as AdvertisingModule;
             // Get a reference to Video Player API
             videoPlayerModule = player.getModule(APIModules.VIDEO_PLAYER) as VideoPlayerModule;
             // Get a reference to Experience API
             experienceModule = player.getModule(APIModules.EXPERIENCE) as ExperienceModule;
             // add a listener for Media Complete Event
             videoPlayerModule.addEventListener(MediaEvent.COMPLETE, onMediaComplete);
             // add a listener to Media Change Event
             videoPlayerModule.addEventListener(MediaEvent.CHANGE, onMediaChange);
             // add a listener for Template Ready Event
             experienceModule.addEventListener(ExperienceEvent.TEMPLATE_READY, onTemplateReady);
                  
             // Get a reference to the player's current Ad Policy
             currentAdPolicy = adModule.getAdPolicy();
             var playerAdKeys:String;
             // reference to the current player Key Value Pairs
             playerAdKeys = currentAdPolicy.playerAdKeys;
             var index:Number;
             // store where the kvp starting with frequency begins
             index = playerAdKeys.indexOf("frequency");
             var indexOfDelimiter:Number;
             // get the index of the key value pair delimiter
             // you can change to whatever delimiter is relevant to your
             // ad translator/ad server 
             indexOfDelimiter = playerAdKeys.indexOf(";", index + 8);
                  
             if(indexOfDelimiter == -1){
                 indexOfDelimiter = playerAdKeys.length;
             }
             // get the number associated with the frequency KVP
             frequency = new Number(playerAdKeys.substring(index + 10, indexOfDelimiter));          
       }
       public function onTemplateReady(evt:Event):void {
            // initially setting the Ad Policy
            setPreRollAds();
       }
       public function onMediaComplete(evt:Event):void {
            // if the video is not evenly divisible by the frequency KVP just play overlay ads
            // else play a preroll video ad and then an overlay
            // this will do the comparison when a viewer watches the video all the way through
            if (videoCounter % frequency != 0){
        	setOverlayAds();
            }
            else {
        	setPreRollAds();
            }
       }
       public function onMediaChange(evt:Event):void {
            // increment the video counter every time the a new video is played
            videoCounter++;

            // if the video is not evenly divisble by the frequency KVP just play overlay ads
            // else play a preroll video ad and then an overlay
            // this will do the comparison when a viewer does not watch the video all the way through
            if (videoCounter % frequency != 0){
        	setOverlayAds();
            }
            else {
        	setPreRollAds();
        	 }    
            }
        
            public function setPreRollAds():void {
        	 var adPolicy:Object = new Object();
        	        	
        	 // set to whatever ad server you use
        	 // adPolicy.adServerURL = "your ad server";
        	 adPolicy.prerollAds = true;
        	 // make sure you have an ad cue point on your videos around a second or two
        	 adPolicy.midrollAds = true;
        	 // set a KVP which will serve a video ad
        	 adPolicy.prerollAdKeys = "formatOverride=0";
        	 // set a KVP which will serve an overlay ad
        	 adPolicy.midrollAdKeys = "formatOverride=1";
        	 adModule.setAdPolicy(adPolicy);
            }
        
            public function setOverlayAds():void {
                 var adPolicy:Object = new Object();        	
                   

// set to whatever ad server you use
// adPolicy.adServerURL = "your ad server";
adPolicy.prerollAds = true;
adPolicy.midrollAds = false;
// set a KVP which will serve an overlay
adPolicy.prerollAdKeys = "formatOverride=1";
adModule.setAdPolicy(adPolicy);
}
}
}

Post new comment

The content of this field is kept private and will not be shown publicly.
0

Comments