{ FOR DEVELOPERS }
Guides
LOGINGET STARTED
Start typing to search…

Ad Proxy for AVOD (VMAP Generator)

Understand how to use built-in VMAP generator to insert several ad breaks in a VOD stream

Ad scheduling for AVOD

If your ad server does not support the generation of a VMAP schedule to tell broadpeak.io where to insert ads in the VOD content, you can use the Ad Proxy feature to define that schedule and indicate how to interact with the ad server.

Creating the Ad Server source

To use this feature, at the time of creating your ad server Source, select the “AdProxy (VMAP Generator)” template.

Next, you need to provide a set of query parameters that configure the ad proxy for your use case:

Parameter

Description

vmapg_tag (required)

VAST tag (ie. URL to the VAST-compliant ad server) that will be called for each ad break. It is recommended to URL-encode it, in particular if contains its own query parameters.

vmapg_pre

If set to “true”, a pre-roll ad opportunity is added to the schedule

vmapg_post

If set to “true”, a post-roll ad opportunity is added to the schedule

vmapg_mids

Use this parameter to define the time points in the asset timeline where mid-roll ad opportunities need to be added. The time points can be expressed as:

  • an integer or float number, defining the time as seconds from the start of the assets (with max 3 decimals)
  • an expression in the form “HH:MM:SS” or “HH:MM:SS.sss”
  • a percentage in the form "n%" (n being an integer); 0% and 100% are valid and define pre-roll and post-roll
  • the value "pre" or "start" (for pre-rolls, functionally equivalent to using vmapg_pre=true)
  • the value "post" or "end" (for post-rolls, functionally equivalent to using vmapg_post=true)

⚠️ The mix of time expressions is not recommended, but is not treated as an error. It may lead to unwarranted side-effects, in particular if combining time e

vmapg_mids_freq

Instead of using vmapg_mids, you can use this parameter if you want regular ad breaks. This parameter needs to be set to an integer or float number, defining the interval as seconds.
⚠️ You must also use vmapg_asset_length in combination with it.

vmapg_asset_length

Used in combination with vmapg_mids_freq to define how long the asset is (in seconds). This ensures mid-roll opportunities cover the full duration of the asset.

vmapg_id_key

Name of the query parameter added to the VAST tag with the ad break identifier. Defaults to breakId if not set. See the section below for information on the value of the identifier

vmapg_skip_to

Defines a timepoint before which no ad break is inserted, even if defined through other query parameters. See the dedicated section below on this option . The time point can be expressed as

  • an integer or float number, defining the time as seconds from the start of the assets (with max 3 decimals)

  • an expression in the form “HH:MM:SS” or “HH:MM:SS.sss”

⚠️ This only applies to values expressing absolute times (integer, float or time expression), or pre-rolls, but not to percentages and post-rolls

💡

Ad Server Query Parameters

Any other parameter (not starting with vmapg_) added to the query string will be passed through unchanged onto the VAST tag sent to the Ad Server.
This provides a very flexible way of defining additional query parameters that need sending to the ad server, without having to URL-encode them and add them to the value of vmapg_tag, and is in particular useful for any parameter that is set dynamically from the streaming URL (such as for dynamic macros).

ℹ️

The vmapg prefix

In a previous version, the query parameters started with bpkio_ instead of vmapg_. The change was made to be more specific and allow new functionality in the Ad Proxy (not related to VMAP generation).

It is recommended to modify your configuration and update it accordingly, but the bpkio_ remains valid for the sake of backward compatibility

Examples

  1. A schedule with just a pre-roll and post-roll, using the VAST tag https://my-ad-server.com/vast
    • vmapg_pre=true&vmapg_post=true&vmapg_tag=https://my-ad-server.com/vast
  2. A schedule with 3 mid-rolls at specific points, using the VAST tag https://my-ad-server.com/vast?campaign=123
  3. A schedule with a pre-roll and mid-rolls every 10 minutes for an asset 45 minute long, using the VAST tag https://my-ad-server.com/vast, and additional parameters to be forwarded to the ad server

Using dynamic parameters

It is likely that you will want to have some of these parameters defined dynamically for each asset in your VOD catalog, instead of being static for all assets. The Ad Proxy (VMAP Generator) supports the same functionality as other Ad Server sources, and can use macros passed in the service URL, as documented in Ad Macros.

For example, let’s say that you want to always have pre-rolls for all assets, but the mid-roll ad insertion points and category are defined on a per-asset basis with values defined by your CMS and/or player.

You could then configure the Ad Proxy (VMAP Generator) source to use queries such as vmapg_tag=https:%2F%2Fmy-ad-server.com%2Fvast%3Fcampaign=123&vmapg_pre=true&vmapg_mids=$arg_cuepoints&category=$arg_category. At playback, the mid-roll ad opportunity timing and category value would be passed as query parameter in the service URL, for example https://stream.broadpeak.io/2ab56412b1163ee1ee25696df4a230b7/bpk-vod/voddemo/index.mpd?cuepoints=30,60,90&category=teenager

Bookmarking and vmapg_skip_to

It is common for VOD streaming solutions to offer to end-users the ability to stop playback, and resume at a later point. It is commonly referred to as a "bookmarking" feature. When monetizing the content with ad breaks, it usually does not make sense to insert ads before the point from which the user will resume playback. Indeed, those ads will likely never been seen.

The vmapg_skip_to query parameter enables this scenario in an easy way. It allows you to pass the bookmark time point, and the Ad Proxy will ensure that no ad break is inserted before that point, regardless of the definition of the cuepoints passed with the vmapg_pre, vmapg_mids and vmapg_mids_freq parameters.

A typical workflow would be:

  • The user starts watching a new asset afresh. The application tracks the time position and records it regularly as a bookmark in the user's record. At some point the user stops and leaves. The bookmark is kept as it's not reached the end of the asset
    • This time record should be adjusted to ignore any ad inserted before that point in the stream, to reflect the point reached by the user in the content's timeline. If using the Broadpeak SmartLib SDK, this conversion can be done easily with the getPositionForBookmark() method
  • At a later point, the user wants to resume the asset. The application retrieves the bookmark for that asset, and adds that value to the streaming URL with the vmapg_skip_to parameter.
❗️

This functionality only applies to values expressing absolute times (integer, float or time expression), or pre-rolls.

Mid-roll expressed as percentages will still results in ad breaks to be inserted, regardless of their relative position to the bookmark point.

Ad break identifiers

To allow the ad server to differentiate between calls made for different ad breaks in the asset, the Ad Proxy adds a query parameter to the VAST tag. By default that parameter is named breakId, but you can choose a different name by setting vmapg_id_key to your own value.

The value of that parameter will be:

For pre-rolls

  • pre, if using vmapg_pre=true
  • preN, for pre-roll positions defined in the vmapg_mids parameter (values of pre, start or 0%). N is an integer starting at 1, and there could be multiple if combining these options.

For post-rolls

  • post, if using vmapg_post=true
  • postN, for pre-roll positions defined in the vmapg_mids parameter (values of post, end or 100%). N is an integer starting at 1, and there could be multiple if combining these options.

For mid-rolls

  • midN, where N starts at 1

Updated 9 days ago