Ads API

The Ads object helps you configure and control ads within THEOplayer. We support VAST and VMAP via our own ad system and our ad system integrations. If you would like to use VPAID, you can use our Google IMA-integration.

Properties

The Ads object provides the following properties:

Property Type Description
playing boolean Indicates whether or not a linear ad is currently playing.
currentAds Array<Ad> An array of the currently active ads (linear and/or non linear). If there are no ads playing, the method returns an empty array. (**)
currentAdBreak AdBreak The active AdBreak (containing the currently playing Ad). (**)
scheduledAds Array <Ad> An array of ads that still needs to be played. (**)

Methods

The Ads object provides the following methods:

Method Arguments Description
addEventListener type : string, listener : EventListener Adds the listener for the given event type. (**)
schedule AdDescription

Schedules a VAST ad. It will be added on top of the already existing ads.
Alternatively, if you want to replace the ads with new ones or set ads while setting up the player, you should set a SourceDescription with an AdDescription.

As per version 2.18.0 this is also an option for our Google IMA integration.

skip   Skips the current linear ad. This is only possible if the player has already played beyond the time where it can be skipped.
removeEventListener type : string, listener : EventListener Removes the listener for the given event type. (**)

Events

The Ads object exposes the following events (via addEventListener):

Event Description
adbegin Thrown to indicate that an ad has begun.
adend Thrown to indicate that an ad has ended.
aderror Thrown to indicate that an ad has encountered an error.
adbreakbegin Thrown to indicate that an AdBreak has begun.
adbreakend Thrown to indicate that an AdBreak has ended.

Ad

An Ad is an abstract object that represents a single ad, which is a creative in the VAST specification. See LinearAd and NonLinearAd for concrete implementations. (**)

Properties

The Ad object provides the following properties:

Property Type Description
adBreak AdBreak A reference to the AdBreak of which the ad is a part of. (also available for VAST-ads)
companions  Array<CompanionAd> An array of CompanionAds associated to the ad, if available within the same Creatives element. (*)
height number The height of the advertisement. (*)
id string The identifier of the creative, provided in the VAST-file. (*)
resourceURI string The URI of the the ad content.
type string Either 'linear' or 'nonlinear', depending on the concrete implementator. (*)
width number The width of the advertisement. (*)

LinearAd

A LinearAd is a concrete implementation of an Ad which represents a linear ad. It extends the properties of the Ad object.

Properties

The LinearAd object provides the following properties:

Property Type Description
duration number The duration of the LinearAd, as provided by the VAST file. This numeric value represents seconds.
mediaFiles Array<MediaFile> An array of mediafiles, which provides some meta data retrieved from the VAST file:
  • delivery: string, should be either 'progressive' or 'streaming' (note: currently we only support progressive).
  • resourceURI: string, the URI of the VAST content.
  • type: string, MIME type.
  • height: number, height of the mediaFile.
  • width: number, width of the mediaFile.
skipOffset  number When the LinearAd can be skipped. This numeric value represents seconds.

NonLinearAd

A NonLinearAd is a concrete implementation of an Ad which represents a non linear ad. It extends the properties of the Ad object.

Properties

The NonLinearAd object provides the following properties:

Property Type Description
clickThrough string The website of the advertiser. Only supported for StaticResource.
skipOffset number When the NonLinearAd can be skipped. This numeric value represents seconds.

CompanionAd

A CompanionAd is included in a LinearAd or a NonLinearAd. It doesn't extend the properties of the Ad object.

Properties

The CompanionAd object provides the following properties:

Property Type Description
adSlotId string An identifier of the element in which the companion ad should be appended.
altText string An alternative description for the companion ad. Only supported for StaticResource.
contentHTML string A generated HTML-string with the content of the companion ad.
clickThrough string The website of the advertis. Only supported for StaticResource.
height number The height of the companion ad.
resourceURI string The URI of the ad content.
width number The width of the companion ad.

AdBreak

An AdBreak is an object that represents a collection of ads that are scheduled at a certain time.

Properties

The AdBreak object provides the following properties:

Property Type Description
ads Array<Ad> An array of all the ads that are available in the current AdBreak.
maxDuration number Indicates the maximum remaining duration of the AdBreak if it would stay playing. This value is indicated in seconds. (*)
maxRemainingDuration number Indicates the remaining maximum duration of the AdBreak. This property also considers the already played content of the current linear ad. This value is indicated in seconds. (*)
timeOffset number Indicates when the AdBreak should be shown in the content video. This value is indicated in seconds.

(*) We download ad data via the just in time principle. This property is only available if the ad has been loaded. 
(**) This is currently not supported in our integration for Google IMA.