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]