VAST and VPAID Plugin API Reference Class: Vast

Vast()

Initialize an instance of the current class using the new keyword along with this constructor.

Properties:

Name	Type	Description
`name`	string	Name of the vast manager, must match what is sent from Backlot and used at the page level
`amc`	object	An internal reference to the Ad Manager Framework
`testMode`	boolean	If enabled, it will put the ad manager in test mode causing certain functions to not load
`ADTYPE`	string	Which ad manger the ad belongs to. This should match the this.name of the ad manager, but doesn't have to.
`ready`	boolean	Used to communicate with the ad manger controller if the manager is ready to go. Default is false and if the ad manager controller sees it as false after initialization then it will destroy the manager.
`currentDepth`	number	Keeps track of how many layers the Ad is wrapped in and sets off a warning if the maximum is reached
`loaded`	boolean	Set to true once the ad has been loaded successfully
`embedCode`	string	Keeps track of the embed code of the movie that is currently playing
`loaderId`	string	Unique id name for the loader, which is required by the API
`lastOverlayAd`	object	Contains the ad information for the overlay that was displayed before it was removed. This is used so we know what to add back to the screen after the video ad is done and the main video hasn't ended.
`adTrackingInfo`	object	The object that holds each individual ad id's tracking urls (including error reporting).
`VAST_AD_CONTAINER`	string	Constant used to keep track of the Vast Ad container div/layer that is used to show the ads
`currentAdBeingLoaded`	object	Stores the ad data of the ad that is currently being loaded
`wrapperParentId`	string	Used to keep track of ad's wrapper parent ID
`ERROR_CODES`	object	Used to define the VAST 3.0 error codes

Methods

isValidVastXML(vastXML) → {boolean}

Helper function to verify that XML is valid

Parameters:

Name	Type	Description
`vastXML`	XMLDocument	Contains the vast ad data to be parsed

Returns:

Returns true if the xml is valid otherwise it returns false.

Type: boolean

isValidRootTagName(vastXML) → {boolean}

Helper function to verify XML has valid VAST root tag.

Parameters:

Name	Type	Description
`vastXML`	XMLDocument	Contains the vast ad data to be parsed

Returns:

Returns true if the root tag is valid otherwise it returns false.

Type: boolean

isValidVastVersion(vastXML) → {boolean}

Helper function to verify XML is a valid VAST version.

Parameters:

Name	Type	Description
`vastXML`	XMLDocument	Contains the vast ad data to be parsed

Returns:

Returns true if the VAST version is valid otherwise it returns false.

Type: boolean

getErrorTrackingInfo(vastXML, ads)

Helper function to grab error information. vastAdSingleParser already grabs error data while creating ad object, but some errors may occur before the object is created. Note: can only live in three places: directly under , , or elements. tags are also optional so they may not always exist.

Parameters:

Name	Type	Description
`vastXML`	XMLDocument	Contains the vast ad data to be parsed
`ads`	object	A jQuery object which contains the collection of ad elements found

checkNoAds(vastXML, ads) → {boolean}

This should be the first thing that happens in the parser function: check if the vast XML has no ads. If it does not have ads, track error urls

Parameters:

Name	Type	Description
`vastXML`	XMLDocument	Contains the vast ad data to be parsed
`ads`	object	A jQuery object which contains the collection of ad elements found

Returns:

true if there are no ads, false otherwise.

Type: boolean

initialize(amc)

Initialize the vast ad manager. For the Vast Ad Manager it will set the local variable for amc to the current ad manager controller passed into the function and add the event listeners to the amc controller that is needed to handle positioning of the overlay when controls are shown and hidden. It will also add event Listeners that are needed for when the user goes into full screen mode or comes out of it.

Parameters:

Name	Type	Description
`amc`	object	The current instance of the ad manager controller

initVpaidAd(width, height, viewMode, desiredBitrate, creativeData, environmentVars)

Initializes the ad by sending the data to the ad unit. We then wait until we receive AD_LOADED from the creative before proceeding with rendering.

Parameters:

Name	Type	Description
`width`	number	Width of the slot where the ad will be placed
`height`	number	Height of the slot where the ad will be placed
`viewMode`	string	Can be either `normal` or `fullscreen`
`desiredBitrate`	number	The bitrate for the ad
`creativeData`	object	Contains the aditional ad parameters for the ad
`environmentVars`	object	Contains the slot and videoSlot elements

registerUi()

Called by Ad Manager Controller. When this function is called, the ui has been setup and the values in amc.ui are ready to be used.

loadMetadata(pbMetadata, baseBacklotMetadata, movieMetadata)

The ad manger controller will call loadMetadata when the metadata has been loaded and ready to be parsed. Currently the vast ad manager will use the metadata to load any pre-rolls that are specified by the user.

Parameters:

Name	Type	Description
`pbMetadata`	object	Contains the page level and Backlot metadata of the specific Ad Manager
`baseBacklotMetadata`	object	Contains the Backlot base metadata
`movieMetadata`	object	Contains the movie metadata that is currently loaded

loadPreRolls[DEPRECATED]()

[DEPRECATED]Checks to see if the current metadata contains any ads that are pre-rolls and of type vast. If there are any then it will load the ads.

loadAllVastAds[DEPRECATED]()

[DEPRECATED]Checks the metadata for any remaining ads of type vast that are not pre-rolls. If it finds any then it will load them.

onAdPlayheadTimeChanged(eventname, playhead, duration)

Registered as a callback with the AMC, which gets called by the Ad Manager Controller when the the play head updates during ad playback.

Parameters:

Name	Type	Description
`eventname`	string	The name of the event for which this callback is called
`playhead`	number	Current video time (seconds)
`duration`	number	Duration of the current video (seconds)

initialPlay()

Registered as a callback with the AMC, which gets called by the Ad Manager Controller when the play button is hit or the video automatically plays the first time. Here it will try to load the rest of the vast ads at this point if there any. This function should only be used if you need to do something the first time the user hits play.

replay()

Registered as a callback with the AMC, which gets called by the Ad Manager Controller when the replay button is clicked. Here it will try to load the rest of the vast ads at this point if there any.

buildTimeline()

TODO: out of date This is required by the Ad Manager Controller but for Vast ads nothing is done here.

Returns:

The array of the new timeline to merge into the controller timeline but Vast Manager doesn't use this function since we add the Ads one by one, so we just return null so it is ignored by the AMC.

adVideoPlaying()

Called when the ad starts playback.

adVideoEnded()

When the ad is finished playing we need to call the AMC callback that was provided to let the AMC know that the ad is finished playing.

adVideoError(adWrapper, errorCode)

When the ad fails to play we need to call the AMC callback that was provided to let the AMC know that the ad is finished playing and we need to follow the process for cleaning up after an ad fails.

Parameters:

Name	Type	Description
`adWrapper`	object	The current Ad's metadata
`errorCode`	number	The error code associated with the VTC error

playAd(adWrapper)

The Ad Manager Controller will call this function when it finds an Ad to play. The type of Ad is checked to see if it is a non-linear or linear Ad. If it is linear then it will hide any overlays that are currently being displayed and add the video to the adVideoElement. It will also call the adStartedCallback for the linear Ad to inform the Ad Manager Controller that a video Ad started playing. Companion ads are checked for and listeners are added to know when the video ends. However, if the ad is a non-linear ad, then createOverlay is called.

Parameters:

Name	Type	Description
`adWrapper`	object	The current Ad's metadata

cancelAd(ad, params)

This is called by the Ad Manager Controller when it needs to cancel an Ad due to a timeout or skip button.

Parameters:

Name	Type	Description
`ad`	object	The Ad that needs to be cancelled
`params`	object	An object containing information about the cancellation code : The amc.AD_CANCEL_CODE for the cancellation

destroy(ad)

Called by the Ad Manager Controller when the module is unregistered, we need to remove any overlays that are visible.

Parameters:

Name	Type	Description
`ad`	object	Ad to cancel if it is not null

ajax(url, errorCallback, dataType, loadingAd, wrapperParentId)

Attempts to load the Ad after normalizing the url.

Parameters:

Name	Type	Description
`url`	string	The url that contains the Ad creative
`errorCallback`	function	callback in case there is an error in loading
`dataType`	string	Type of data, currently either "xml" if vast fails to load and "script" if it loads successfully.
`loadingAd`	object	The current Ad metadata that is being loaded
`wrapperParentId`	string	The current ad's "parent" ad id. Could be undefined if ad does not have parent/wrapper. We want to pass this in to the next vast response so the new ad knows who its parent is for tracking event purposes.

playerClicked(amcAd, showPage)

Opens a page based on the clickthrough url when the user click on the Ad.

Parameters:

Name	Type	Description
`amcAd`	object	Ad wrapper that is sent from the Ad Manager Controller that contains the data
`showPage`	boolean	If set to true then we show the page, if it is false then we don't show the page

pauseAd(amcAd)

Pauses the ad element.

Parameters:

Name	Type	Description
`amcAd`	object	The current ad data

resumeAd(amcAd)

Resume the ad element.

Parameters:

Name	Type	Description
`amcAd`	object	The current ad data

hideOverlay(currentAd)

When the Ad Manager Controller needs to hide the overlay it will call this function. We will store the current ad for reference. Vast ad doesn't need to do much other then save the reference.

Parameters:

Name	Type	Description
`currentAd`	object	In order to not lose reference to the overlay object that is currently being shown, it is stored in this object

showOverlay()

This function gets called by the Ad Manager Controller when an ad has completed playing. If the main video is finished playing and there was an overlay displayed before the post-roll then it needs to be cleared out of memory. If the main video hasn't finished playing and then it needs to be displayed agained but VAST doesn't need to do anything here.

cancelOverlay()

This function gets called by the Ad Manager Controller when an overlay has been canceled by clicking the close button.

openUrl(url) → {boolean}

Opens a new page pointing to the URL provided.

Parameters:

Name	Type	Description
`url`	string	The url that we need to open in a new page

Returns:

true, if the URL is valid. Returns false, if url is invalid.

Type: boolean

loadUrl(url)

Calls ajax to load the Ad via the url provided.

Parameters:

Name	Type	Description
`url`	string	The Ad creative url

onVastError()

If the Ad fails to load this callback is called.

trackError(code, currentAdId)

This method pings all the ad's error URLs with a specific error code if the error URL contains the macro, "[ERRORCODE]". If ad has a parent wrapper, then go up the chain and ping wrapper's error urls as well.

Parameters:

Name	Type	Description
`code`	number	Error code
`currentAdId`	boolean	Ad ID of current ad

pingURL(code, url)

Helper function to ping error URL. Replaces error macro if it exists.

Parameters:

Name	Type	Description
`code`	number	Error code
`url`	string	URL to ping

pingURL(code, urls)

Helper function to ping error URLs.

Parameters:

Name	Type	Description
`code`	number	Error code
`urls`	Array.<string>	URLs to ping

extractStreamForType(streams, type) → {string}

Extracts the creative based on the format type that is expected.

Parameters:

Name	Type	Description
`streams`	Array.<object>	The stream choices from the metadata
`type`	string	The type of video we want to use for the creative

Returns:

The creative url if it finds one, otherwise null.

Type: string

mergeVastAdResult(ad, wrapperAds)

Takes all the ad data that is in the inline xml and merges them all together into the ad object.

Parameters:

Name	Type	Description
`ad`	object	The ad object
`wrapperAds`	object	The object containing wrapper ads parameters

checkCompanionAds(adInfo)

Checks if there is any companion ads associated with the ad and if one is found, it will call the Ad Manager Controller to show it.

Parameters:

Name	Type	Description
`adInfo`	object	The Ad metadata

parser(vastXML, adLoaded) → {Array.<object>}

The xml needs to get parsed and and an array of ad objects is returned.

Parameters:

Name	Type	Description
`vastXML`	XMLDocument	The xml that contains the ad data
`adLoaded`	object	The ad loaded object and metadata

Returns:

An array containing the ad(s) if ads are found, otherwise it returns null.

Type: Array.<object>

parseAds(vastXML, adLoaded) → {Array.<object>}

Parses ad objects from the Vast XML.

Parameters:

Name	Type	Description
`vastXML`	xml	The xml that contains the ad data
`adLoaded`	object	The ad loaded object and metadata

Returns:

An array of ad objects

Type: Array.<object>

onResponse(wrapperParentId, adLoaded, xml)

When the ad tag url comes back with a response.

Parameters:

Name	Type	Description
`wrapperParentId`	string	The current ad's "parent" ad id. Could be undefined if ad does not have parent/wrapper. We want to pass this in to the next vast response so the new ad knows who its parent is for tracking event purposes.
`adLoaded`	object	The ad loaded object and metadata
`xml`	XMLDocument	The xml returned from loading the ad

onVastResponse(adLoaded, xml, wrapperParentIdArg)

When the vast Ad is loaded correctly it will call this callback. Here the data is parsed to see if it is a linear or nonLinear Ad. It will pull the tracking, impression, companion and clicking information. Then merge the results and send it to the correct handler based on if it is Linear or not.

Parameters:

Name	Type	Description
`adLoaded`	object	The ad loaded object and metadata
`xml`	XMLDocument	The xml returned from loading the ad
`wrapperParentIdArg`	string	Is the current ad's "parent" ad id. This argument would be set on an ajax call for a wrapper ad. This argument could also be undefined if ad did not have parent/wrapper.

onVMAPResponse(xml)

Handler for VMAP XML responses.

Parameters:

Name	Type	Description
`xml`	XMLDocument	The xml returned from loading the ad

getVpaidImpressions() → {array}

Get tracking events. This is only required for VPAID ads

Returns:

Array with impressions urls

Type: array

getVpaidTracking(parent) → {array}

Get tracking events. This is only required for VPAID ads

Parameters:

Name	Type	Description
`parent`	object	DOM Element to look for tracking events

Returns:

Array with tracking events and urls

Type: array

sendVpaidError()

Send error. This is only required for VPAID ads

sendVpaidImpressions()

Send impressions. This is only required for VPAID ads

sendVpaidTracking(type)

Send tracking events. This is only required for VPAID ads

Parameters:

Name	Type	Description
`type`	string	Event name to be send

sendVpaidClickTracking()

Send click tracking event. This is only required for VPAID ads

onAdVolumeChanged(eventname, volume)

Callback for Ad Manager Controller. Handles volume changes.

Parameters:

Name	Type	Description
`eventname`	string	The name of the event for which this callback is called
`volume`	number	The current volume level

resize(width, height, viewMode)

Resizes the ad slot. This is only required for VPAID ads

Parameters:

Name	Type	Description
`width`	integer	New width to resize to
`height`	integer	New height to resize to
`viewMode`	string	Can take values: fullscreen or normal