Packagecom.brightcove.api.modules
Classpublic class AdvertisingModule
InheritanceAdvertisingModule Inheritance APIModule Inheritance flash.events.EventDispatcher

API class for handling advertising features.



Public Properties
 PropertyDefined By
 Inheritedmodule : Object
[read-only] Returns the instance of the module that is wrapped by this instance.
APIModule
Public Methods
 MethodDefined By
  
AdvertisingModule(module:Object)
Constructor.
AdvertisingModule
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = true):void
[override] Adds a listener for an event.
APIModule
  
allowThirdPartyControl(pControl:Boolean):void
If true, disassociates the video player controls with the video player and allows for the listening to video control events to manipulate their own third party ad as they choose.
AdvertisingModule
  
This method is deprecated.
AdvertisingModule
  
enableAdFormats(... formats):void
Enables the player to send additional possible format IDs in ad requests.
AdvertisingModule
  
enableExternalAds(enable:Boolean = true):void
Enables the player to broadcast an event if an ad format is returned from the server that is not natively supported by the player.
AdvertisingModule
  
enableOverrideAds(enable:Boolean = true):void
Prevents the player from making any ad calls to an external ad server.
AdvertisingModule
  
getAdPolicy():Object
Returns the properties of the current ad policy.
AdvertisingModule
  
Returns an Object that describes properties of the ad currently rendered in the player.
AdvertisingModule
  
Gets the URL of the currently loaded Ad Rules SWF.
AdvertisingModule
  
Gets the URL of the currently loaded Ad Translator SWF.
AdvertisingModule
  
Returns an array of format IDs supported by the player.
AdvertisingModule
  
Returns whether the external ads flag is enabled in the player.
AdvertisingModule
  
Returns whether the override ads flag is enabled in the player.
AdvertisingModule
  
Returns whether or not the player controls are showing "Sponsor Message", indicating advertising mode.
AdvertisingModule
  
Returns whether or not player should stay in full screen mode when an external ad event is fired.
AdvertisingModule
  
Allows user to get the current 3rd party ad time in seconds.
AdvertisingModule
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
[override] Removes a listener for an event.
APIModule
  
requestAd(cuePointKVP:String, queueRequest:Boolean = false):void
Requests an ad using the currently loaded ad translator.
AdvertisingModule
  
Informs the player that an external ad has completed playing.
AdvertisingModule
  
setAdPolicy(obj:Object):void
Allows some of the properties of the current ad policy to be set.
AdvertisingModule
  
setAdRules(swfURL:String):void
Sets the Ad Rules SWF by URL or by the name of a specified preloaded class.
AdvertisingModule
  
setAdTranslator(swfURL:String):void
Sets the Ad Translator SWF by URL or by the name of a specified preloaded class.
AdvertisingModule
  
setStayInFullScreen(pStayInFullScreen:Boolean):void
Sets whether or not the player should stay in full screen mode when an external ad event is fired.
AdvertisingModule
  
setThirdPartyTime(pTime:Number):void
Allows user to set the time in the player controls directly.
AdvertisingModule
  
showAd(ad:Object = null):void
Renders an ad in the player in the format defined by the object passed to the method.
AdvertisingModule
  
showSponsorMessage(show:Boolean = true):void
Hides all controls except time controls and sets time controls to advertising mode, showing only "Sponsor Message" in the player controls.
AdvertisingModule
  
stopAd():void
Stops and ends the currently playing ad.
AdvertisingModule
Events
 Event Summary Defined By
  Dispatched when an ad finishes playing in the player.AdvertisingModule
  Dispatched when an ad pauses playing back in the video window.AdvertisingModule
  Dispatched after all post-roll ads have completed or immediately after a post-roll ad has been requested and no ad is returned.AdvertisingModule
  Dispatched as an ad plays back in the video window.AdvertisingModule
  Dispatched immediately after an ad has been received from the ad server.AdvertisingModule
  Dispatched when an ad resumes playback in the video window after being previously paused.AdvertisingModule
  Dispatched when the adRulesReady() method is called in an Ad Rules SWF.AdvertisingModule
  Dispatched when an ad starts initial playback in the video window.AdvertisingModule
  Dispatched when an ad insertion point is reached and either a) the developer has chosen to override all ad calls in the player by setting the override ads flag to true, or b) an unknown ad format has been returned from the ad server and the developer has set the external ads flag to true.AdvertisingModule
Public Constants
 ConstantDefined By
  DEFAULT_AD_TRANSLATOR : String = defaultAdTranslator
[static] Value returned from getCurrentAdTranslator() when default DFP translator is used.
AdvertisingModule
Constructor Detail
AdvertisingModule()Constructor
public function AdvertisingModule(module:Object)

Constructor.

Parameters
module:Object — module to wrap with this API class.
Method Detail
allowThirdPartyControl()method
public function allowThirdPartyControl(pControl:Boolean):void

If true, disassociates the video player controls with the video player and allows for the listening to video control events to manipulate their own third party ad as they choose. This method was added specifically to provide more flexibility when developing custom ad SWFs. The following changes occur when set to true: - sets the player controls into advertising mode (showing only "Sponsor Message," play/pause, volume and timestamp) - allows for the time to be set through setThirdPartyTime - prevents player controls from controlling video playback in the player when an ad display SWF is in use - allows user to listen to button events and volume control events in the ad display SWF to control their own video playback as they see fit To exit this advertising mode call allowThirdPartyControl(false)

Parameters

pControl:Boolean — Boolean specifying whether or not the player or a third party is controlling the native video/ad player.

disableForExternalAd()method 
public function disableForExternalAd():void

This method is deprecated. Use showSponsorMessage() or allowThirdPartyControl() instead. Disables user interaction within the player and removes the video controls from the video player. Useful for when a video ad is rendered over the player, outside of the player's controls. To return control to the player call resumeAfterExternalAd()

See also

enableAdFormats()method 
public function enableAdFormats(... formats):void

Enables the player to send additional possible format IDs in ad requests. By default, all video players support video ads and overlays. Other players, depending on their components, support additional formats such as synched banners and takeovers. The method takes a variable number of arguments, each of which should be an integer indicating the additional format to support. See Supported Ad Formats for a list of current supported formats.

Parameters

... formats — number of ad formats (as IDs) to enable in the experience.

enableExternalAds()method 
public function enableExternalAds(enable:Boolean = true):void

Enables the player to broadcast an event if an ad format is returned from the server that is not natively supported by the player. This allows for an external object to capture the event and render the ad, if necessary. The Brightcove recommendation is to call this method in the event handler for ExperienceEvent.TEMPLATE_LOADED. Usually, this handler is set up as onTemplateLoaded(event) if the Javascript code snippet is being used. If the player has autoStart set to true via either the Publishing Module, configuration parameters, or BEML then this method must be called in the event handler of ExperienceEvent.TEMPLATE_LOADED for override ads to work as expected. A more descriptive example of how to use External Ads can be found in the Development center. Using External Ad Calls

Parameters

enable:Boolean (default = true) — to enable the "externalAd" event so that it fires when the player receives an unsupported ad format.

See also

enableOverrideAds()method 
public function enableOverrideAds(enable:Boolean = true):void

Prevents the player from making any ad calls to an external ad server. Instead, when an ad is needed based on ad logic in the player, the "externalAd" event will fire and wait for an external object to determine the necessary ad to serve. The Brightcove recommendation is to call this method in the event handler for ExperienceEvent.TEMPLATE_LOADED. Usually, this handler is set up as onTemplateLoaded(event) if the Javascript code snippet is being used. If the player has autoStart set to true via either the Publishing Module, configuration parameters, or BEML then this method must be called in the event handler of ExperienceEvent.TEMPLATE_LOADED for override ads to work as expected. A more descriptive example of how to use override Ads can be found in the Development center. Using External Ad Calls

Parameters

enable:Boolean (default = true) — to enable the "externalAd" event so that it fires when the player requires an ad to be served.

See also

getAdPolicy()method 
public function getAdPolicy():Object

Returns the properties of the current ad policy.

Returns
Object — Returns an Object with the following properties: adServerURL, playAdOnLoad, prerollAds, midrollAds, postrollAds, playerAdKeys, onLoadAdKeys, prerollAdKeys, midrollAdKeys, postrollAdKeys, adPlayCap, titleBasedAdInterval, titleAdPlayInterval, timeBasedAdInterval, timeAdPlayInterval, titleAdPlayInterval, firstAdPlay, overrideAds, externalAds, additionalAdTargetingParams, adTranslationSWF

Example
This example calls getAdPolicy(), reads the flag that indicates if pre-rolls were set in a player, and reads the pre-roll ad keys ActionScript
         
         private var adModule:Object;
         private var player:BrightcovePlayer = new BrightcovePlayer();
         
         // called when template loads, we use this to store a reference to the player and modules
         
         private function onTemplateLoaded(event:Event):void {
             adModule = player.getModule("advertising");
         }
             
         private function getPreRollAdsInfo():void {
             var  adPolicy:Object = adModule.getAdPolicy();
             var  prerollAdsOn:Boolean = adPolicy.prerollAds;
             var  prerollAdKeys:String = adPolicy.prerollAdKeys;
         }
        
JavaScript
        
         var player;
         var adModule;
         
         // called when template loads, we use this to store a reference to the player and modules
         
         function onTemplateLoaded(pExperience) {
             player = brightcove.getExperience(pExperience);
             adModule = player.getModule(APIModules.ADVERTISING);
         }
             
         function getPreRollAdsInfo(){
                 
             var  adPolicy = adModule.getAdPolicy();
             var  prerollAdsOn= adPolicy.prerollAds;
             var  prerollAdKeys = adPolicy.prerollAdKeys;
         }
        
getCurrentAdProperties()method 
public function getCurrentAdProperties():Object

Returns an Object that describes properties of the ad currently rendered in the player. A good place to call this method is on the adStart event, but in general it can be called while an ad is being rendered.

All ad formats share the following properties:

In addition this method returns format-specific properties. For example: Ad formats with video ads: videoURL, videoClickURL. Ad formats with overlay ads: overlayURL, overlayClickURL. A more descriptive explanation of these ad objects can be found in the Brightcove advertising operations documentation. Ad Formats

For Overlay or Video Pods, a trackingStartURLs property might be included for the expanding and collapsed banners. These track start URLs are named expandedBannerTrackStartURLs and collapsedBannerTrackStartURLs respectevely. This is to differentiate them from the root level track URLs. The same applies for the expanding banner duration in Overlay Pods which is named expandingBannerDuration

Returns
Object — Object containing ad properties
getCurrentAdRules()method 
public function getCurrentAdRules():String

Gets the URL of the currently loaded Ad Rules SWF. This will be null if no Ad Rules SWF is currently set. Note that since setAdRules() functions asynchronously, calling getCurrentAdRules() immediately after setAdRules() may not return the URL just set.

Returns
String — The URL of the current Ad Rules SWF or null if no Ad Rules SWF is set.

See also

getCurrentAdTranslator()method 
public function getCurrentAdTranslator():String

Gets the URL of the currently loaded Ad Translator SWF. This will be null if an Ad Rules SWF SWF is in use since Ad Rules SWFs are responsible for setting the Ad Translator. The URL will be equal to the named constant DEFAULT_AD_TRANSLATOR if the default DFP Translator is used and no Ad Rules SWF is used. Note that since setAdTranslator() functions asynchronously, calling getAdTranslator() immediately after setAdTranslator() may not return the URL just set.

Returns
String — The URL of the Ad Translator SWF or null.

See also

getEnabledAdFormats()method 
public function getEnabledAdFormats():Array

Returns an array of format IDs supported by the player. See Supported Ad Formats in the Brightcove help docs for a list of current supported formats.

Returns
Array — An array of format IDs supported by the player.
getExternalAdsEnabled()method 
public function getExternalAdsEnabled():Boolean

Returns whether the external ads flag is enabled in the player. This flag enables the player to broadcast an "externalAd" event if an ad format is returned from the server that is not natively supported by the player.

Returns
Boolean — True if external ads are enabled.

See also

getOverrideAdsEnabled()method 
public function getOverrideAdsEnabled():Boolean

Returns whether the override ads flag is enabled in the player. The override ads flag prevents the player from making any ad calls to an external ad server and instead fires an "externalAd" event when an ad needs to be rendered.

Returns
Boolean — True if the override ads flag is enabled.

See also

getShowSponsorMessage()method 
public function getShowSponsorMessage():Boolean

Returns whether or not the player controls are showing "Sponsor Message", indicating advertising mode.

Returns
Boolean — True if "Sponsor Message" is currently showing in the player controls.

See also

getStayInFullScreen()method 
public function getStayInFullScreen():Boolean

Returns whether or not player should stay in full screen mode when an external ad event is fired.

Returns
Boolean

See also

getThirdPartyTime()method 
public function getThirdPartyTime():Number

Allows user to get the current 3rd party ad time in seconds. This should only be used when implementing custom ad solutions outside of the Brightcove player. allowThirdPartyControl must be called first in order to use this method, otherwise, '0' will be returned.

Returns
Number

See also

requestAd()method 
public function requestAd(cuePointKVP:String, queueRequest:Boolean = false):void

Requests an ad using the currently loaded ad translator. Use this method to request ads whenever you would like or in the case where you would like to override the default ad policy of the player. Note that ad requests do not happen by default if an ad is currently playing, but you can change this behavior by setting the queueAd parameter.

Parameters

cuePointKVP:String — A String of additional key-value pairs to send with this particular ad call.
 
queueRequest:Boolean (default = false) — A Boolean indicating whether to keep the ad request in a queue to retry later if an ad is currently playing. The default is false.

See also


Example
The following code requests an ad, appending the specified key-value pairs to the ad call. To request a midroll ad, call requestAd at any time during media playback.
         adModule.requestAd("key=value");
         
To simulate a preroll ad request, set up a handler for MediaEvent.BEGIN, as shown below, and call requestAd() in the handler. The ad should appear to play as if it is a preroll ad. If using the Brightcove default translator (ie:DFP), the actual ad call will contain a key-value pair that indicates the cue point is a midroll insertion and not a preroll. Feel free to add your own key-value pairs in requestAd() to indicate to your ad server that the ad trafficked should be a preroll ad.
         private function onTemplateReady(event:ExperienceEvent):void {
             videoPlayerModule.addEventListener(MediaEvent.BEGIN, onMediaBegin);
         }
         
         private function onMediaBegin(event:MediaEvent):void {
             advertisingModule.requestAd("adCuePoint=PREROLL");
         }
         
There's no easy way to simulate a postroll ad request using requestAd() but it can be done. To request a postroll ad, set up a handler for MediaEvent.BEGIN, as shown below, and then set up a handler for MediaEvent.PROGRESS there. In your MediaEvent.PROGRESS handler, request an ad once the media position and duration are the same value, rounding those values to ensure equality. Then, remove the MediaEvent.PROGRESS listener so that the request isn't made multiple times due to rounding the position value. When the next video begins, the MediaEvent.PROGRESS handler will be added back again, so that a postroll is called on the following video as well. Again, if using the Brightcove default translator (ie:DFP), the actual ad call will contain a key-value pair that indicates the cue point is a midroll insertion and not a postroll. Feel free to add your own key-value pairs in requestAd() to indicate to your ad server that the ad trafficked should be a postroll ad.
         private function onTemplateReady(event:ExperienceEvent):void {
             videoPlayerModule.addEventListener(MediaEvent.BEGIN, onMediaBegin);
         }
         
         private function onMediaBegin(event:MediaEvent):void {
             videoPlayerModule.addEventListener(MediaEvent.PROGRESS, onMediaProgress);
         }
         
         private function onMediaProgress(event:MediaEvent):void {
             var videoPosition:Number = Math.round(videoPlayerModule.getVideoPosition());
             var videoDuration:Number = Math.round(videoPlayerModule.getVideoDuration());
             if (videoPosition == videoDuration) {
                 advertisingModule.requestAd("adCuePoint=POSTROLL");
                 videoPlayerModule.removeEventListener(MediaEvent.PROGRESS, onMediaProgress);
             }
         }
         
resumeAfterExternalAd()method 
public function resumeAfterExternalAd():void

Informs the player that an external ad has completed playing. The player then resumes content playback. If you have called showAd() to play an ad, you do not need to call this method. showAd() gives control back to the player once the Ad completes.

See also

setAdPolicy()method 
public function setAdPolicy(obj:Object):void

Allows some of the properties of the current ad policy to be set. If a property isn't defined, then the current ad policy value is kept. See the code sample in the article, Dynamic Ad Policies using the setAdPolicy API.

Parameters

obj:Object — object containing any of the following properties: adServerURL, playerAdKeys, adPlayCap, onLoadAdKeys, prerollAdKeys, midrollAdKeys, postrollAdKeys, playAdOnLoad, prerollAds, midrollAds, postrollAds


Example
This example sets pre-rolls and the ad server URL using setAdPolicy() ActionScript
         private var adModule:Object;
         private var player:BrightcovePlayer = new BrightcovePlayer();
         
         // called when template loads, we use this to store a reference to the player and modules
         
         private function onTemplateLoaded(event:Event):void {
             adModule = player.getModule("advertising");
             setPreRollAds("http://someadserver.com/ads/adpserver/");
         }
             
         private function setPreRollAds(adServerURL:String):void {
             var adPolicy = new Object();
                 
             adPolicy.adServerURL = adServerURL;
             adPolicy.prerollAds = true;
             adPolicy.prerollAdKeys ="key=somevalue"
             adModule.setAdPolicy(adPolicy);
         }
        
JavaScript
         var player;
         var adModule;
         
         // called when template loads, we use this to store a reference to the player and modules
         
         function onTemplateLoaded(pExperience) {
             player= brightcove.getExperience(pExperience);
             adModule = player.getModule(APIModules.ADVERTISING);
             setPreRollAds("http://someadserver.com/ads/adpserver/");
         }
             
         function setPreRollAds(adServerURL){
                 
             var adPolicy = new Object();
                 
             adPolicy.adServerURL = adServerURL;
             adPolicy.prerollAds = true;
             adPolicy.prerollAdKeys ="key=somevalue"
             adModule.setAdPolicy(adPolicy);
         }
        

This example sets Pre-roll ads using setAdPolicy(), traces out the ad policy using getAdPolicy(), and traces out the current ad properties when the ad starts, using getCurrentAdProperties()

        package {
           import flash.display.Sprite;
           import flash.display.StageScaleMode;
           import flash.events.Event;
        
           public class BCPlayer extends Sprite{
        
              // BrihtcovePlayer is a class created with the
              // AS snippet from the Publishing Module       
              private var bcp:BrightcovePlayer = new BrightcovePlayer();
              private var adModule:Object;
              private var experienceModule:Object;
        
              public function BCPlayer(){
                  stage.scaleMode = StageScaleMode.NO_SCALE;
                  addChild(bcp);
                  bcp.addEventListener("templateLoaded", onTemplateLoaded);
              }
        
              private function onTemplateLoaded(evt:Event):void {
                 experienceModule = bcp.getModule("experience");
                 adModule = bcp.getModule("advertising");
                 // Set Pre-rolls after the player has loaded
                 setPreRollAds();
                 // Trace the new Ad Policy
                 displayAdPolicy();
                 // Add a listener to the adStart event
                 adModule.addEventListener("adStart",onAdStart);
               }
        
               // Display the current Ad Policy
               private function displayAdPolicy():void{
                   var newAdPolicy:Object = adModule.getAdPolicy();
                   trace(" Ad Policy");
                   for (var prop:String in newAdPolicy) {     
                       trace(prop + " = " + newAdPolicy[prop])
                   }
               }
        
               // Call after an Ad starts. Displays the ad
               // properties using the getCurrentAdProperties Ad API
               private function onAdStart(evt:Event):void{
                   var adObject:Object = adModule.getCurrentAdProperties();
                   trace("Current Ad");
                   for (var prop:String in adObject) {     
                        trace(prop + " = " + adObject[prop])
                   } 
               }
        
                // Sets Pre-Roll ads on runtime  
                private function setPreRollAds():void{
                   var adPolicy:Object = new Object();
                   adPolicy.adServerURL = "http://youradserver.com/ads/adserver";
                   adPolicy.playerAdKeys = "key=value";
                   adPolicy.prerollAds = true;
                   adModule.setAdPolicy(adPolicy);
                }
                   
           }
        }
        
setAdRules()method 
public function setAdRules(swfURL:String):void

Sets the Ad Rules SWF by URL or by the name of a specified preloaded class. This function returns immediately but the actual loading of the Ad Rules SWF is done asynchronously. Any insertion points that are hit during the loading of an Ad Rules SWF will be blocked until the Ad Rule SWF either finishes loading or fails to load. By setting an Ad Rules SWF the Ad Translator is reset to the default DFP Translator. If you wish to set an Ad Rules SWF and an Ad Translator, the Ad Translator can be set from within the Ad Rules SWF itself. Similarly, to unset the Ad Rules SWF, the Ad Translator can be set with setAdTranslator(). Use of setting the Ad Rules SWF by a preloaded class allows you to select any included class to act as the Ad Rules SWF.

Parameters

swfURL:String — The URL to use or the name of a preloaded class to act as the Ad Rules SWF to be used in the player.

See also


Example

This example stores away the current Ad Rules before assigning a new one

ActionScript
          
          private var adModule:Object;
          private var player:BrightcovePlayer = new BrightcovePlayer();
          private var oldAdRulesURL:String;
          
          // called when template loads, we use this to store a reference to the player and modules 
          private function onTemplateLoaded(event:Event):void {
              adModule = player.getModule("advertising");
          }
         
         //get the current Ad Rules URL so we can restore it later if we want
         oldAdRulesURL = adModule.getCurrentAdRules();
         //change the Ad Rules
         adModule.setAdRules("http://example.com/ad_rules.swf");     
         //Note that we could have also changed the Ad Rules by specifying the name of
         //a preloaded class. Ex:// adModule.setAdRules("myexamples.adrules.AdRulesExample"); 
         
         
JavaScript
         
          var player;
          var adModule;
          var oldAdRulesURL;
          
          // called when template loads, we use this to store a reference to the player and modules
          
          function onTemplateLoaded(pExperience) {
              player = brightcove.getExperience(pExperience);
              adModule = player.getModule(APIModules.ADVERTISING);
          }
              
         //get the current Ad Rules URL so we can restore it later if we want
         oldAdRulesURL = adModule.getCurrentAdRules();
         //change the Ad Rules
         adModule.setAdRules("http://example.com/ad_rules.swf");     
         //Note that we could have also changed the Ad Rules by specifying the name of
         //a preloaded class. Ex:// adModule.setAdRules("myexamples.adrules.AdRulesExample"); 
         
setAdTranslator()method 
public function setAdTranslator(swfURL:String):void

Sets the Ad Translator SWF by URL or by the name of a specified preloaded class. This function returns immediately but the actual loading of the Ad Translator SWF is done asynchronously. Any insertion points that are hit during the loading of an Ad Translator SWF will be blocked until the Ad Translator SWF either finishes loading or fails to load. By setting an Ad Translator SWF any Ad Rules SWF currently set is removed. If you wish to set an Ad Rules SWF and an Ad Translator SWF, you should use setAdRules() to load an Ad Rules SWF and the Ad Translator can be set from within the Ad Rules SWF itself. The default DFP translator can be set by passing in the named constant DEFAULT_AD_TRANSLATOR. Use of setting the Ad Translator by a preloaded class allows you to select any included class to act as the Ad Translator SWF.

Parameters

swfURL:String — The URL of the Ad Translator SWF to be used in the player.

See also


Example

This example stores away the current Ad Translator before assigning a new one

ActionScript
          
          private var adModule:Object;
          private var player:BrightcovePlayer = new BrightcovePlayer();
          private var oldAdTranslatorURL:String;
          
          // called when template loads, we use this to store a reference to the player and modules 
          private function onTemplateLoaded(event:Event):void {
              adModule = player.getModule("advertising");
          }
         
         //get the current Ad Translator URL so we can restore it later if we want
         oldAdTranslatorURL = adModule.getCurrentAdTranslator();
         //change the Ad Translator
         adModule.setAdTranslator("http://example.com/ad_translator.swf");     
         //Note that we could have also changed the Ad Translator by specifying the name of
         //a preloaded class. Ex:// adModule.setAdTranslator("myexamples.adtranslators.AdTranslatorExample");
           
         
JavaScript
         
          var player;
          var adModule;
          var oldAdTranslatorURL;
          
          // called when template loads, we use this to store a reference to the player and modules
          
          function onTemplateLoaded(pExperience) {
              player = brightcove.getExperience(pExperience);
              adModule = player.getModule(APIModules.ADVERTISING);
          }
              
         //get the current Ad Translator URL so we can restore it later if we want
         oldAdTranslatorURL = adModule.getCurrentAdTranslator();
         //change the Ad Translator
         adModule.setAdTranslator("http://example.com/ad_translator.swf");     
         //Note that we could have also changed the Ad Translator by specifying the name of
         //a preloaded class. Ex:// adModule.setAdTranslator("myexamples.adtranslators.AdTranslatorExample");  
                  
setStayInFullScreen()method 
public function setStayInFullScreen(pStayInFullScreen:Boolean):void

Sets whether or not the player should stay in full screen mode when an external ad event is fired. The default is for the player to always exit full screen (if the player is in full screen mode) when an external ad event is fired. If set to true, the player will remain in fullscreen mode while an ad is rendered either on the page or via showAd(). The default setting of 'false' is an effort to prevent customers from breaking IAB guidelines if they choose to render an ad unit that is not inside the video window (like a banner loaded in the Brightcove player, for example). When the player is in full screen mode, ad units like banners cannot be seen by users, which violates IAB guidelines. Brightcove recommends using setStayInFullScreen() only if the ad being rendered is a simple video ad.

Parameters

pStayInFullScreen:Boolean — specifying whether or not to stay in fullscreen. If true, the player will always stay in full screen while an external ad is rendered. The default value is false and, in that case, the player will always exit fullscreen mode when an external ad event is fired.

See also


Example
The following code ensures that the player will not exit full screen when the external ad event is fired.
        adModule.setStayInFullScreen(true); 
        adModule.addEventListener(BCAdvertisingEvent.EXTERNAL_AD, onExternalAd); 
        
setThirdPartyTime()method 
public function setThirdPartyTime(pTime:Number):void

Allows user to set the time in the player controls directly. This should only be used when implementing custom ad solutions outside of the Brightcove player. allowThirdPartyControl must be called first in order to use this method. This method should be called continuously as the ad progresses in order to update the visual timestamp. If you want the time to not show up, you can set this to Number.NaN.

Parameters

pTime:Number — current ad time in milliseconds.

See also


Example
The following example updates the player controls to show how much time is left in the current ad play. This assumes that your custom ad integration provides some way to detect your ad progress, total ad duration, and current ad position.
        
             // Assumes that MyAdProgressEvent has a totalDuration and a current position properties
             public function onAdProgress(pEvent:MyAdProgressEvent):void{
                // Displays a decreasing timer as the Ad progresses.
                advertisingModule.setThirdPartyTime(pEvent.totalDuration - pEvent.position);
             }
        
        
showAd()method 
public function showAd(ad:Object = null):void

Renders an ad in the player in the format defined by the object passed to the method. The ad format must be one recognized by the player for it to render, otherwise it will be ignored.

Parameters

ad:Object (default = null) — object containing properties that match the rich media ad templates accepted by the player. A more descriptive explanation of these ad objects can be found in the Brightcove advertising operations documentation (Ad Formats documentation). This object can also be of type XML (if using Actionscript) or a string xml representation, if passing xml directly is the preferred method.

For Overlay or Video Pods, if you need to send the trackingStartURLs property for the expanding and collapsed banners, you need to use expandedBannerTrackStartURLs and collapsedBannerTrackStartURLs respectively. This is to differentiate them from the root level track URLs. The same applies for the expanding banner duration in Overlay Pods which is named expandingBannerDuration.


Example
The following example plays a video ad via an object that contains the appropriate ad properties. ActionScript example:
        
           private function playVideoAd():void {
              var videoAd:Object = new Object();
              videoAd.type = "videoAd";
              videoAd.duration = "15";
              videoAd.trackStartURLs= ["http://start.com"];
              videoAd.trackMidURLs = ["http://mid.com","http://midurl.com"];
              videoAd.trackEndURLs = ["http://end.com"];
              videoAd.trackPointTime= "0";
              videoAd.videoClickURL= "http://en.wikipedia.org/wiki/Ginger_ale";
              videoAd.videoURL= "http://brightcove.vo.llnwd.net/o2/unsecured/ads/Hendersons_15fps.flv";
        
              adModule.showAd(videoAd);  
           }     
         
        
Javascript example:
              var videoAd = new Object();
              videoAd.type = "videoAd";
              videoAd.duration = "15";
              videoAd.trackStartURLs= ["http://start.com"];
              videoAd.trackMidURLs = ["http://mid.com","http://midurl.com"];
              videoAd.trackEndURLs = ["http://end.com"];
              videoAd.trackPointTime= "0";
              videoAd.videoClickURL= "http://en.wikipedia.org/wiki/Ginger_ale";
              videoAd.videoURL= "http://brightcove.vo.llnwd.net/o2/unsecured/ads/Hendersons_15fps.flv";
        
              adModule.showAd(videoAd);       
         
        
The following example plays a video ad via a string xml representation. Javascript example:
              var ad = "<videoAd trackPointTime='0' version='1' trackStartURLs='http://start.com' 
                        trackMidURLs='http://mid.com,http://yahoo.com' trackEndURLs='http://end.com' 
                        trackPointURLs='http://point.com' duration='15' houseAd='true'>
                        <videoURL>http://brightcove.vo.llnwd.net/o2/unsecured/ads/Hendersons_15fps.flv</videoURL>
                        <videoClickURL>http://en.wikipedia.org/wiki/Ginger_ale</videoClickURL></videoAd>";
        
              adModule.showAd(ad);
        
        
The following example plays a video ad via an Actionscript XML object. Actionscript example:
              var ad:XML = new XML( 
                              <videoAd trackPointTime='0' version='1' trackStartURLs='http://start.com' 
                                   trackMidURLs='http://mid.com,http://yahoo.com' trackEndURLs='http://end.com' 
                                   trackPointURLs='http://point.com' duration='15' houseAd='true'>
                                          <videoURL>http://brightcove.vo.llnwd.net/o2/unsecured/ads/Hendersons_15fps.flv</videoURL>
                                          <videoClickURL>http://en.wikipedia.org/wiki/Ginger_ale</videoClickURL>
                              </videoAd>
                           );
        
              adModule.showAd(ad as Object);
        
        
showSponsorMessage()method 
public function showSponsorMessage(show:Boolean = true):void

Hides all controls except time controls and sets time controls to advertising mode, showing only "Sponsor Message" in the player controls.

Parameters

show:Boolean (default = true) — or not to set controls to only show "Sponsor Message."

See also

stopAd()method 
public function stopAd():void

Stops and ends the currently playing ad. If video content was previously playing and the ad is linear, the content will be resumed when the ad ends. Otherwise, content play is not affected. If multiple ads are set to play consecutively, the next ad in the block will immediately render upon the current ad completion (after stopAd() is called).


Example
ActionScript
                  adModule = player.getModule("advertising");
         adModule.stopAd();
                  
JavaScript
                   adModule = player.getModule(APIModules.ADVERTISING);
          adModule.stopAd();
                  
Event Detail
adComplete Event
Event Object Type: com.brightcove.api.events.AdEvent
AdEvent.type property = com.brightcove.api.events.AdEvent.AD_COMPLETE

Dispatched when an ad finishes playing in the player.

The AdEvent.AD_COMPLETE constant defines the value of the type property of the event object for an adComplete event. This indicates when an ad completes.
adPause Event  
Event Object Type: com.brightcove.api.events.AdEvent
AdEvent.type property = com.brightcove.api.events.AdEvent.AD_PAUSE

Dispatched when an ad pauses playing back in the video window.

The AdEvent.AD_PAUSE constant defines the value of the type property of the event object for an adPause event. This indicates when a linear ad pauses. Linear ads include video ads and certain ad SWFs.
adPostRollsComplete Event  
Event Object Type: com.brightcove.api.events.AdEvent
AdEvent.type property = com.brightcove.api.events.AdEvent.AD_POSTROLLS_COMPLETE

Dispatched after all post-roll ads have completed or immediately after a post-roll ad has been requested and no ad is returned. It also fires when the media completes if no post-rolls are enabled.

The AdEvent.AD_POSTROLLS_COMPLETE constant defines the value of the type property of the event object for an adPostRollsComplete event. This event is fired after all post-roll ads have completed or immediately after a post-roll ad has been requested and no ad is returned. It also fires when the media completes if no post-rolls are enabled.
adProgress Event  
Event Object Type: com.brightcove.api.events.AdEvent
AdEvent.type property = com.brightcove.api.events.AdEvent.AD_PROGRESS

Dispatched as an ad plays back in the video window. This event can be used to display progress or a countdown to the viewer.

The AdEvent.AD_PROGRESS constant defines the value of the type property of the event object for an adProgress event. This indicates the progress of a linear ad. The position information can also be found through methods in the video module. Linear ads include video ads and certain ad SWFs.
adReceived Event  
Event Object Type: com.brightcove.api.events.AdEvent
AdEvent.type property = com.brightcove.api.events.AdEvent.AD_RECEIVED

Dispatched immediately after an ad has been received from the ad server. This event fires before ad start.

The AdEvent.AD_RECEIVED constant defines the value of the type property of the event object for an adReceived event. This indicates when an ad has been received. This event has a property named ad, the value of which is a string containing the original ad XML sent by the ad source. This ad XML can then be parsed to extract any of the XML nodes. This event fires before ad start.
adResume Event  
Event Object Type: com.brightcove.api.events.AdEvent
AdEvent.type property = com.brightcove.api.events.AdEvent.AD_RESUME

Dispatched when an ad resumes playback in the video window after being previously paused.

The AdEvent.AD_RESUME constant defines the value of the type property of the event object for an adResume event. This indicates when a linear ad resumes after a pause. Linear ads include video ads and certain ad SWFs.
adRulesReady Event  
Event Object Type: com.brightcove.api.events.AdEvent
AdEvent.type property = com.brightcove.api.events.AdEvent.AD_RULES_READY

Dispatched when the adRulesReady() method is called in an Ad Rules SWF. This event was used in the past to indicate when a video could be loaded but is not needed for that purpose anymore, as the player now handles the timing for video loading with ad rules SWFs.

The AdEvent.AD_RULES_READY constant defines the value of the type property of the event object for an adRulesReady event. This event is fired when the adRulesReady() method is called in an Ad Rules SWF. This event was used in the past to indicate when a video could be loaded but is not needed for that purpose anymore, as the player now handles the timing for video loading with ad rules SWFs.
adStart Event  
Event Object Type: com.brightcove.api.events.AdEvent
AdEvent.type property = com.brightcove.api.events.AdEvent.AD_START

Dispatched when an ad starts initial playback in the video window.

The AdEvent.AD_START constant defines the value of the type property of the event object for an adStart event. This indicates when an ad starts.
externalAd Event  
Event Object Type: com.brightcove.api.events.AdEvent
AdEvent.type property = com.brightcove.api.events.AdEvent.EXTERNAL_AD

Dispatched when an ad insertion point is reached and either a) the developer has chosen to override all ad calls in the player by setting the override ads flag to true, or b) an unknown ad format has been returned from the ad server and the developer has set the external ads flag to true.

The AdEvent.EXTERNAL_AD constant defines the value of the type property of the event object for an externalAd event. This fires when external ads are enabled and an external ad has been found.
Constant Detail
DEFAULT_AD_TRANSLATORConstant
public static const DEFAULT_AD_TRANSLATOR:String = defaultAdTranslator

Value returned from getCurrentAdTranslator() when default DFP translator is used. Also the value that can be used as an argument to the setAdTranslator() method.