Advertising

Ad scheduling, VAST/VMAP/VPAID support, and advertising API

AdInteractionType

Enum

Enumeration Members

Vpaid

Vpaid: "vpaid"

AdQuartile

Enum

Enumeration Members

FIRST_QUARTILE

FIRST_QUARTILE: "firstQuartile"

MIDPOINT

MIDPOINT: "midpoint"

THIRD_QUARTILE

THIRD_QUARTILE: "thirdQuartile"

Interface

Defines basic properties available for every ad type

Extended by

Properties

clickThroughUrl?

optional clickThroughUrl?: string

The url the user should be redirected to when clicking the ad.

clickThroughUrlOpened?

optional clickThroughUrlOpened?: () => void

Callback function to track the opening of the clickThroughUrl.

Returns

void

companionAds?

optional companionAds?: CompanionAd[]

The CompanionAds that should be served with the ad.

data?

optional data?: AdData

Holds various additional ad data.

extensions?

optional extensions?: VastAdExtension[]

The parsed custom Extension tags

Since: 8.39.0

height

height: number

The height of the ad.

id?

optional id?: string

Identifier for the ad. This might be autogenerated.

isLinear

isLinear: boolean

Determines whether an ad is linear, i.e. playback of main content needs to be paused for the ad.

mediaFileUrl?

optional mediaFileUrl?: string

The corresponding media file for the ad.

verifications?

optional verifications?: any[]

The parsed Verification tags of the corresponding AdVerifications tag. Every tag is handled as an array and the
property names are the exact same as the tag/attribute names found in the manifest (case-sensitive). The text
content of a tag is saved to a content property.

width

width: number

The width of the ad.

AdBreak

Interface

Extends

AdConfig

Extended by

Properties

ads?

optional ads?: Ad[]

The ads scheduled for this AdBreak.

id

id: string

The id of the corresponding AdBreakConfig.
If the AdBreak was generated out of a VMAP tag, then the ID present in the
VMAP tag will be taken. If none is present in the VMAP tag, it will be generated.

replaceContentDuration?

optional replaceContentDuration?: number

Specifies how many seconds the ad break(s) should replace of the main video content.

Inherited from

AdConfig.replaceContentDuration

scheduleTime

scheduleTime: number

The time in seconds in the media timeline the AdBreak is scheduled for.

AdBreakConfig

Interface

Extends

AdTagConfig

Extended by

Properties

discardAfterPlayback?

optional discardAfterPlayback?: boolean

Specifies whether ad breaks are discarded after they are played back, played over or tried to be played back but
failed due to some condition.
When set to false, ad breaks are played again when seeking back to a previous ad break position and never
discarded in any of the above cases.

The flag will be ignored when ImaAdTagConfig.passthroughMode
is set to ImaPassthroughMode.VastAndVmap

Default is true.

Inherited from

AdTagConfig.discardAfterPlayback

fallbackTags?

optional fallbackTags?: AdTag[]

Defines a list of fallback ad tags which will be tried one after the other if the original ad tag does not
provide a valid response. The fallback ad tags need to have the same AdTagType as the main tag.

Inherited from

AdTagConfig.fallbackTags

id

id: string

Unique identifier of the ad break. Used to be able to identify and discard the ad break dynamically.

linearAdUiConfig?

optional linearAdUiConfig?: LinearAdUiConfig

Holds relevant information for the advertising UI.

Inherited from

AdTagConfig.linearAdUiConfig

persistent?

optional persistent?: boolean

If set, the ad tag will be processed and rescheduled automatically when a new source is loaded.

Inherited from

AdTagConfig.persistent

position

position: string

Defines when the ad break shall be started. Default is 'pre'.

Allowed values are:

'pre': pre-roll ad
'post': post-roll ad
fractional seconds: '10', '12.5' (mid-roll ad)
percentage of the entire video duration: '25%', '50%' (mid-roll ad)
timecode [hh:mm:ss.mmm]: '00:10:30.000', '01:00:00.000' (mid-roll ad)

preloadOffset?

optional preloadOffset?: number

Specifies how many seconds before the ad break would start playing should the ad tag (and if possible the media
files of the resulting ad response) start pre-loading.
Default is 0.

replaceContentDuration?

optional replaceContentDuration?: number

Specifies how many seconds the ad break(s) should replace of the main video content.

Inherited from

AdTagConfig.replaceContentDuration

AdConfig

Interface

Extended by

Properties

replaceContentDuration?

optional replaceContentDuration?: number

Specifies how many seconds the ad break(s) should replace of the main video content.

AdData

Interface

Holds various additional ad data. Refer to ImaAdData or
BitmovinAdData for more information on what
additional data is available when using our Google IMA SDK implementation or our native VAST implementation.

Extended by

VastAdData

Properties

bitrate?

optional bitrate?: number

The average bitrate of the progressive media file as defined in the VAST response.

maxBitrate?

optional maxBitrate?: number

The maximum bitrate of the streaming media file as defined in the VAST response.

mimeType?

optional mimeType?: string

The MIME type of the media file or creative as defined in the VAST response.

minBitrate?

optional minBitrate?: number

The minimum bitrate of the streaming media file as defined in the VAST response.

AdMediaFileQuality

Interface

Properties

bitrate?

optional bitrate?: number

bitrate of ad media file.

height

height: number

height of the ad media file.

maxBitrate?

optional maxBitrate?: number

maximum bitrate of ad media file.

minBitrate?

optional minBitrate?: number

minimum bitrate of ad media file.

width

width: number

width of the ad media file.

AdPricing

Interface

Properties

currency

currency: string

The three-letter ISO-4217 currency symbol that identifies the currency of the value provided (e.g. USD, GBP, etc.).

model

model: string

Identifies the pricing model as one of: CPM, CPC, CPE, or CPV.

value

value: number

A numerical value that represents a price that can be used in real-time bidding systems.

AdSurvey

Interface

Properties

type?

optional type?: string

The MIME type of the resource being served.

uri

uri: string

A URI to any resource relating to an integrated survey.

AdSystem

Interface

Properties

name

name: string

The name of the ad system that returned the ad.

version?

optional version?: string

The version number of the ad system that returned the ad.

AdTag

Interface

Properties

type

type: AdTagType

Specifies whether the ad tag is a VAST, VMAP or VPAID tag. VMAP tags will be loaded immediately after scheduling.

url

url: string

Defines the path to an ad manifest. If the tag is a VMAP manifest, the resulting ad breaks will be scheduled as
described in the manifest, otherwise the ad breaks will be handled as pre-roll ads if no further information is
specified in the position property.

AdTagConfig

Interface

Extends

AdConfig

Extended by

Properties

discardAfterPlayback?

optional discardAfterPlayback?: boolean

The flag will be ignored when ImaAdTagConfig.passthroughMode
is set to ImaPassthroughMode.VastAndVmap

Default is true.

fallbackTags?

optional fallbackTags?: AdTag[]

linearAdUiConfig?

optional linearAdUiConfig?: LinearAdUiConfig

Holds relevant information for the advertising UI.

persistent?

optional persistent?: boolean

If set, the ad tag will be processed and rescheduled automatically when a new source is loaded.

replaceContentDuration?

optional replaceContentDuration?: number

Specifies how many seconds the ad break(s) should replace of the main video content.

Inherited from

AdConfig.replaceContentDuration

tag

tag: AdTag

Defines the url and type of the ad manifest. If the tag is a VAST or VPAID manifest, then more specific
scheduling options can be defined in the AdBreakConfig.

AdTagPlaceholders

Interface

Properties

assetUrl?

optional assetUrl?: string[]

Placeholders for the URL of the content asset

domain?

optional domain?: string[]

Placeholders for the domain of the current page

height?

optional height?: string[]

Placeholders for the height of the player

page?

optional page?: string[]

Placeholders for the URL of the current page

playbackTime?

optional playbackTime?: string[]

Placeholders for the current playback time of the player

random?

optional random?: string[]

Placeholders for a 8 digit random number

referrer?

optional referrer?: string[]

Placeholders for the URL of the referring page

timestamp?

optional timestamp?: string[]

Placeholders for the current UNIX timestamp of the client

width?

optional width?: string[]

Placeholders for the width of the player

AdTagType

Enum

Enumeration Members

VAST

VAST: "vast"

VMAP

VMAP: "vmap"

VPAID

VPAID: "vpaid"

Deprecated: Please use VAST even when scheduling VPAID ad tags.

Advertiser

Interface

Properties

id?

optional id?: string

An identifier for the advertiser, provided by the ad server.

name

name: string

The name of the advertiser as defined by the ad serving party.

AdvertisingConfig

Interface

Single VAST tag example:

advertising: {
  adBreaks: [{
    tag: {
      url: 'http://your.ad.provider/vast-manifest.xml',
      type: 'vast'
    }
  }],
}

This is the most simple config example to play a single pre-roll ad.

Single VMAP tag example:

advertising: {
  adBreaks: [{
    tag: {
      url: 'http://your.ad.provider/vmap-manifest.xml',
      type: 'vmap'
    }
  }]
}

This config example will immediately download the VMAP manifest and schedule the resulting ad break(s) based on
information in the manifest.

This example plays all the ad breaks in the VMAP manifest based on timing information in the manifest itself,
while the three VAST ads are played as a pre-roll, mid-roll at 8 minutes and 30 seconds and a post-roll ad.
Additionally, the strategy chosen here will result in every seeked-over ad break being played. The latter two
manifests are loaded 5 seconds in advance.

Mixed example:

advertising: {
  adBreaks: [{
    tag: {
      url: 'http://your.ad.provider/vmap-manifest.xml',
      type: 'vmap'
    },
  }, {
    tag: {
      url: 'http://your.ad.provider/vast-manifest.xml',
      type: 'vast'
    },
    replaceContentDuration: 5,
    persistent: true,
    id: 'pre-roll-1',
    position: 'pre',
  }, {
    tag: {
      url: 'http://your.ad.provider/vast-manifest.xml',
      type: 'vast'
    },
    id: 'mid-roll-1',
    position: '00:08:30.000',
    preloadOffset: 5
  }, {
    tag: {
      url: 'http://your.ad.provider/vast-manifest.xml',
      type: 'vast'
    },
    persistent: true,
    id: 'post-roll-1',
    position: 'post',
    preloadOffset: 5
  }],
  strategy: {
    shouldLoadAdBreak: (adBreak) => true,
    shouldPlayAdBreak: (adBreak) => true,
    shouldPlaySkippedAdBreaks: (skipped, from, to) => skipped,
  }
}

Extended by

Properties

adBreaks?

optional adBreaks?: AdConfig[]

Defines a collection of ad breaks which will be played at the specified position in each AdBreakConfig.

adContainer?

optional adContainer?: () => HTMLElement

Defines a function which returns a container that is used for displaying ads.

Returns

HTMLElement

companionAdContainers?

optional companionAdContainers?: () => HTMLElement[]

Defines a function which returns an array of containers for the ad module to fill with companion ads.

Returns

HTMLElement[]

disableStorageApi?

optional disableStorageApi?: boolean

When set to true, the ad module will be prohibited from using the browser's localStorage.

Defaults to disableStorageApi, if present, and falls back to false.

Since: v8.91.0

placeholders?

optional placeholders?: AdTagPlaceholders

List of placeholder strings that will be replaced in the ad manifest URL with the corresponding values.

Since: 8.1.0

strategy?

optional strategy?: RestrictStrategy

Defines an object with two functions which will be called if an ad break is about to start or when ads are seeked
over. If this property is not set manually, then only the last ad that was seeked over will be played.

trackers?

optional trackers?: Trackers

Defines tracker configurations for the relevant packages such
as the Open measurement which will be loaded to provide
additional tracking information for ads.

videoLoadTimeout?

optional videoLoadTimeout?: number

Specifies the amount of milliseconds before the loading of an ad from a given ad manifest times out.
Default is 8000.

withCredentials?

optional withCredentials?: boolean

Specifies whether to send credentials such as cookies or authorization headers along with the ad requests. The
server needs to explicitly accept them for CORS requests, otherwise the request will fail.
Default is true.

AdvertisingError

Interface

Properties

adConfig?

optional adConfig?: AdConfig

code

code: number

deficiencyData?

optional deficiencyData?: DeficiencyData

The underlying player error that caused this ad error, when available. This is currently populated for
server-guided ad insertion (SGAI) / HLS interstitial playback failures so the original network or decoding error
can be inspected.

message?

optional message?: string

AdvertisingModuleErrorCode

Enum

Enumeration Members

AD_TAG_TYPE_NOT_MATCHING

AD_TAG_TYPE_NOT_MATCHING: 110

The loaded manifest did not correspond to the given ad tag type.

COULD_NOT_LOAD_AD_MANIFEST

COULD_NOT_LOAD_AD_MANIFEST: 404

There was a problem downloading the ad manifest from the specified URI.

REQUIRED_PLAYER_MODULE_MISSING

REQUIRED_PLAYER_MODULE_MISSING: 2000

There was a problem playing the ad because a required player module is missing.

CompanionAd

Interface

Ad which gets displayed in combination with a linear or overlay ad

Properties

height

height: number

The height of the companion ad.

width

width: number

The width of the companion ad.

Creative

Interface

Properties

adId?

optional adId?: string

The ad server's unique identifier for the creative. Specified in Creative.adId in the VAST response.

id?

optional id?: string

Identifies the ad server that provides the creative. Specified in Creative.id in the VAST response.

universalAdId?

optional universalAdId?: UniversalAdId

A unique creative identifier that is maintained across systems. Specified in Creative.UniversalAdId in the
VAST response.

DeficiencyData

Interface

A snapshot of the underlying player error that caused an AdvertisingError, when one is available (e.g. a
network or decoding failure during ad playback). It exposes the original cause - including the player error code and
any additional data - which would otherwise be lost behind the ad error code.

Properties

code

code: number

The original player error code (a Core.ErrorCode), e.g. distinguishing a network from a decoding failure.

data?

optional data?: object

Additional data attached to the original player error.

Index Signature

[key: string]: unknown

message?

optional message?: string

The message of the original player error.

name?

optional name?: string

The name of the original player error code.

DownloadTiming

Interface

Properties

downloadTime

downloadTime: number

The total time it took for the ad manifest to be downloaded in seconds.

timeToFirstByte?

optional timeToFirstByte?: number

The time-to-first-byte for the ad manifest request in seconds.

LinearAd

Interface

Defines a linear ad which requires the playback of the content to stop

Extends

Ad

Properties

clickThroughUrl?

optional clickThroughUrl?: string

The url the user should be redirected to when clicking the ad.

Inherited from

Ad.clickThroughUrl

clickThroughUrlOpened?

optional clickThroughUrlOpened?: () => void

Callback function to track the opening of the clickThroughUrl.

Returns

void

Inherited from

Ad.clickThroughUrlOpened

companionAds?

optional companionAds?: CompanionAd[]

The CompanionAds that should be served with the ad.

Inherited from

Ad.companionAds

data?

optional data?: AdData

Holds various additional ad data.

Inherited from

Ad.data

duration

duration: number

The duration of the ad.

extensions?

optional extensions?: VastAdExtension[]

The parsed custom Extension tags

Since: 8.39.0

Inherited from

Ad.extensions

height

height: number

The height of the ad.

Inherited from

Ad.height

id?

optional id?: string

Identifier for the ad. This might be autogenerated.

Inherited from

Ad.id

isLinear

isLinear: boolean

Determines whether an ad is linear, i.e. playback of main content needs to be paused for the ad.

Inherited from

Ad.isLinear

mediaFileUrl?

optional mediaFileUrl?: string

The corresponding media file for the ad.

Inherited from

Ad.mediaFileUrl

skippable?

optional skippable?: boolean

Specifies whether the ad is skippable or not.

Deprecated: - This will be removed with player version 9. This can be inferred from skippableAfter

skippableAfter?

optional skippableAfter?: number

Time in seconds, after which the ad is skippable. The ad is not skippable if this property is not set.

uiConfig?

optional uiConfig?: LinearAdUiConfig

Holds relevant information for displaying the ad.

verifications?

optional verifications?: any[]

Inherited from

Ad.verifications

width

width: number

The width of the ad.

Inherited from

Ad.width

LinearAdUiConfig

Interface

Configuration object for the LinearAd Ui.

In case the bitmovin-player-ui is used, available from https://github.com/bitmovin/bitmovin-player-ui, message
placeholders such as: {remainingTime}, {adDuration} or {playedTime} are available to customize the ad messages:

{
  message: 'This ad will end in {remainingTime}',
  untilSkippableMessage: 'This ad is skippable in {remainingTime}',
  skippableMessage: 'You can skip this ad now.'
}

Properties

message?

optional message?: string

Message that gets displayed while an ad is active.

requestsUi?

optional requestsUi?: boolean

Specifies whether the ads need a UI.

skippableMessage?

optional skippableMessage?: string

Message that gets diplayed after the ad becomes skippable.

untilSkippableMessage?

optional untilSkippableMessage?: string

Message that gets displayed while a skippable ad is not yet skippable.

ModuleInfo

Interface

Properties

name

name: string

version

version: string

OmidVerificationVendor

Type

OmidVerificationVendor = "COMSCORE" | "DOUBLEVERIFY" | "GOOGLE" | "INTEGRAL_AD_SCIENCE" | "MEETRICS" | "MOAT" | "NIELSEN" | "PIXELATE" | "OTHER"

Vendor names as defined in the IMA SDK at https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima?hl=en#.OmidVerificationVendor
Will be mapped by the player to the appropriate numerical value once the IMA SDK is loaded.

OmSdkAccessModeRules

Interface

Lets you control the rules for choosing the AccessMode for an ad.
The player will try to match from the most restrictive (limited) to the least restricted (full)
and will take the first matching access mode.

Properties

creative?

optional creative?: RegExp[] | OmidVerificationVendor[]

The verification script and creative are sandboxed from the publisher page.
However, the script has direct access to the creative.
Has no effect when using the IMA ad module.

domain?

optional domain?: RegExp[] | OmidVerificationVendor[]

The verification script is sandboxed and cannot access the creative or publisher page.
However, the script is loaded in such a way that it can directly confirm what publisher
domain it is on.

full?

optional full?: RegExp[] | OmidVerificationVendor[]

The verification script has direct access to the creative and the publisher page.

limited?

optional limited?: RegExp[] | OmidVerificationVendor[]

The verification script is sandboxed and cannot access the creative or publisher page,
and cannot directly confirm what publisher domain it is on.

OmSdkTracker

Interface

You will have to include the AdvertisingOmSdk
module into the player before creating an instance.

If you are using the AdvertisingIma module only the onAccessMode
callback will have an effect.

Example


<script type="text/javascript" src="./bitmovinplayer.js"></script>
<script type="text/javascript" src="./modules/bitmovinplayer-advertising-bitmovin.js"></script>
<script type="text/javascript" src="./modules/bitmovinplayer-advertising-omsdk.js"></script>
<!-- your html body here -->
<script type="text/javascript">
  bitmovin.player.Player.addModule(bitmovin.player['advertising-bitmovin'].default);
  bitmovin.player.Player.addModule(bitmovin.player['advertising-omsdk'].default);
  var conf = {
    key: '<yourPlayerKey>',
    advertising: {
      adBreaks: [{
        tag: {
          url: '<http://location-of-your-ad.xml>',
          type: 'vast'
        },
        position: 'pre',
      }],
      trackers: {
        omSdk: {
          partnerName: '<yourOmSdkPartnerName>',
          partnerVersion: '<yourOmSdkParnterVersion>',
        },
      }
    },
  };
  var player = new bitmovin.player.Player(document.getElementById('player'), conf);

Properties

contentUrl?

optional contentUrl?: string

Allows you to customize the current content url used. This can be useful when the same urls with different
parameters need to be included under the same content url for easier tracking.

If the content url is not provided the default current href will be used.

onAccessMode?

optional onAccessMode?: (ad) => OmSdkAccessModeRules

By default accessMode will be set as AccessMode.FULL for all requests when using the Bitmovin Ad module.
When using the IMA Ad module the default will be AccessMode.LIMITED.

For usage with the IMA ad module, an array of strings matching an OmidVerificationVendor is required
to build a map for the omidAccessRules.

For usage with the Bitmovin ad module, an array of Regular Expressions needs to be provided. For each verification in the ad, if the JavaScriptResource matches one regular expression
the appropriate access mode will be used to construct a VerificationScriptResource.

If one entry is in two different access modes, the more restrictive one will be applied.

Parameters

any

The ad object that is currently being played. For IMA this will be the AdsRequest for which the access rules should apply.

Returns

OmSdkAccessModeRules

Example


const rulesForBAM: OmSdkAccessModeRules = {
  limited: [new RegExp('examplevendor1.com/.*$')],
  full: [/examplevendor2\.com/],
};
const rulesForIMA: OmSdkAccessModeRules = {
  limited: ['OTHER'],
  domain: ['DOUBLEVERIFY', 'GOOGLE'],
};
const omSdkTracker: OmSdkTracker = {
  onAccessMode: _adOrAdRequest => (isUsingIMA ? rulesForIMA : rulesForBAM),
};

partnerName

partnerName: string

The partner name associated with your OM SDK account

partnerVersion

partnerVersion: string

The version associated with your OM SDK account

serviceWindowProxy?

optional serviceWindowProxy?: "parent" | "self" | "top"

By default, the OM SDK Session Client Library will assume the Service Script is present
in the same frame the library is loaded in. Use this config to override the behavior.
Default is top to indicate that window.top shall be used.

verificationResources?

optional verificationResources?: VerificationResource[]

By default it will use an empty array. Allows loading of verification urls.

Example


const adConfig: AdvertisingConfig = {
  adBreaks: [
    // your ads here
  ],
  trackers: {
    omSdk: {
      partnerName: '<yourOmSdkPartnerName>',
      partnerVersion: '<yourOmSdkParnterVersion>',
      verificationResources: [
        {
          validationScriptUrl:
             './Validation-Script/omid-validation-verification-script-v1.js',
        },
      ],
    },
  },
};

OverlayAd

Interface

Ad which gets displayed during content playback

Extends

Ad

Properties

clickThroughUrl?

optional clickThroughUrl?: string

The url the user should be redirected to when clicking the ad.

Inherited from

Ad.clickThroughUrl

clickThroughUrlOpened?

optional clickThroughUrlOpened?: () => void

Callback function to track the opening of the clickThroughUrl.

Returns

void

Inherited from

Ad.clickThroughUrlOpened

companionAds?

optional companionAds?: CompanionAd[]

The CompanionAds that should be served with the ad.

Inherited from

Ad.companionAds

data?

optional data?: AdData

Holds various additional ad data.

Inherited from

Ad.data

extensions?

optional extensions?: VastAdExtension[]

The parsed custom Extension tags

Since: 8.39.0

Inherited from

Ad.extensions

height

height: number

The height of the ad.

Inherited from

Ad.height

id?

optional id?: string

Identifier for the ad. This might be autogenerated.

Inherited from

Ad.id

isLinear

isLinear: boolean

Determines whether an ad is linear, i.e. playback of main content needs to be paused for the ad.

Inherited from

Ad.isLinear

mediaFileUrl?

optional mediaFileUrl?: string

The corresponding media file for the ad.

Inherited from

Ad.mediaFileUrl

verifications?

optional verifications?: any[]

Inherited from

Ad.verifications

width

width: number

The width of the ad.

Inherited from

Ad.width

PlayerAdvertisingAPI

Interface

Methods

discardAdBreak()

discardAdBreak(adBreakId): void

Discards all scheduled ad breaks with the given ID. Also stops the current ad break if it has the same ID.

Parameters

adBreakId

string

The ID of the ad break which shall be removed from the scheduled ad breaks.

Returns

void

Since: v8.0

getActiveAd()

getActiveAd(): Ad

Returns the currently active ad, or null if no ad is active.

Returns

Ad

the active Ad, or null if none is active

Since: v8.1

getActiveAdBreak()

getActiveAdBreak(): AdBreak

Returns the currently active ad break, or null if no ad break is active.

Returns

AdBreak

the active AdBreak, or null if none is active

Since: v8.0

getModuleInfo()

getModuleInfo(): ModuleInfo

Returns the name and version of the currently used advertising module.

Returns

ModuleInfo

Since: v8.1

isLinearAdActive()

isLinearAdActive(): boolean

Returns true if a linear ad is currently active (playing or paused). Returns false otherwise.

Returns

boolean

Since: v8.0

list()

list(): AdBreak[]

Returns all scheduled ad breaks. Does not include currently active ad breaks.

Returns

AdBreak[]

Array containing all the scheduled ad breaks.

Since: v8.0

schedule()

schedule(adConfig): Promise<AdBreak[]>

Schedules resulting ad break(s) of an ad config for playback.

Parameters

adConfig

AdConfig

The ad configuration used to schedule one or more ad breaks.

Returns

Promise<AdBreak[]>

Promise that resolves with the ad breaks that were scheduled as a result of the given ad config.

Since: v8.0

skip()

skip(): Promise<void>

Skips the current ad. Has no effect if the ad is not skippable, if no ad is active or if the IMA module is used (disabled by IMA in version 3.607.0).

Returns

Promise<void>

Promise that resolves when the ad has been skipped and the ad player is done with cleanup of events and states.

Since: v8.0

RestrictStrategy

Interface

Properties

shouldLoadAdBreak

shouldLoadAdBreak: (toLoad) => boolean

A callback function that will be called every time an ad break is about to load. The return value decides
whether the ad break will actually be loaded or discarded from the ad schedule.

Parameters

toLoad

AdBreak

Returns

boolean

shouldPlayAdBreak

shouldPlayAdBreak: (toPlay) => boolean

A callback function that will be called every time an ad break is about to start. The return value decides
whether the ad break will actually start playing or be discarded from the ad schedule.

Parameters

toPlay

AdBreak

Returns

boolean

shouldPlaySkippedAdBreaks

shouldPlaySkippedAdBreaks: (skipped, from, to) => AdBreak[]

A callback function that will be called after every seek where ad breaks were scheduled in between the original
time and the seek target. The return value decides which ad breaks will be played after the operation finished.

The default behaviour is to playback the most recent AdBreak.

Parameters

skipped

AdBreak[]

from

number

to

number

Returns

AdBreak[]

Trackers

Interface

Properties

omSdk?

optional omSdk?: OmSdkTracker

Used in the advertising module to implement the open measurement SDK.

UniversalAdId

Interface

Properties

idRegistry

idRegistry: string

The registry website where the unique creative ID is cataloged. Default value is 'unknown'.

value

value: string

The unique creative identifier. Default value is 'unknown'.

VastAdData

Interface

Extends

AdData

Extended by

Properties

adDescription?

optional adDescription?: string

A longer description of the ad. Specified in InLine.Description in the VAST response.

adSystem?

optional adSystem?: AdSystem

The ad system that returned the ad. Specified in InLine.AdSystem in the VAST response.

adTitle?

optional adTitle?: string

A common name for the ad. Specified in InLine.AdTitle in the VAST response.

advertiser?

optional advertiser?: Advertiser

The advertiser as defined by the ad serving party. Specified in InLine.Advertiser in the VAST response.

apiFramework?

optional apiFramework?: string

Identifies the API needed to execute an interactive media file or communicate with the creative. Specified in
MediaFile.apiFramework for linear ads or NonLinear.apiFramework for non-linear ads in the VAST response.

bitrate?

optional bitrate?: number

The average bitrate of the progressive media file as defined in the VAST response.

Inherited from

AdData.bitrate

codec?

optional codec?: string

The codec used to encode the file which can take values as specified by https://tools.ietf.org/html/rfc4281.
Specified in MediaFile.codec in the VAST response.

creative?

optional creative?: Creative

Contains various data about the Creative. Specified in InLine.Creative or Wrapper.Creative in the
VAST Response.

delivery?

optional delivery?: string

Either 'progressive' for progressive download protocols or 'streaming' for streaming protocols. Specified in
MediaFile.delivery in the VAST response.

maxBitrate?

optional maxBitrate?: number

The maximum bitrate of the streaming media file as defined in the VAST response.

Inherited from

AdData.maxBitrate

mediaFileId?

optional mediaFileId?: string

The media file ID. Specified in MediaFile.id in the VAST response.

mimeType?

optional mimeType?: string

The MIME type of the media file or creative as defined in the VAST response.

Inherited from

AdData.mimeType

minBitrate?

optional minBitrate?: number

The minimum bitrate of the streaming media file as defined in the VAST response.

Inherited from

AdData.minBitrate

minSuggestedDuration?

optional minSuggestedDuration?: number

The minimum suggested duration that the creative should be displayed. Specified in NonLinear.minSuggestedDuration
in the VAST response.

pricing?

optional pricing?: AdPricing

Used to provide a value that represents a price that can be used by real-time bidding (RTB) systems. Specified
in Inline.Pricing in the VAST response.

survey?

optional survey?: AdSurvey

URI to any resource relating to an integrated survey. Specified in InLine.Survey in the VAST response.

wrapperAdIds?

optional wrapperAdIds?: string[]

The IDs of the Wrapper ads, starting at the InLine ad and ending at the outermost Wrapper ad. Contains an
empty array if there are no Wrapper ads.

VastAdExtension

Interface

Properties

attributes

attributes: VastAdExtensionAttributes

The attributes of the tag

children

children: VastAdExtension[]

The nested children of the tag

name

name: string

The name of the tag

value

value: string

The value of the tag

VastAdExtensionAttributes

Interface

Indexable

[key: string]: string

VastErrorCode

Enum

Enumeration Members

COMPANION_AD_INVALID_DIMENSIONS

COMPANION_AD_INVALID_DIMENSIONS: 601

Unable to display companion because creative dimensions do not fit within companion display area (i.e., no
available space).

EXPECTING_DIFFERENT_DURATION

EXPECTING_DIFFERENT_DURATION: 202

Expected ad with different duration.

EXPECTING_DIFFERENT_LINEARITY

EXPECTING_DIFFERENT_LINEARITY: 201

Expected ad with different linearity.

EXPECTING_DIFFERENT_SIZE

EXPECTING_DIFFERENT_SIZE: 203

Expected ad with different size or bitrate.

FILE_NOT_FOUND

FILE_NOT_FOUND: 401

Unable to find Linear/MediaFile from URI.

GENERAL_COMPANIONADS_ERROR

GENERAL_COMPANIONADS_ERROR: 600

A general CompanionAds error occurred and no further details are known.

GENERAL_LINEAR_ERROR

GENERAL_LINEAR_ERROR: 400

Unable to display the linear ad.

GENERAL_NONLINEARADS_ERROR

GENERAL_NONLINEARADS_ERROR: 500

A general NonLinearAds error occurred and no further details are known.

GENERAL_VPAID_ERROR

GENERAL_VPAID_ERROR: 901

A VPAID error occurred.

GENERAL_WRAPPER_ERROR

GENERAL_WRAPPER_ERROR: 300

A general wrapper error occurred. This can mean that some wrappers were not reachable or timed out.

MEDIAFILE_URI_TIMEOUT

MEDIAFILE_URI_TIMEOUT: 402

Timeout of MediaFile URI.

NO_ADS_VAST_RESPONSE

NO_ADS_VAST_RESPONSE: 303

No ads VAST response after one or more Wrappers.

NO_SUPPORTED_COMPANION_RESOURCE_TYPE

NO_SUPPORTED_COMPANION_RESOURCE_TYPE: 604

Could not find Companion resource that is supported.

NO_SUPPORTED_MEDIAFILE

NO_SUPPORTED_MEDIAFILE: 403

Could not find MediaFile that is supported, based on the attributes of the MediaFile element.

NO_SUPPORTED_NONLINEAR_RESOURCE_TYPE

NO_SUPPORTED_NONLINEAR_RESOURCE_TYPE: 503

Could not find NonLinear resource that is supported.

NONLINEAR_AD_INVALID_DIMENSIONS

NONLINEAR_AD_INVALID_DIMENSIONS: 501

Unable to display NonLinear ad because creative dimensions do not align with creative display area (i.e., creative
dimensions too large).

PROBLEM_DISPLAYING_MEDIAFILE

PROBLEM_DISPLAYING_MEDIAFILE: 405

There was a problem displaying the MediaFile. Possible causes are CORS issues, unsupported codecs, mismatch
between mime type and video file type or an unsupported delivery method.

TRAFFICKING_ERROR

TRAFFICKING_ERROR: 200

Received an ad type that was not expected and/or cannot be displayed.

UNABLE_TO_DISPLAY_REQUIRED_COMPANION

UNABLE_TO_DISPLAY_REQUIRED_COMPANION: 602

A required companion ad can not be displayed.

UNABLE_TO_FETCH_COMPANION_RESOURCE

UNABLE_TO_FETCH_COMPANION_RESOURCE: 603

Unable to fetch CompanionAds/Companion resource.

UNABLE_TO_FETCH_NONLINEAR_RESOURCE

UNABLE_TO_FETCH_NONLINEAR_RESOURCE: 502

Unable to fetch NonLinearAds/NonLinear resource.

UNDEFINED_ERROR

UNDEFINED_ERROR: 900

An unexpected error occurred and the cause is not known.

VAST_SCHEMA_VALIDATION_ERROR

VAST_SCHEMA_VALIDATION_ERROR: 101

The VAST validates as XML, but does not validate per the VAST schema.

VERSION_NOT_SUPPORTED

VERSION_NOT_SUPPORTED: 102

The VAST version of the ad response is not supported.

WRAPPER_LIMIT_REACHED

WRAPPER_LIMIT_REACHED: 302

Too many wrapper responses have been received with no InLine response.

WRAPPER_VAST_URI_TIMEOUT

WRAPPER_VAST_URI_TIMEOUT: 301

Timeout of VAST URI provided in Wrapper element.

XML_PARSING_ERROR

XML_PARSING_ERROR: 100

The ad response contained an error.

VerificationResource

Interface

Represents a verification script resource that comes in a VAST extension for
VAST versions <= 3 or a verification node for VAST versions >= 4

Properties

params?

optional params?: string

Optional stringified parameters to be used by the verification script

validationScriptUrl

validationScriptUrl: string

The location of the verification script file

vendorKey?

optional vendorKey?: string

An optional vendor key to be used by the verification script

VmapTrackingEvent

Interface

Properties

type

type: VmapTrackingEventType

The tracking event type as defined by VmapTrackingEventType.

url

url: string

The URL to be requested by this tracking event.

VmapTrackingEventType

Enum

Enumeration Members

BreakEnd

BreakEnd: "breakend"

BreakStart

BreakStart: "breakstart"

Error

Error: "error"