The standard Brightcove ad formats are typically displayed within the layout of a Brightcove player. However, using the Brightcove external ad API, you can display ads outside in the player, anywhere in your web page. By using external ads, you can synchronize additional ad units with any Brightcove player, from embedded single video players to large multi-playlist players. The placement of external ads is handled by JavaScript or ActionScript code you write to communicate with the Brightcove player. This code is deployed and managed on your site as a page (JavaScript) or as a SWF (ActionScript). By using an integrated design and these APIs, you can create a seamless user experience.
If the player template you're using supports synchronized ad units within the player, you can choose to traffic these as usual, or use the real estate in the player for other design elements.
By default, when an ad response comes from an ad server back to a player, the player inspects the response to see if it is in the form of XML that matches a known supported ad format. If it does match, then the player displays the ad normally. If it does not match, and if external ads have been not been enabled, then the ad response is ignored. If, however, you have enabled external ads, then the ad response can be sent to an external ads function, which processes the ad and handles its display.
As a result, if you want to display an external ad, you need to make sure that the incoming ad doesn't match a supported ad format. You can do this as easily as using a different root element for the XML in the ad response. For example, if your external ad is a 468x60 banner, you could assign a root node like <BannerExternal468x60> to distinguish it from the <Banner468x60> format. Then, when an ad is returned with <BannerExternal468x60>, it will not be recognized as a supported ad format and it will be handled by the external ad function.
Your external ad function has complete control over what to do with the incoming external ad. It needs to parse the incoming XML, recognize the specified ad units, and render them at the appropriate places outside or within the player.
You can download a zip file that includes examples of how to implement external ads using JavaScript or ActionScript.
This topic includes the following sections:
The following steps discuss how to set up external ads in the abstract; see the specific JavaScript or ActionScript sections for more detailed instructions.
You can also prevent the player from making ad requests by setting the enableOverrideAds property to true. In this case, the player continues to determine when an ad should be requested based on its ad logic but instead of calling to an external server, it halts playback; instead of passing the ad formats to the external code, it passes the player context (for example, title and lineupId) and allows your code to serve ads accordingly. See Overriding player ad behavior for more information.
Important: If you are using JavaScript with your players, you must not only check Enable ActionScript/JavaScript APIs for the player in the Publishing module, but also add this line to your publishing code for the player:
<script src="http://admin.brightcove.com/js/APIModules_all.js"> </script>
To enable external ads using JavaScript in the page embedding the player, you set the external ad parameter to true by calling the enableExternalAds method of the Ad Module in the Player API and set a callback function for the External Ad event. When the player encounters an unknown format, it halts video playback and calls the callback function passing the ad XML it received. You pass control back to the player by calling the resumeAfterExternalAd() method of the Ad Module in the Player API. For example:
<script language="javascript">
var player;
var adModule;
// called when template loads, we use this to store a reference to
// the player and modules and add event listeners for external Ads
function onTemplateLoaded(experienceID) {
player= brightcove.getExperience(experienceID);
// Get a reference to the Ad Module API
adModule = player.getModule(APIModules.ADVERTISING);
//Enable External Ads
adModule.enableExternalAds(true);
// Set a callback function for the externalAd event
adModule.addEventListener(BCAdvertisingEvent.EXTERNAL_AD, onExternalAd);
// Set a callback function for the Ad Complete event
adModule.addEventListener(BCAdvertisingEvent.AD_COMPLETE, onAdComplete);
}
function onExternalAd(evt) {
/* perform whatever ad actions are necessary with adXML(i.e adModule.showAd(adXML) ),
when complete you can call resumeAfterExternalAd to pass control back to the
player. In this example, resumeAfterExternalAd is called onAdComplete */
}
function onAdComplete(evt) {
adModule.resumeAfterExternalAd();
}
</script>
For an example of how to implement external ads in JavaScript, download the Ad API examples zip file. The JavaScript example is in the directory external-ads-examples/enableExtAds.
Similar to JavaScript, you enable external ad calls in ActionScript by:
enableExternalAds method of the Ad Module API,externalAd event, andresumeAfterExternalAd() method.The player plays ads as it normally would, but when encounters an unknown ad format in the XML returned from the ad, the player halts video playback and fires the event externalAd. You pass control back to the player by calling the resumeAfterExternalAd() method of the Ad Module in the Player API. For example:
package {
// import Brightcove Player
import BrightcovePlayer;
import flash.display.Sprite;
import flash.events.Event;
public class SingleVideoPlayerExternalAds extends Sprite {
private var bcp:BrightcovePlayer = new BrightcovePlayer();
private var adModule:Object;
public function SingleVideoPlayerExternalAds() {
addChild(bcp);
bcp.addEventListener("templateLoaded", templateLoaded);
}
// call when the player has been loaded
public function templateLoaded(evt:Event):void {
// Get a reference to the Ad Module API
adModule = bcp.getModule("advertising");
// Enable External Ads
adModule.enableExternalAds(true);
// Set a callback function for the externalAd event
adModule.addEventListener("externalAd", onExternalAd);
}
public function onExternalAd(evt:Event):void {
/* perform whatever ad actions are necessary with adXML (i.e adModule.showAd(adXML) ),
when complete you can call resumeAfterExternalAd to pass control back to the player */
var adXML:XML = new XML (evt["ad"]);
trace(adXML);
adModule.resumeAfterExternalAd();
}
}
For an example of how to implement external ads in ActionScript, download the Ad API examples zip file. The ActionScript example is in the directory external-ads-examples/extAdsAS3.
The player fires events specific to ad handling to which you can subscribe. These events are identical for JavaScript and ActionScript.
| event | description |
|---|---|
| externalAd | Fired 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. |
| adStart | Fired when an ad starts initial playback in the video window. |
| adResume | Fired when an ad resumes playback in the video window after being previously paused. |
| adPause | Fired when an ad pauses playing back in the video window. |
| adProgress | Fired as an ad plays back in the video window. This event can be used to display progress or a countdown to the viewer. |
| adComplete | Fired when an ad finishes playing in the player. |
In JavaScript, you can use event constants instead of hardcoding event names:
BCAdvertisingEvent.AD_COMPLETE = "adComplete"; BCAdvertisingEvent.AD_PAUSE = "adPause"; BCAdvertisingEvent.AD_PROGRESS = "adProgress"; BCAdvertisingEvent.AD_RESUME = "adResume"; BCAdvertisingEvent.AD_START = "adStart"; BCAdvertisingEvent.EXTERNAL_AD = "externalAd";
In addition to the above functionality, you can also override player ad requests. The enabledOverrideAds method in both the JavaScript and ActionScript enables this functionality. When enabledOverrideAds is called, the player continues evaluating, based on its ad logic, where and how many ads are needed. However, when it determines an ad needs to be played, it does not call an external ad server; instead, it halts playback and performs the following:
The externalAd event is fired, but instead of sending the ad information received from the server, the function receives an XML object of the form:
<externalAd lineupId="0" titleId="17038"/>
Your JavaScript code then executes outside the context of the player. To pass control back to the player, call the resumeAfterExternalAd() method of the Ad Module in the Player API. For an example of how to play external Ads with override Ads setting, download the Ad API examples zip file. The JavaScript example is in the directory external-ads-examples/extAdsOverrideAds.
The externalAd event fires as in the first ActionScript example above, but instead of sending the ad info in the event object, the handler receives ad XML in the following form:
<externalAd lineupId="0" titleId="17038"/>
The ActionScript and shell SWF do what they needed to do outside of the context of the player and then return control to the player by calling the resumeAfterExternalAd() method of the Ad Module in the Player API. In addition, you can use the ActionScript API to play a Flash Video ad in the player by passing in a collection of properties that the player forms into the required XML:
adModule.showAd(adObject:Object);
Upon completion of the video ad, the player executes as it normally would after an ad completion (resume playing if it was playing prior to the ad, or fire the externalAd event again if another ad was needed according to the ad logic).
This section lists the formats of ad creatives supported by the player's showAd() method. Note that not all formats are available in all player templates.
In each ad format, there is a trackStartURLs property in which you can set the list of URLs to fire to track impressions. This attribute must be sent as an array and not a simple string. Otherwise, the tracking point won't be fired. For example:
objAd.trackStartURLs = ["http://tracking.com"];
or for multiple tracking URLs
objAd.trackStartURLs = ["http://tracking.com","http://tracking2.com" ];
and not:
objAd.trackStartURLs = "http://tracking.com";
| property | description |
|---|---|
| type:String | the ad format ("banner") |
| trackStartURLs:Array | the list of URLs to fire to track impressions when the banner is shown |
| bannerURL:String | the URL to the banner asset (JPG or SWF) |
| bannerClickURL:String | the URL to launch when the banner is clicked |
var ad =
{
type:"banner",
bannerURL:"http://www.site.com/ad.jpg",
bannerClickURL:"http://www.site.com",
trackStartURLs:["http://someTrackingServer"]
};
adModule.showAd(ad);
| property | description |
|---|---|
| type:String | the ad format ("videoAd") |
| trackStartURLs:Array | the list of URLs to fire to track impressions when the video starts playing |
| videoURL:String | the URL to the video asset (FLV or SWF) |
| videoClickURL:String | the URL to launch when the video is clicked |
| duration:Number | the length of the video ad in seconds |
var ad =
{
type:"videoAd",
videoURL:"http://www.site.com/ad.flv",
videoClickURL:"http://www.site.com",
trackStartURLs:["http://someTrackingServer"],
duration:10
};
adModule.showAd(ad);
| property | description |
|---|---|
| type:String | the ad format ("synchedBanner") |
| trackStartURLs:Array | the list of URLs to fire to track impressions when the video starts playing |
| videoURL:String | the URL to the video asset (FLV or SWF) |
| videoClickURL:String | the URL to launch when the video is clicked |
| collapsedBannerURL:String | the URL to the small banner asset (JPG or SWF) |
| expandedBannerURL:String | the URL to the large banner asset (JPG or SWF) |
| bannerClickURL:String | the URL to launch when either banner is clicked |
| duration:Number | the length of the video ad in seconds |
var ad =
{
type:"synchedBanner728x90",
videoURL:"http://www.site.com/ad.flv",
videoClickURL:"http://www.site.com",
bannerClickURL:"http://www.site.com",
collapsedBannerURL:"http://www.site.com/collapsedAd.jpg",
expandedBannerURL:"http://www.site.com/expandedAd.jpg",
trackStartURLs:["http://someTrackingServer"],
duration:10
};
adModule.showAd(ad);
| property | description |
|---|---|
| type:String | the ad format ("overlay") |
| trackStartURLs:Array | the list of URLs to fire to track impressions when the overlay starts playing |
| overlayURL:String | the URL to the overlay asset (SWF) |
| overlayClickURL:String | the URL to launch when the overlay is clicked |
| duration:Number | the length of the overlay ad in seconds |
var ad =
{
type:"overlay",
overlayURL:"http://www.site.com/ad.swf",
overlayClickURL:"http://www.site.com",
trackStartURLs:["http://someTrackingServer"],
duration:10
};
adModule.showAd(ad);
| property | description |
|---|---|
| type:String | the ad format ("SynchedOverlay468x60") |
| trackStartURLs:Array | the list of URLs to fire to track impressions when the video starts playing |
| overlayURL:String | the URL to the overlay asset (SWF) |
| overlayClickURL:String | the URL to launch when the overlay is clicked |
| collapsedBannerURL:String | the URL to the small banner asset (JPG or SWF) |
| expandedBannerURL:String | the URL to the large banner asset (JPG or SWF) |
| bannerClickURL:String | the URL to launch when either banner is clicked |
| duration:Number | the length of the video ad in seconds |
var ad =
{
type:"SynchedOverlay468x60",
overlayURL:"http://www.site.com/ad.swf",
overlayClickURL:"http://www.site.com",
bannerClickURL:"http://www.site.com",
collapsedBannerURL:"http://www.site.com/collapsedAd.jpg",
expandedBannerURL:"http://www.site.com/expandedAd.jpg",
trackStartURLs:["http://someTrackingServer"],
duration:10
};
adModule.showAd(ad);