VAST Ad-Tag Macros Explained: The Complete Reference (IAB, Google, Roku)

A VAST macro is a placeholder token inside an ad tag URL - like [CACHEBUSTING], %%CACHEBUSTER%%, or ROKU_ADS_CACHE_BUSTER - that the video player, ad server, or SSAI stitcher swaps for a real value the instant an ad is requested. One static tag becomes a live, per-request tag carrying a cache-buster, a timestamp, the device advertising ID, the viewer's consent string, the page URL, and the player size. Miss the macros and everything downstream breaks quietly: caches and CDNs collapse identical requests, impression counts go wrong, targeting has nothing to work with, and privacy signals never reach the ad server. This is the exhaustive reference - the syntax used by IAB VAST, Google Ad Manager, and Roku's RAF, every standard macro with what the player substitutes, a worked example, and the privacy macros you cannot skip. To assemble and test a tag hands-on, use the VAST Macro Builder.

Why a static ad tag needs macros

An ad tag is just a URL. When the ad break arrives the player fetches it, and the ad server responds with VAST XML describing the ad. But the same URL is fetched millions of times - on different devices, for different viewers, under different privacy regimes. A macro is how one URL adapts to each of those requests.

Three things go wrong without macros:

• Caching and counting. Identical URLs get cached by browsers, CDNs, and proxies. The [CACHEBUSTING] macro drops a random number into every request so each one is unique - which is what stops impression and tracking beacons from being deduplicated.
• Targeting. The ad server needs context to choose an ad: content ID, genre, player size, geo, device type. Macros carry that context on the request.
• Privacy and compliance. GDPR consent, US Privacy (CCPA), COPPA / child-directed, and limit-ad-tracking signals all travel as macros. If they are missing, the ad server has to assume the worst - and buyers drop their bids.

Macro syntax: three ecosystems, one idea

The concept is universal; only the delimiters change. You will meet three syntaxes.

A few rules apply everywhere:

• Macros live in the query string of the tag (?key=[MACRO]&key2=[MACRO2]). The parameter names (key) are defined by the receiving ad server; the macro token is the value.
• The component that owns the tag at each hop does the substitution. A player or SSAI stitcher fills client-side macros (device ID, IP, player size) before it calls the ad server; an ad server can fill more and forward the rest to any downstream wrapped tag.
• An unfilled macro should be dropped or left blank - never sent literally. A request that still contains a raw [IFA] tells the ad server your integration is broken.

The IAB VAST standard macros

These are defined by the IAB Tech Lab in the VAST 4 macro specification and work in any spec-compliant player, whatever your ad server. They are the portable baseline: support these and your tags travel. Square brackets are the delimiter.

A handful appear on almost every tag: [CACHEBUSTING] (defeat caches), [TIMESTAMP], [IFA] + [IFATYPE] + [LIMITADTRACKING] (device identity and opt-out), [DEVICEIP] and [DEVICEUA] (client), [DOMAIN] / [PAGEURL] / [APPBUNDLE] (where the ad runs), [PLAYERSIZE], and the regulation set [GDPRCONSENT] / [GPPSTRING] / [REGULATIONS].

Google Ad Manager macros

Google Ad Manager and the IMA SDK predate some of the IAB tokens and use their own %%MACRO%% syntax, with ${MACRO} for privacy signals. If you serve through GAM, these are the tokens you place in the tag; GAM fills them.

Two GAM-specific things are worth knowing. First, the click and destination URL macros come in three escaping levels - _UNESC, _ESC, and _ESC_ESC - because a click URL is often nested inside another redirect, and each hop needs one more level of URL-encoding. Second, consent uses ${...}, not %%...%%: ${GDPR}, ${GDPR_CONSENT_XXXX} (replace XXXX with your IAB Global Vendor List ID), and ${ADDTL_CONSENT}.

Roku RAF macros

Roku's Advertising Framework (RAF) differs in one important way. Instead of embedding a delimited token, you set the bare ROKU_ADS_* keyword as the value of a query parameter, and RAF replaces the whole value at request time. So &dev=ROKU_ADS_TRACKING_ID becomes &dev=<the RIDA>. RAF is the on-device library that renders ads in Roku channels, so these are the macros available when you serve into Roku's SDK.

Privacy and consent macros: do not skip these

Consent is the one area where a missing macro is not just a data-quality problem - it is a compliance and revenue problem. Buyers drop bids when they cannot read a consent signal. Here is how the major regimes map across the three ecosystems.

Advanced macros, decoded: the consent strings

Most macros carry a simple value. A few carry an encoded string whose individual characters each mean something, and getting one character wrong makes a demand partner silently drop the bid. These are the macros worth reading closely.

Breaking down the us_privacy string

The us_privacy string - the CCPA / US Privacy signal, carried by %%TAG_PARAM:us_privacy%% in Google Ad Manager and on your own parameter for IAB VAST and Roku RAF - is defined by the IAB Tech Lab and is exactly four characters. Each position is a single flag:

Read left to right. 1YNN means "version 1, notice given, the user has not opted out, not covered by the LSPA" - a normal, fully addressable US request. Flip the third character to 1YYN and the user has opted out: partners like Google then apply Restricted Data Processing (RDP) and Roku's RAF limits what it passes downstream, so expect fewer targeted bids. When CCPA does not apply at all, the optional fields use the not-applicable hyphen, giving 1---. The one string you must never emit is a literal, unresolved macro: if us_privacy=%%TAG_PARAM:us_privacy%% reaches the ad server unfilled, the request is malformed and demand collapses.

GDPR (TCF) and GPP strings

Europe's signals work the same way but are longer and Base64-encoded rather than human-readable. ${GDPR} (or [REGULATIONS]=gdpr) is a single 1/0 flag for "does GDPR apply?", while ${GDPR_CONSENT_XXXX} and [GDPRCONSENT] carry the full IAB TCF v2 consent string - a Base64 payload encoding purposes and vendor permissions that the SSP decodes, not you. The newer Global Privacy Platform string ([GPPSTRING] with [GPPSECTIONID]) is one container that can carry the US Privacy, US-state, and TCF sections together. You never hand-edit these - a consent management platform produces them - but you must pass them through unmodified and never URL-encode them twice.

A worked example: build a VAST tag with macros

Start with a plain base tag - an ad-server endpoint with a placement. It works, but it is blind:

https://ads.example-ssp.com/vast?slot=preroll&app=com.example.tv

Add a cache-buster so every request is unique and beacons count, then device identity so the buyer can frequency-cap and target (with the opt-out flag), then context - where the ad runs and how big the player is - and finally consent, without which much of the demand disappears. Put together, the authored tag is:

https://ads.example-ssp.com/vast?slot=preroll
  &cb=[CACHEBUSTING]
  &ifa=[IFA]&ifa_type=[IFATYPE]&lat=[LIMITADTRACKING]
  &app=[APPBUNDLE]&url=[PAGEURL]&size=[PLAYERSIZE]&content=[CONTENTID]
  &gdpr=[REGULATIONS]&gdpr_consent=[GDPRCONSENT]

At request time the player substitutes each token, and the ad server receives a concrete URL:

https://ads.example-ssp.com/vast?slot=preroll
  &cb=48213307
  &ifa=38400000-8cf0-11bd-b23e-10b96e40000d&ifa_type=rida&lat=0
  &app=com.example.streaming&url=https%3A%2F%2Fexample.com%2Fwatch&size=1920%2C1080&content=movie-987
  &gdpr=gdpr&gdpr_consent=CPcqB8APcqB8AAKAsAENCZCg

That is exactly what the VAST Macro Builder does: tick the macros you need and it shows both the authored tag and a simulated filled request. Send that request with the VAST Ad Tag Simulator to preview the exact URL, headers, and curl command a Roku or Fire TV player would use, then parse what the ad server returns - inline ad, wrapper, media files, tracking, or a no-fill. Paste the VAST XML into the VAST Tag Validator to confirm the response is spec-valid.

Best practices and common mistakes

• Match the syntax to the consumer. Sending [CACHEBUSTING] to Google Ad Manager (which wants %%CACHEBUSTER%%) leaves the token unfilled. Know which system reads the tag.
• Never send an unfilled macro literally. If a value is unavailable, drop the parameter or send it empty. A raw ifa=[IFA] reaching the ad server is a bug.
• Get the escaping level right. In redirect chains, each extra hop needs one more layer of URL-encoding - that is why GAM offers _ESC and _ESC_ESC variants.
• Carry macros down the wrapper chain. In a VAST wrapper, macros on the outer VASTAdTagURI must be forwarded to the wrapped tag, or the final ad server gets nothing.
• Always include the privacy set. Missing consent macros suppress demand and create compliance exposure. Add them by default, not on request.
• Test with real tokens filled. Use the builder's simulated request to sanity-check the URL, then validate the returned XML.

The bottom line

Macros are the small, unglamorous plumbing that makes a single ad tag work across every device, viewer, and privacy regime. The three ecosystems - IAB VAST, Google Ad Manager, and Roku RAF - express the same handful of ideas (cache-bust, identify, contextualize, obtain consent) in different delimiters. Learn the cache-buster, the device ID, the context, and the consent macros for the system you serve through, keep the full reference handy, and never let an unfilled token reach the ad server.

Frequently Asked Questions