Class: AdManagerController

AdManagerController

The ad manager controller main class. This class is registered as a module with the player.

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.
MUTE_STATE_CHANGED string Raised when the user changes the mute state during an ssai ad.
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

willRequireEmbedCodeMetadata()

Called when an ad manager plugin will require the provider for an embed code
Fires:
  • OO.EVENTS.event:WILL_REQUIRE_EMBED_CODE_METADATA

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.

notifyAdTimelineReceived(timeline)

Notifies the player a timeline of ads has been received. Used for SSAI ads.
Parameters:
Name Type Description
timeline array The list of objects containing the ad timeline.
Fires:
  • OO.EVENTS.event:SSAI_AD_TIMELINE_RECEIVED

notifySSAIAdPlaying(duration)

Notifies the player a when an SSAI ad break has started
Parameters:
Name Type Description
duration number The duration of the ad break
Fires:
  • OO.EVENTS.event:SSAI_PLAY_SINGLE_AD

notifySSAIAdPlayed()

Notifies the player a when an SSAI ad break has ended
Fires:
  • OO.EVENTS.event:SSAI_SINGLE_AD_PLAYED

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.