<Impression id="myserver">
  http://ad.server.com/impression/dot.gif?s=x]]>x
</Impression>

Not enclosed in a CDATA section.

<Impression id="myserver">
  <![CDATA[http://ad.server.com/impression/dot.gif?s=x]]>x]]>
</Impression>

CDATA section used but appears to end early because of the ]]> characters before the x, potentially allowing content injection attacks.

<Impression id="myserver">
  <![CDATA[http://ad.server.com/impression/dot.gif?s=x]]]]>
  <![CDATA[>]]>x
</Impression>

Correct and backwards compatible.

Finally, a VAST-compliant ad response must conform to certain additional dependencies that cannot be expressed in the VAST 4 XSD. For example, one ad type of either <InLine> or <Wrapper> is allowed but not both. Another example is the protocol for providing 3 readyto-serve media files, ideally separate from any interactive components (see section 3.9). The XSD can only validate for whether you’ve provided a URI under <MediaFile>; it cannot validate whether the appropriate files have been provided. Such dependencies are further described throughout this document.

2.3.4 Tracking

VAST tracking is implemented using a number of individual tracking elements that map to video events, such as video start or video completion. Each of these elements contains a reference to a server-side resource, which historically has been an 1x1 pixel image, but may also be a script or document reference. Calls to these resources are counted by the ad server or other measurement vendor to tally up the total for a specific video event.

The media player is required to request the resource file for any included tracking elements from the URI provided at the appropriate times, or “fire” the tracking element. Advertisers and publishers depend on accurate tracking records for billing, campaign effectiveness, market analysis, and other important business intelligence and accounting. Good tracking practices throughout the industry are important to the success and growth of digital video and audio advertising.

The use of multiple impression URIs enables the ad server to share impression-tracking information with other ad serving systems, such as a vendor or partner ad server employed by the advertiser. When multiple impression elements are included in a VAST response, the media player is required to request all impressions at the same time or as close as possible to the same time. Any significant delay between impression requests may result in count discrepancies between ad serving systems.

2.3.5 VAST Wrappers

Wrappers provide a way for one ad server to redirect a media player to another, secondary ad server to retrieve an ad, multiple ads, or yet another VAST Wrapper.

One ad server may redirect to another for a variety of reasons:

• The first ad server has selected a specific advertiser campaign to fill the inventory. In this case the redirect instructs the secondary ad server to return specific ads from a particular ad campaign.
• The first ad server is delegating a specific piece of inventory for either a single ad or an entire Pod of ads to the secondary ad server to fill with any ads that are within an established agreement between the two parties.
• An ad server may wish to delegate delivery of the specific ad creative file(s) to a separate asset repository/host (ad cloud).
• An ad server may have no ad to return and may return a redirect to a backfill provider.

2.3.5.1 Infinite Loops and Dead Ends

When serving an ad involves a chain of Wrappers, an infinite loop is possible where a chain of Wrappers never results in a final InLine VAST response. Another case involves a finite number of VAST Wrappers in which the resulting InLine response is used as a decisioning mechanism to find an ad instead of delivering the ad as required. In these cases, the decisioning mechanism may never return an ad or may take too long to return the ad.

In general, VAST Wrappers should be limited to five before resulting in an InLine response. If the player detects more than five Wrappers, the player may reject any subsequent responses in the chain, replace the [ERRORCODE] macro in the VAST/Ad/Wrapper/Error URI if provided to indicate that the Wrapper limit was reached, and move on to the next option for an ad. Error codes should be sent for all wrappers in the chain where provided.

When an InLine response fails to produce an ad within the timeframe identified in VPAID or other ad framework, the player may reject the ad, send error code 304 to indicate that no ad was produced in the given timeframe, and move on to the next option for an ad. Error codes should also be sent to any wrappers preceding the InLine response.

2.3.5.2 Wrapper Conflict Management and Precedence

When creative elements, such as Companion creative or click-throughs, are included directly in the Wrapper response, conflict may occur. In a VAST ad, whether served with multiple Wrappers or in one Inline response, all creative offered is intended to be part of the same creative concept, and the media player should attempt to display all creative presented in the response (or in a chain of responses). However, when a conflict occurs, the media player should favor creative elements offered closest to the InLine response.

For example, if a wrapper contains companion creative and the InLine response also contains companion creative, the companion creative in the Inline response should be selected (unless both creative can be displayed without conflict).

In another example, if the InLine response is absent of any companion creative but two or more Wrappers contain companion creative, then creative for the Wrapper served closest to the InLine response should be favored. However, if multiple creative can be served without conflict, the media player should attempt to display whatever creative it can.

With respect to ClickThrough handling, if the InLine response doesn’t include a ClickThrough element and one or more of the calling Wrappers includes a ClickThrough element, then the ClickThrough element closest to the InLine response must be favored. Similarly, if the inLine response includes a ClickThrough element then this must be favored over ClickThrough element(s) specified in calling Wrappers.

Error Reporting

The element enables the media player to provide feedback to ad servers when an Ad cannot be served. In VAST 3.0, detailed error codes and specifications for format are provided to enable detailed error logging for better ad serving diagnostics.

Providing more detailed error codes enables stronger diagnostics and enables better technology development over time. If ad servers can collect more detailed information about why their ads or specific creative couldn’t be served, they can improve their systems to produce fewer errors.

The element is an optional element nested within the or element. It is used to track errors for an Ad. An error for an Inline Ad that is part of a chain of Wrappers will produce an error for each of the Wrappers used to serve the Inline Ad.

An element is also provided at the root VAST level and is primarily used to report a “No Ad” response. See section 2.3.6.4) for more information. 2.3.6.1 Ad Server Details: Element An element includes a URI that provides a tracking resource for the error. This error-tracking resource is called when the media player is unable to display the Ad.

The following example is a sample VAST response that includes the element for an Inline Ad.

<InLine>
…
<Error>
<![CDATA[http://adserver.com/error.gif]]>
</Error>
…
</InLine>

If the ad server wants to collect more specific details about the error from the media player (as listed in section2.3.6.3), an [ERRORCODE] macro can be included in the URI. 2.3.6.2 Media Player Details

If an error occurs while trying to load an Ad and the element is provided, the media player must:

• Request the error source file using the URI provided.
• Replace the [ERRORCODE] macro, if provided, with the appropriate error code listed in the table in section 2.3.6.3. At a minimum, error code 900 (Unidentified error) can be used, but a more specific error code benefits all parties involved.

If the Ad was served after a chain of Wrapper ad responses, the media player must also return error details as listed above for each Wrapper response that also includes error parameters. Macro responses must be correctly percent-encoded per RFC 3986.

The following table lists VAST error codes and their descriptions.

VAST Error Codes Table

No Ad Response

When the ad server does not or cannot return an Ad, the VAST response should contain only the root element with optional element, as shown below:

<VAST version="4.1">
<Error>
<![CDATA[http://adserver.com/noad.gif]]>
</Error>
</VAST>

The VAST element is optional but if included, the media player must send a request to the URI provided when the VAST response returns an empty InLine response after a chain of one or more wrappers. If an [ERRORCODE] macro is included, the media player should substitute with error code 303. Besides the VAST level resource file, no other tracking resource requests are required of the media player in a no-ad response in either the Inline Ad or any Wrappers.

Industry Icon Support

Several initiatives in the advertising industry involve using an icon that overlays on top of an Ad creative to provide some extended functionality such as to communicate with consumers or otherwise fulfill requirements of a specific initiative. Often this icon and its functionality may be provided by a vendor, and is not necessarily served by the ad server or included in the creative itself.

One example of icon use is for compliance to certain Digital Advertising Alliance (DAA) selfregulatory principles for interest-based advertising (IBA). This section provides an overview of how media players can support the use of icons in a general manner while using the DAA’s AdChoices program, as a specific example.

Icons are optional for audio, and can be used in the context of a companion banner. But since audio ad players are not required to have a rendering engine, icons are not a requirement when the adType is “audio” or “hybrid”.

Icon Use Case: AdChoices for Interest-Based Advertising (IBA)

The Digital Advertising Alliance (DAA) sets forth principles that endeavor to give consumers a better understanding of and greater control over ads that are customized based on the consumer’s online behavior. This control is made available to the consumer in the form of the AdChoices icon, which is displayed in a prominent location in or around the Ad creative.

When a consumer clicks the icon, they may be offered: information about the ad server and data providers used to select the Ad, options to learn more about online behavioral advertising (OBA), and the ability for consumers to opt out from receiving OBA ads in the future.

The Element VAST 3.0 introduced the element, which is offered under the creative element for both Inline and Wrapper ad elements.

The following diagram illustrates the general process for how the element is represented in a VAST response.

The Icon Provider Server represented in this diagram may be the same server that serves the VAST response but more commonly, is a vendor that serves the icon from its own systems.

When the element is included in the VAST response, the media player must display the object as an overlay on top of the Linear Ad with which the icon is served and after the ad has started (i.e. first frame of video is displayed in the player).

Viewability Verification and Interactive Linear Creative

VAST 4 adds new sections in the Linear file for viewability, ad verification, and interactive creative files. These new sections offer performance and measurement benefits but also add a level of complexity.

Player compliance with VAST 4 requires appropriate execution of these files. The player should execute the ad in the following order:

1. Start loading verification resources.
2. Start loading video assets and interactive resources.
3. Initialize interactive resources.
4. Start ad playback.

Player expectations on these added features are summarized here and further defined in their corresponding sections.

Publisher Viewability

Publishers have the option to offer viewable impression tracking on the ad using the <ViewableImpression> feature added in VAST 4. Three URIs may be provided to track whether the ad was <Viewable>, <NotViewable>, or <ViewUndetermined> (see section 3.5).

Note that this feature is specific to (the likely uncommon) situation where the publisher is the party monitoring ad geometry and making the viewability determination. As such, it will very likely be limited to situations where the buyer and seller have some prior relationship and agreement around measurement mechanics and the viewability standard used. It is not a general replacement for, nor should it be confused with, measurement and reporting of viewability by third-party verification services (as in section 2.4.2). These URIs are not intended for reporting viewability determinations from such parties.

This feature is not applicable to audio ads.

Viewability with Ad Verification Services

Ad Verification services can be requested for measurement by adding a <Verification> element under <AdVerifications> including their executable resources and associated per-impression metadata. Multiple vendors may use this feature to measure the same ad session. All verification resources listed in the VAST should be executed, including those from any intermediary VASTs, barring exceptions based on a whitelist or other pre-defined rules as outlined below.

A VAST 4 player must check for these elements, however, players may optionally either: refuse to execute unknown resources or declare it as not supported. The recommended process is to consult an IAB TechLab-provided/certified list of known verification vendors and domains, although the exact mechanism is left to the publisher/player. The player must request each associated verificationNotExecuted tracking event URI (with the [REASON] macro filled with reason code 1) in the case that it refuses to execute one or more verification script (see section 3.17.4 for details).

Verification resources should be executed as required by the OMID specification. If the code cannot be executed as provided, any included verificationNotExecuted tracking events URIs must be sent with the appropriate reason code (e.g. not supported, error, etc.).

Interactive Linear Creative Files

In VAST 4, the <MediaFile> should only be used to include video or audio files. For Linear files that require an API framework to be executed, the new <InteractiveCreativeFile> should be used to include these files. Once the <AdVerifications> element has been checked for verification code, the element should be checked for code in order to execute the ad. When the <InteractiveCreativeFile> cannot be executed, the <Error> should be sent and the player may check the <MediaFiles> element for any media files that are available to be played.

This script asset should only be used to enable interactive, dynamic or other creative capabilities and not used for viewability, client-side arbitration, or other non-creative uses.

VAST Implementation

VAST is an XML schema for providing metadata about an ad for in-stream video or audio that is parsed by a player or by a server on the player's behalf. This section provides the details for forming the VAST.

Beginning with section 3.1, each element available in VAST is described and a table summarizes information about hierarchy, requirements, and attributes. Each VAST element that includes nested elements is defined under a second-level heading in this document.

Third-level headings represent nested elements that have no additional nested elements under them.

Links to the table of contents (TOC) and the schema are provided under each heading to aid in navigation. The human-readable schema in section summarizes VAST elements and provides a link to the chapter that describes the element in more detail.

Before forming a VAST document, considerations for the XML namespace and browser security for JavaScript or other scripting languages should be established as follows.

XML Namespace

Whenever VAST is used in conjunction with any other XML template, such as with VMAP or VAST extensions, a namespace should be declared for each so that the elements of one are not confused with the elements of another.

For more information, visit: http://www.w3.org/TR/REC-xml-names/

Browser Security

Modern browsers restrict Adobe Flash and JavaScript runtime environments from retrieving data from other servers. Since typical VAST responses come from other servers, measures must be taken for each.

Cross Origin Resource Sharing (CORS) for JavaScript

In order for JavaScript media players to accept a VAST response, ad servers must include a CORS header in the http file that wraps the VAST response. The CORS header must be formatted as follows:

Access-Control-Allow-Origin: <origin header value> Access-Control-Allow-Credentials: true

These HTTP headers allow an ads player on any origin to read the VAST response from the ad server origin. The value of Access-Control-Allow-Origin should be the value of the Origin header sent with the ad request.

Setting the Access-Control-Allow-Credentials header to true will ensure that cookies will be sent and received properly.

Note: For requests where the Origin header is null, ad servers should respond with only Access-Control-Allow-Origin: * (and no Access-Control-Allow-Credentials header) to prevent breaking on originless requests, such as those from iOS wkwebviews.

For more information, visit http://www.w3.org/TR/cors

Declaring the VAST Response

All VAST responses share the same general structure. Each VAST response is declared with as its topmost element along with the version attribute indicating the official version with which the response is compliant. For example, a VAST 4.1 response is declared as follows:

<VAST version="4.1">
As with all XML documents, each element must be closed after details nested within the
element are provided. The following example is a VAST response with one nested <Ad>
element.
<VAST version="4.1">
<Ad>
<!--ad details go here-->
</Ad>

VAST

VAST is the root node for a VAST-compliant ad response and is used to declare the VAST 3.2 VAST response as described in section 3.1.

*either <Error> or <Ad> may be provided but not both

Error (VAST)

Used to report a no-ad response. When the ad server does not or cannot return an Ad, the VAST response should contain only the root <VAST> element with one or more <Error> elements, as shown below:

<VAST version="4.1">
<Error>
<![CDATA[http://adserver.com/noad.gif]]>
</Error>
</VAST>

The VAST <Error> element is optional but if included, the media player must use the URI provided to notify the server that no ad was returned. Multiple <Error> elements may be provided to notify multiple parties of the no-ad response.

Ad

The <Ad> element may contain an <InLine> ad or a <Wrapper>. The wrapper points to a secondary server for another VAST response, which may be another wrapper or an InLine response. An InLine response contains the ad creative necessary to execute ad playback.

Ad Pods and Stand-Alone Ads

While a single <Ad> element represents the most common VAST response, multiple ads may be included as either stand-alone ads or a Pod of ads, or a mix of both. Ads in a Pod are distinguished by using the sequence attribute for an <Ad>, denoting which ad plays first, second, and so on. If the player supports Ad Pods, sequenced ads are played in numerical order and all ads in the Pod should be played to the best of the player's ability. All sequence values in a VAST response must be unique.

Non-sequenced ads, are stand-alone ads and considered part of an "ad buffet" from which the player may select one or more ad to play in any order. Stand-alone ads may be included in a VAST response with an Ad Pod and may be used to substitute an ad in the Pod when an ad cannot be played.

The following diagram illustrates some options for how the element may be represented in a VAST response.

If the media player cannot display an entire Ad Pod or any stand-alone ads, it can decline from loading the ad resources and use the error URI, if provided, to notify the server.

Playing a Pod of Ads

When electing to play a Pod of ads returned by the ad server, the media player must play the ads in the Pod in the prescribed sequence and should play as many of the ads as possible. The player may elect to truncate any ads at the end of an Ad Pod if either: the ads cannot be played because they cannot physically fit into the ad break in the stream (such as when time is limited in a live stream) or if the Pod violated any limits specified by the media player request (for example: number of ads to return, or maximum pod duration).

When an Ad Pod is the result of following a VAST <Wrapper> the same impression and tracking URIs in the VAST <Wrapper> are called as each ad in the Pod is played.

Should an ad in the Pod fail to play, the media player should substitute an un-played stand-alone ad from the response. If stand-alone ads are unavailable, the player should move on to the next ad in the Ad Pod.

If a Wrapper is used to provide an ad in the Ad Pod, the Wrapper can use attributes, allowMultipleAds=false and followAdditionalWrappers=false to prevent performance issues that result from an unmanaged string of Wrappers and multiple ads in an Ad Pod.

| Media Player Implementation Note | If multiple <Ad> elements are provided with sequence attributes and the player supports Ad Pods, all ads in the Pod must be played to the best of the player's ability. If not supported or the Pod cannot be played, the media player should use the error-tracking URI, if provided, to notify the server. A special exemption exists when using VMAP. Please visit http://iab.com/vmap for information on VMAP. |

The Ad Element

Properties for the element are listed in the following table.

*The Ad element requires exactly one child, which can either be an <InLine> or <Wrapper> element.

InLine

Within the nested elements of an <InLine> ad are all the files and URIs necessary to play and track the ad. In a chain of <Wrapper> VAST responses, an <InLine> response ends the chain.

| Player Support | Required | | Required in Response | One of <InLine> or <Wrapper> is required, but both are not allowed | | Parent | Ad | | Bounded | 0-1 | | Sub-elements | AdSystem*, AdTitle*, Impression*, AdServingId*, Category, Description, Advertiser, Pricing, Survey, Error, Extensions, ViewableImpression, AdVerifications, Creatives*, Expires |

*required

3.4.1 AdSystem

The ad serving party must provide a descriptive name for the system that serves the ad. Optionally, a version number for the ad system may also be provided using the version attribute.

3.4.2 AdTitle

The ad serving party must provide a title for the ad using the element. If a longer description is needed, the element can be used.

3.4.3 AdServingId

Any ad server that returns a VAST containing an ad must generate a pseudo-unique identifier that is appropriate for all involved parties to track the lifecycle of that ad. This should be inserted into the <AdServingId> element, and also be included on all outgoing tracking pixels. The purpose of this id is to greatly reduce the amount of work required to compare impression-level data across multiple systems, which is otherwise done by passing proprietary IDs across different systems and matching them.

This value should be different for each <InLine> in a VAST (i.e. each <Ad> in an Ad Pod or buffet should have distinct <AdServingId> values). The player is responsible for parsing this value and using it to fill the associated macro (see section 6) on tracking pixels.

Using a GUID for the AdServingId value is recommended. Other formats are acceptable, provided they are generally sufficiently unique to allow different systems to match tracking data. Ad servers may also choose to prepend their AdSystem or a shortened version of their server name to ID value, so that the originating server can easily be identified from the ID alone.

Example: ServerName-47ed3bac-1768-4b9a-9d0e-0b92422ab066

Note that only <InLine> elements may provide an <AdServingId>. Servers providing <Wrapper> VASTs may learn the ad serving ID by including the [ADSERVINGID] macro in their tracking pixels.

3.4.4 Impression

The ad server provides an impression-tracking URI for either the InLine ad or the Wrapper using the <Impression> element. All <Impression> URIs in the InLine response and any Wrapper responses preceding it should be triggered at the same time when the impression for the ad occurs, or as close in time as possible to when the impression occurs, to prevent impression-counting discrepancies.

3.4.5 Category

Used in creative separation and for compliance in certain programs, a category field is needed to categorize the ad’s content. Several category lists exist, some for describing site content and some for describing ad content. Some lists are used interchangeably for both site content and ad content. For example, the category list used to comply with the IAB Quality Assurance Guidelines (QAG) describes site content, but is sometimes used to describe ad content.

The VAST category field should only use AD CONTENT description categories.

The authority attribute is used to identify the organizational authority that developed the list being used. In some cases, the publisher may require that an ad category be identified.

If required by the publisher and not provided, the publisher may skip the ad, notify the ad server using the <Error> URI, if provided (error code 204), and move on to the next option.

If category is used, the authority= attribute must be provided.

*Optional unless the publisher requires ad categories. The authority attribute is required if categories are provided. Example: 232 (where the IAB Ad Product Taxonomy is being used, and 232 is the category and maps to a particular category - say Automobiles or Designer Clothing) |

3.4.6 Description

When a longer description of the ad is needed, the element can be used.

3.4.7 Advertiser

Providing an advertiser name can help publishers prevent display of the ad with its competitors. Ad serving parties and publishers should identify how to interpret values provided within this element.

3.4.8 Pricing

Used to provide a value that represents a price that can be used by real-time bidding (RTB) systems. VAST is not designed to handle RTB since other methods exist, but this element is offered for custom solutions if needed. If the value provided is to be obfuscated or encoded, publishers and advertisers must negotiate the appropriate mechanism to do so.

When included as part of a VAST Wrapper in a chain of Wrappers, only the value offered in the first Wrapper need be considered.

*required

3.4.9 Survey

The survey node is deprecated in VAST 4.1, since usage was very limited and survey implementations can be supported by other VAST elements such as 3rd party trackers.

Ad tech vendors may want to use the ad to collect data for resource purposes. The <Survey> element can be used to provide a URI to any resource file having to do with collecting survey data. Publishers and any parties using the <Survey> element should determine how surveys are implemented and executed. Multiple survey elements may be provided.

A type attribute is available to specify the MIME type being served. For example, the attribute might be set to type="text/javascript". Surveys can be dynamically inserted into the VAST response as long as cross-domain issues are avoided.

3.4.10 Expires

The number of seconds in which the ad is valid for execution. In cases where the ad is requested ahead of time, this timing indicates how many seconds after the request that the ad expires and cannot be played. This element is useful for preventing an ad from playing after a timeout has occurred. If no value is provided, the response can be played back at any time indefinitely after being received by the player.

3.4.11 Error (InLine and Wrapper)

The <Error> element contains a URI that the player uses to notify the ad server when errors occur with ad playback. If the URI contains an [ERRORCODE] macro, the media player must populate the macro with an error code as defined in section 2.3.6.

If no specific error can be found, error 900 may be used to indicate an undefined error; however, every attempt should be made to provide an error code that maps to the error that occurred. The <Error> element is available for both the InLine or Wrapper elements.

3.5 ViewableImpression

The ad server may provide URIs for tracking publisher-determined viewability, for both the InLine ad and any Wrappers, using the <ViewableImpression> element. Tracking URIs may be provided in three containers: <Viewable>, <NotViewable>, and <ViewUndetermined>.

The point at which these tracking resource files are pinged depends on the viewability standard the player has implemented, in agreement with or with the understanding of the buyer.

Player support for the <ViewableImpression> element is optional. When used, URIs for the Inline ad as well as any wrappers used to serve the ad should all be triggered at the same time, or as close in time as possible to when the criteria for the individual event is met.

Note – ViewableImpression is not applicable for Audio use cases.

3.5.1 Viewable

The <Viewable> element is used to place a URI that the player triggers if and when the ad meets criteria for a viewable video ad impression.

3.5.2 NotViewable

The <NotViewable> element is a container for placing a URI that the player triggers if the ad is executed but never meets criteria for a viewable video ad impression.

3.5.3 ViewUndetermined

The <ViewUndetermined> element is a container for placing a URI that the player triggers if it cannot determine whether the ad has met criteria for a viewable video ad impression.

3.6 Creatives

The <Creatives> (plural) element is a container for one or more <Creative> (singular) element used to provide creative files for the ad. For an InLine ad, the <Creatives> element nests all the files necessary for executing and tracking the ad.

In a Wrapper, elements nested under <Creatives> are used mostly for tracking.

Companion and Icon creative may be included in a Wrapper, but files for Linear and NonLinear ads can only be provided in the InLine version of the ad.

3.7 Creative

Each <Creative> element contains nested elements that describe the type of ad being served using nested sub-elements. Multiple creatives may be used to define different components of the ad. At least one <Linear> element is required under the Creative element.

*required General Implementation Note: The Creative sequence attribute should not be confused with the Ad sequence attribute. Creative sequence identifies the sequence of multiple creative within a single ad and does NOT define a Pod. Conversely, the Ad sequence identifies the sequence of multiple ads and defines an Ad Pod. See section 3.3.1 for details about Ad Pods. |

3.7.1 UniversalAdId

A required element for the purpose of tracking ad creative, the <UniversalAdId> is used to provide a unique creative identifier that is maintained across systems. This creative ID may be generated with an authoritative program, such as the AD-ID® program in the United States, or Clearcast in the UK. Some countries may have specific requirements for ad-tracking programs.

The UniversalAdId element is required in 4, but the attribute value for idRegistry and the idValue in the node are to be used to support a company’s need for tracking ad creative. If no common registry is used, a value of "unknown" may be used. Ad servers and publishers should discuss what is required for this field to support a successful ad campaign.

Note: A creative id can also be included in the adId attribute used in the <Creative> element, but that creative id should be used to specify the ad server’s unique identifier. The UniversalAdId is used for maintaining a creative id for the ad across multiple systems.

Note – VAST 4.0 had an attribute “idValue” that was a duplicate of the node value and so was removed as of 4.1. Media players should not fail if this attribute is present, but should always use the Content as the source of truth for the creative ID value.

*required Examples - CNPA0484000H AAA/BBBB123/030 Note: With VAST 4.2 we now allow multiple UniversalAdID elements to be passed in a VAST response |

3.7.2 CreativeExtensions

When an executable file is needed as part of the creative delivery or execution, a <CreativeExtensions> element can be added under the <Creative>. This extension can be used to load an executable creative with or without using the <MediaFile>.

A <CreativeExtension> (singular) element is nested under the <CreativeExtensions> (plural) element so that any XML extensions are separated from VAST XML. Additionally, any XML used in this extension should identify an XML name space (xmlns) to avoid confusing any of the extension element names with those of VAST.

The nested <CreativeExtension> includes an attribute for type, which specifies the MIME type needed to execute the extension.

3.7.3 CreativeExtension

Used as a container under the CreativeExtensions element, this node is used to delineate any custom XML object that might be needed for ad execution.

3.8 Linear

Linear Ads are the video or audio formatted ads that play linearly within the streaming content, meaning before the streaming content, during a break, or after the streaming content. A Linear creative contains a <Duration> element to communicate the intended runtime and a <MediaFiles> element used to provide the needed video or audio files for ad execution.

*required

3.8.1 Duration

The ad server uses the <Duration> element to denote the intended playback duration for the video or audio component of the ad. Time value may be in the format HH:MM:SS.mmm where .mmm indicates milliseconds. Providing milliseconds is optional.

3.8.2 AdParameters

Some ad serving systems may want to send data to the media file when first initialized. For example, the media file may use ad server data to identify the context used to display the creative, what server to talk to, or even which creative to display. The optional <AdParameters> element for the Linear creative enables this data exchange.

The optional attribute xmlEncoded is available for the <AdParameters> element to identify whether the ad parameters are xml-encoded. If true, the media player can only decode the data using XML. Media players operating on earlier versions of VAST may not be able to XML-decode data, so data should only be xml-encoded when being served to media players capable of XML-decoding the data.

When a VAST response is used to serve a VPAID ad unit, the <AdParameters> element is currently the only way to pass information from the VAST response into the VPAID object; no other mechanism is provided.

MediaFiles

Since the first version of VAST, the MediaFiles element was designated for linear video files. Over the years as digital video technology advanced, the media files placed in a VAST tag have come to include complex files that require API integration. Players not equipped with the technology to execute such files may be unable to play the ad or execute interactive components. In ads that require API integration, VAST 4 separates media and interactive files. While <MediaFiles> node focus shifts to the exclusive delivery of media (video and audio), the dedicated <InteractiveCreativeFile> element (see section 3.9.3) opens opportunities for rendering modern secure interactive components in parallel with video and audio assets. The dedicated <Verification> element allows for measurement capabilities. Disjoining media and executable files enables a wider range of players to consume enhanced ads as well as performance improvements.

It is worth noting that when multiple MediaFile nodes are present, the publisher should decide which file to play based on attributes of the MediaFile nodes and not the structure of the document (e.g. defaulting to the first MediaFile included in the document).

Linear media files should be submitted as follows:

Video/Audio file only: Include three elements (section 3.9.1), each with a URI to a ready-to-serve video or audio file at quality levels for high, medium, and low. Please review the IAB Tech Lab Digital Video Ad Format Guidelines for guidance on ready-to-serve file quality specifications. Video/Audio file for use in ad-stitching: In addition to the three ready-to-serve files, use the <Mezzanine> element (section 3.9.2) to include a URI to the raw video or audio file. Please review the IAB Tech Lab Digital Video Ad Format Guidelines for guidance on mezzanine file specifications.

Interactive linear video file: In addition to at least one ready-to-serve video/audio file included in the <MediaFile> element, use the <InteractiveCreativeFile> element (section 3.9.3) to include a URI to the interactive media file, specifying the API framework required to execute the file. The components of the <MediaFiles> elements:

*required **required in ad-stitched video executions

3.9.1 MediaFile

In VAST 4.x <MediaFile> should only be used to contain the video or audio file for a Linear ad. In particular, three ready-to-serve files should be included, each of a quality level for high, medium, or low. A ready-to-serve video/audio file is a media that is transcoded to a level of quality that can be transferred over an internet connection within a reasonable time for viewing. Each ready-to-serve file must be of the same MIME type and, if different MIME types files are made available for the ad, three ready-to-serve files should represent each MIME type separately.

When an interactive API is needed to deliver and execute the Linear Ad, the URI to the interactive file should be included in the <InteractiveCreativeFile>. In addition, at least one ready-to-serve video ad should be available in <MediaFile> so that the video ad can be played by the video player.

Guidelines for ad files that fulfill quality levels of high, medium, or low can be found in the IAB Tech Lab Digital Video Ad Format Guidelines. An adaptive bitrate streaming file featuring files at the three quality levels may also be provided.

*required **if an API framework is needed to execute the ad, please use <InteractiveCreativeFile> to provide API files.

3.9.2 Mezzanine

The media player may use a raw mezzanine file to transcode video or audio files at quality levels specific to the needs of certain environments. An XSD will validate this element as optional, but a mezzanine file is required in ad-stitched executions and whenever a publisher requires it. If no mezzanine file is available, this element may be excluded; however, publishers that require it may ignore the VAST response when not provided. If an ad is rejected for this reason, error code 406 is available to communicate the error when an <Error> URI and macro are provided.

Publishers consume mezzanine files to transcode the media into a form publisher’s system and user devices support. The mezzanine file should never be used for the direct ad playback. The mezzanine file specifications are defined in the IAB Tech Lab Digital Video Ad Format Guidelines.

• VAST tags served to ad-stitching servers require a mezzanine file; server may reject the VAST response if no mezzanine file is provided.

3.9.3 InteractiveCreativeFile

For any media file that uses interactive APIs for advanced creative functionality, the <InteractiveCreativeFile> element is used to identify the file and the framework needed for execution. Providing the interactive portion for a media file in a section of VAST separate from the video/audio file enables players to more easily play the video/audio file when no support is available to execute the API, especially for players that work with an ad-stitching service or make ad calls from a server on behalf of the player. The player should attempt to execute the interactive file before attempting to load any <MediaFile>, but if the file cannot be executed, the player should trigger any included error URIs and use error code 409 when macros are provided.

The “file” can be a direct URL or can be an inline data URI. While providing a URL was customary for VAST before 4.3, saving connection time by providing a small, inline, data URI enhances the consumer ad experience by saving connection times. This saving is only possible if the inline data URI is small enough. Since the data URI payload will likely be a HTML payload, the recommendation is to make this as small as possible. Once the size of the data URI becomes prohibitively large, use a URL to save the response size of the VAST, itself.

Note on Audio Ads: While not in use today, this could be used for pure audio interactivity outside of a click on devices like Alexa.

3.9.4 ClosedCaptionFiles

Optional node that enables closed caption sidecar files associated with the ad media (video or audio) to be provided to the player. Multiple files with different mime-types may be provided as children of this node to allow the player to select the one it is compatible with.

Note: It is expected that all the media files tied to parent MediaFiles node are associated with the same original creative and therefore of the same media length as well as accurately synchronized with closed captioned media segments times, so all the files under ClosedCaptionFiles should work for all the MediaFile nodes.

3.9.5 ClosedCaptionFile

Individual closed caption files for various languages.

3.10 VideoClicks

The <VideoClicks> element provides URIs for clickthroughs, clicktracking, and custom clicks and is available for Linear Ads in both the InLine and Wrapper formats. Both InLine and Wrapper formats offer the ClickThrough, ClickTracking and CustomClick elements. These elements are defined in the following sections.

3.10.1 ClickThrough

The <ClickThrough> is a URI to the advertiser’s site that the media player opens when a viewer clicks the ad. The clickthrough is available in the InLine and Wrapper formats and is used when the Linear ad unit cannot handle a clickthrough.

3.10.2 ClickTracking

Multiple <ClickTracking> elements can be used in the case where multiple parties would like to track the Linear ad clickthrough.

3.10.3 CustomClick

The <CustomClick> is used to track any interactions with the linear ad that do not include the clickthrough click and do not take the viewer away from the media player. For example, if an ad vendor wants to track that a viewer clicked a button to change the ad's background color, the <CustomClick> element holds the URI to notify the ad vendor that this click happened. An API may be needed to inform the player that a click occurred and that the corresponding URI should be activated.

3.11 Icons

The industry icon feature was defined in VAST 3.0 to support initiatives such as privacy programs. An example of such a program is the AdChoices program for interest-based advertising (IBA). Though the VAST icon feature was initially created to support privacy programs, it was designed to support other programs that require posting an icon with the linear ad.

This feature is only offered for Linear Ads because icons can be easily inserted in NonLinear ads and companion creative using existing features. Icon source files may also be included in a wrapper if necessary.

The structure for Linear icons uses the <Icons> element (plural) as a container for one or more <Icon> elements (singular). Each <Icon> element provides containers for the creative resource file in section 3.15. Icon tracking is described in sections 3.11.2 to 3.11.5. See section 2.3.7 for details about industry icon support in VAST.

3.11.1 Icon

Nested under the <Icons> element, the Icon is used to provide one or more creative files for the icon that represents the program being implemented along with any icon tracking elements. Multiple <Icon> elements may be used to represent multiple programs.

3.11.2 IconViewTracking

The view tracking for icons is used to track when the icon creative is displayed. The player uses the included URI to notify the icon server when the icon has been displayed.

3.11.3 IconClicks

The <IconClicks> element is a container for <IconClickThrough> and <ClickTracking>.

3.11.4 IconClickThrough

The <IconClickThrough> is used to provide a URI to the industry program page that the media player opens when the icon is clicked.

3.11.5 IconClickTracking

<IconClickTracking> is used to track click activity within the icon.

3.11.6 IconClickFallbackImages

The <IconClickFallbackImages> element is used to provide information disclosure for platforms which do not support HTML rendering, by baking the information into an image. This is a fallback for when the buyer cannot rely on <IconClickThrough> for disclosure. When an icon click occurs, the ad must pause and the image must be rendered above the video. The player must provide a means for the user to close the dialogue, for example by pressing the back button. The image must not be obstructed and should not be downloaded unless a click-action occurs.

3.11.6.1 IconClickFallbackImage

The <IconClickFallbackImage> element is used to display information when an icon click occurs.

3.12 NonLinearAds

NonLinear ads are the overlay ads that display as an image or rich media on top of video content during playback. Within an InLine ad, at least one of <Linear> or <NonLinearAds> needs to be provided within the <Creative> element. NonLinearAds are not applicable to Audio use cases. The <NonLinearAds> element is a container for the <NonLinear> creative files and tracking resources. If used in a wrapper, only the tracking elements are available. NonLinear creative cannot be provided in a wrapper ad. NonLinear ad creative use non-video creative files that are described in section 3.15. Tracking event elements are described in section 3.14. Ad parameters are used to provide contextual information to the ad and are described in section 3.8.2.

3.12.1 NonLinear

Each <NonLinear> element may provide different versions of the same creative using the <StaticResource>, <IFrameResource>, and <HTMLResource> elements in the InLine VAST response. In a Wrapper response, only tracking elements may be provided.

3.12.2 NonLinearClickThrough

Most NonLinear creative can provide a clickthrough of their own, but in the case where the creative cannot provide a clickthrough, such as with a simple static image, the <NonLinearClickThrough> element can be used to provide the clickthrough.

A clickthrough may need to be provided for an InLine ad in the following situations:

• Static image file
• Any static resource file where the media player handles the click, such as when “playerHandles=true” in a VPAID AdClickThru event. NonLinearClickThrough is only available for InLine ads.

3.12.3 NonLinearClickTracking

When the NonLinear ad creative handles the clickthrough in an InLine ad, the element is used to track the click, provided the ad has a way to notify the player that that ad was clicked, such as when using a VPAID ad unit. The NonLinearClickTracking element is also used to track clicks in Wrappers. NonLinearClickTracking might be used for an InLine ad when:

• Any static resource file where the media player handles the click, such as when “playerHandles=true” in a VPAID AdClickThru event.

NonLinearClickTracking is used in a Wrapper Ad in the following situations:

• Static image file
• Flash file with no API framework (deprecated)
• Flash file in which apiFramework=clickTAG (deprecated)
• Any static resource file where the media player handles the click, such as when “playerHandles=true” in a VPAID AdClickThru event

3.13 CompanionAds

Companion Ads are secondary ads included in the VAST tag that accompany the video/audio ad. The <CompanionAds> element is a container for one or more <Companion> elements, where each Companion element provides the creative files and tracking details. Companion Ads, including any creative, may be included in both InLine and Wrapper formatted VAST ads. The required attribute for the <CompanionAds> element provides information about which Companion creative to display when multiple Companions are supplied and whether the ad can be displayed without its Companion creative. The value for required can be one of three values: all, any, or none.

The expected behavior for displaying Companion ads depends on the following values:

• all: the media player must attempt to display the contents for all <Companion> elements provided. If all companion creative cannot be displayed, the ad should be disregarded and the ad server should be notified using the <Error> element.
• any: the media player must attempt to display content from at least one of the <Companion> elements provided (i.e. display the one with dimensions that best fit the page). If none of the companion creative can be displayed, the ad should be disregarded and the ad server should be notified using the <Error> element.
• none: the media player may choose to not display any of the companion creative, but is not restricted from doing so. The ad server may use this option when the advertiser prefers that the master Linear or NonLinear ad be displayed even if the companion cannot be displayed. If not provided, the media player can choose to display content from any or none of the <Companion> elements.

VAST 4.1 includes a new attribute for companions: renderingMode.

Previous versions of VAST did not allow for the ad server to specify how and when companions would be shown. An asset and width/height information were included, and the assumption was that the companion would be shown alongside the video as a banner. This usage of companions has dropped out of favor over time, while a new usage of the companion as an asset to be displayed full-screen after the video has gained favor in mobile in-app inventory. The renderingMode attribute accommodates the newer end-card use case as part of VAST while laying the groundwork for additional uses of the companion.

The renderingMode attribute accepts a few values. The publisher player/SDK has control of which of these renderingMode values are supported and this should be communicated as part of the publisher ad format specs.

Companion as End-Card

A value of "end-card" signals to the player that this companion ad is meant to be shown after the video stops playing. The end-card should match the dimensions of the preceding video. If the companion width and height are not zero, the player may use these values to infer the aspect ratio of the companion ad.

Companion duration is a new consideration for the end-card and assumed to be controlled by the publisher player/SDK and communicated as part of the publisher ad format specs. Known variations in market include an “infinite” duration, which requires the viewer to close the end-card after it is shown, and a timed duration. For any companion that suspends content playback, such as an in-stream ad, and does not include a time-out, the player/SDK must implement a close control to prevent users from being trapped in the ad. For out- stream ads that do not interfere with content, the close control is not mandatory. It is also up to the publisher whether a skippable video should show an associated end-card when the video is skipped. Most implementations by major mobile SDKs currently do so.

Click-throughs triggered from the companion should make sure to open in a new browser window rather than replacing the existing end card or another window needed by the app. This ensures that the consumer can exit the webpage that’s loaded upon clicking through the ad and to make sure that the app experience isn’t disrupted.

The VAST event of closeLinear must be fired upon the companion closing. This allows for ads that use companions to know when the companion was dismissed. Companies providing the end card creative should adhere to IAB Tech Lab LEAN guidelines.

Companion as Concurrent Display Ad A value of "concurrent" signals to the player that this companion ad is meant to be shown alongside the video for the duration of the video playback. This reflects the original use of the companion in desktop inventory.

Additional Creative Uses of the Companion Ad

The companion ad may be used for new implementations, and as such new values of the renderingMode attribute may be used if supported by the publisher and the ad server. The renderingMode may use other values other than the ones listed to support these additional use cases. For example, proprietary formats that show content alongside a video could be supported by the standard with a “split-screen” renderingMode, displaying a 1:1 aspect ratio video, alongside an equal sized companion in both portrait and landscape mode.

The goal is that renderingMode will provide some initial standards support for format innovation in environments that cannot, or will not, support VPAID with future spec changes to follow market developments.

Default or Empty renderingMode

The renderingMode attribute may be omitted. In this case, the player will assume that the renderingMode value is set as “default” and will handle the companion in whatever way it does by default.

Non-Creative Use of the Companion Ad

The companion is intended to be used as an additional creative element. Inclusion of a companion to support non-creative functionality (e.g. additional tracking) is considered to be contrary to the intention of the spec.

3.13.1 Companion

Both InLine and Wrapper VAST responses may contain multiple companion items where each one may contain one or more creative resource files using the elements: StaticResource, IFrameResource, and HTMLResource. Each <Companion> element may provide different versions of the same creative.

The resource elements for providing creative resources are defined in section 3.15. Tracking elements are also available for each companion element. Ad parameters are used to provide contextual information to the ad and are described in section 3.8.2.

• required

3.13.2 AltText

The AltText element is used to provide a description of the companion creative when an ad viewer mouses over the ad.

3.13.3 CompanionClickThrough

Most companion creative can provide a clickthrough of their own, but in the case where the creative cannot provide a clickthrough, such as with a simple static image, the CompanionClickThrough element can be used to provide the clickthrough.

A clickthrough may need to be provided for an InLine ad in the following situations:

• Static image file
• Any static resource file where the media player handles the click, such as when “playerHandles=true” in a VPAID AdClickThru event.

3.13.4 CompanionClickTracking

When the companion ad creative handles the clickthrough in an InLine ad, the CompanionClickTracking element is used to track the click, provided the ad has a way to notify the player that that ad was clicked, such as when using a VPAID ad unit. The CompanionClickTracking element is also used in Wrappers to track clicks that occur for the Companion creative in the InLine ad that is returned after one or more wrappers.

CompanionClickTracking might be used for an InLine ad when:

• Any static resource file where the media player handles the click, such as when “playerHandles=true” in a VPAID AdClickThru event CompanionClickTracking is used in a Wrapper in the following situations:
• Static image file. Any static resource file where the media player handles the click, such as when “playerHandlesClick=true” in VPAID
• Any static resource file where the media player handles the click, such as when “playerHandlesClick=true” in VPAID

3.14 Tracking Event Elements

The <TrackingEvents> element is a container for <Tracking> elements used to define specific tracking events described in section 3.14.1. Multiple tracking events can be used to help all the relevant parties track the ad’s performance. Each tracking event URI should be included one <Tracking> element, using the event attribute to identify which event is to be tracked.

The following example shows the section of a VAST response that represents 3 tracking events: two start events, each for a different server, and a complete event.

<TrackingEvents> 
<Tracking event="start"> 
<![CDATA[http://server1.com/start.jpg]]> 
</Tracking> 
<Tracking event="start"> 
<![CDATA[http://server2.com/start2.jpg]]> 
</Tracking> 
<Tracking event="progress" offset="3"> 
<![CDATA[http://server1.com/progress.jpg]]> 
</Tracking> 
 
<Tracking event="complete"> 
<![CDATA[http://server1.com/complete.jpg]]> 
</Tracking> 
</TrackingEvents>

3.14.1 Tracking Event Descriptions

VAST is used to track a number of ad events using the <TrackingEvents> and <Tracking> elements. Tracking for impressions is covered in section 3.4.3 and clickthroughs are covered in their relevant sections. Review the schema in section 5 to find more details about tracking the different ad types in VAST. Each <Tracking> element contains a URI for the tracking resource of one event. The media player uses these URIs to notify the ad server when the identified event occurs.

In some cases the media player cannot detect that an event has occurred unless a third party, such as the ad creative or a verification script, communicates the event through a framework such as OMID or VPAID. For example, the adExpand event for NonLinear ads requires the ad to notify the media player that it has expanded. In such cases, the player must support these tracking events to the extent that they support the individual frameworks.

The following list of metrics is derived from the IAB Digital Video In-Stream Ad Metric Definitions where more detailed metric definitions can be found.

The values accepted for tracking events are described in the following list:

Player Operation Metrics (for use in Linear and NonLinear Ads)

• mute: the user activated the mute control and muted the creative.
• unmute: the user activated the mute control and unmuted the creative.
• pause: the user clicked the pause control and stopped the creative.
• resume: the user activated the resume control after the creative had been stopped or paused.
• rewind: the user activated the rewind control to access a previous point in the creative timeline.
• skip: the user activated a skip control to skip the creative.
• playerExpand: the user activated a control to extend the player to a larger size. This event replaces the fullscreen event per the 2014 Digital Video In-Stream Ad Metric Definitions.
• playerCollapse: the user activated a control to reduce player to a smaller size. This event replaces the exitFullscreen event per the 2014 Digital Video In-Stream Ad Metric Definitions.
• notUsed: This ad was not and will not be played (e.g. it was prefetched for a particular ad break but was not chosen for playback). This allows ad servers to reuse an ad earlier than otherwise would be possible due to budget/frequency capping. This is a terminal event; no other tracking events should be sent when this is used. Player support is optional and if implemented is provided on a best effort basis as it is not technically possible to fire this event for every unused ad (e.g. when the player itself is terminated before playback).

Linear Ad Metrics

• loaded: This event should be used to indicate when the player considers that it has loaded and buffered the creative’s media and assets either fully or to the extent that it is ready to play the media
• start: This event is used to indicate that an individual creative within the ad was loaded and playback began. As with creativeView, this event is another way of tracking creative playback. Macros defined to describe auto-play and muted states.
• firstQuartile: The creative played continuously for at least 25% of the total duration at normal speed.
• midpoint: The creative played continuously for at least 50% of the total duration at normal speed.
• thirdQuartile: The creative played continuously for at least 75% of the duration at normal speed.
• complete: The creative was played to the end at normal speed so that 100% of the creative was played.
• otherAdInteraction: An optional metric that can capture all other user interactions under one metric such a s hover-overs, or custom clicks. It should NOT replace clickthrough events or other existing events like mute, unmute, pause, etc.
• progress: The creative played for a duration at normal speed that is equal to or greater than the value provided in an additional offset attribute for the <Tracking> element under Linear ads. Values can be time in the format HH:MM:SS or HH:MM:SS.mmm or a percentage value in the format n%. Multiple progress events with different values can be used to track multiple progress points in the linear creative timeline. This event can be used in addition to, or instead of, the “quartile” events (firstQuartile, midpoint, thirdQuartile, complete). The additional <Tracking> offset value can be used to help track a view when an agreed upon duration or percentage of the ad has played.
• closeLinear: The viewer has chosen to close the linear ad unit. This is currently in-use by some of the largest mobile SDKs to mark the dismissal of the end card companion that follows the video, as well as a close of the video itself, if applicable.

NonLinear Ad Metrics

• creativeView: Not to be confused with an impression, this event indicates that an individual creative portion of the ad was viewed. An impression indicates that at least a portion of the ad was displayed; however an ad may be composed of multiple creative, or creative that only play on some platforms and not others. This event enables ad servers to track which ad creative are viewed, and therefore, which platforms are more common.
• acceptInvitation: The user clicked or otherwise activated a control used to pause streaming content, which either expands the ad within the player’s viewable area or “takes-over” the streaming content area by launching an additional portion of the ad. An ad in video format ad is usually played upon acceptance, but other forms of media such as games, animation, tutorials, social media, or other engaging media are also used.
• adExpand: The user activated a control to expand the creative.
• adCollapse: The user activated a control to reduce the creative to its original dimensions.
• minimize: The user clicked or otherwise activated a control used to minimize the ad to a size smaller than a collapsed ad but without fully dispatching the ad from the player environment. Unlike a collapsed ad that is big enough to display it’s message, the minimized ad is only big enough to offer a control that enables the user to redisplay the ad if desired.
• close: The user clicked or otherwise activated a control for removing the ad, which fully dispatches the ad from the player environment in a manner that does not allow the user to re-display the ad.
• overlayViewDuration: The time that the initial ad is displayed. This time is based on the time between the impression and either the completed length of display based on the agreement between transactional parties or a close, minimize, or accept invitation event.
• otherAdInteraction: An optional metric that can capture all other user interactions under one metric such a s hover-overs, or custom clicks. It should NOT replace clickthrough events or other existing events like mute, unmute, pause, etc.
• creativeView: Since Companion Ads use browser technology for display, tracking metrics can be built into the creative. The only VAST event available for tracking companion creative is the creativeView event. This event enables ad servers to track when companion creative are viewed.

Interactive Ad Metric

• interactiveStart: With VAST 4, video playback and interactive creative playback now happens in parallel. Video playback and interactive creative start may not happen at the same time. A separate way of tracking the interactive creative start is needed. The interactive creative specification (SIMID, etc.) will define when this event should be fired.

3.14.2 TrackingEvents

The <TrackingEvents> element is available for Linear, NonLinear, and Companion, elements in both InLine and Wrapper formats. When the media player detects that a specified event occurs, the media player is required to trigger the tracking resource URI provided in the nested <Tracking> element. When the server receives this request, it records the event and the time it occurred.

3.14.3 Tracking

Each <Tracking> element is used to define a single event to be tracked. Multiple tracking elements may be used to define multiple events to be tracked, but may also be used to track events of the same type for multiple parties. When using the progress event, an offset attribute for linear ads can be used to notify the ad server when the ad's progress has reached the identified percentage or time value indicated. When percentages are used, the progress event can offer tracking that represent the quartile events (firstQuartile, midpoint, thirdQuartile, and complete).

When skippable ads are supported, the progress event is used to identify when the ad counts as a view even if the ad is skipped. For example, if the tracking offset is set to 00:00:15 (15 seconds) but the ad is skipped after 20 seconds, then a creativeView event may be recorded for the Linear creative.

If adType is “audio” or “hybrid”, progress events should be fired even if the media playback is in the background. The offset attribute is only available for the <Tracking> element under <Linear>.

3.14.1 and differ for <Linear>, <NonLinear>, and <Companion>. Offset Only available when <Linear> is the parent. Accepts values of time in the format HH:MM:SS or as a percentage in the format n%. When the progress of the Linear creative has matched the value specified, the included URI is triggered. If the duration is not known when the offset is set to a percentage value, the progress event may be ignored.

3.15 Creative Resource Files for Non-Video and Non-Audio Creative

NonLinear ads, Companions, and Industry Icons are non-video and non-audio creative, so creative files are nested using elements that define the type of creative resource file provided: StaticResource, IFrameResource, and HTMLResource.

These resource nodes are available under the elements: <NonLinear>, <Companion>, and <Icon> in the InLine format; however, in Wrapper format, resource files may only be provided under the <Companion> and <Icon> elements. NonLinear elements in Wrapper format are only used for tracking, and resource files are not allowed.

Multiple creative files may be included using these components, but each element should contain one or more files to represent different versions of the creative for use in different environments. The media player can choose which file to use when more than one resource file is provided within a single container.

For example, if an ad server wants to submit both a static image and an HTML creative for a NonLinear ad, then the NonLinear portion of the VAST response would be formatted as follows:

<NonLinearAds> 
<NonLinear> 
<StaticResource> 
<![CDATA[http://adserver.com/staticresourcefile.jpg]]> 
</StaticResource> 
<HTMLResource> 
<![CDATA[<html><body>I'm a html snippet</body></html>]]> 
</HTMLResource> 
 
 
</NonLinear> 
</NonLinearAds>

The three resource file elements are described in the following sections.

3.15.1 StaticResource

The URI to a static creative file to be used for the ad component identified in the parent element, which is either: <NonLinear>, <Companion>, or <Icon>.

*required

3.15.2 IFrameResource

The URI to an HTML resource file to be loaded into an iframe by the publisher. Associated with the ad component identified in the parent element, which is either: <NonLinear>, <Companion>, or <Icon>.

3.15.3 HTMLResource

A “snippet” of HTML code to be inserted directly within the publisher’s HTML page code.

3.16 AdVerifications

The <AdVerifications> element contains one or more <Verification> elements, which list the resources and metadata required to execute third-party measurement code in order to verify creative playback.The <AdVerifications> element is used to contain one or more <Verification> elements, which are used to initiate a controlled container where code can be executed for collecting data to verify ad playback details.

3.17 Verification

The <Verification> element contains the executable and bootstrapping data required to run the measurement code for a single verification vendor. Multiple <Verification> elements may be listed, in order to support multiple vendors, or if multiple API frameworks are supported. At least one <JavaScriptResource> or <ExecutableResource> should be provided. At most one of these resources should selected for execution, as best matches the technology available in the current environment.

If the player is willing and able to run one of these resources, it should execute them BEFORE creative playback begins. Otherwise, if no resource can be executed, any appropriate tracking events listed under the <Verification> element must be fired.

*required

3.17.1 JavaScript Resource

A container for the URI to the JavaScript file used to collect verification data. Some verification vendors may provide JavaScript executables which work in non-browser environments, for example, in an iOS app enabled by JavaScriptCore. These resources only require methods of the API framework, without relying on any browser built-in functionality. Players that execute verification code in a browser or webview context should prefer browserOptional="false" resources if both are available, but may also execute browserOptional="true" resources. Players that execute verification code in a non-browser environment (e.g. JavaScriptCore) may only execute resources marked browserOptional="true". If only browserOptional="false" resources are provided, the player must trigger any provided verificationNotExecuted tracking events with reason code 2, to indicate the provided code is not supported (see Section 3.17.4).

*required **while optional, if neither JavascriptResource or ExecutableResource are executed, the player must trigger the verificationNotExecuted tracking events with reason code 2

3.17.2 ExecutableResource

A reference to a non-JavaScript or custom-integration resource intended for collecting verification data via the listed apiFramework.

*required **while optional, if neither JavascriptResource or ExecutableResource are executed, the player must trigger the verificationNotExecuted tracking events with reason code 2

3.17.3 TrackingEvents

The verification vendor may provide URIs for tracking events relating to the execution of their code during the ad session. The player must trigger the request of these URIs in the scenarios listed in section 3.17.4.

3.17.4 Tracking

Each <Tracking> element is used to define a single event to be tracked by the verification vendor. Multiple tracking elements may be used to define multiple events to be tracked, but may also be used to track events of the same type for multiple parties. One event type is currently supported:

• verificationNotExecuted: The player did not or was not able to execute the provided verification code

The following macros should be supported specifically in URIs for this event type (in addition to all macros from the global macro set in section 6).

• [REASON] - The reason code corresponding to the cause of the failure.

*required

3.17.5 VerificationParameters

<VerificationParameters> contains a CDATA-wrapped string intended for bootstrapping the verification code and providing metadata about the current impression. The format of the string is up to the individual vendor and should be passed along verbatim.

3.18 Extensions

Ad servers can use this XML node for custom extensions of VAST. When used, custom XML should fall under the nested <Extension> (singular) element so that custom XML can be separated from VAST elements. An XML namespace (xmlns) should also be used for the custom extension to separate it from VAST components.

The following example includes a custom XML element within the <Extensions> element.

<Extensions> 
<Extension> 
<CustomXML>…</CustomXML> 
<Extension> 
</Extensions> 

The publisher must be aware of and be capable of executing any VAST extensions in order to process the content.

3.18.1 Extension

One instance of <Extension> should be used for each custom extension. The type attribute is a custom value which identifies the extension.

3.19 Wrapper

VAST Wrappers are used to redirect the media player to another server for either an additional <Wrapper> or the VAST <InLine> ad. In addition to the URI that points to another file, the Wrapper may contain tracking elements that provide tracking for the InLine ad that is served following one or more wrappers. A Wrapper may also contain <Companion> creative and <Icon> creative. And while <Linear> and <NonLinear> elements are available in the Wrapper, they are only used for tracking. No media files are provided for Linear elements, nor are resource files provided for NonLinear elements. Other elements offered for InLine ads may not be offered for Wrappers.

To find out if an element is offered for Wrappers, check the human-readable schema in section 5 .

• required

3.19.1 VASTAdTagURI

While VAST Wrappers don’t provide all the same elements offered for an InLine ad, the is the only element that is unique to Wrappers. The VASTAdTagURI is used to provide a URI to a secondary VAST response. This secondary response may be another Wrapper, but eventually a VAST wrapper must return an ad. In VAST 4 the player is only required to accept five wrappers ads. If no InLine ads are returned after 5 Wrappers, the player may move on to the next option.

3.19.2 BlockedAdCategories

Ad categories are used in creative separation and for compliance in certain programs. In a wrapper, this field defines ad categories that cannot be returned by a downstream ad server. This value is used to populate the [BLOCKEDADCATEGORIES] request macro in VASTAdTagURI strings, and can also be used by the player to reject InLine ads with Category fields that violate the BlockedAdCategories fields of upstream wrappers (see section 3.4.5). If an InLine ad is skipped due to a category violation, the client must notify the ad server using the URI, if provided (error code 205), and move on to the next option.

*Optional unless the publisher requires ad categories. The authority attribute is required if categories are provided.

4 Migration to VAST 4.x

VAST 4 offers features to support long-form video, server-side tracking, industry-wide creative tracking, and viewability and verification tracking. While the advance in features is alluring, media players will need time to upgrade their systems. During the transition period from VAST 3.0 to 4 (or 2.0 to 4), prepare to manage varying feature support in the market. VAST 4 was designed to be backward compatible with version 3.0 and VAST 3.0 was designed to be backwards compatible with version 2.0.

However, features introduced in the newer versions will typically not be back ported to older-versioned players. Also, features explicitly called out as deprecated or removed will break backward compatibility. The following sections outline a few notes to consider as VAST 4 is introduced into the market.

4.1 Advertisers and Ad Technology Vendors

Design ads that can be successfully delivered to lower versioned VAST players while still optimizing the response with new 4 capabilities. For example:

• VAST 4 ads discourage the use of VPAID or other interactive ad units that require an API to execute in the <MediaFile>. The new <InteractiveCreativeFile> was provided to accommodate such ads. However, in older versions, an interactive unit may be provided in addition to the video <MediaFile> in order to ensure interactive files are executed where possible in older VAST version players.
• In a 4 response, use both the Creative adId attribute as well as the new <UniversalAdId> element to provide a creative ad ID.

4.2 Ad Servers and Networks

Be prepared to manage the variability with VAST versions. For example, if a player specifically requests a VAST 3.0 response, then the ad server should limit responses to VAST 3.0.

If one or more verification vendors are involved, use VAST 4 to provide verification code in the new <AdVerification> node, but expect that older versioned players will not recognize the verification node.

An important change discussed during 4.1 is the concept of standardized ad requests using AdCOM and POST requests. This is something that likely will require a phased approach on ad servers and so should be planned accordingly. The group recommends that servers start supporting POST requests (in addition to GET requests) in the near future and look into related scaling issues, because the AdCOM based ad request support will be developed next.

4.3 Media Players

VAST 4 players should continue to accept ads on older versions of VAST because it will take time for the entire industry to upgrade.

5 Human Readable VAST XML Schema

The following schema models the structure for VAST along with available attributes.

*Either the InLine or the Wrapper element is required and only one is allowed.

6 Macros

6.1 Introduction

Ad servers and other entities need access to additional data from the publisher to meet client needs for a clearer view into the details of how and where their video is being shown.

The following macros enable the media player to provide these additional data points. Some may need to be relayed from the publisher ad server to the player in turn before the player can pass them on.

The following overview outlines the various macros, in which contexts they are applicable and their meaning.

Macro Formatting and Replacement

All macro names are surrounded by square brackets, for example:[EXAMPLE]. When replacing the macro with a value, the whole name - including brackets - needs to be replaced with the value. For example, if you’d want to replace the [EXAMPLE] macro in the URL https://mydomain.com/something?test=`[EXAMPLE]` with the value somevalue, you would get https://mydomain.com/something?test=somevalue

Macro Replacement Responsibility The responsibility to properly replace macros with their proper values lies with the party that will perform the HTTP request.

In the most common scenario, both for VAST URLs and tracking pixel URLs, this would be the video player that’s executing the ad.

In some cases a server might perform the macro replacement on behalf of the video player, for example in the case of server-side ad insertion where the server is performing tracking pixel requests on behalf of the client.

Marking Macro Values as Unknown or Unavailable For any macros that are marked as optional or deprecated and where the actual macro is not provided, the following special values must be inserted into the macro to indicate the reason for not providing the information:

Implementation Note: do not replace all unknown macros with -1, only do this for macros specifically mentioned in this section that you decide not to implement.

Macro Value URI Encoding

Some macros must be populated as a series of values rather than a single value. These macros use the Array<T> data type. This is a list of T values where T is another data type like string or integer. When replacing a macro with such a list, the value should be rendered as a set of values separated by a comma (","), and no spacing. For example: the values stringA and stringB would be encoded as stringA,stringB.

When replacing macros, make sure to apply encodeURIComponent to any value, to avoid creating invalid URLs. However, note that encoding should be applied to individual values only, not the entire macro replacement string (i.e. unencoded commas should separate distinct values).

For example, to encode the values abc/def and y=z, you’d replace the macro with abc%2Fdef,y%3Dz

Note that each individual value is properly encoded, but the comma between values is not.

In the examples given below, if the URI-encoded version differs from the unencoded original, both are given for the sake of clarity. However, the encoded version must always be used as a macro substitution.

Note: In order to ensure that new macros can be added without requiring a new VAST version at every change, we are maintaining the latest list on the IAB Tech Lab’s VAST github repository. Please visit http://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html for the latest list and for more details on the process of adding new macros.

6.2 List of Macros

Please reference the Macro list in GitHub for the most up to date macros.

https://interactiveadvertisingbureau.github.io/vast/vast4macros/vast4-macros-latest.html