VPAID APIs

This document lists all of the VPAID APIs.  They are marked as either supported or not supported by Video Cloud along with comments on the support or functionality. Both non-linear and linear VPAID APIs are supported. We plan to continue enhancing our VPAID API support. To learn more about the VPAID APIs, see the Introduction to VPAID or the VPAID specification.

• VPAID methods
• VPAID properties
• VPAID events

VPAID methods

function handshakeVersion(playerVPAIDVersion : String) : String;
The version string that is returned from this function should be "1.0".  If the player can not determine that the version string matches 1.0, the ad must be canceled.

function initAd(width : Number, height : Number, viewMode : String, desiredBitrate : Number, creativeData : String, environmentVars : String) : void;
The viewMode parameter is either "normal" or "fullscreen" and never "thumbnail".  The desiredBitrate parameter will always be -1.  The creativeData parameter contains the AdParameters.  The environmentVars parameter is always null.

function resizeAd(width : Number, height : Number, viewMode : String) : void;
The width and height parameters always match the maximum display area allotted for the ad in the current view mode.

function startAd() : void;
This function is called when the ad should start displaying. Make sure to dispatch event AdStarted to let the player know the ad has started.

function stopAd() : void;
This function is called when the ad should stop displaying or if it needs to be canceled. Make sure to dispatch event AdStopped to let the player know the ad has stopped displaying.

function pauseAd() : void;
This function is called to pause ad playback. Make sure to dispatch event AdPaused to let the player know the ad is currently paused.

function resume Ad() : void;
This function is called to resume ad playback following a call to pauseAd(). Make sure to dispatch event AdPlaying to let the player know the ad has resumed playing.

function expandAd() : void;

function collapseAd() : void;

VPAID properties

function get adLinear() : Boolean;
Both non-linear and linear ads are supported.

function get adExpanded() : Boolean;

function get adRemainingTime() : Number;
Returns how much time the ad has left for playback, in seconds.

function get adVolume() : Number;
Returns the current volume of the ad. The Number value returned should be between 0 and 1.

function set adVolume(value : Number) : void;
Sets the volume of the ad. The player will call this function if the user uses the volume control to set ad volume. The adVolume value passed be will between 0 and 1.

VPAID events

public static const AdLoaded : String = "AdLoaded";
Dispatching this event tells the player that the ad has finished loading anything needed for the ad and is ready for display.

public static const AdStarted : String = "AdStarted";
The player simply logs a message when the ad is started and doesn't do anything else with this event.

public static const AdStopped : String = "AdStopped";
Dispatching this event tells the player that the ad has stopped and can be removed.

public static const AdLinearChange : String = "AdLinearChange";
Both non-linear and linear ads are supported. 

public static const AdExpandedChange : String = "AdExpandedChange";

public static const AdRemainingTimeChange : String = "AdRemainingTimeChange";
Dispatching this event tells the player that the adRemainingTime is changing relative to the current duration of the ad. Only dispatch this event if the ad duration needs to expand or contract during ad play (for example, if the ad become interactive during rendering). If the ad duration doesn't change then do not send this event. For more information, see the VPAID documentation.

public static const AdVolumeChange : String = "AdVolumeChange";
Dispatching this event tells the player that the ad has changed its volume.

public static const AdImpression : String = "AdImpression";
This is an IAB-required event that must be fired.  For a non-linear ad, this impression should be fired once the creative is first displayed.

public static const AdVideoStart : String = "AdVideoStart";

public static const AdVideoFirstQuartile : String= "AdVideoFirstQuartile";

public static const AdVideoMidpoint : String = "AdVideoMidpoint";

public static const AdVideoThirdQuartile : String= "AdVideoThirdQuartile";

public static const AdVideoComplete : String = "AdVideoComplete";

public static const AdClickThru : String = "AdClickThru";
This is an IAB-required event that must be fired when the ad is clicked on by the user. The event has three parameters that can also be passed for event handling:

• "url" is a String that can be used to specify the click thru url;
• "id" is a String that can be used for tracking purposes;
• "playerHandles" is a Boolean. If true, the player will open a new browser window to the url. If false, the ad will handle the event.

public static const AdUserAcceptInvitation : String= "AdUserAcceptInvitation";

public static const AdUserMinimize : String = "AdUserMinimize";

public static const AdUserClose : String = "AdUserClose";

public static const AdPaused : String = "AdPaused";

public static const AdPlaying : String = "AdPlaying";

public static const AdLog : String = "AdLog";
Messages sent through AdLog go to the Brightcove Player Debugger (http://admin.brightcove.com/viewer/BrightcoveDebugger.html). Filter to "type: Advertising" to see only VPAID and advertising-related messaging.

public static const AdError : String = "AdError";
Dispatching this event tells the player that an error occurred with the ad. The error message is output in the Brightcove Player Debugger, just like AdLog messages, and the currently-playing ad is stopped.