Introduction

VAST (Video Ad Serving Template) is a specification defined and released by the Interactive Advertising Bureau (IAB) who sets a standard for communication requirements between ad servers and video players to display video ads.

Using VAST, a digital signage player can automatically request an ad from an ad server, display it and report back to the ad server. This is important for advertisers because it gives them control of their ads and provides them live impression and tracking data.

To link the stacks platform to an ad server, special web addresses are used. These web addresses (also known as URLs) are issued by the ad server and will typically be provided by an advertising agency.

Ad servers that require JSON to posted as part of the request to further customise the advert selection process are supported. Both the address and the POST can be dynamically customised using macros which are variables in square brackets.

Example DooH ad servers include Hivestack and Place Exchange. We also have an adapter built in that converts Vistar Media JSON responses into VAST responses for use on our players.

Any ad server that returns a VAST response should be compatible with our implementation.

Linking a sequence to VAST

To link the sequence into stacks, perform the following steps:

1. On the Sequences tab, click Add Sequence to display the Sequence dialog.
2. On the General tab, enter a Label for the new sequence e.g. My VAST Ads.
3. In the Type dropdown menu, select Populated by Ad Server.
   
4. Enter the ad server address in the Ad Server Address field.
5. If required, enter request body in the Ad Server Data field.
6. Click Save.

If Preview in admin interface is selected, the new sequence will be displayed in the admin interface. Please note, the ads shown may not be the same as those played by the player. This is because most ad servers dynamically change the ads based a variety of metrics and the players will be issued different responses. Many ad servers will return no ads, in which case an error will be displayed. Please make sure you test the ad server setup on the output screen. It is recommended to leave Preview in admin interface disabled so it does not interfere with ad server metrics.

To display the ads within your main sequence of content, add a new item in your main sequence that displays the VAST sequence as an inner sequence.

1. On the Sequences tab, click the Open button on your main content sequence.
2. Click the Add button in an available slot to display the Stack item dialog.
3. On the Display tab, select Inner sequence from the top dropdown menu.
   
4. Select your VAST sequence from the Sequence dropdown menu.
5. Click Save.

Ad Server Setup Examples

Hivestack Setup Example

When displaying the same sequence on multiple screens, it is useful to move the Hivestack UUID out of the sequence's Ad Server Address into the screen data. 

Add the field hivestackUuid into screen data populated with the screen UUID provided from Hivestack.

The sequence Ad Server Address should then reference the data field as a VAST macro (square brackets):

For Testing:

https://uat.hivestack.com/nirvana/api/v1/units/[hivestackUuid]/schedulevast

For Live:

https://apps.hivestack.com/nirvana/api/v1/units/[hivestackUuid]/schedulevast

Ad Servers for digital signage often require additional data to supplement what is specified in the address. This data is typically JSON sent in the body of the ad request. Platforms such as Place Exchange (OpenRTB) and Vistar (Custom) can be sent supplemental data by populating the Ad Server Data field.

Place Exchange Setup Example

Ad server address provided by Place Exchange

Ad server data example:

{
  "deals":[
    {
      "at":3,
      "bidfloor":1,
      "bidfloorcur":"USD",
      "name":"prod-video-test"
    }
  ]
}

Vistar Setup Example

Ad server address provided by Vistar

Ad server data example:

{
  "api_key": "VISTAR-API-KEY",
  "network_id": "VISTAR-NETWORK-ID",
  "venue_id": "VISTAR-VENUE-ID",
  "device_id": "[screenId],
  "display_time": [PROJECTED_DISPLAY_TIMEUNIX],
  "latitude": [gpsLatitude],
  "longitude": [gpsLongitude],
  "display_area": [
   {
    "id": "[screenId]",
    "supported_media": ["image/jpeg","video/mp4"],
    "allow_audio": true,
    "width": [screenWidth],
    "height": [screenHeight],
    "min_duration": 1,
    "max_duration": 100,
    "static_duration": 5
  }
  ]
}

Replace RED with values provided from Vistar. These values can be moved into screen data and referenced using macros similar to the Hivestack example above.

Do not provide gpsLatitude or gpsLongitude if device is not mobile

Important implementation details

SignageNode

glplayer-2022-05-20.apk+

signagenode-2022-07-23.apk+

SignageNode (previously GLPlayer) prepares VAST items a few seconds before they are due to display (as arranged in the sequence / playlist). This period is known as the Prepare Period and can be configured on the SignageNode settings page. If there are any problems during this period, the item is silently skipped and playback progresses to the next item.

Errors and skip notifications are added to the messages section on the status page.

If multiple items referring to VAST sequences are stacked, the top most item that returns an ad will be displayed.

The first time an advert is played it is cached while playing. If the advert media address is the same for subsequent plays, the media is read from the internal cache. Some ad servers do not maintain consistent addresses for the media. This will waste bandwidth unfortunately.

Standard player 

android-player-25.0.apk+

Our standard digital signage player software must download videos fully before they play. This presents difficulties when using VAST as VAST is designed for streaming. To work around this limitation, the standard player downloads asynchronously to playback.

1. Communication with the ad server occurs approximately 5 minutes before the advert is projected to be displayed. (or duration of loop if shorter).
2. The most suitable media files are downloaded to local storage.
3. The VAST sequence becomes ready for display.
4. When the main sequence progresses to the ad server populated sequence, it will be displayed.

Since preparing the ad server populated sequence occurs asynchronously to playback, ad servers must not assume that playback occurs immediately after downloading the VAST. There will typically be a 5 minute delay before the ad is displayed. The ad will not be displayed if it fails to download within 5 minutes. After displaying the ad, it will be invalidated to trigger repeat communications with the ad server 5 minutes before it is next required.

Sequences are dynamic, which means scheduling is only approximate. VAST requests will occur approximately 5 minutes before the item is displayed, but may be 0 to 10 minutes (see vastMaxAge below).

For tracking both impressions and playback progress, the VAST must correctly define Impression and Tracking events. The player will perform these callbacks synchronously to playing the ad.

In general, digital signage players are not interactive. For this reason interactive options such as skipping ads and clickable web links are not supported.

VAST Features supported

Features supported:

• VAST 2.0 to 4.2 XML responses
• Vistar JSON responses (when address contains vistarmedia.com)
• Linear MP4 video creatives
• Impression reporting
• Wrappers
• AdPods (multiple ads)
• Closed caption files (VAST 4.1+)
• Expires
• Error reporting
• Tracking

loaded
start
firstQuartile
midPoint
thirdQuartile
complete
progress

• Macros:

[TIMESTAMP]
[CACHE_BREAKER]
[CACHEBUSTING]
[ERRORCODE]
[VASTVERSIONS]
[CLICKTYPE]
[PLAYERSTATE]
[PLAYERSIZE]
[LATLONG]
[ADTYPE]
[ADSERVINGID]
[START]
[DURATION]
[DVC_SID]
[DEVICEID]
[IP_ADDRESS]
[USER_AGENT]
[CLIENTUA]
[GIVN] (see advanced options)

A macro matching screen data can also be used.

[screenId] will be replaced with the screen id of the device making the request.

Features not supported:

This is a native Java implementation. HTML, CSS and JavaScript features are not supported. The following features are also ignored.

• Icons
• Categories
• Ad verification code
• Non-linear ads
• Companion ads
• VPAID
• Video clicks
• Skippable ads

Advanced options

Advanced options can be added to screen data:

[GIVN] is populated using the Google PAL library (SignageNode-2024-06-24+ only).

The app id (or bundle id) incorporated into the [GIVN] parameter will be DS Loader:

net.targetr.stacks.central

The following parameters can be set in screen data to be added to this encrypted field:

The following advanced options are supported within the VAST sequence data (standard player only):

VAST Response Example

The VAST XML structure can be checked by opening the VAST URL in a web browser. It should look something like this:

<VAST version="2.0">
 <Ad>
  <InLine>
   <AdSystem version="1.0">My Ad System</AdSystem>
   <AdTitle>My Ad</AdTitle>
   <Impression>http://example.com/impression</Impression>
   <Creatives>
    <Creative>
     <Linear>
      <Duration>00:00:10</Duration>
      <MediaFiles>
       <MediaFile delivery="progressive" type="video/mp4">
         http://www.example.com/video-ad.mp4
       </MediaFile>
      </MediaFiles>
     </Linear>
    </Creative>
   </Creatives>
  </InLine>
 </Ad>
</VAST>

The stacks platform supports VAST versions 2.0 to 4.2 as defined at the top of the XML. Ensure media file delivery is progressive. Also ensure the type is video/mp4.