Using AdsWizz Multi-Ad VAST with External Channels

Overview

ART19's External Channels now supports AdsWizz's multi-ad VAST format. Instead of creating a separate External Channel for each ad position (pre-roll, mid-roll, post-roll), you can use a single External Channel to request ads across multiple positions in an episode through a single request URL to AdsWizz.

Note: This multi-ad VAST construct is exclusive to AdsWizz only. For other third-party ad servers, continue using individual External Channel campaigns per position.

How It Works

AdsWizz's Multi-ad VAST is supported through their adEvents query parameter, where you can define multiple ad breaks within a single VAST request URL. The adEvents parameter is a URL-encoded JSON array. Each AdEvent element represents one ad break. You can define up to 7 ad breaks per AdEvents array: 1 pre-roll, up to 5 mid-rolls, and 1 post-roll. You only need to include the positions you want to target. Here is the structure of a single ad break:

{
  "eventId": {{ prerollMarkerpointId }},
  "adBreakIndex": "preroll",
  "duration": {{ prerollDuration }},
  "zones": [
    { "zoneAlias": "your_preroll_zone" }
  ]
}

AdEvent Object Fields

#	Field	Description
1	eventId (required)	This is the unique identifier for the AdEvent. To ensure ads are delivered to specific markerpoints within the episode, use the corresponding *MarkerpointId macro for this value. If this ID is a random value, the ad(s) may play at any random markerpoint in the episode.
2	adBreakIndex	The position label. Must be one of: preroll, midroll_1, midroll_2, midroll_3, midroll_4, midroll_5, or postroll.
3	duration	The maximum total duration (in milliseconds) of ads that can be returned for this ad break. This can be the *Duration macro or a static value. Note: If not provided, and maxAds and maxDuration are also not provided, the default value of 60 seconds (60000 milliseconds) is used.
4	zones	A list of AdsWizz zones to request ads from for this AdEvent. When multiple zones are specified, they are used as a waterfall. If multiple zones are provided, they function as a waterfall: each zone is only used if the preceding zone's ads did not satisfy the duration threshold.

Zone Object Fields

#	Field	Description
1	zoneAlias (required)	The name of the zone alias to request ads from for this ad break event.
2	maxAds	The maximum number of ads to request from this zone. Note: If maxAds and maxDuration are both missing for a zone alias, then a default value of 1 will be used for maxAds for this zone alias.
3	maxDuration	The maximum total duration (in milliseconds) of ads that can be returned from this zone. This can be the *Duration macro or a static value. If maxDuration is larger than the top-level duration, then the top-level duration will take precedence over maxDuration.

Setting Up a Multi-Ad VAST Campaign

Step 1: Create a New External Channel

Navigate to External Channels and select "New External Channel". Give it a descriptive name (e.g. "AdsWizz Multi-VAST"). Select your AdsWizz ad server from the dropdown in the Ad Source card.

Step 2: Build the VAST Request URL

Construct the request URL with your query parameters. The key difference from a standard single-position VAST URL is The zone alias is not in the URL path (no /alias/your_zone segment). Instead, the adEvents parameter contains a JSON array defining all ad breaks and their zones.

Note: The AdsWizz AdEvents parameter will only work with VAST 4.0.

Step 3: Configure the adEvents Parameter

Enable the Ad Events JSON toggle to show the adEvents JSON template. This JSON will automatically get appended to the request URL through the ?adEvents= query parameter. The entire request URL will be automatically URL-encoded.

Enable multiple Ad Events

You are able to specify multiple ad breaks within a single request URL through multiple AdEvent objects. You only need to include the positions you want to target. For example, if you only want pre-roll and post-roll, include only those two objects in the array.

What happens if an episode doesn't have a midroll markerpoint but my adEvents includes a midroll?
ART19 only populates macros for marker points that exist in the episode. If a midroll marker point is not present in the episode, any corresponding midroll ad event in the adEvents object will be ignored, and ads will still be returned for the remaining valid ad events.

Enable Multiple Zones Per Break

You can specify multiple zone aliases per ad break object within the AdEvent object.

Configure the Volume of Ads

You can control the volume of ads returned per ad break by specifying the duration field in your AdEvent, and the volume of ads returned per zone by specifying the maxAds and maxDuration fields within each Zone object. Various permutations of these optional fields can be applied. Static or dynamic values (macros) can be used for the duration fields.

• AdsWizz recommends using either maxDuration or maxAds. If both are used, ads will be returned until one of the constraints is met.
• When setting static values for duration, always specify a duration slightly longer than the reference ad duration you expect (e.g. 66000 for a 60-second ad duration).

Example:

{
  "eventId": {{ prerollMarkerpointId }},
  "adBreakIndex": "preroll",
  "duration": {{ prerollDuration }},
  "zones": [
    {
      "zoneAlias": "my_preroll_zone",
      "maxDuration": 66000,
      "maxAds": 2
    }
  ]
}

Markerpoint and Duration Macros

These macros are specific to AdsWizz's multi-ad VAST URL and are populated automatically by ART19 at request time.

• The markerpoint macro can be used for the eventId field. Be sure to use the respective markerpoint macro you plan to target for that ad event for the eventId. If a random value is provided to the eventId, the ad(s) may play at a random markerpoint.
• The duration macro can be used for the duration or maxDuration fields. The duration macro will populate the fields with the maximum content duration of the markerpoint.

#	Position	Markerpoint Macro	Duration Macro
1	Pre-roll (the first pre-roll)	{{ prerollMarkerpointId }}	{{ prerollDuration }}
2	Mid-roll 1	{{ midroll1MarkerpointId }}	{{ midroll1Duration }}
3	Mid-roll 2	{{ midroll2MarkerpointId }}	{{ midroll2Duration }}
4	Mid-roll 3	{{ midroll3MarkerpointId }}	{{ midroll3Duration }}
5	Mid-roll 4	{{ midroll4MarkerpointId }}	{{ midroll4Duration }}
6	Mid-roll 5	{{ midroll5MarkerpointId }}	{{ midroll5Duration }}
7	Post-roll (the last post-roll)	{{ postrollMarkerpointId }}	{{ postrollDuration }}

Note: Multi-ad VAST does not currently support multiple pre-rolls or post-rolls, nor does it support generic marker point type targeting (e.g., all pre-rolls, all mid-rolls, all post-rolls). To target these positions using your AdsWizz ad source, create a new external channel with a single-tag VAST URL configured for those positions.

Migrating from Single-Position Campaigns

If you currently use separate External Channel campaigns per position (e.g. one for pre-roll, one for mid-roll, one for post-roll), you can consolidate them into a single multi-ad VAST campaign:

• Create a new multi-ad VAST External Channel campaign using the steps above.
• Add the same series to the new campaign.
• Schedule the old campaigns at a specific time.
• Schedule the new campaign to start at the same time the old campaigns end.

Important: Do not run both the old single-position campaigns and the new multi-ad campaign simultaneously for the same series and positions, as this could result in duplicate ad requests.

Additional Information

For additional information, please see the AdsWizz support article on this feature.