Video Advertising Suite

Docs

Classes

PublisherAPI

Typedefs

AdBreak : Object

Definition of the upcoming ad slot.

EnvironmentVars : Object

Used for passing implementation-specific runtime variables.

Wrapper : Array

List of URLs that have been requested during a chain of ad server requests.

UniversalAdID : Object

A unique creative ID for the ad across multiple systems.

PublicAdSlot : Object

Collection of data that describes the current ad slot.

PublicAd : Object

Collection of data for the current running ad

AdInfo : Object

Collection of data that describes the current video ad.

AdError : Object

Description object of the most recent ad error or null.

Wrapper : Object

Description object of a AdTag request.

CompanionAd : Object

Secondary ads included in the VAST tag that accompany the video ad.

CompanionAdResource : Object

Definition of a secondary ad by type.

Extension : Object

Custom XML element that extends the video ad.

ClosedCaption : Object

Subtitle files for the current creative in different languages

AdVerification : Object

Object contains the executable and bootstrapping data required to run the measurement code for a single verification vendor.

PluginError : Object

Description object of the most recent error or null.

PublisherAPI

Kind: global class

new PublisherAPI(playerProxy, config)

Param Type Description
playerProxy Object extended from FacadeBase
config Object Global configuration

publisherAPI.ad ⇒ PublicAd

Returns information about the current ad, like companions, icons, verifications and more.

Kind: instance property of PublisherAPI
Returns: PublicAd - Represents static information about the current ad

publisherAPI.adSlot ⇒ PublicAdSlot

Returns information about the current ad-break, like times and more.

Kind: instance property of PublisherAPI
Returns: PublicAdSlot - Represents static information about the current ad-break

publisherAPI.error ⇒ PluginError

Requests details about the most recent error that has occurred on the smartclientcore.

Kind: instance property of PublisherAPI
Returns: PluginError - Description object of the most recent error or null.

publisherAPI.rawXML ⇒ XML

Returns all of the collected XML that has been collected for the whole slot

Kind: instance property of PublisherAPI
Returns: XML - XML as live parsable DOM representation, querySelector and similar work on this

publisherAPI.dispose() ⇒ void

Removes all event listeners.

Kind: instance method of PublisherAPI

publisherAPI.initAdSlot(adBreak, environmentVars) ⇒ Promise

Invokes a commercial break by requesting the specified ad setup from the ad server.

Kind: instance method of PublisherAPI
Returns: Promise - Resolves if loading the ad manifests has been completed

Param Type Description
adBreak AdBreak Configuration for the upcoming ad break.
environmentVars EnvironmentVars Defines environment conditions for the upcoming ad break

publisherAPI.startAdSlot()

Starts the ad break. The add-on responds by sending an ON_AD_SLOT_START event notifying the video player the ad break is going to start.

Kind: instance method of PublisherAPI

publisherAPI.stopAdSlot()

Stops a running ad break. The add-on responds by sending an ON_AD_SLOT_COMPLETE event notifying the video player it has closed and cleaned up ad resources. Also the content of the video player has been reset.

Kind: instance method of PublisherAPI

publisherAPI.skipAd() ⇒ void

Skips (stops) a running single ad The add-on responds by sending the ON_AD_SKIPPED event notifying the video player it has closed and cleaned up a single ad.

_Note: The add-on does proceed with the next ad. Canceling the whole ad break requires calling stopAdSlot() instead.

Kind: instance method of PublisherAPI

publisherAPI.resize(boundingRectangle, viewMode) ⇒ void

Following a resize of the video player, the video player calls resize() to allow the add-on to scale and reposition itself within the display area. The add-on responds by sending an ON_AD_SIZE_CHANGED event.

Kind: instance method of PublisherAPI

Param Type Description
boundingRectangle Rectangle The video content display as a Rectangle {width, height, top, left}
viewMode string Current viewing mode (normal, fullscreen, thumbnail, dynamic)

publisherAPI.clickThrough(playerHandles) ⇒ string

Following a click on the ad, the video player calls clickThrough() to allow the add-on to request the advertisers landing page and call the ClickThru tracking requests.

Kind: instance method of PublisherAPI
Returns: string - The landing page URL.

Param Type Default Description
playerHandles Boolean false Whether the player takes responsibility for opening the landing page URL. Defaulting to false if omitted.

publisherAPI.iconClickThrough(iconProgram, playerHandles) ⇒ string

Following a click on an Industry Icon ad, the video player calls iconClickThrough() to allow the add-on to request the advertisers landing page and call the ClickThru tracking requests.

Kind: instance method of PublisherAPI
Returns: string - The landing page URL.

Param Type Default Description
iconProgram string The program represented in the icon
playerHandles Boolean false Whether the player takes responsibility for opening the landing page URL. Defaulting to false if omitted.

publisherAPI.iconView(iconProgram) ⇒ void

The view tracking for icons is used to track when the icon creative is displayed.

Kind: instance method of PublisherAPI

Param Type Description
iconProgram string The program represented in the icon

publisherAPI.verificationNotExecuted(vendor, reason)

The player did not or was not able to execute the provided verification code.

Kind: instance method of PublisherAPI

Param Type Description
vendor string An identifier for the verification vendor.
reason number The reason code corresponding to the cause of the failure.

publisherAPI.companionView(companionId) ⇒ void

Requests the view trackers when a creative resource is displayed. The method should be called for each resource file of a Companion Ad.

Kind: instance method of PublisherAPI

Param Type Description
companionId string Value of the id attribute from the CompanionAd object.

publisherAPI.companionClickThrough(companionId, playerHandles) ⇒ string

Following a click on a Companion ad, the video player calls companionClickThrough() to allow the add-on to call the ClickThru tracking requests and request the advertisers landing page (most likely with StaticResource creative resource only).

Kind: instance method of PublisherAPI
Returns: string - The landing page URL.

Param Type Default Description
companionId string Value of the id attribute from the CompanionAd object.
playerHandles Boolean true Whether the player takes responsibility for opening the landing page URL. Defaulting to true since most companion creatives do handle clickthroughs by their own (HTMLResource, IFrameResource).

publisherAPI.pauseAd()

Pauses the current ad break. The add-on responds by sending the ON_AD_PAUSED event.

Kind: instance method of PublisherAPI

publisherAPI.resumeAd()

Resumes the current ad break. The add-on responds by sending the ON_AD_PLAYING event.

Kind: instance method of PublisherAPI

AdBreak : Object

Definition of the upcoming ad slot.

Kind: global typedef
Properties

Name Type Description
type string of the ad slot. See AdBreak.type Defaulting to linear.
tag string AdRequest URL
response string direct VAST XML
opener string
bumper string
closer string

EnvironmentVars : Object

Used for passing implementation-specific runtime variables.

Kind: global typedef
Properties

Name Type Description
desiredBitrate number Indicates the desired bitrate in kilobits per second (kbps). The player uses this information to select Mediafiles with an appropriate bitrate. Defaulting to null.
desiredMimeTypes [ 'Array' ].<string> Declaration of accepted media types. Defaulting to types that the browser eventually is able to play. Types must be compliant with the IANA Media Type standard
desiredVPAIDVendors [ 'Array' ].<string> Declaration of accepted VPAID vendors (whitelist). Each specified String has to represent an unique identifier that can be found within the creative media file URL, most likely the domain name. If omitted, the plugin tries to deliver VPAID creatives from each vendor.
deviceType string Can be either mobile, tablet, desktop or tv. Defaulting to null.
deviceScreenSize Dimension Maximum size we can achieve when entering fullscreen.
networkReachability string Can be either wan, wifi or unreachable. Defaulting to null.
macro Object as defined by the VAST 4.1 specification.
vastMacroValues Object See EnvironmentVars.macro.
prefetchBuffetAds boolean In order to replace invalid ads in a pod instantly at runtime, buffet ads from wrapper responses must be loaded up-front. prefetchBuffetAds determines whether stand-alone ads (buffet) will be loaded together with the pod of ads or not. Defaulting to false if omitted.
adContainer HTMLElement The element that should be used to deliver non-video creative files. Defaulting to null if omitted.

Wrapper : Array

List of URLs that have been requested during a chain of ad server requests.

Kind: global typedef

UniversalAdID : Object

A unique creative ID for the ad across multiple systems.

Kind: global typedef
Properties

Name Type Description
idRegistry string A string used to identify the URL for the registry website where the unique creative ID is cataloged. Defaulting to unknown.
idValue string A string identifying the unique creative identifier. Defaulting to unknown.

PublicAdSlot : Object

Collection of data that describes the current ad slot.

Kind: global typedef
Properties

Name Type Description
currentClip number Index of the current ad, regardless of its variant.
totalClips number Total number of ads within the current ad break, regardless of variants.
currentCommercial number Index of the current ad of variant COMMERCIAL. Defaulting to -1
totalCommercials number Total number of ads with variant COMMERCIAL within the current ad break
totalCommercialsDuration number Total duration of ads with variant COMMERCIAL within the current ad break
totalCommercialsCurrentTime number Current time of all ads with variant COMMERCIAL within the current ad break

PublicAd : Object

Collection of data for the current running ad

Kind: global typedef
Properties

Name Type Description
isExpanded boolean Indicates if the ad is currently in a expanded state
isInteractive boolean Returns whether the current ad is interactive (most likely by using VPAID) or * not.
isLinear boolean Indicates whether the ad’s current mode of operation is linear or non-linear.
isSkippable boolean If true, the ad can be skipped, based on AdTag skip delay and configurable skipp offset. Changes of the state can be monitored by listening on ON_AD_SKIPPABLE_STATE_CHANGE
skipOffset number Time in seconds when ad will become skippable based on playback progress. Will return -1 if ad won't become skippable.
hasClickThrough boolean Returns whether the current ad has a ClickThrough target (URL) or not.
width number Width of the ad in pixels, as given from AdTag
height number Height of the ad in pixels, as given from AdTag
currentTime number Current time of ad in seconds
remainingTime number Remaining time of ad in seconds
duration number Duration of current ad, given in seconds
volume number get and set volume of the current running ad
companions [ 'Array' ].<CompanionAd> The value of this property is an Array that provides ad companion details for each <Companion> element. The video player should request this value whenever it receives the ON_COMPANIONS_DETECTED event.
extensions [ 'Array' ].<Extension> The value of this property is an Array that provides ad extension details for the <Extensions> element. The video player should request this value whenever it receives the ON_EXTENSIONS_DETECTED add-on event.
icons [ 'Array' ].<Icon> The value of this property is an Object that provides ad icon details for the <Icon> element. The video player should request this value whenever it receives the ON_ICONS_DETECTED add-on event.
closedCaptions [ 'Array' ].<ClosedCaption> The value of this property is an Array of caption details for the <ClosedCaption> element. The video player should request this value whenever it receives the ON_CLOSED_CAPTIONS_DETECTED add-on event.
verifications [ 'Array' ].<AdVerification> The value of this property is an Array that provides details for each <Verification> element. The video player may request this value whenever it receives the ON_VERIFICATIONS_DETECTED add-on event, depending on whether the player takes care of the Open Measurement.
info [ 'Object' ].<AdInfo> Collection of data that describes the current video ad.
error [ 'Object' ].<AdError> Description object of the most recent ad error.
wrappers [ 'Array' ].<Wrapper> List of Wrapper objects, starting with the initial request up to the last requested tag URI.

AdInfo : Object

Collection of data that describes the current video ad.

Kind: global typedef
Properties

Name Type Description
adId string Value of the id attribute from the VAST > Ad node
title string Value of the VAST > Ad > AdTitle node
variant string Ad variant, depending on the current schedule and VAST manifest.
skippable Boolean The default value for this property is false. When the ad reaches a point where it can be skipped, the ad unit updates this property to true and sends the ON_AD_SKIPPABLE_STATE_CHANGE event. The video player can check this property at any time, but should always check it when the ON_AD_SKIPPABLE_STATE_CHANGE event is received.
duration number Total time of the current ad
currentTime number Current time of the current ad
universalAdID UniversalAdID A unique creative identifier that is maintained across different ad systems.

AdError : Object

Description object of the most recent ad error or null.

Kind: global typedef
Properties

Name Type Description
code number Code according to IAB VAST 4.0 Error Codes Table.
timestamp number Current client time Date.now()
description string A human-readable string which provides specific diagnostic information to help the reader understand the error condition which occurred.

Wrapper : Object

Description object of a AdTag request.

Kind: global typedef
Properties

Name Type Description
url string Tag URI
loadStart string Current client ISO time when starting the request.
loadEnd string Current client ISO time after receiving the response.
loadTime number Time in milliseconds between loadStart and loadEnd

CompanionAd : Object

Secondary ads included in the VAST tag that accompany the video ad.

Kind: global typedef
Properties

Name Type Description
id string Value of the id attribute from the Creative > CompanionAds > Companion node
companionXML xml Full node.
resources [ 'Array' ].<CompanionAdResource> The companion ad may contain one or more resources to represent different versions of the creative for use in different environments. The media player can choose which resource to use when more than one resource file is provided.

CompanionAdResource : Object

Definition of a secondary ad by type.

Kind: global typedef
Properties

Name Type Description
type string Type of the companion creative resource. Can be either StaticResource, IFrameResource or HTMLResource
resource string The asset URL to be loaded.

Extension : Object

Custom XML element that extends the video ad.

Kind: global typedef
Properties

Name Type Description
type string The MIME type of any code that might be included in the extension. Type should be compliant with the IANA Media Type standard
extensionXML xml Full node.

ClosedCaption : Object

Subtitle files for the current creative in different languages

Kind: global typedef
Properties

Name Type Description
fileURL string URL to the subtitle file
type string MIME type of the offered file
language string Language of the file that is provided

AdVerification : Object

Object contains the executable and bootstrapping data required to run the measurement code for a single verification vendor.

Kind: global typedef
Properties

Name Type Description
vendor string An identifier for the verification vendor.
verificationParameters string Information intended for bootstrapping the verification code and providing metadata about the current impression. The format of the string is up to the individual vendor.
javascriptResource Object Object with url, apiFramework and browserOptional
tracking Object Array of single tracking elements, e.g. verificationNotExecuted.

PluginError : Object

Description object of the most recent error or null.

Kind: global typedef
Properties

Name Type Description
code number A number which represents the general type of error that occurred.
timestamp number Current client time Date.now()
message string A human-readable string which provides specific diagnostic information to help the reader understand the error condition which occurred.