--- title: "Video banner reference" description: "Every field of the five video banner types, the saved-banner sections (VAST tracking, Video files, Companions), publisher video requirements, Serve from our server, the ISCI / Ad-ID code, click-through macros and the REST calls — the companion to the Video banners guide." type: "reference" audience: [network-manager] keywords: [video banner fields, VAST tracking, playback events, third-party pixels, progress points, video files, renditions, mezzanine, companions, CompanionAds, ISCI, Ad-ID, UniversalAdId, serve from our server, refresh copy, video compliance, media files API, companions API, videoFileUrl, mediaAssetId] ui_path: "Account → Advertisers → campaign → Add banner for Video Placement" --- Fetch the complete documentation index at: https://epom.com/ad-server/docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Video banner reference The companion to [Video banners](https://epom.com/ad-server/docs/guides/advertising/banner-video.md). The guide has the steps, the caveats and the fix-it checklist; this page holds every field, the saved-banner sections in full, the ISCI / Ad-ID rules, the click-through macros and the REST calls. What a stitcher receives and how several networks share one slot are on [Video in waterfalls, pods and SSAI](https://epom.com/ad-server/docs/guides/advertising/video-waterfalls-and-ssai.md). ## The five types | Type | Use when | |---|---| | **Local Video** | You have the file. Epom hosts it and wraps it in VAST. | | **External Video** | The file sits on your CDN; you give Epom its URL. | | **Third Party VAST/VPAID Tag URL** | Another ad server hands you a VAST or VPAID tag. | | **VPAID Framework** | You use an interactive framework your network administrator installed, with per-banner parameters. | | **Advanced Local Video(s) (Beta)** | You want several renditions of one creative in a single VAST response. | **Local Video** and **External Video** are also offered on **email** placements. The other three are video-placement-only. ## What each type asks for Verified by opening the create form for each type on both placement types it accepts: | Field | Local Video | External Video | VAST/VPAID tag | VPAID Framework | Advanced Local Videos | |---|---|---|---|---|---| | Banner creative (upload, **From link** or **Media library**) | ✓ | — | — | — | — (added after save: the Media files card takes an upload or **Media library**) | | Banner link (file URL) | — | **required** | — | — | — | | Serve from our server | — | optional | — | — | — | | URL (click-through) | optional | optional | **required** — the tag | optional | optional | | Title | ✓ | ✓ | **absent** | ✓ | ✓ | | ISCI / Ad-ID code | ✓ | ✓ | — | ✓ | ✓ | | Ad-ID registry | ✓ | ✓ | — | ✓ | ✓ | | VPAID framework | — | — | — | **required** | — | | In-Stream video type | — | — | ✓ | — | — | | VAST properties | — | — | ✓ | — | — | | Ad unit | — | — | — | — | — | No video type asks for an ad unit. (Ad units are required on a video placement only for the *non-video* types — HTML Code, Local File and External File.) **In-Stream video type** offers *Linear Video ad* and *Non-linear Video ad*. Only a subset of banner types can be non-linear — HTML Code, Local File, External File and the VAST tag — so the video-file types are always linear. **VAST properties** are the three wrapper switches: **Follow additional wrappers**, **Allow multiple ads**, **Fallback on no ads**. (Earlier *Sandboxed iframe*, *Always hide controls*, *Max execution time* and *Max iterations* settings were removed — they matched no IAB schema and no player read them.) **Local Video — the file.** Drop the file into **Banner creative**. The **File source** switch above the drop zone offers two other ways in: **From link**, where you paste the file's address (public http/https only, within the network's video size limit and never more than 100 MB) and it is downloaded once when you save and stored exactly like an upload — so the host need not stay online — and **Media library**, which uses a [library](https://epom.com/ad-server/docs/guides/advertising/media-library.md) video. After saving, the upload zone is replaced by a **Video file** row that plays the creative right there in the form, with download and delete buttons. Underneath it, **Video info** reports what the platform read from the file: resolution, duration, video bitrate, frame rate, codecs, container, audio, loudness and file size. With the *Video Creative Requirements* permission it also lists each linked site whose publisher spec is switched on, with whether the file is served there. Nothing in it blocks the save. **Third Party VAST/VPAID Tag URL.** Paste the tag into **URL** — required here, unlike the file types — and pick the **In-Stream video type**. This type has **no Title field**: the tag's own VAST response supplies the ad title. ## Publisher video requirements A publisher can set a video spec on a site (resolution, duration, bitrate, codecs, loudness and so on) and switch it on. An uploaded video that misses it is not served on that site. The verdict shows where you link: - **Which creatives are checked.** Only a **Local Video** (its file) and an **Advanced Local Video(s)** banner (each of its renditions). An Advanced Local Video(s) creative is served on a site when **at least one** rendition meets the spec, and that site's VAST carries only the renditions that do, best first — see [Video files](#video-files--advanced-local-videos-only). Every other creative — External Video, VAST tag, VPAID framework, HTML Code, image — reads *Not checked* and is never stopped. A spec that is switched off checks nothing. - **On the banner.** *Video info* lists each linked site, as a link to that site's requirements, with a **Meets spec**, **Not checked** or **Not served: …** badge (the reasons follow the colon). The **Linked placements** card opens with *Not served on N linked placement(s): the file misses that publisher's spec*; in the tree each failing link carries a red **Not served** pill whose tooltip lists what is missed, and the grid has a **Publisher spec** column. - **Before you link.** Ticking a not-yet-linked placement whose site spec the file misses shows a warning above **Save**: *N of the placements you are linking have video requirements this file misses: it will be linked but not served there.* The link is still made. The verdicts need the *Video Creative Requirements* permission (enabled or read-only); without it the badges, pills and warnings are absent. The spec itself is set on the site — see [Video creative requirements](https://epom.com/ad-server/docs/guides/inventory/video-creative-requirements.md). ## Video file too big? Size limit, format and compression - **Format.** A Local Video upload must be a video file — anything else is refused with "Must be video (mp4 or flv)". Whether a player can play it is a separate question: MP4 with H.264 video and AAC audio is what web and mobile players accept most widely. - **Size limit.** The upload is refused with "File is bigger than N MB" above the network's **Max allowed video file size** (20 MB by default; Epom sets it network-wide). Native video assets use the same limit. - **Epom does not shrink your file by default.** Compress the video before uploading — lower the bitrate or the resolution in any video encoder — or serve it from your own host as an **External Video**, which has no upload limit (unless **Serve from our server** is ticked, which checks the downloaded copy like an upload). - **Server-side compression (set by Epom).** Epom can configure a network to re-encode video uploads (H.264, AAC stereo, web-optimized): a Local Video file on save, and an Advanced Local Videos original into each resolution you tick. It is off by default; when it is on, the Local Video size limit applies to the **re-encoded** file. When it is off, Advanced Local Videos stores only the original you uploaded. Ask Epom support or your account manager whether it is enabled before relying on it. - **Compression never upscales.** A resolution larger than the uploaded file is not made: a 720p upload with 1080p ticked gives no 1080p rendition. An *Original resolution* that is already H.264 in MP4 (with AAC audio or none) and within the size limit is stored as uploaded, not re-encoded; any other original is re-encoded at its own size. - A **publisher's video spec** (bitrate, codec, loudness…) is checked separately, per site — see [Check video creatives against a publisher's spec](https://epom.com/ad-server/docs/guides/inventory/video-creative-requirements.md). ## Serving an external file from our server An External Video normally plays from its link on every impression, so the advertiser's host has to stay up and fast for the whole flight. **Serve from our server** keeps the link in the banner but, when you save, downloads the file behind it, checks it like an upload and plays that copy instead — the VAST `MediaFile` then points at our storage. ![Serve from our server on an External Video banner](https://epom.com/docs-images/ad-server/banner-video-reference/hosted-copy.webp) - **A changed link is downloaded again** on the next save. **Refresh copy** downloads the same link again, for a file that changed behind an unchanged address — nothing is re-fetched on its own. - **A download that fails blocks the save**, with the reason under the link (not reachable, too large, not a video, not a public address). - **Clearing the box** plays the link again and drops the copy. - The same box exists for **External File** images and **External Native** assets. ## The saved-banner video sections These exist only on a **saved** banner. If you don't see one, save the banner first. ### VAST tracking A card of its own at the bottom of the banner, on video placements only and **never for OpenRTB banners** — event tracking for RTB video comes from the bid's own markup. A new video banner starts with the events an admin set under **Default VAST tracking events → New video banners** (see [Rules, defaults and taxonomies](https://epom.com/ad-server/docs/guides/admin/rules-and-defaults.md)). Three parts: - **Playback events** — the standard VAST milestones, grouped as *Quartiles & completion* (Ad Loaded, Ad Creative View, Ad Start, the three quartiles, Ad Complete), *Interaction* (Ad Skip, Mute, Unmute, Pause, Resume, Fullscreen, Exit Fullscreen, Expand, Collapse) and *Viewability & other* (Ad Viewable Impression, Ad Repeated Viewable Impression, Ad Not Viewable Impression, Ad View Undetermined Impression). Tick the ones you want and **Save** — this section has its own Save button. - **Third-party pixels** — a tracking URL that fires on impression, on click, or on a chosen VAST event. The list shows each URL in full; click a URL or its *Fires on* value to change it in place. - **Progress points** — fire a conversion action at a custom time or percentage. The Title list is your conversion actions, so it is empty until you have some. The card opens **collapsed** and its playback events have their own **Save** button, separate from the banner's. Ticking events and pressing the banner's Save does not store them. ### Video files — Advanced Local Videos only **Video files** sits right under **Banner type**, where a Local Video keeps its file, and is always open. On a banner that is not saved yet it only says that files are added once the banner is saved — save first, then add them. Add files from one of three sources — choosing is adding, there is no separate Add step: - **Upload** — drop or pick several videos at once. Each one goes up on its own row with its progress; a file still waiting or uploading can be cancelled, and one that fails says why on its row with **Try again**. - **From link** — paste one public link per line and press **Add files**. Each link is downloaded once and stored with the creative (the same checks as a Local Video's link: reachable, a video, within the size limit); a refused link shows the reason on its own row. - **Media library** — tick several [media library](https://epom.com/ad-server/docs/guides/advertising/media-library.md) videos and **Add files**. Files the banner already has are shown ticked and cannot be picked again. A library file is referenced, not copied. If one of the picked files is refused, none is added and the refused one says why. **Resolutions** appear only where the installation's video compression is on: *Original resolution*, 1080p, 720p, 480p, 360p, 320p, 240p (the first four ticked by default) make lower renditions from an upload or a link, never one larger than the file. With compression off every file is stored as it is, so add each rendition you encoded. Every file is a card in the order the VAST serves them — **highest bitrate first, then widest**. The first card is marked **Served first · Mezzanine**: it is the file a stitcher transcodes from. A publisher whose [video spec](#publisher-video-requirements) is switched on receives only the renditions that meet it, still best first, so its stitcher transcodes from the best file it accepts. With the *Video Creative Requirements* permission each card names the linked sites it is **Served on** and those it is **Not on**, and the per-site verdicts are listed under the files. When no rendition meets a linked site's spec, a warning above the cards names that site: the creative is not served there until you add a rendition that fits. Each card shows a still with the frame height, the file name (a link-added file shows its link), where it came from (*Upload*, *Link* or *Media library*) and its facts — resolution, bitrate, duration, codecs, aspect ratio and size — plus **Play** (inline), **Download** and **Remove**. Removing a library file leaves it in the library; an uploaded or downloaded file is deleted. A card is flagged when its **duration** differs from the first file's by more than half a second (the VAST's Duration is the first file's) or its **aspect ratio** differs (players letterbox when they switch). There is no manual order. ![Video files of an Advanced Local Video(s) banner: three renditions in serving order, the first marked Served first · Mezzanine, each naming the linked sites it is served on and not on, under a warning for the linked site no rendition meets](https://epom.com/docs-images/ad-server/banner-video-reference/advanced-renditions.webp) A banner with no video file at all is **not served** — it is skipped as having nothing to play, like a Local Video without its file — so add at least one rendition before linking it. **Video files** appears only for *Advanced Local Video(s)* — a plain Local Video banner has one file and no rendition list. Switching an existing banner to Advanced does not move its file into the rendition set. ### Companions A **Companions** subsection on Local Video, External Video and Advanced Local Videos banners. Companion banners render beside the player. The subsection opens by itself once the banner has companions, and its header shows how many. **Add a companion**: pick the resource type, fill in what it needs (below) and press **Add**; a refusal is shown under the row. Four resource types: | Resource type | You provide | |---|---| | Static Resource | an uploaded image file (Local Video, Advanced Local Video(s)) or an image URL (External Video) | | HTML Resource (Static Markup) | markup, plus width and height | | HTML Resource (Template Markup) | a video-companion template, plus width and height | | IFrame Resource | a URL, plus width and height | Each companion is a card: a preview (a static image shows the image itself; HTML markup is rendered without running its scripts; a template and an IFrame show a labelled frame of their size), the size, the type, its resource, and where a click goes — a static image opens the **banner's URL**, the others carry their click in the markup, the template or the framed page. An HTML card opens a larger preview; a static card opens its image and an IFrame card its page. **Remove** asks first. ![The Companions subsection](https://epom.com/docs-images/ad-server/banner-video-reference/vast-companions.webp) ## Companion banners next to the video (VAST CompanionAds) Companions you add on the **Companion ads** card go into the VAST response as `` of the same creative as the video. Whether and where they appear is decided by the **player** (and the page around it) — the player must support companions and have a slot of a matching size; Epom only delivers them in the response. A **Third Party VAST/VPAID Tag URL** banner has no Companion ads card: whatever companions the partner's own VAST carries are passed on as they are. For a banner placed *inside* the player (an overlay or a non-linear ad), use the banner's **In-Stream video type → Non-linear** instead — see [Linear vs non-linear](https://epom.com/ad-server/docs/concepts/video-vast-vpaid-explained.md#linear-vs-non-linear-the-in-stream-video-type). A banner's companions are written into the VAST only when the banner has a click-through (landing) URL; without one the response carries the video alone. Third Party VAST tag banners and DSP video never get Epom companions — the partner's own VAST decides. ## ISCI / Ad-ID code CTV and broadcast publishers identify every spot by its industry code: the Ad-ID (formerly ISCI) in the US, or a Clearcast clock number in the UK. They check the code on delivery and reconcile their invoices against it, so it has to reach them unchanged. Enter it on the video banner, and Epom sends it in every VAST response for that creative: | VAST version | Where the code goes | |---|---| | 4.1, 4.2, 4.3 | `ABCD1234000H` and the Creative's `adId` attribute | | 4.0 | `` and the Creative's `adId` attribute | | 2.0, 3.0 | the Creative's `AdID` attribute, described by those schemas as "Ad-ID for the creative (formerly ISCI)", plus a `UniversalAdId` extension as the IAB VAST CTV Addendum 2024 defines it (see [what a stitcher receives](https://epom.com/ad-server/docs/guides/advertising/video-waterfalls-and-ssai.md#what-a-server-side-ad-insertion-stitcher-receives)) | The registry defaults to `ad-id.org`. Change it only when the code comes from another registry, for example `clearcast.co.uk`. The code and the registry each take up to 64 characters. A banner without a code keeps sending `unknown`, which is what VAST 4 prescribes when no code exists. The code is also an analytics dimension. Group a General report by **ISCI / Ad-ID** to add up delivery per spot across every banner that carries it. Filter a General report or an Impressions, Clicks or Conversions log by one or more codes; the filter offers the codes set on the banners you can report on. The logs also show the code as a column next to the banner. See [Analytics dimensions](https://epom.com/ad-server/docs/reference/analytics-dimensions.md). **Who sees it:** the code fields, the group-by, the filter and the log column all need the **Banner ISCI / Ad-ID Code** permission — ask your network admin to switch it on for the roles that traffic video. The fields appear on a **video placement** only, for Local Video, External Video, VPAID Framework and Advanced Local Video(s) — an email placement's Local or External Video has none. Without it the banner form has no code fields, the API leaves a code it is sent unchanged and lists it under `ignoredFields`, and reports offer neither the dimension nor the filter. Codes already saved keep going out in VAST whoever edits the banner. > **Corner case:** reports read the code from the banner at the time the report runs. If you > change a banner's code, its past delivery moves to the new code too — they are not stored > per impression. > **Corner case:** companion creatives in the same response keep `unknown`. The code identifies > the video spot, not the companion banner next to it. > **Corner case:** a Third Party VAST/VPAID Tag URL banner has no code field. The creative, and > its UniversalAdId, come from the other ad server's response. ## Macros in the video’s click-through URL (domain, placement, click ID) The banner's **URL** becomes the VAST ``, and it goes through the same macro processing as any landing page before it is written — so `https://offer.example.com/?src=$$PAGE_DOMAIN$$&pl=$$PLACEMENT_ID$$&cid=$$CLICK_ID$$` reaches the viewer filled in. By default the `` is Epom's click redirect with that landing page inside it, so the click is counted on the way. Two limits: - **The page domain is often not known in video.** A player that loads the VAST from its own frame sends its own address, which is never taken for the page, so `$$PAGE_DOMAIN$$` comes out empty. Pass the page in the VAST tag instead — the **Page Domain** and **Page URL** tag parameters take the player's macros, see [Passing the page from a player or ad server](https://epom.com/ad-server/docs/reference/invocation-codes.md#passing-the-page-from-a-player-or-ad-server) — and read it back as described in [Why is `$$PAGE_DOMAIN$$` empty?](https://epom.com/ad-server/docs/reference/macros.md#why-is-page_domain-or-referer_domain-empty). - **A partner's VAST tag keeps its own click-through.** On a *Third Party VAST/VPAID Tag URL* banner Epom writes a wrapper: the tag URL itself is macro-processed (so you can pass the domain or placement *to the partner*), and Epom adds its own click tracking, but the `` is the partner's, inside their VAST. Epom cannot rewrite it — ask the partner to put the parameter in their landing URL. ## Other corner cases > **Corner case — AdParameters are VPAID only.** `` appears in VPAID responses, > where it configures the VPAID unit. A plain VAST response has none. > **Corner case:** **Show skip button after (seconds)** is gated on the *Banner Video Skip Button* > permission. On networks where that permission was never granted to any role the field never > appears, whatever the placement's own skip settings say. > **Note:** for video bought programmatically, use an [OpenRTB banner](https://epom.com/ad-server/docs/guides/advertising/banner-openrtb-dsp.md) > with video mime types rather than a file type. ## Over the API - `POST /rest-api/banner/{bannerId}/update.do` takes the video settings of this page: `skipButtonShowAfterSeconds` (with the Video Skip Button permission), `returnAsIframe`, `title`, and for a VAST tag banner the three VAST 4.0 wrapper flags — which apply even when `bannerType` is not resent. `GET /rest-api/banner/{bannerId}.do` returns them. - **The file.** A **Local Video** takes a multipart `videoFile`; or `videoFileUrl`, a public http/https address the server downloads once and stores (up to the video size limit — 20 MB by default, never more than 100 MB); or `mediaAssetId`, a [Media Library](https://epom.com/ad-server/docs/guides/advertising/media-library.md) video. An **External Video** takes `videoFileLink`, with `hostExternalFiles=true` for **Serve from our server** and `refreshHostedFiles=true` (update only) to download the link again. A save reads the link to confirm it is a video and to fill **Video info**, but an update that keeps the link of a banner that already is an External Video with its video info stored does not read it again, so an unrelated update does not depend on the advertiser's host being up; a new link, a change of banner type or `refreshHostedFiles=true` reads it again. - **ISCI / Ad-ID.** `universalAdIdValue` and `universalAdIdRegistry` (an empty value clears the code). Without the *Banner ISCI / Ad-ID Code* permission they are left unchanged and listed under `ignoredFields`. - `GET /rest-api/banner/{bannerId}/video-compliance.do` returns the file's facts and, with the *Video Creative Requirements* permission, the verdict per linked site; for an Advanced Local Video(s) banner, `renditions` also gives each rendition's verdict per linked site. - The **Companions** card is `/rest-api/banner/{bannerId}/vast/companions.do`: `GET` lists, `POST` adds one without an upload (`type=STATIC` with an image URL in `externalCreativeLink`; `IFRAME` with the frame URL; `HTML_STATIC` with `markup`; `HTML_TEMPLATE` with a Video Companion `templateId` — the last three with `width` and `height`), and `DELETE .../companions/{companionId}.do` removes one. It needs the VAST Companion Ads permission. - The **Media files** card of an Advanced Local Video(s) banner is `/rest-api/banner/{bannerId}/vast/media-files.do`: - `GET` lists the renditions **in served order** (`servedFirst` on the first), each with its public `url`, `source` (`UPLOAD`, `LINK` with the `sourceUrl` it was downloaded from, or `LIBRARY` with its `mediaAssetId`) and `facts` (resolution, duration, bitrate, frame rate, codecs, container, audio, file size, loudness). It also answers `editable` and `options`: `compressionEnabled`, the `scales` that can be made, and `maxFileSizeBytes`. - `POST` uploads a multipart `file` or downloads a public `url` — checked and limited exactly like a Local Video's `videoFileUrl` — with `scaleTo` picking the renditions where the network compresses video (`ORIGINAL`, `_1080P` … `_240P`); a resolution larger than the file is left out and named in `skippedScales`. - `POST .../media-files/from-library.do` adds media library videos by reference: one as `mediaAssetId`, several at once as `mediaAssetIds`. Every file is checked first (a video you can see, within the video size limit); if one is refused, nothing is added and each refused file is named in `errors['mediaAssetIds[]']`. A video the banner already has is listed in `skipped` instead of being added twice. - `DELETE .../media-files/{mediaFileId}.do` removes one — an uploaded file is erased, a library file stays in the library. It needs the Advanced Local Video(s) permission (`whoami.may.advancedLocalVideos` for the assistant). The assistant's `creative_create` with `kind` `VIDEO_RENDITIONS` creates such a banner with its files in one step. ## Per-role notes - **Advertiser** — no **Add banner for Video Placement** on the stock role. Your network manager switches video creatives on for your role, and links them to placements. - **Network manager** — video creatives are on the stock role; a role is changed in **Admin → Users & access → User roles & permissions**. - **Can view share** — uploads and grids are read-only, the add and delete buttons on media files and companions are hidden, and the VAST tracking card appears at all only if something is already configured. Ask the owner for **Can edit** if you need to change the creative. - **Custom roles** — each video type, companions, VAST event tracking, Advanced media files and **Show skip button after** can be switched off per role. A hidden field's value sent anyway is not saved. ## Related - [Video banners](https://epom.com/ad-server/docs/guides/advertising/banner-video.md) — the guide - [Video in waterfalls, pods and SSAI](https://epom.com/ad-server/docs/guides/advertising/video-waterfalls-and-ssai.md) - [Reuse creative files with the Media Library](https://epom.com/ad-server/docs/guides/advertising/media-library.md) - [Video placements](https://epom.com/ad-server/docs/guides/inventory/placement-video.md) - [Diagnose video ad playback failures (VAST errors)](https://epom.com/ad-server/docs/troubleshooting/vast-errors-and-playback.md) - [Banner types — decision guide](https://epom.com/ad-server/docs/guides/advertising/banners-overview.md) - [OpenRTB (DSP) banners](https://epom.com/ad-server/docs/guides/advertising/banner-openrtb-dsp.md) - [Other admin tools](https://epom.com/ad-server/docs/guides/admin/admin-tools.md) — where your network administrator installs a VPAID framework