Controllers - Advertising Controller

The Advertising controller can be requested from the global theoplayer variable:

theoplayer.onReady = function () {
    var adsController = theoplayer.controller(0,'AdsController');
    adsController.addVast('preroll.xml', '0%', 5);


addVast(url, offset, skip, addCompanionsRequest) Adds the VAST file located at url to the player. Other parameters described below.
addVmap(url, skip, addCompanionsRequest) Adds the VMAP file located at url to the player. Other parameters described below.
addAdvertisement(src, offset, skip, addCompanionsRequest) Adds a non-VAST advertisement to the player. The src parameter should link to a valid video file. Other parameters described below.
showAdBreak THEOplayer supports ads during livestreams by exposing this function. First, advertisements need to be added that tell the order to play this in. This can be done by adding advertisements with an offset equal to '#' concatenated with the position in the advertisement sequence, for example '#1'. When the livestream allows an occasion for an advertisement break, this function can be called to show all of the advertisements that were prepared.

Method Parameters

offset (optional) This optional parameter allows you to determine the place of the specified ad. Five different formats are allowed:
  • seconds: a numeric value representing the number of seconds into the video the ad should play
  • time: in the format hh:mm:ss.mmm (.mmm is optional), for example '00:35:30.000'
  • percentage: in the format n%, where n is a value from 0-100, for example 50%
  • pre/post: The value 'pre' signifies that the video is a preroll and should be played before the actually video can be viewed. The value 'post' signifies that the video is a postroll and should be played after the original video.
  • positions: in the format #n where n is a positive number that determines the position of the ad. This type of offsets are useful when livestreaming, as all the advertisements specified this way will appear in the stated order when an adbreak is started through the AdsController.
skip (optional) This optional parameter allows to override the amount of seconds a viewer must watch a pre-roll ad before it can be skipped. A negative value of -1 disables ad skipping. This will affect all linear ads specified in the VAST or VMAP file.
addCompanionsRequest(companions) (optional) This optional parameter serves as a handler function, which receives a list of companion ad DOM-elements that should be added to the page to display companion ads. This allows you to choose the placement of companion ads to better fit the page layout.


isAdPlaying Returns true if an ad is currently playing, false otherwise.


adblockdetected Fired when a file related to an advertisement could not get loaded in.
adbegin Fired when a linear ad starts to play.
adended Fired when a linear ad finishes playing.