{ FOR DEVELOPERS }
Guides
LOGINGET STARTED

VAST, VMAP & Creatives

Consideration for xml payloads returned by ad servers and rules on selection of creatives

Suggest Edits

📘

VAST and VMAP protocols

A generic technical introduction to those protocols is provided in the Streaming Foundations section:

This page addresses specifically the want broadpeak.iosupports those protocols

Protocols

VAST

broadpeak.io supports VAST version 3.0.

VAST payloads marked as version 4.0 or above can be supported, provided they do not make use of functionality introduced with those standards, other than the following:

  • UniversalAdId
  • Mezzanine

VMAP

broadpeak.io supports VMAP version 1.0 and 1.01.

The VAST ads can be supplied either as external URLs (AdTagURI) or inline (VASTAdData)

Selection of MediaFile

A VAST payload contains one or more Ads. Each Ad node typically contains one Creative of Linear type, which represents the actual ad content that will be delivered to the end-user. It is common for that creative asset to be provided in different versions (different quality levels or formats), usually as MediaFiles.

<VAST version="3.0">
  <Ad id="slot_1234">
    <InLine>
      <AdSystem>Example Ad Server</AdSystem>
      <AdTitle>Sample Ad</AdTitle>
      <Creatives>
        <Creative id="1456" AdID="creative-001">
          <Linear>
            <Duration>00:00:30</Duration>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4" bitrate="5000" width="1920" height="1080" scalable="true" maintainAspectRatio="true">
                <![CDATA[http://www.example.com/creative.mp4]]>
              </MediaFile>
              <MediaFile delivery="streaming" type="application/x-mpegURL" bitrate="3000" width="1920" height="1080" minBitrate="45" maxBitrate="3240" scalable="true" maintainAspectRatio="true">
                <![CDATA[http://www.example.com/creative.m3u8]]>
              </MediaFile>
            </MediaFiles>
            <TrackingEvents>
              <!-- ... -->
            </TrackingEvents>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

Example of a VAST 3.0 payload

<VAST version="4.3">
  <Ad id="slot_1234">
    <InLine>
      <AdSystem>Example Ad Server</AdSystem>
      <AdTitle>Sample Ad</AdTitle>
      <Creatives>
        <Creative sequence="1" adId="creative-001">
          <UniversalAdId idRegistry="example-ad-id" idValue="1234567890"></UniversalAdId>
          <Linear>
            <Duration>00:00:30</Duration>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4" bitrate="500" width="640" height="360" scalable="true" maintainAspectRatio="true">
                <![CDATA[http://www.example.com/creative.mp4]]>
              </MediaFile>
              <MediaFile delivery="streaming" type="application/x-mpegURL" bitrate="3000" width="1920" height="1080" minBitrate="45" maxBitrate="3240" scalable="true" maintainAspectRatio="true">
                <![CDATA[http://www.example.com/creative.m3u8]]>
              </MediaFile>
              <Mezzanine delivery="progressive" type="video/mp4" width="1920" height="1080" fileSize="8000">
                <![CDATA[http://www.example.com/creative_mezzanine.mp4]]>
              </Mezzanine>
            </MediaFiles>
            <TrackingEvents>
              <!-- ... -->
            </TrackingEvents>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

Example of a VAST 4.3 payload

Selection Rules

When processing the VAST/VMAP payload, the platform selects one creative to insert for each Ad. The rules that define which creative is selected are as follows, and depend on whether the transcoding service is enabled on the service:

Transcoding enabled

  1. If the payload is VAST 4 and there is a Mezzanine present of type video/mp4, it is selected. If multiple mezzanines are present, the one with the highest fileSize is selected.
  2. Otherwise, the list of MediaFiles is evaluated to find a progressive file with one of the following types (in order of preference). If more than one is available, the one with highest bitrate is selected.
    1. video/mp4
    2. audio/mpeg (ie. MP3)
    3. audio/wav
    4. audio/ogg
    5. video/mp2t
    6. audio/mp2t

📘

Audio-only

If you use broadpeak.io to produce audio-only streams (eg. for online radio), the VAST payload should contain at least one file of type audio/mpeg (ie. MP3) or audio/wav.

Transcoding not enabled

The platform checks whether there is any "streaming" MediaFile with a type that matches the source's type:

  • application/x-mpegURL for an HLS stream
  • application/dash+xml for a DASH stream

📘

Hybrid

Note that this selection rule is also used if transcoding is enabled but no suitable progressive file was found in the Ad node. This enables scenarios in which some ads require transcoding, but others are already processed and insertable without further processing.

Reusability Rules

In the cases where the selected progressive creative file needs to be transcoded, broadpeak.io calculates an identifier for that creative, and looks up its cache to determine whether it has been processed before and can be reused. You should ensure that at least one of the following rules match, or there is a risk that ads will not be efficiently inserted in the streams.

The rules that define that identifier are as follows:

UniversalAdId in VAST 4

If the payload is VAST 4, and there is a UniversalAdId present, the identifier is the combination of the idRegistry and idValue attributes of the UniversalAdId node.

<Ad>
    <!-- ... -->
    <Creative>
        <UniversalAdId idRegistry="example-ad-id" idValue="1234567890"></UniversalAdId>
        <!-- ... -->
    </Creative>
</Ad>

Creative id + AdID

Otherwise, and typically for VAST 3, the identifier is the combination of the AdID and id attributes of the Creative node.

<Ad>
    <!-- ... -->
    <Creative AdID="creative-001" id="682">
        <!-- ... -->
    </Creative>
</Ad>

🚧

Constraints

  • Note that both attributes must be present
  • The AdID parameter is case-sensitive. The VAST 4.0 spec moved to the use of adId (which can also sometimes incorrectly be found in 3.0 payloads), but that attribute is not supported

MediaFile URL

If neither of the previous rules applies, the full URL of the selected MediaFile itself is used (including any query parameter).

Conformity of Ad Creatives

When the transcoding is enabled on an Ad Insertion service, broadpeak.io will transcode, package and originate the creative as HLS or MPEG-DASH format. Below is the list of supported output codecs and containers available.

Video Codecs

  • H.264 / AVC1 (ISO/IEC 14496-10)
  • H.265 / HEVC (ISO/IEC 23008-2)

Video Containers

  • MP4 (fmp4) (for DASH and HLS)
  • TS (for HLS)

Audio Codecs

  • AAC / MPEG 4-AAC (LC, HE) (ISO/IEC 14496-3)

Updated 4 months ago