Run a pre-roll waterfall across several video networks (JW Player, Google IMA)

You have four video demand partners, each with its own VAST tag, and you want the player to try them in order — the first that fills plays, the rest are skipped. This page shows the two ways to build that with Epom and the one setting that turns a waterfall into “play everything”.

Who this is for

Network managers and publishers running in-stream video. You need a Video Placement and Third Party VAST/VPAID Tag URL banners (one per partner tag).

Prerequisites

• Your role can create video placements (Video Placements) and Third Party VAST tag banners (Third Party VAST/VPAID Tag URL).
• The VAST tag of every partner, and to know which macros each one expects in it.
• A video player that can take a list of fallback tags (JW Player’s ad schedule, your own Google IMA code) if you choose Option A.

Steps

1. Create one Third Party VAST/VPAID Tag URL banner per partner tag, with the partner’s macros filled in — see Macros in the partner’s VAST tag.
2. Keep Return (ads in pod) at 1 on the video placement(s) you will use, and leave maxAds off the tag URL — see the next section for why.
3. Build the order: one placement per partner, ordered in the player (Option A), or one placement with priorities (Option B).
4. Load a test page with the player and confirm a single ad plays and an empty partner falls through.
5. After a day of traffic, check fill per partner — see Reading fill per network.

Why the player plays every ad: one VAST response = one ad, unless you ask for a pod (sequence)

For each request to a video placement Epom picks one banner by priority, weight and targeting and returns it. A Third Party VAST/VPAID Tag URL banner is returned as a VAST Wrapper that points the player at the partner’s tag.

The placement’s Return (ads in pod) setting (or maxAds on the tag URL) changes that: with a value above 1 Epom returns several <Ad> elements in one VAST and numbers them with sequence="1", sequence="2"… A numbered set is an ad pod in the VAST standard — players including JW Player and Google IMA play every ad in it, one after another. That is why a “waterfall in one tag” built with a pod shows the viewer four ads instead of the first one that fills. Keep Return (ads in pod) at 1 for a waterfall.

Option A — the player runs the waterfall (recommended)

1. Create one Video Placement per partner — Pre-roll — network 1, Pre-roll — network 2…
2. In each, link the one Third Party VAST/VPAID Tag URL banner for that partner.
3. Copy each placement’s VAST tag (Ad Tags & API → VAST Tags).
4. Give the player the tags in order as its fallback list — in JW Player the ad schedule’s list of tags for the slot, in Google IMA your own code requesting the next tag on an AdError or empty response.

The player tries tag 1; if the partner returns no ad, it moves on to tag 2. Epom then sees a request on every placement the player reached, so each placement’s Fill Rate is that network’s fill rate — the per-network picture you cannot get from a single tag.

Option B — one Epom tag, Epom chooses

Link all partner banners to one video placement with Return (ads in pod) = 1 and order them with campaign priority and weight, or with daisy chaining. Epom returns the single best eligible wrapper per request.

What Epom cannot know is whether the partner behind that wrapper will actually fill — it learns that only when the player fires the ad’s Error URL. A wrapper whose partner is empty is a missed ad for that request; there is no second wrapper in the same response to fall back to. Use this when the partners fill reliably and you mainly want Epom’s targeting, capping and priorities; use Option A when fill per partner varies.

The VAST 4 wrapper flags

A Third Party VAST/VPAID Tag URL banner has VAST 4.0 Wrapper properties: Follow additional wrappers, Allow multiple ads and Fallback on no ads. They become the followAdditionalWrappers, allowMultipleAds and fallbackOnNoAd attributes of the <Wrapper> — only when the tag is requested as VAST 4.0 or later (the VAST Tags tab’s version picker; 4.2 by default). On VAST 2.0 and 3.0 tags they are not sent.

They tell the player how to treat the partner’s answer behind this one wrapper — whether it may unwrap further, accept a pod from the partner, or fall back when the partner is empty. They do not turn several Epom ads into a waterfall, and players differ in how strictly they honour them; a numbered pod is played in full regardless.

Macros in the partner’s VAST tag

The tag URL in the banner is macro-processed before it goes into the wrapper, so partners get the page and device data they ask for. Common ones:

Partner wants	Macro
Page URL (encoded)	$$REFERER_ESC$$
Page host / domain	$$REFERER_DOMAIN$$ (host, subdomain included)
Cache-buster	$$RANDOM$$ or $$TIMESTAMP$$
Viewer IP / user agent	$$REMOTE_IP_ESC$$, $$CLIENT_USER_AGENT_ESC$$
App bundle, device ID, consent	$$BUNDLE$$, $$IFA$$, $$GDPR$$, $$GDPR_CONSENT_IAB$$
A value your player passes	$$CUSTOM_PARAM_ESC(name)$$ for &cp.name=… on the Epom tag

A macro with no value is removed rather than left in the URL. The page URL comes from the requestUrl parameter if the player sends it, otherwise from the request’s Referer — for a player inside an iframe or an app that is often not the article, so pass requestUrl on the Epom tag. Full list: Macros reference.

Companions and AdParameters

• Companion ads (a banner shown beside the video) are added from a video banner’s Companion ads card — on Local Video, External Video and Advanced Local Videos banners, and only when the banner has a landing URL. A Third Party VAST tag passes on whatever companions the partner’s own VAST contains; whether the player displays them is up to the player.
• AdParameters appear only in VPAID responses, where they carry the VPAID unit’s settings. A plain VAST tag has no AdParameters; to hand your player extra data use the banner’s title (the <AdTitle>, macros allowed) or companions.

Reading fill per network

• Option A: Fill Rate per placement in a General report is the per-network fill.
• Option B: requests cannot be split by advertiser, so General shows no fill per partner. Compare each banner’s impressions with the placement’s requests, and read the Advanced report’s No ads, which also counts player Error pings — see Analytics discrepancies.

Corner cases and gotchas

Corner case: maxAds on the tag URL wins over the placement’s Return (ads in pod). A tag copied from an older setup with maxAds=4 still asks for a four-ad pod after you set the placement to 1. Values outside 1–20 are ignored and the placement setting applies.

Corner case: a VMAP request is not a waterfall either — without maxAds it returns up to the placement’s VMAP pre-roll count of ads for each break.

Corner case: the wrapper flags are dropped on a VAST 2.0 or 3.0 tag. If a partner relies on Fallback on no ads, give the player a VAST 4.x tag.

Corner case: in Option B a wrapper whose partner returns nothing is a lost request — Epom has already answered with that one wrapper and cannot offer the next. Only the player (Option A) can move on to another tag.

Corner case: a paused video placement does not offer its tag in the new interface, and a paused placement serves nothing — a player still holding that tag skips straight to the next one, which shows up as zero requests on that placement rather than as low fill.

Per-role notes

• Publisher: builds the placements and copies the tags; the partner banners are usually created by the network manager or an advertiser account and linked to the publisher’s placements.
• Network manager: can do both sides, and sees fill per placement and per banner in reports.
• Custom-role users: without Third Party VAST/VPAID Tag URL the banner type is not offered; without Video Placements the placement type is not offered; the Companion ads card needs VAST Companion Ads. See Video banners.

Related

• Video banners
• Video placements
• Sell pre-roll video in your player
• Diagnose video ad playback failures
• Set up daisy chaining and passbacks