kaltura-player-js

Ads

The Kaltura TV Platform Player supports the addition of 3rd party monetization solutions via its plugin system. To allow easy integration and to support playback and analytics using any 3rd party solution, the player defines an advertizing framework using APIs and a standard event scheme.

Any plugin that adds support for ads is expected to follow the controller, timeline, and events scheme. This document details the ads controller, which allows controlling ad-related operations, the ad timeline (which explains how a typical order of events looks like), and the ad events and their associated payload.

Ads Controller

To query the player regarding the ad’s state in the current playback, you can use the ads controller by referencing player.ads. The ads controller is responsible for tracking and communicating with the active ads plugin, as well as for collecting and saving the current ads state and data.

A complete reference to the AdsController can be found here.

Examples:

Know when a scheduled ad break will play

const layout = player.ads.getAdBreaksLayout();
console.log(layout); // [0, 15, -1]

Check if all ads are completed

if (player.ads.allAdsCompleted) {
  // do something
}

Check if this is the middle of an ad break

if (player.ads.isAdBreak()) {
  // do something
}

Get the current ad break data

if (player.ads.isAdBreak()) {
  const adBreak = player.ads.getAdBreak();
  // do something
}

Get the current ad data

if (player.ads.isAdBreak()) {
  const ad = player.ads.getAd();
  // do something
}

Ad Events Timeline

During ad playback, there are events that get triggered to indicate the current ad state or state changes. Some events are life cycle indicators and will always get triggered, while others are reactive to specific actions – such as the user clicking the ad – and may or may not be triggered.

In the following diagram you can observe the events timeline from the point that an ad break starts to the point that the ad break ends.

If you want to know when playback has started/ended – whether the playback includes ads or not – use the following events:

• PLAYBACK_START - Triggered on the first play request for playback. If a pre-roll ad is about to play, this event will be triggered before the pre-roll. If no pre-roll ad is about to play, this event will be triggered before any other content event including FIRST_PLAY.

• PLAYBACK_ENDED - Triggered when playback is ended. If a post-roll ad is about to play, this event will be triggered after post-roll. If no post-roll ad is about to play, this event will be triggered after any other content event including ENDED.

You can observe the following timeline diagram that simulates these events’ exact location:

Ad Events

Events List
AD_CAN_SKIP
AD_MANIFEST_LOADED
AD_LOADED
AD_STARTED
AD_RESUMED
AD_PAUSED
AD_CLICKED
AD_SKIPPED
AD_COMPLETED
AD_ERROR
ALL_ADS_COMPLETED
AD_BREAK_START
AD_BREAK_END
AD_FIRST_QUARTILE
AD_MIDPOINT
AD_THIRD_QUARTILE
USER_CLOSED_AD
AD_VOLUME_CHANGED
AD_MUTED
AD_PROGRESS

#

AD_CAN_SKIP

Fires when an ad’s skippable state has changed and the ad can be skipped.

#

AD_MANIFEST_LOADED

Fires when the ad manifest has been loaded and the ad layout is available.

payload parameters:

Name	Type	Description
adBreaksPosition	Array<number>	An array that represents the ad break’s time on the media timeline.

#

AD_LOADED

Fires when an ad has been loaded and ad data is available.

payload parameters:

Name	Type	Description
ad	Ad	The ad data

#

AD_STARTED

Fires when an ad has been started and ad data is available.

payload parameters:

Name	Type	Description
ad	Ad	The ad data

#

AD_RESUMED

Fires when the ad resumed after a pause.

#

AD_PAUSED

Fires when the ad paused.

#

AD_CLICKED

Fires when the ad has been clicked by the user.

#

AD_SKIPPED

Fires when the ad has been skipped.

#

AD_COMPLETED

Fires when the ad completes playing.

#

AD_ERROR

Fires when an error occurred while the ad was loading or playing.


payload parameters:

Name	Type	Description
severity	string	The error severity
category	string	The error category
code	number	The error code
data	Object	The error data: the original ad error can be accessed by data.innerError.

#

ALL_ADS_COMPLETED

Fires when the player is done playing all the ads.

#

AD_BREAK_START

Fires before an ad break is about to start.

payload parameters:

Name	Type	Description
adBreaK	AdBreak	The ad break data

#

AD_BREAK_END

Fires when an ad break is finished.

#

AD_FIRST_QUARTILE

Fires when the ad playhead crosses first the quartile.

#

AD_MIDPOINT

Fires when the ad playhead crosses the midpoint.

#

AD_THIRD_QUARTILE

Fires when the ad playhead crosses the third quartile.

#

USER_CLOSED_AD

Fires when the ad is closed by the user.

#

AD_VOLUME_CHANGED

Fires when the ad volume has changed.

#

AD_MUTED

Fires when the ad volume has been muted.

#

AD_PROGRESS

Fires on ad time progress.

payload parameters:

Name	Type	Description
adProgress	AdProgressObject	The ad progress data

Type AdProgressObject

{
  currentTime: number,
  duration: number
}

Ads API Reference

• AdBreak
  • Parameters
  • type
  • position
  • numAds
• Ad
  • Parameters
  • id
  • contentType
  • url
  • title
  • position
  • duration
  • clickThroughUrl
  • posterUrl
  • skipOffset
  • linear
  • width
  • height
  • bitrate
  • skippable
  • vpaid
  • streamId
• AdsController
  • Parameters
  • allAdsCompleted
  • isAdBreak
  • getAdBreaksLayout
  • getAdBreak
  • getAd
  • skipAd
  • playAdNow
    • Parameters

AdBreak

Parameters

• options PKAdBreakOptions - The ad break data options.

type

Returns string - The ad break type - pre/mid/post.

position

Returns string - The ad break position on the playback timeline.

numAds

Returns string - The number of ads inside the ad break.

Ad

Parameters

• id string Ad ID.
• options PKAdOptions - The ad data options.

id

Returns string - The ad ID.

contentType

Returns string - The ad content type.

url

Returns string - The ad URL.

title

Returns string - The ad title.

position

Returns string - The ad position inside the ad break.

duration

Returns string - The ad duration.

clickThroughUrl

Returns string - The ad click-through URL.

posterUrl

Returns string - The ad poster URL.

skipOffset

Returns string - The ad skip offset.

linear

Returns string - Whether the ad is linear.

width

Returns string - The ad width.

height

Returns string - The ad height.

bitrate

Returns string - The ad bitrate.

skippable

Returns boolean - Whether the ad is skippable or not.

vpaid

Returns boolean - Whether the ad is vpaid or not.

streamId

Returns string - The ad streamId.

AdsController

Parameters

• player Player The player.
• adsPluginController IAdsController - The controller of the current ads plugin instance.

allAdsCompleted

Returns boolean - Whether all ads are completed.

isAdBreak

Returns boolean - Whether we’re in an ad break.

getAdBreaksLayout

Returns Array<number> - The ad break’s layout (cue points).

getAdBreak

Returns AdBreak? - Gets the current ad break data.

getAd

Returns Ad? - Gets the current ad data.

skipAd

Skips an ad.

Returns void

playAdNow

Play an ad on demand.

Parameters

• adTagUrl string - The ad tag url to play.

Returns void

This site is open source. Improve this page.