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 from a 3rd party VAST provider. We have documentation on integrating with specific VAST providers at the bottom of this article.

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
COUNTRY

Short ISO code for the country, based on GeoIP lookup

US

SUBDIVISIONS

csv list of ISO subdivision codes, based on GeoIP lookup

US-MA,US-CT

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

APPLECATEGORIES

A csv list of Apple top level and sub categories for the feed.

Arts, Performing Arts

CCPACOVERED

Indicates if the request comes from California.

true

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

BLOCKEDADCATEGORIESALL

Like above, but includes sub categories for any top level category.

IAB21,IAB21-1,IAB21-2,IAB21-3,IAB21-4

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]

 

Triton

We have tested our integration with Triton, and worked with their excellent staff to determine recommendations on how to use Triton VAST tags in Dovetail. Please also refer to the Triton VAST docs on supported macros when deciding on how to setup your tags.

Custom fields like [KEYWORDS] can come through the "ttags" param, depending on how targeting is specified in Triton. For example, you can also pass in the episode [GUID] along with the [KEYWORDS] to allow targeting or excluding specific episodes, as shown below.

IAB category blocking on Triton also uses IAB v1 categories, however, on Triton a top level category does not automatically block subcategories, so Dovetail provides a different macro [BLOCKEDADCATEGORIESALL] which includes all subcategories for any top level category blocked in Dovetail.

Here are some additional suggestions of using Dovetail macros with Triton query parameters:

Triton Param Dovetail Macro / Value Notes
stid ##### Required to have a Triton station ID
feed-type podcast Not a macro, but a suggested value to include
type [BREAKTYPE]roll Required break type, expects `preroll`, `midroll`, or `postroll`
ttag [GUID],[KEYWORDS] Pass in keywords that are on an episode, including the GUID of the episode to allow per episode targeting.
iab-categories-to-exclude [BLOCKEDADCATEGORIESALL] See note above; categories to block.
series-title [PODCASTTITLE]  
episode-title [EPISODETITLE]  
lat [LATITUDE]  
long [LONGITUDE]  
episode-url [CONTENTURI]  
maxAds [BREAKMAXADS] To use Ad Pods and combine requests.

 

Example, basic:

https://xxxxxxxx.live.streamtheworld.com/ondemand/ars?stid=xxxxxx&type=preroll&ttag=[GUID],[KEYWORDS]

 

Example, with all the suggested options:

https://xxxxxxxx.live.streamtheworld.com/ondemand/ars?stid=xxxxxx&feed-type=podcast&type=[BREAKTYPE]roll&ttag=[GUID],[KEYWORDS]&iab-categories-to-exclude=[BLOCKEDADCATEGORIESALL]&series-title=[PODCASTTITLE]&episode-title=[EPISODETITLE]&lat=[LATITUDE]&long=[LONGITUDE]&episode-url=[CONTENTURI]

 

Dovetail also supports Triton's use of Ad Pods by specifying &maxAds=[BREAKMAXADS] in a request. This will cause Dovetail to consolidate requests for multiple ads with the same VAST url to a single request (i.e. if pre 1 and pre 2 have the same VAST url including BREAKMAXADS, Dovetail will make one request for maxAds=2).

 

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://xxxxx-vast.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]

 

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