Advertising
Ads
vpPlayer('vp-ads').setup({
video: {
file: "the_video_file_path",
advertising: true,
ads: {
skipAd: {
state: true,
skipFrom: 5,
},
vmap: 'string',
VPAIDmode: 'string',
enableProgrammability: false,
functions: [
{
isDynamicKey: false,
isDynamicValue: false,
key: 'string',
order: 1,
value: 'string',
},
],
bidding: false,
afterMidrollBacktrack: {
state: false,
seconds: 0,
},
adBreaks: [
{
adTagUrl: [],
breakType: 'midroll',
breakTimingType: 'time',
breakTimingValue: 10,
},
],
bidders: [
{
name: 'bidderName',
params: [
{
paramName: 'placementId',
paramType: 'string',
paramValue: '846836',
},
{
paramName: 'propertyId',
paramType: 'string',
paramValue: '105135',
},
],
},
],
},
config: {
adAnnouncement: {
state: false,
timeBeforeAd: 5,
},
adsRequireInteraction: false
}
}
});
PROPERTY | DESCRIPTION |
---|---|
ads Object | Configures the ads and the vast service to be used |
vmap string | A single VMAP link that contains all the ads to be played in the video |
VPAIDmode string | Specifies the VPAID mode to be used |
bidding Boolean | Specifies if there will be bidding for ads |
enableProgrammability boolean | Specifies if there will be ad programmability |
functions array[Object] | After enabling programmability you will be able to create functions or choose functions which were created before. Each function represents one key and value pair, the key/value property can be dynamic or static and they will be added to the tag URLs of the ad schedule. |
adBreaks Array | An array of objects that specify all ads to be played and their configurations |
adTagUrl Array | An array of Vast Url links which will be used as waterfall |
breakType string | Either preroll, midroll or postroll |
breakTimingType string | Either "time" or "percentage" |
breakTimingValue Number | The time when the ad should play, either in seconds or percentage |
bidders Array | Array of bidders which will be used for bidding on the ads of the video |
name string | Name of the bidder |
params Array | Paramaters of the bidder |
paramName string | Paramater used by some bidders that stores the parameter name |
paramType string | Paramater used by some bidders that stores the type of the parameter in string format |
paramValue string | Paramater used by bidders that stores the value of the parameter. (paramValue is converted to paramType specified in the other property) |
adsRequireInteraction boolean | Specifies if intereaction is needed in order to show ads in player |
Ad Breaks
vpPlayer('vp-ads').setup({
video: {
file: "the_video_file_path",
ads: {
adBreaks: [
{
adTagUrl: [],
breakType: 'midroll',
breakTimingType: 'time',
breakTimingValue: 10,
},
],
},
}
});
PROPERTY | DESCRIPTION |
---|---|
adBreaks Array | An array of ad objects like the following. |
adTagUrl Array | An array of Vast Url links which will be used as waterfall. |
breakType string | Either preroll, midroll or postroll. |
breakTimingType string | Either "time" or "percentage". |
breakTimingValue Number | The time when the ad should play, either in seconds or percentage. |
Static Ad Breaks
The staticAds
object has the following properties:
type
: a string that specifies the type of ads. In this case, the value is "STATIC", which indicates that these are static ads (i.e., the ad content does not change over time).adBreaks
: an array of objects that define the ad breaks for the video. Each object in theadBreaks
array represents a single ad break and has the following properties:adTagUrl
: an array of strings that specifies the URL(s) of the ad(s) to be played during the ad break.breakType
: a string that specifies the type of ad break. Possible values include "preroll" (played before the main video), "midroll" (played during the main video), and "postroll" (played after the main video).breakTimingType
: a string that specifies how the ad break is triggered. Possible values include "time" (triggered based on the elapsed time of the main video) and "percentage" (triggered based on the percentage of the main video that has been played).breakTimingValue
: a number that specifies the timing of the ad break based on the value ofbreakTimingType
. IfbreakTimingType
is "time",breakTimingValue
specifies the elapsed time of the main video at which the ad break should be triggered. IfbreakTimingType
is "percentage",breakTimingValue
specifies the percentage of the main video that has been played at which the ad break should be triggered.
const staticAds = {
type: "STATIC",
adBreaks: [
{
adTagUrl: ["https://example.com/ad-tag.xml"],
breakType: "preroll",
breakTimingType: "time",
breakTimingValue: 0,
},
{
adTagUrl: ["https://example.com/ad-tag.xml"],
breakType: "midroll",
breakTimingType: "time",
breakTimingValue: 20,
},
{
adTagUrl: ["https://example.com/ad-tag.xml"],
breakType: "midroll",
breakTimingType: "percentage",
breakTimingValue: 50,
},
{
adTagUrl: ["https://example.com/ad-tag.xml"],
breakType: "postroll",
breakTimingType: "time",
breakTimingValue: 0,
},
],
}
In this particular configuration, there are four ad breaks defined: a preroll ad break at the beginning of the video, two midroll ad breaks at 20 seconds into the video and at the 50% duration of the video, and a postroll ad break at the end of the video.
Each ad break is triggered based on the elapsed time of the main video, as indicated by the breakTimingType
of "time" for each ad break.
Dynamic Ad Breaks
The dynamicAds
object defines a set of ad breaks to be dynamically inserted during video playback.
There are three ad breaks defined in the adBreaks
array: a preroll, a midroll, and a postroll ad break.
Each object inside the adBreaks
array includes the following properties:
breakType
:
Specifies the type of ad break:"preroll"
– shown before content begins."midroll"
– inserted during content."postroll"
– appears after content ends.
adTagUrl
:
An array of ad tag URLs used to request ads. This string may include dynamic placeholders that are replaced at runtime:{count}
– Replaced with the sequential index of the ad break.{position}
– Replaced with the value ofbreakType
(e.g., "preroll", "midroll", "postroll").
Example:
https://example.com/ad-tag-{position}-{count}.xml
→https://example.com/ad-tag-midroll-2.xml
schedule
:
Defines when and how ad breaks occur. Theschedule
object contains the following key properties:ranges
:
This array defines rules for how many ad breaks are allowed, based on the total duration of the video. Each range includes:startTime
andendTime
defining a video length interval (in seconds). These values do not refer to where ad breaks happen inside the video, but to the overall length of the video.count
indicating the maximum number of ad breaks allowed for videos whose total duration falls within this range.
Example:
startTime: 0
,endTime: 120
,count: 2
→ For videos between 0 and 120 seconds long, allow up to 2 ad breaks.
You can define multiple ranges to cover various video durations:
startTime: 0
,endTime: 120
,count: 2
startTime: 121
,endTime: 600
,count: 4
startTime: 601
,endTime: Infinity
,count: 6
To ensure proper scheduling of ad breaks for all videos, the ranges
property in the schedule
object should always have a range from 0 to infinity. This ensures that ad breaks can be properly scheduled for the entire duration of the video. Without this, videos with durations outside the defined ranges may not receive any ad breaks or may behave unpredictably, leading to a degraded viewing experience.
liveCount
:
Specifies the number of ad breaks that should occur during the live stream. This property is which is only applicable for live videos.Additional scheduling properties for midroll ad breaks:
type
:
Defines the scheduling method."CUSTOM"
allows explicit break times via thebreaks
array."RECURRING"
schedules breaks at regular intervals.
algorithm
:
Specifies the spread algorithm that will be used to determine when the ad breaks OCCURS. Possible values include:
"PASSIVE"
,"AGGRESSIVE"
,"SIMILAR_DISTANCE"
, or"CUSTOM"
.breaks
:
An array of specific times (in seconds) at which midroll ad breaks should occur. This is used only for "CUSTOM" spread algorithms.protectFirst
/protectLast
:
Specifies the number of seconds at the beginning and/or end of the video, respectively, that should not contain ad breaks.occurEvery
:
Is applicable only for "RECURRING" schedules, defines the interval in seconds between ad breaks.
Spread algorithms are essential for determining the placement of ad breaks within video content. They dictate how ad breaks are distributed relative to the video's duration. There are four primary types of spread algorithms:
PASSIVE: This algorithm prioritizes content at the beginning of the video. It places fewer ad breaks earlier on, gradually increasing their frequency towards the end. For instance, in a 20-minute video with three ad breaks, the breaks might be positioned at the 10-minute, 15-minute, and 17.5-minute marks.
AGGRESSIVE: In contrast, the aggressive algorithm places more ad breaks at the beginning of the video, with their frequency decreasing as the video progresses. For example, in a 20-minute video with three ad breaks, these breaks could appear at 2.5 minutes, 5 minutes, and 10 minutes.
SIMILAR_DISTANCE: This algorithm distributes ad breaks evenly throughout the video, maintaining consistent intervals between them. For a 20-minute video with three ad breaks, the breaks would be placed at 5-minute, 10-minute, and 15-minute intervals.
CUSTOM: The custom algorithm offers the most flexibility, allowing users to precisely define the timestamps for each ad break. This is achieved by configuring the
breaks
property within theranges
object.
const dynamicAds = {
type: "DYNAMIC",
adBreaks: [
{
adTagUrl: ["https://example.com/ad-tag-{count}.xml"],
breakType: "preroll",
schedule: {
ranges: [
{
startTime: 0,
endTime: 150,
count: 1,
},
{
startTime: 151,
endTime: Infinity,
count: 2,
},
],
liveCount: 4,
},
},
{
adTagUrl: ["https://example.com/ad-tag-{count}.xml"],
breakType: "midroll",
schedule: {
type: "CUSTOM",
ranges: [
{
startTime: 0,
endTime: 150,
count: 1,
breaks: [40],
},
{
startTime: 151,
endTime: Infinity,
count: 3,
breaks: [33, 45, 40, 50, 66],
},
],
algorithm: "PASSIVE",
protectFirst: 0,
protectLast: 0,
occurEvery: 1000,
},
},
{
adTagUrl: ["https://example.com/ad-tag-{count}.xml"],
breakType: "postroll",
schedule: {
ranges: [
{
startTime: 0,
endTime: 150,
count: 1,
},
{
startTime: 151,
endTime: Infinity,
count: 2,
},
],
liveCount: 4,
},
},
],
}
Bidders
vpPlayer('vp-ads').setup({
video: {
file: "the_video_file_path",
ads: {
bidding: true,
bidders: [
{
name: 'bidderName',
params: [
{
paramName: 'paramName',
paramType: 'paramType',
paramValue: 'paramValue',
},
{
paramName: 'paramName',
paramType: 'paramType',
paramValue: 'paramValue',
},
],
},
],
},
}
});
PROPERTY | DESCRIPTION |
---|---|
bidders Array | Array of bidders which will be used for bidding on the ads of the video. |
name string | Name of the bidder. |
params Object | Paramaters of the bidder. |
propertyId Number | Parameter used by some bidders. |
placementId Number | Parameter used by some bidders. |
Ads Announcement
vpPlayer('vp-ads').setup({
video: {
file: "the_video_file_path"
},
config: {
adAnnouncement: {
state: false,
timeBeforeAd: 5,
},
}
});
PROPERTY | DESCRIPTION |
---|---|
adAnnouncement object | Object used to configure the announcement of ads. |
state boolean | Determines if ads should be announced before they start. |
timeBeforeAd int | Determines how many seconds before the adbreak should the announcement start. |
Midroll backtrack
vpPlayer('vp-ads').setup({
video: {
file: "the_video_file_path",
ads: {
afterMidrollBacktrack: {
state: false,
seconds: 0,
}
},
}
});
PROPERTY | DESCRIPTION |
---|---|
afterMidrollBacktrack object | Object used to configure if video should jump back after a midroll ends. |
state boolean | Determines if video playback should backtrack after midroll. |
seconds int | Determines how many seconds back from its inital point should the video start after a midroll. |
Ads programability
The enableProgrammability
property is a boolean value that determines whether programmatic behavior is enabled for the player. If enableProgrammability
is true
, the player will be able to use programmatic behavior. If enableProgrammability
is false
, the player will not be able to use programmatic behavior.
The functions
property is an array of objects that define programmatic behavior for the player. Each object in the array has the following properties:
isDynamicKey
: a boolean value that determines whether thekey
property is static or dynamic. IfisDynamicKey
istrue
, thekey
property is treated as the name of a method that will be called to get the desired value. IfisDynamicKey
isfalse
, thekey
property is treated as a static value.isDynamicValue
: a boolean value that determines whether thevalue
property is static or dynamic. IfisDynamicValue
istrue
, thevalue
property is treated as the name of a method that will be called to get the desired value. IfisDynamicValue
isfalse
, thevalue
property is treated as a static value.key
: a string that specifies the name of a key that will be added to the player's URL parameters. IfisDynamicKey
istrue
, this property specifies the name of a method that will be called to get the desired value.order
: a number that specifies the order in which the key-value pair should be added to the URL parameters.value
: a string that specifies the value of the key that will be added to the player's URL parameters. IfisDynamicValue
istrue
, this property specifies the name of a method that will be called to get the desired value.
To use programmatic behavior, you need to create a function and then select the name of that function from the select list in order to add it to the player's workflow.
vpPlayer("vp-ads-programability").setup({
video: {
file: 'string',
ads: {
enableProgrammability: true,
functions: [
{
isDynamicKey: false,
key: 'key',
isDynamicValue: false,
value: 'value',
order: 1,
},
{
isDynamicKey: false,
key: 'key',
isDynamicValue: true,
value: 'value',
order: 2,
},
{
isDynamicKey: true,
key: 'key',
isDynamicValue: false,
value: 'value',
order: 3,
},
{
isDynamicKey: true,
key: 'key',
isDynamicValue: true,
value: 'value',
order: 4,
},
],
},
},
});
window.key = function() {
return "a";
};
window.value = function() {
return "b";
}
Every element will create a key
/value
pair of the form key=value
, explained by order property in functions[i].order
- Key is static, value is static therefore the output is
key=value
- Key is static, value is dynamic therefore the output is
key=b
- Key is dynamic, value is static therefore the output is
a=value
- Key is dynamic, value is dynamic therefore the output is
a=b
The programability response will be key=value&key=b&a=value&a=b