How can I integrate programmatic ads using VAST?

VAST (Video Ad Serving Template) tags are supported in creatives. Instead of making a regular MP3 based ad, and uploading an audio file, you can make a creative of type 'VAST' and specify a VAST URL.

VAST creatives can be added to any flight, with any priority or targeting, just like any other creative. When a VAST creative is selected for a download, Dovetail will use the VAST url defined in the creative to retrieve a VAST response with a programmatic ad to be inserted in the download.

If a VAST creative does not fill (i.e. no ad is returned when it is called), then Dovetail will try to find a lower priority non-VAST ad to fill with, which is useful for making sure there is always some kind of ad in a break.

Dovetail supports and has been tested with VAST versions 2 and 4, though 4 is preferred. VAST Wrappers are not supported, only inline VAST ads.

VAST HTTP Headers

When Dovetail makes a VAST request, it sets a number of HTTP headers based on the original podcast client's request:

Header Description Example
USER-AGENT Podcast client's USER-AGENT Overcast/3.0 (+http://overcast.fm/; iOS podcast app)

X-DEVICE-USER-AGENT

Same as USER-AGENT Overcast/3.0 (+http://overcast.fm/; iOS podcast app)
X-FORWARDED-FOR
Podcast client's truncated IP 75.25.62.0
X-DEVICE-IP
Same as XFF 75.25.62.0
REFERER
Podcast client's REFERER
https://myshow.com
X-DEVICE-REFERER Same as REFERER https://myshow.com

 

VAST Macros

VAST tags support macros in them, and Dovetail supports most of the tags from the VAST standard.

Dovetail supports VAST macros in urls either surrounded by square brackets (e.g. /?value=[MACRO]) which is the format suggested in VAST 4.3, or using the older practice of double percent signs (e.g. /?value=%%MACRO%%).

Besides many of the macros defined in the VAST 4.3 spec, there are also some additional custom macros to support podcast advertising.

Below is a list of the supported tags, and any default values:

Custom and VAST 4.x Macros

Macro

Description Example

Dovetail Custom Macros

GUID

Podcast episode GUID (i.e. <guid/> tag in RSS 123e4567-e89b-12d3-a456-426655440000
PODCAST Podcast ID, unique to Dovetail. 123
PODCASTTITLE
Podcast title Music Igniter
EPISODETITLE
Episode title Episode 1: Title
EPISODECATEGORIES
The IAB category for this episode IAB1-1
EPISODEDURATION
Duration in seconds of the episode
3600
LISTENERID Listener ID based on request User Agent & IP Address; how IAB measurement defines unique listeners.

1234567890123.123e4567-e89b-12d3-a456-426655440000

LATITUDE Estimated latitude, based on GeoIP lookup 42.3639
LONGITUDE Estimated longitude, based on GeoIP lookup -71.13295
KEYWORDS

Comma separated list of keywords for contextual advertising, from keywords and categories on the episode.

education,environment

RSS

Public URL for the podcast feed

https://example.ai/rss.xml

BREAKTYPE

Like BREAKPOSITION but "pre", "mid", or "post"

post

New VAST 4.x Macros

CONTENTCAT Not supported  
GPPSECTIONID Not supported  
GPPSTRING Not supported  
PLAYBACKMETHODS Not supported  
STOREID Not supported  
STOREURL Not supported  

Generic Macros

TIMESTAMP

Current time in ISO extended format

2023-09-13T18:19:09.488797Z

CACHEBUSTING

Random 8-digit integer

49216940

Ad Break Info

ADCATEGORIES

Not supported

 

ADCOUNT

Number of ads requested

1

ADTYPE

Media type of ad requested

audio

BLOCKEDADCATEGORIES

List of blocked IAB categories

IAB25,IAB26

BREAKMAXADLENGTH
Defaults to 60 seconds 60
BREAKMAXADS
Number of ads requested 1
BREAKMAXDURATION

Number of ads * 60 seconds

120

BREAKMINADLENGTH

Minimum length per ad, defaults to 0 seconds

0

BREAKPOSITION

1=pre, 2=mid, 3=post, 0=multiple/unknown

2

MEDIAPLAYHEAD

Not applicable, always -1

-1

PLACEMENTTYPE
Type of ad placement from this AdCOM list 11
TRANSACTIONID
UUID for this request 123e4567-e89b-12d3-a456-426655440000
UNIVERSALADID
Not supported  

Client Info

CLIENTUA
Client request's user agent (i.e. DEVICEUA) Podcast App 1.0
DEVICEIP
Client IP, truncated for privacy (ends in 0) 75.25.62.0
DEVICEUA
Client request's user agent Podcast App 1.0
IFA
UUID for this listener (i.e. for IP & UA) 123e4567-e89b-12d3-a456-426655440000
IFATYPE
Type of IFA, always synthetic: sessionid sessionid
LATLONG
Latitude and longitude, comma separated
42.3639,-71.13295
SERVERSIDE
2 = "Server fires request or tracking call on behalf of another server" 2
SERVERUA
User agent for the server
Dovetail/3.0 (+https://prx.org)

Publisher Info

APPBUNDLE
Not supported  
DOMAIN
Top level domain for serving
dovetail.prxu.org
PAGEURL
Not supported  
APIFRAMEWORKS
None
 
CLICKTYPE
Not clickable = 0
0
EXTENSIONS
Not supported
 
MEDIAMIME
MIME type of the podcast
audio/mpeg
OMIDPARTNER
Not supported
 
PLAYERCAPABILITIES
Not supported
 
VASTVERSIONS
VAST 4.1 and 4.3 (not wrapped)
11,13
VERIFICATIONVENDORS
Not supported
 
ADPLAYHEAD
Not supported
 
ADSERVINGID
Not supported
 
ASSETURI
Not supported
 
CONTENTID
Podcast episode GUID (equivalent to the GUID macro)
123e4567-e89b-12d3-a456-426655440000
CONTENTURI
Podcast episode enclosure URL
https://d.prxu.org/g/f.mp3
PLAYERSTATE
Not supported
 
PLAYERSIZE
Not supported
 
CLICKPOS
Not supported
 
ERRORCODE
Not supported
 
REASON
Not supported
 
LIMITADTRACKING
Always 1, user prefers limited tracking
1
GDPRCONSENT
Always -1, impossible to have consent
-1
REGULATIONS
Not supported (gdpr and coppa)
-1

 

System Integrations and Examples

Adswizz

For Adswizz, Dovetail will combine VAST calls when the VAST url is identical, requesting enough ads for the combined request. For example, if midrolls 1, 2, and 3 all use the same VAST URL, then the will be combined into a single VAST request, with a `maxAds=[BREAKMAXADS]` set to 3, so `maxAds=3` in the request. If multiple ads are returned, they will then be meted out to the zones in sequential order.

Example:

https://my-account.deliveryengine.adswizz.com/vast/4.0/request/alias/myshow_post?awCollectionId=[PODCAST]&awEpisodeId=[CONTENTID]&aw_0_cnt.url=[CONTENTURI]&aw_0_cnt.rss=[RSS]&aw_0_1st.puid1=[IFA]&lat=[LATITUDE]&lon=[LONGITUDE]&aw_0_1st.kw=[KEYWORDS]&maxAds=[BREAKMAXADS]&cat_exclude=[BLOCKEDADCATEGORIES]

 

Audiohook

For Audiohook VAST integration, specify VAST version 4, inline responses, and that the IP will come from the X-DEVICE-IP HTTP header (as detailed above):

Example:

https://directvast.audiohook.com/my-account/vast?placement-type=pre&vast-type=inline&vspec=4&ip=header-x-device-ip&feed-url=[RSS]&episode-url=[CONTENTURI]&ua=[CLIENTUA]&bcat=[BLOCKEDADCATEGORIES]&ord=[CACHEBUSTING]

 

Triton

For Triton VAST integration, please refer to their docs on supported macros. Custom fields like keywords come through as ttags, and may be used to pass in values depending on how targeting is specified in Triton:

Example:

https://cmod-apac.live.streamtheworld.com/ondemand/ars?stid=123456&type=preroll&ttag=[KEYWORDS],[GUID]

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request