Macros are placeholders in the VAST URL that the player replaces with real values at the moment an ad is requested. Use macros to pass context (such as the page URL, player dimensions, or clip details) to your ad server dynamically.
1.0 | Standard Macros
| Macro | Explanation | Value |
|---|---|---|
[url] | The URL the player is placed on. If the player is placed in an iFrame and the option “attempt iFrame breakout” is not used, the [url] will be the URL of the iFrame. | URL encoded string |
[deeplink] | The deep link of the mediaclip (is the same as [url] if not set) | URL encoded string |
[timestamp] | A unique number generated at the time of the VAST request. Used by ad servers to prevent cached (stale) ad responses from being reused. | Number |
[correlator] | Serves the same purpose as [timestamp]. Ties multiple ad requests on the same page together so the ad server can avoid showing the same ad twice in one session. | Number |
[playerwidth] | The width of the player in pixels. When responsive sizing is used, the width will return the width of the player at the moment of ad request. | Number |
[playerheight] | The height of the player in pixels. When responsive sizing is used, the height will return the height of the player at the moment of ad request. | Number |
[clipTitle] | The clip title. Only available for in-stream content. | URL encoded title string |
[clipID] | The clip ID. Only available for in-stream content. | ID string |
[playmode] | The playmode selected by the player. Useful when using key/value targeting in combination with Google Ad Manager (GAM). | String |
[format] | The format selected by the player. Similar to [playmode] but returns a different value. | String |
[consent_string] | The TCF consent string retrieved from the CMP (Consent Management Platform) on the page. Use this to pass GDPR consent data to your ad server. Read more about consent management for demand tags. | String |
[gdpr_applies] | Whether GDPR applies in the current context, as determined by the CMP. Read more about consent management for demand tags. | 1 (applies) or 0 (does not apply) |
[gpt_targeting] | All Google Publisher Tag (GPT) targeting key/value pairs currently set on the page, serialised as a query string (e.g. section=news&env=prod). Requires googletag to be present on the page. | URL encoded string |
[gpt_targeting_<key>] | The value of a single Google Publisher Tag (GPT) targeting key (e.g. section=news&env=prod with [gpt_targeting_section] returns news). Multiple values for the same key are joined with a comma. Requires googletag to be present on the page. | String |
[mediaclip_<field>] | Any field from the mediaclip data object. Replace <field> with the field name (e.g. [mediaclip_title], [mediaclip_id]). Only available for in-stream content. Read more about the available default mediaclip fields. | Depends on field |
[playout_<field>] | Any field from the playout configuration. Replace <field> with the field name (e.g. [playout_code]). | Depends on field |
Do not hardcode a fixed value for the correlator parameter in your VAST URL. A static correlator causes the ad server to treat every ad request as part of the same session, which can result in ad deduplication (the same ad being blocked from appearing more than once, or no ad being served at all after the first request). Either use the [correlator] or [timestamp] macro, or leave the parameter empty (&correlator=) so that BB fills it dynamically.
2.0 | Custom Parameters
In addition to the standard macros above, you can pass custom key/value pairs from the player embed code into the VAST URL.
- Include
macro_<key>=<value>in the embed code parameters - Include
%%<key>%%in the VAST URL - The player will substitute
%%<key>%%with the value passed in the embed code parameter (macro_<key>=<value>)
For example:
- Include
%%foo%%in an ad tag URL (VAST URL):
https://yourcompanyname.bbvms.com/mediaclip/123456.xml?output=vast&targeting=%%foo%% - Embed the player using the following URL source:
https://yourcompanyname.bbvms.com/p/default/c/987654.js?macro_foo=bar - This will result in the player requesting the following VAST URL:
https://yourcompanyname.bbvms.com/mediaclip/123456.xml?output=vast&targeting=bar
3.0 | Using macros in consent management for demand tags
If your website uses a consent management platform (CMP) to collect GDPR consent from visitors, you need to pass that consent information to your ad partners. Blue Billywig does this using macros in your demand tags.
A demand tag is the ad request URL you configure in your line items: the URL that Blue Billywig sends to your ad partner to request an ad. By adding consent macros to that URL, Blue Billywig automatically fills in the visitor’s consent status before the request is sent.
In 2019, IAB Europe and the IAB Tech Lab introduced TCF 2.0 (Transparency & Consent Framework), which standardized how GDPR consent is communicated across the programmatic advertising ecosystem. Blue Billywig supports TCF 2.0 through these macros.
3.1 | Update demand tags
To pass consent information to your ad partners, add one or both of the following macros to your demand tag URL in the line item settings. Blue Billywig replaces each macro with the appropriate value at the time the ad request is made.
The macros are standardized and work across demand partners:
[gdpr_applies]— replaced with0(GDPR does not apply) or1(GDPR applies), depending on the visitor’s location.[consent_string]— replaced with the Transparency & Consent (TC) string from the CMP, which encodes the visitor’s consent choices. This macro is the most important to demand partners and is used most frequently. If no CMP is present or the visitor has not yet given consent, the macro is left empty.
3.2 | Macro examples
Each demand partner includes consent parameters differently in their ad request URL. Below are some common examples. Replace XXXXXXXX or XXXXXX with your own partner-provided IDs, and append or update the consent parameters in your existing demand tag URL.
- https://pubads.g.doubleclick.net/gampad/ads?iu=/XXXXXXXX/URL&description_url=[url]&tfcd=0&npa=0&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=&iab_string=[consent_string]&gdpr_consent=[consent_string]
- http://ads.stickyadstv.com/vast/vpaid-adapter/XXXXXXXX?_fw_gdpr=[gdpr_applies]&_fw_gdpr_consent=[consent_string]
- https://vid.pubmatic.com/AdServer/AdServerServlet?adtype=13&pubId=XXXXXX&siteId=XXXXXX&adId=XXXXXXX&vadFmt=2&vminl=1&vmaxl=120&vh=338&vw=600&placement=3&vtype=1&vpos=1&vplay=2&vskip=0&vcom=0&vfmt=1&sec=1&gdpr=[gdpr_applies]&gdpr_consent=[consent_string]
- https://secure.adnxs.com/ptv?id=XXXXXXXX&gdpr=[gdpr_applies]&gdpr_consent=[consent_string]