Video Advertising Suite

Docs

Classes

AdSlotAPI

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.

NonLinearAds : Object

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

Linear : Object

Linear Ads are the video or audio formatted ads that play linearly within the streaming content.

MediaFileResource : Object

contains all relevant data for the mediaFile

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.

AdSlotAPI

Kind: global class

new AdSlotAPI(playerProxy, config)

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

adSlotAPI.ad ⇒ PublicAd

Returns information about the current ad, like companions, icons, variations, verifications and more. The contents of variations depend on the advertising medium, the following things can be found there:

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

adSlotAPI.adSlot ⇒ PublicAdSlot

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

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

adSlotAPI.error ⇒ PluginError

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

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

adSlotAPI.rawXML ⇒ XML

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

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

adSlotAPI.dispose() ⇒ void

Removes all event listeners that the SDK itself had previously added.

Kind: instance method of AdSlotAPI

adSlotAPI.initAdSlot(adBreak, environmentVars) ⇒ Promise

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

Kind: instance method of AdSlotAPI
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

adSlotAPI.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 AdSlotAPI

adSlotAPI.stopAdSlot() ⇒ Promise

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 AdSlotAPI
Returns: Promise - - Whether the ad slot could be closed and cleaned up or not.

adSlotAPI.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 AdSlotAPI

adSlotAPI.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 AdSlotAPI

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)

adSlotAPI.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 AdSlotAPI
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.

adSlotAPI.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 AdSlotAPI
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.

adSlotAPI.iconView(iconProgram) ⇒ void

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

Kind: instance method of AdSlotAPI

Param Type Description
iconProgram string The program represented in the icon

adSlotAPI.verificationNotExecuted(vendor, reason)

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

Kind: instance method of AdSlotAPI

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

adSlotAPI.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 AdSlotAPI

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

adSlotAPI.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 AdSlotAPI
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).

adSlotAPI.pauseAd()

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

Kind: instance method of AdSlotAPI

adSlotAPI.resumeAd()

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

Kind: instance method of AdSlotAPI

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.
adBreakPosition number of the ad slot. See AdBreak.adBreakPosition
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.
vastMacros Object VAST macros and their values as defined in https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html
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.
currentCommercial number Index of the current ad of variant COMMERCIAL. Defaulting to -1
totalClips number Total number of ads within the current ad break, regardless of variants.
totalCommercials number Total number of ads with variant COMMERCIAL within the current ad break
totalPlayableClips number Total number of playable ads within the current ad break, regardless of variants.
totalPlayableCommercials number Total number of ads with the 'COMMERCIAL' variant within the current ad break that are playable.
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.
variations [ 'Array' ].<NonLinearAds> The value of this property is an Array that provides nonLinear creative details for each <NonLinearAds> element.
linear [ 'Array' ].<Linear> The value of this property is an Array that provides linear creative details for each <Linear> element.
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
currentClip number Index of the current ad, regardless of its variant.
currentCommercial number Index of the current ad of variant COMMERCIAL. Defaulting to -1
currentTime number Current time of the current ad
duration number Total time of the current ad
idValue string A string identifying the unique creative identifier. Defaulting to unknown.
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.
totalClips number Total number of ads within the current ad break, regardless of variants.
totalCommercials number Total number of ads with variant COMMERCIAL within the current ad break
totalPlayableClips number Total number of playable ads within the current ad break, regardless of variants.
totalPlayableCommercials number Total number of ads with the 'COMMERCIAL' variant within the current ad
title string Value of the VAST > Ad > AdTitle node
variant string Ad variant, depending on the current schedule and VAST manifest.
universalAdId UniversalAdId A unique creative identifier that is maintained across different ad systems.
universalAdIds [ 'Array' ].<UniversalAdId> A list of multiple creative identifiers that are 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.

NonLinearAds : Object

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

Kind: global typedef
Properties

Name Type Description
apiFramework string A string that identifies an API that is needed to execute the creative.
adParameters Object Pass information from the VAST response into the SIMID/VPAID object
clickThroughURL string URIs for clickThrough
clickTracker array URIs for clickTracker
creativeTrackers Object URIs for creativeTracker
height number Height of the ad in pixels, as given from AdTag
id string An optional identifier for the creative
expandedHeight number The maximum pixel height of the creative in its expanded state.
expandedWidth number The maximum pixel width of the creative in its expanded state.
maintainAspectRation boolean Maintain the original canvas aspect ratio (width/height) when resizing.
minSuggestedDuration string Specified by advertiser.
resources array Array of resources with their attributes and contents parsed into properties.
scalable boolean Value that indicates whether the media file is meant to scale to larger dimensions.
width number Width of the ad in pixels, as given from AdTag

Linear : Object

Linear Ads are the video or audio formatted ads that play linearly within the streaming content.

Kind: global typedef
Properties

Name Type Description
captions [ 'Array' ].<ClosedCaption> Subtitle files for the current creative in different languages
creativeTrackers Object Overview of all trackers that could be triggered.
icons Object The ad icon details for the <Icon> element.
mediaFiles [ 'Array' ].<MediaFileResource> from the parsed VAST response with various sub-information like bitrate, mimType, URL etc.
selectedMediaFile MediaFileResource is the selected media file and its information

MediaFileResource : Object

contains all relevant data for the mediaFile

Kind: global typedef
Properties

Name Type Description
apiFramework string identifies the API needed to execute an interactive media file.
bitrate number value specifies the average bitrate for the media file.
height number The native height of the video file, in pixels. (0 for audio ads)
linearity string Type of linearity (linear/nonlinear)
mimeType string Type of media file.
variableDuration boolean Identifies whether the ad always drops when the duration is reached, or if it can potentially extend the duration by pausing the underlying video or delaying the adStopped call after adVideoComplete.
width number The native width of the video file, in pixels. (0 for audio ads).

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
language string Language of the file that is provided
type string MIME type of the offered file

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.