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 the adBreaks 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 of breakTimingType. If breakTimingType is "time", breakTimingValue specifies the elapsed time of the main video at which the ad break should be triggered. If breakTimingType 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,
        },
    ],
}

note

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 of breakType (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. The schedule 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 and endTime 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

Schedule Ranges

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 the breaks 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 explanation

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 the ranges 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 the key property is static or dynamic. If isDynamicKey is true, the key property is treated as the name of a method that will be called to get the desired value. If isDynamicKey is false, the key property is treated as a static value.
• isDynamicValue: a boolean value that determines whether the value property is static or dynamic. If isDynamicValue is true, the value property is treated as the name of a method that will be called to get the desired value. If isDynamicValue is false, the value 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. If isDynamicKey is true, 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. If isDynamicValue is true, 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";
}

Ads programability explanation

Every element will create a key/value pair of the form key=value, explained by order property in functions[i].order

1. Key is static, value is static therefore the output is key=value
2. Key is static, value is dynamic therefore the output is key=b
3. Key is dynamic, value is static therefore the output is a=value
4. 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