VAST & VPAID

View IAB's standards, guidelines, and best practices for:

VAST
VPAID

Custom VAST Extensions

The response from an ad server may contain custom VAST extensions. These custom VAST extensions are included in the response provided for:

Live/linear streaming via the Ping method.
On-demand streaming via the Preplay method.

Extensions Array

An ad server provides custom VAST extensions in XML format. The rules through which this XML content is converted to JSON are explained below.

An ad server will return a XML tag called Extensions that contains all custom VAST elements. Each node that is directly underneath this tag will be reported as a child object of the extensions array.
The key for this child object is determined by the Extension tag's type attribute. For example, the key for the following Extension tag is "waterfall."
```
<Extension fallback_index="0" type="waterfall" />
```

This child object will contain an object for each additional attribute in its Extension tag. For example, the above "waterfall" object will contain a "fallback_index" object.

...
                     {
                        "waterfall":[  
                           {  
                              "fallback_index":"0"
                           }
                        ]
                     },
...

Nested nodes will be converted into nested objects. For example, the following "geo" object contains two nested objects (i.e., Country and Bandwidth).

<Extension type="geo">
      <Country>US</Country>
      <Bandwidth>0</Bandwidth>

The resulting JSON for the above XML is:

...
                     {   
                        "geo":[  
                           {  
                              "Country":"US"
                           },
                           {  
                              "Bandwidth":"0"
                           }
                        ]
                     }, 
...

🚧
Exception: If a nested node only contains text, then the corresponding object's key will be the tag and the object's value will be the text contained within the tag.

Example

A sample XML response from an ad server is provided below.

<Extensions>
	<Extension fallback_index="0" type="waterfall" />
	<Extension type="geo">
		<Country>US</Country>
		<Bandwidth>0</Bandwidth>
	</Extension>
	<Extension type="activeview">
		<CustomTracking>
			<Tracking event="viewable_impression">https://pubads.g.doubleclick.net/pagead/conversion/?ai=BYW1B...AHHw&sigh=qtzpMUZ5DzM&label=viewable_impression&acvw=[VIEWABILITY]&gv=[GOOGLE_VIEWABILITY]&ad_mt=[AD_MT]</Tracking>
			<Tracking event="abandon">https://pubads.g.doubleclick.net/pagead/conversion/?ai=BYW1B...AHHw&sigh=qtzpMUZ5DzM&label=video_abandon&acvw=[VIEWABILITY]&gv=[GOOGLE_VIEWABILITY]</Tracking>
		</CustomTracking>
	</Extension>
	<Extension type="metrics">
		<FeEventId>8_zT4LjWGM7gpAOa7p8Q</FeEventId>
		<AdEventId>CIDG5POK7dICFReRaQodN-kNMw</AdEventId>
	</Extension>
</Extensions>

The above custom VAST extensions will be included in the Preplay and Ping responses under the extensions array as indicated below.

...
		"extensions":[  
                     {  
                        "waterfall":[  
                           {  
                              "fallback_index":"0"
                           }
                        ]
                     },
                     {  
                        "geo":[  
                           {  
                              "Country":"US"
                           },
                           {  
                              "Bandwidth":"0"
                           }
                        ]
                     },
                     {  
                        "activeview":[  
                           {  
                              "CustomTracking":[  
                                 {  
                                    "Tracking":"https://pubads.g.doubleclick.net/pagead/conversion/?ai=BpL3zK...AYRAB&sigh;=edOT3dMFSbQ&label;=viewable_impression&acvw;=[VIEWABILITY]&gv;=[GOOGLE_VIEWABILITY]&ad;_mt=[AD_MT]",
                                    "event":"viewable_impression"
                                 },
                                 {  
                                    "Tracking":"https://pubads.g.doubleclick.net/pagead/conversion/?ai=BpL3zK...AYRAB&sigh;=edOT3dMFSbQ&label;=video_abandon&acvw;=[VIEWABILITY]&gv;=[GOOGLE_VIEWABILITY]",
                                    "event":"abandon"
                                 }
                              ]
                           }
                        ]
                     },
                     {  
                        "metrics":[  
                           {  
                              "FeEventId":"KSL1WK-fN4X6vgKH4pnoBQ"
                           },
                           {  
                              "AdEventId":"CO-FsISnrNMCFVWxTwodkIgH_Q"
                           }
                        ]
                     }
                  ],
...

VPAID

Information that facilitates the interaction between a video player and a VPAID ad unit is included in the response provided for:

Live/linear streaming via the Ping method.
On-demand streaming via the Preplay method.

📘
The ad break portion of the response for both of these methods is identical and information on it may be found in the Preplay API article.

Basic Setup

Perform the following steps:

Set up the player to perform the following tasks whenever it encounters a VPAID ad unit:
1. Display the ad.
2. Fire ad-related events.
3. Send beaconing data by leveraging the event data provided in the events object.
📘
Server-side beaconing will not be triggered for VPAID (Video Player-Ad Interface Definition) ad units.
Live/Linear Streaming Only: Enable the Ad Impressions and the Linear Ad Data features on a per session basis by setting the pingf parameter to 5.

Live/Linear Streaming

Ad slate will be inserted into a live/linear stream for the duration of each VPAID ad. By default, this allows the live/linear stream to resume immediately after the completion of the VPAID ad. However, users that interact with a VPAID ad unit may cause the ad to exceed this duration. It is important to set up your video player to handle this type of situation.

Common methods for handling this situation are:

Close the VPAID ad unit once the predefined duration has elapsed.
Set up the video player to allow live content to resume playback in the background once the predefined duration has elapsed. This allows the player to remain synched with the live stream.
Wait until the user's interaction with the VPAID ad unit has completed before submitting the next request for content. This will cause the video player to lag behind live content for the length of time between the end of the specified duration and when playback was resumed. However, it prevents a user from missing out on live content due to this ad interaction.

📘
Reduce bandwidth usage by setting up the video player to switch to a lower ray during a VPAID ad.

On-Demand Streaming

On-demand content will contain a placeholder ad for each VPAID ad unit. This placeholder ad consists of two seconds of black frames. A video player should be configured to pause playback upon detecting these black frames and resume playback once the user's interaction with the VPAID ad unit has completed.

Sample API Response

VPAID information is reported in the exact same manner for both the Ping and Preplay methods.

...
	"ads": {
		"breaks": [{
				"breakId": "0.0.0.1234567890",
				"ads": [{
						"mimeType": "application/javascript",
						"apiFramework": "VPAID",
						"companions": [],
						"creative": "https://.../ad/.../vpaid.js",
						"width": 640,
						"duration": 15,
						"height": 480,
						"events": {
							"firstquartiles": [
								"http://account.v.fwmrm.net/ad/1/1?..."
							],
							"clicktrackings": [
								"http://account.v.fwmrm.net/ad/1/1?..."
							],
							"GENERIC": "http://account.v.fwmrm.net/ad/1/1?...",
							"midpoints": [
								"http://account.v.fwmrm.net/ad/1/1?..."
							],
							"thirdquartiles": [
								"http://account.v.fwmrm.net/ad/1/1?..."
							],
							"impressions": [
								"http://account.v.fwmrm.net/ad/1/1?..."
							],
							"completes": [
								"http://account.v.fwmrm.net/ad/1/1?..."
							]
						}
					}
				],
				"duration": 15,
				"height": 0,
				"width": 0,
				"timeOffset": 0,
				"position": "preroll",
				"type": "linear",
				"events": {
					"impressions": [
						"http://account.v.fwmrm.net/ad/1/1?..."
					]
				}
			}, {
...