Ad Manager Controller Documentation Class: AdManagerController

AdManagerController(messageBus, id)

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

Parameters:

Name	Type	Description
`messageBus`	object	The player message bus.
`id`	string	The ID of the player module.

Properties:

Name	Type	Description
`adManagerSettings`	object	Ad settings used by the ad manager controller.
`playerSettings`	object	Ad settings specific to the player.
`backlotSettings`	object	Ad settings set in Backlot.
`pageSettings`	object	Ad settings set at the page level.
`ui`	object	The current instance of the `AdManagerControllerUi` class.
`platform`	object	The current instance of `AdManagerControllerPlatform` class.
`currentEmbedCode`	string	Code representing the current content video stream.
`movieMetadata`	object	Metadata for the content video stream.
`startTime`	number	The start position of the content video stream (seconds).
`movieDuration`	number	The duration of the content video stream (seconds).

Members

EVENTS

Events to which ad managers can subscribe. These events are not processed on the standard message bus.

Properties:

Name	Type	Description
`INITIAL_PLAY_REQUESTED`	string	Raised the first time playback is requested.
`REPLAY_REQUESTED`	string	Raised when a stream is replayed.
`PLAY_STARTED`	string	Raised when the content video first begins to play.
`PLAYHEAD_TIME_CHANGED`	string	Raised periodically during content playback, reporting the current position and duration.
`AD_PLAYHEAD_TIME_CHANGED`	string	Raised periodically during ad playback, reporting the current position and duration.
`PAUSE`	string	Raised when the content video is paused.
`RESUME`	string	Raised when the content video is resumed.
`CONTENT_COMPLETED`	string	Raised when the content video completes.
`CONTENT_AND_ADS_COMPLETED`	string	Raised when the content video and all ads have completed playing.
`SIZE_CHANGED`	string	Raised when the size of the player is changed.
`CONTENT_CHANGED`	string	Raised when the content video is changed.
`FULLSCREEN_CHANGED`	string	Raised when the player enters and exits fullscreen mode.
`VOLUME_CHANGED`	string	Raised when the user requests a change in video volume.
`AD_VOLUME_CHANGED`	string	Raised when the user requests a change in video volume against the `OO.VIDEO.ADS` element.
`MAIN_CONTENT_IN_FOCUS`	string	Raised when the main element has gained focus.
`VIDEO_TAG_FOUND`	string	Raised when an embedded tag has been found in the video stream.
`CONTENT_URL_CHANGED`	string	Raised when a url has been selected to stream from.
`NONLINEAR_AD_DISPLAYED`	string	Raised when the UI has successfully rendered the nonlinear ad.
`DEVICE_ID_SET`	string	Raised when the player generates a guid to identify the device or reads the stored guid from browser local storage. Reports the guid as the device id.

Example

var amc = new AdManagerController(mb, id);
amc.addPlayerListener(amc.EVENTS.INITIAL_PLAY_REQUESTED, callback);

ADTYPE

Defines possible ad types.

Properties:

Name	Type	Description
`LINEAR_OVERLAY`	string	The type name for an ad that is not a video but requires the main video be paused.
`NONLINEAR_OVERLAY`	string	The type name for an ad that is not a video and does not require the main video be paused.
`LINEAR_VIDEO`	string	The type name for an ad that is a video and requires the main video be paused.
`COMPANION`	string	The type name for an ad that is a companion ad.
`AD_REQUEST`	string	The type name for an ad request.
`UNKNOWN_AD_REQUEST`	string	The type name for an unknown ad request.

Example

var amc = new AdManagerController(mb, id);
var ad = new amc.Ad(position, duration, name, adObj, amc.ADTYPE.LINEAR_VIDEO);

AD_CANCEL_CODE

Defines ad cancellation codes.

Properties:

Name	Type	Description
`SKIPPED`	string	The ad was skipped by the user via the skip ad button
`TIMEOUT`	string	The ad timed out
`ERROR`	string	The ad threw an error
`STREAM_ENDED`	string	The main video stream ended

Methods

loadAdModule(adManager, path, callback)

Loads an ad module asynchronously from the network.

Parameters:

Name	Type	Description
`adManager`	string	The name of the ad manager making the request (`{adManager}.name`).
`path`	string	The network path to the remote ad module to load.
`callback`	function	Calls this function when the network request is complete with one parameter indicating success (`true`) or failure (`false`).

onAdManagerReady(True)

When one ad manager reports it is ready, the ad manager controller checks all of the registered managers to see if they are ready.

Parameters:

Name	Type	Description
`True`	boolean	to notify the player to create an MP4 ad video element, false otherwise

Fires:

OO.EVENTS.event:AMC_ALL_READY

reportPluginLoaded()

Called when a ad manager plugin has set itself to ready. The ad manager controller will then fire an OO.EVENTS.PLUGIN_LOADED evemt containing the plugin name and load time to see if they are ready.

Fires:

OO.EVENTS.event:PLUGIN_LOADED

removeAdManager(adManager)

Unregisters an ad manager. This is called when an ad manager fails to set up or become ready.

Parameters:

Name	Type	Description
`adManager`	string	The name of the ad manager.

Fires:

OO.EVENTS.event:AMC_ALL_READY

appendToTimeline(adManagerTimeline)

Adds ads to the controller's ad timeline. This function can be called at any time.

Parameters:

Name	Type	Description
`adManagerTimeline`	Array.<OO.AdManagerController#Ad>	An array of ads to add to the timeline. The ads are not required to be in time order.

showCompanion(companion)

Raises an event on the message bus to notify listeners that a companion ad is to be shown.

Parameters:

Name	Type	Description
`companion`	object	The companion ad to display.

Fires:

OO.EVENTS.event:WILL_SHOW_COMPANION_ADS

adManagerWillControlAds(adManagerName)

Blocks the AMC from bringing up the end screen until adManagerDoneControllingAds() is called.

Parameters:

Name	Type	Description
`adManagerName`	string	The name of the ad manager.

forceAdToPlay(adManager, ad, adType, streams, duration)

Forces an ad to play immediately, bypassing the timeline.

Parameters:

Name	Type	Description
`adManager`	object	The name of the ad manager that will play the ad.
`ad`	object	An object containing all the optional parameters for the ad.
`adType`	ADTYPE	The type of ad you are trying to force.
`streams`	object	Object containing the ad video stream types.
`duration`	number	The duration of the ad.

adManagerDoneControllingAds(adManagerName)

Unblocks the ad manager controller so it can bring up the end screen.

Parameters:

Name	Type	Description
`adManagerName`	string	The name of the ad manager.

getCurrentPlayhead() → {number}

Function to return the value of current playhead.

Returns:

The current playhead represented in seconds.

Type: number

getAdManagerLoadTimeout() → {number}

Getter for AD_MANAGER_LOAD_TIMEOUT.

Returns:

The timeout constant.

Type: number

getAdLoadTimeout() → {number}

Getter for AD_LOAD_TIMEOUT.

Returns:

The timeout constant.

Type: number

isLastAdPlayed() → {boolean}

Determines whether the last ad in the timeline is marked as played.

Returns:

true if the last ad in the timeline is marked as played, false otherwise.

Type: boolean

sendURLToLoadAndPlayNonLinearAd(ad, adId, url)

Dispatches a WILL_PLAY_NONLINEAR_AD event with the nonLinear ad URL.

Parameters:

Name	Type	Description
`ad`	object	Contains the ad details.
`adId`	string	Contains the unique ID that the AMC provides to the ad.
`url`	string	The URL for the overlay image.

Fires:

OO.EVENTS.event:WILL_PLAY_NONLINEAR_AD

showSkipVideoAdButton(allowButton, offset)

Sets the flag allowSkipButtonToBeShow to True or false, called by the ad managers. NOTE: It is important to call this function before starting to play the ad, so that the flag is set when the play head updates.

Parameters:

Name	Type	Description
`allowButton`	boolean	If set to `true`, then the skip button will be displayed, provided the page level parameter is also set. If set to `false`, the button will be prevented from displaying, even if the page level parameter is set to `true`.
`offset`	string	Optional parameter which includes a time offset value in seconds which must be met before skip button is shown. If a percent ('%') is suffixed, will be treated as a percentage of duration rather than seconds. Will only be accepted if allowButton is valid.

updateMainStreamUrl(newUrl)

Update the url of the main stream content being played.

Parameters:

Name	Type	Description
`newUrl`	string	The new url to be used.

Fires:

OO.EVENTS.event:VC_UPDATE_ELEMENT_STREAM

playAd(ad)

Triggers playback of an ad.

Parameters:

Name	Type	Description
`ad`	object	From `this.Ad`, the object representing the ad.

Fires:

OO.EVENTS.event:AD_POD_STARTED
OO.EVENTS.event:WILL_PLAY_SINGLE_AD
OO.EVENTS.event:WILL_PLAY_NONLINEAR_AD

focusAdVideo()

Tells the ui class to transition to the ad video element.

notifyPodStarted(adId, numberOfAds)

Notifies the player that an ad or a set of podded ads has begun. This cancels any ad timeouts.

Parameters:

Name	Type	Description
`adId`	string	The ID of the ad (`Ad.id`).
`numberOfAds`	number	The number of ads in the pod or set.

Fires:

OO.EVENTS.event:AD_POD_STARTED

notifyPodEnded(adId)

Notifies the player that an ad or a set of podded ads has ended.

Parameters:

Name	Type	Description
`adId`	string	The ID of the ad (`Ad.id`).

Fires:

OO.EVENTS.event:AD_POD_ENDED

notifyNonlinearAdStarted(adId)

Notifies the player that a nonlinear ad has begun. This cancels any ad timeouts.

Parameters:

Name	Type	Description
`adId`	string	The ID of the ad (`Ad.id`).

notifyNonlinearAdEnded(adId)

Notifies the player that a nonlinear ad has ended.

Parameters:

Name	Type	Description
`adId`	string	The ID of the ad (`Ad.id`).

Fires:

OO.EVENTS.event:NONLINEAR_AD_PLAYED

notifyLinearAdStarted(adId, properties)

Notifies the player that a single linear ad has started. The ad may be within a pod of ads.

Parameters:

Name	Type	Description
`adId`	string	The id of the AMC ad recieved from playad()
`properties`	object	Properties of the ad. This is an object containing `name` (string), `duration` (seconds), `clickUrl` (string), `indexInPod` (number indicating the position among podded ads (1 for first ad, 2 for second, etc), `skippable` (boolean).

Fires:

OO.EVENTS.event:WILL_PLAY_SINGLE_AD

notifyLinearAdEnded(adId)

Notifies the player that a single linear ad has ended. The ad may be within a pod of ads.

Parameters:

Name	Type	Description
`adId`	string	The ID of the ad (`Ad.id`).

Fires:

OO.EVENTS.event:SINGLE_AD_PLAYED

hidePlayerUi(showAdControls, showAdMarquee)

Requests the player to hide its UI. Used by Ad Managers that handle their own UI.

Parameters:

Name	Type	Description
`showAdControls`	boolean	override to show the ad controls
`showAdMarquee`	boolean	override to show the ad marquee

Fires:

OO.EVENTS.event:SHOW_AD_MARQUEE

showNonlinearAdCloseButton()

Requests the player to show the nonlinear ad close button.

Fires:

OO.EVENTS.event:SHOW_NONLINEAR_AD_CLOSE_BUTTON)

addPlayerListener(eventName, callback)

Adds listeners on events in AdManagerController.EVENTS that are triggered by this class.

Parameters:

Name	Type	Description
`eventName`	string	The name of the event for which this callback is called.
`callback`	function	The listener callback function.

removePlayerListener(eventName, callback)

Removes listeners on events in AdManagerController.EVENTS that are triggered by this class.

Parameters:

Name	Type	Description
`eventName`	string	The name of the event for which this callback is called.
`callback`	function	The listener callback function.

adsClicked(prop)

When an ad is clicked:

If the ad is playing and if possible, pause the ad and show controls.
If the ad was paused, resume it and hide controls if necessary. However if SETTINGS.ALLOW_AD_CLICK_THROUGH_ON_VIDEO is set to false (default is true) then we want to ignore the click if it comes from the video window.

Parameters:

Name	Type	Description
`prop`	object	The argument from the event that contains an object having the source from which the button was clicked.

adsClickthroughOpened()

Called when an ad's clickthrough URL is opened. Currently, it is called by each individual ad manager, because clickthroughs behave differently across the different ad managers (Google IMA, FreeWheel, VAST).

Fires:

OO.EVENTS.event:ADS_CLICKTHROUGH_OPENED

onSkipAd()

When the ad is closed with the X button, cancel the ad.

onNonlinearAdDisplayed(eventname)

Callback triggered when the UI successfully displays the nonlinear ad.

Parameters:

Name	Type	Description
`eventname`	string	The name of the event for which this callback is called.

getRegisteredAdManagers() → {Array.<Object>}

Returns a list of all registered ad managers. This can be used in testing.

Returns:

A list of all registered ad managers.

Type: Array.<Object>

unregisterAdManager(name)

Unregisters an ad manager.

Parameters:

Name	Type	Description
`name`	string	The name of the ad manager to unregister, traditionally represented by `adManager.name`.