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]