What is a macro?
A macro is a placeholder in a URL that ART19 automatically fills in with real data each time an ad is served. Instead of hard-coding something like an episode ID into a measurement pixel, you drop in a macro and ART19 swaps in the correct value every time the ad plays. This is how a third party (a measurement vendor, or your own external channel) knows exactly what was served.
Macros only work if they are written in the exact format ART19 expects. If the format is off, ART19 will not recognise the macro, the placeholder will not be replaced, and the request will fire with the literal placeholder text instead of real data. When that happens the tag does nothing useful, so getting the format right is essential.
The golden rule: wrap every macro in double curly braces
Every ART19 macro must be wrapped in double curly braces, like this:
{{ seriesID }}
Two opening braces, the macro name, two closing braces. ART19's own buttons add a space just inside each brace, and that is the format you will see throughout this guide. The same applies whether you are setting up a 3rd party measurement pixel or a VAST line item in External Channels.
Which macros can I use?
The available macros depend on what you are setting up, and the two use different sets - so always check the right article for the one you are working with:
- 3rd party measurement pixels: see 3rd Party Measurement Overview for the full list of supported macros.
- VAST line items and external channels: see Using External Channels to create VAST line item connections for the full list of supported macros.
Correct vs incorrect
Correct: {{ seriesID }}
Incorrect (these will not work):
- { seriesID } - single braces
- %%seriesID%% - percent signs
- [seriesID] - square brackets
- {{ series_id }} or {{ SeriesID }} - wrong name or spelling
The most common mistake is pasting a tag from a third party that still contains THEIR placeholder style (for example %%EPISODE_ID%% or [TIMESTAMP]). You need to replace each of the vendor's placeholders with the matching ART19 macro. Do not assume the tag arrives ready to go.
The foolproof way: use the parameter buttons
You do not have to type macros by hand. When you open a measurement destination (for a 3rd party pixel) or the Ad Source of a VAST external channel and click into the URL field, you will see a row of buttons - one for each macro available there. The available macros differ between the two, but they work in exactly the same way.
- If there is already a placeholder in the URL that needs replacing, highlight the entire placeholder first.
- With it highlighted, click the matching button - ART19 swaps in its own macro in the correct format.
- To add a macro from scratch, place your cursor where the value should go and click the button to insert it.
Using the buttons guarantees the format is right, so it is the recommended approach.
Check it worked: error messages and the URL preview
A URL can look right but still be wrong, so check both of these before you set the destination to Active:
-
Error messages - if something is wrong, ART19 shows a red error directly beneath the URL field. For example, a misspelled macro shows "Invalid macro(s): series_ID", and other problems (such as a stray extra "?" in the URL) are flagged too. Fix anything listed here.
-
Sample Ping (or Example URL for VAST line items) - this preview shows exactly what the URL will look like when it fires. Set up correctly, the macros are replaced with real values - for example {{ timestamp }} becomes something like 1782296200947. If the preview still shows {{ ... }} placeholders, the macros are not being read and need fixing.
In the above example the Series ID is incorrectly displaying the placeholder text, but Episode ID and Timestamp are correctly re-formatted.
If you are not 100% sure it is right, contact support before the line item goes live so we can confirm it for you. It is far easier to fix beforehand than after a campaign has started.
Which macro do I use? Matching a partner's macro to ART19
When a tag comes from a measurement vendor, SSP or DSP, it usually still contains that partner's own placeholders in their format - for example %%CACHEBUSTER%%, [TIMESTAMP] or ${GDPR_CONSENT}. ART19 will not recognise these: you need to swap each one for the matching ART19 macro, or remove it if there is no equivalent. Because ART19 inserts ads server-side into audio downloads (not in a browser or video player), several common macros do not apply at all - remove them rather than leave them in.
| Partner macro (any format) | What it is for | On ART19 |
|---|---|---|
| CACHEBUSTER, CB, cache-buster | Stops caching | Use {{ random }}
|
| TIMESTAMP, TS | Time of impression | Use {{ timestamp }} (or {{ timestampISO }}) |
| EPISODE_ID, CONTENT_ID | Episode identifier | Use {{ episodeID }}
|
| SHOW_ID, PODCAST_ID, PROGRAM_ID | Show / series identifier | Use {{ seriesID }}
|
| AD_ID, CREATIVE_ID | The ad served | Use {{ adID }} (3rd party pixels only) |
| IP, IP_ADDRESS, DEVICE_IP | Listener IP | Use {{ encryptedDeviceIP }} (3rd party pixels only - ART19 never exposes a raw IP) |
| USER_AGENT, UA | Device user agent | Use {{ deviceUserAgent }} (VAST / External Channels only) |
| GDPR, GDPR_CONSENT, TCF consent string | EU consent | Remove - not passed in server-side podcast serving |
| US_PRIVACY, CCPA, GPP | US privacy strings | Remove - handled at the platform level, not in the tag |
| REFERRER, PAGE_URL, SITE_URL | Page / referrer URL | Remove - there is no browser or page context |
| PLAYER_WIDTH, PLAYER_HEIGHT, PLAYER_SIZE | Player dimensions | Remove - not applicable to audio |
| CLICK_URL, CLICKTAG | Click redirect | Remove - audio ads have no click-through |
| DEVICE_ID, IDFA, GAID | Mobile ad identifiers | Remove - not available |
| DOMAIN, APP_BUNDLE | App or domain | Remove - not applicable |
| LATITUDE, LONGITUDE, geo coordinates | Geo | Remove - geo-targeting is server-side and not exposed in the tag |
If a macro is not in this table and is not in the supported list for what you are setting up (3rd party pixels and VAST / External Channels use different sets), remove it - an unsupported placeholder left in the URL will fire as literal text. If in doubt, contact support before the line item goes live.