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 has the following properties:

There are three ad breaks defined in the adBreaks array: a preroll ad break, a midroll ad break, and a postroll ad break.

The adTagUrl property specifies the URL of the ad tag that will be used to request the ad.

Custom properties

The adtagUrl may contain a placeholder {count}, which will be replaced with the number of the ad break at runtime.

The breakType property specifies the type of ad break, which can be "preroll", "midroll", or "postroll".

The schedule property contains information about when the ad break will occur. For preroll and postroll ad breaks, the schedule object contains a ranges array, which defines the range of durations in which the ad break may occur.

Ranges schedule

It is important that the ranges property in the schedule object always has a range from 0 to infinity. This ensures that ad breaks can be properly scheduled for the entire duration of the video. If a range other than 0 to infinity is provided, ad breaks may not be properly scheduled and could result in a degraded viewing experience for the user.

The liveCount property, which is only applicable for live videos, specifies the number of ad breaks that should occur during the live stream.

For midroll ad breaks, the schedule object contains additional properties. The type property specifies the type of schedule, which can be "CUSTOM" or "RECURRING". The algorithm property specifies the spread algorithm that will be used to determine when the ad breaks will occur. Possible values are "PASSIVE", "AGRESSIVE", "SIMILAR_DISTANCE", or "CUSTOM".

Spread algorithms explanation

Spread algorithms determine where ad breaks are placed in relation to the content. There are four types of spread algorithms:

1. PASSIVE: places ad breaks at the beginning of the video, with fewer ad breaks and more content at the beginning, and fewer content and more ad breaks towards the end. For example, if you have a 20 minute video with 3 ad breaks, the spread algorithm would place the ad breaks at 10 minutes, 15 minutes, and 17.5 minutes.
2. AGRESSIVE: places ad breaks at the beginning of the video, with more ad breaks and less content at the beginning, and more content and fewer ad breaks towards the end. For example, if you have a 20 minute video with 3 ad breaks, the spread algorithm would place the ad breaks at 2.5 minutes, 5 minutes, and 10 minutes.
3. SIMILAR_DISTANCE: places ad breaks at regular intervals throughout the video. For example, if you have a 20 minute video with three ad breaks, the spread algorithm would place the ad breaks at 5 minutes, 10 minutes, and 15 minutes.
4. CUSTOM: allows you to specify the exact time at which ad breaks should be placed. You can do this by setting the breaks property in the ranges object.

The protectFirst and protectLast properties specify the number of seconds at the beginning and end of the video, respectively, that should not contain ad breaks. The occurEvery property, which is only applicable for "RECURRING" schedules, specifies the number of seconds between ad breaks. The ranges array for midroll ad breaks may also contain a breaks array, which is used only for "CUSTOM" spread algorithms and specifies the specific times at which ad breaks should occur.

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