What is Ad Macros?

Updated September 2026 · Reviewed by the Flicknexs platform team

Quick answer

Ad macros are dynamic placeholders in ad tags that the player or server replaces with runtime data like device ID or video title. They allow advertisers to track context without hardcoding values. Operators use them to pass viewer context to ad servers for better targeting and reporting.

Key takeaways

  • Macros replace placeholders with live data at playback time.
  • Common macros include device ID, user agent, and video duration.
  • Incorrect syntax breaks ad delivery or causes tracking failures.
  • SSAI resolves macros server-side, while client-side ads resolve in the player.

How Ad Macros work

An ad macro is a text string inside a VAST XML tag that gets swapped for real data before the ad plays. The player or ad server scans the ad URL or tracking pixel for these placeholders. It then substitutes the value based on the current environment.

For example, a macro like {playerWidth} becomes 1920 on a full-screen desktop player. A macro like {deviceID} might become a unique identifier for that specific app instance. This happens in milliseconds, before the ad creative loads.

In client-side ad insertion, the player handles this replacement. In server-side ad insertion, the ad server does it. The ad server knows the viewer's IP, location, and device type, so it can fill the macros with more precise data. The player then receives a fully resolved ad tag.

Most macro errors come from typos or unsupported fields. If the player does not recognize a macro, it may leave the placeholder as-is or drop the ad entirely. Always test ad tags in a sandbox environment before pushing them to production.

Why Ad Macros matter for a streaming business

Ad macros turn static ad spots into dynamic inventory. Without them, you serve the same ad to every viewer in a region. With them, you can pass the video title, channel name, or viewer location to the ad server. This allows for contextual targeting. An ad for a sports drink can appear only during sports content.

Operators care about this because it improves ad relevance and click-through rates. Higher relevance means advertisers pay more for the same inventory. It also improves viewer experience because ads feel less random.

Macros also help with fraud detection. By passing device and session data, you can verify that ads are served to real humans on real devices. This protects your reputation with ad buyers.

Finally, macros simplify reporting. Advertisers can see exactly which video or channel generated a click. This transparency builds trust and encourages repeat business.

Common mistakes with Ad Macros

Operators often make these errors when implementing ad macros:

  • Unsupported macros: Using a macro the player does not recognize. This causes silent failures or broken ads.
  • Case sensitivity errors: Some systems require exact casing. {DeviceID} may fail if the system expects {deviceID}.
  • Overloading URLs: Too many macros can make the ad URL too long, causing truncation or parsing errors.
  • Ignoring privacy rules: Passing sensitive data like exact location or personal identifiers without consent violates privacy laws.
  • Not testing edge cases: Macros may behave differently on mobile versus web. Test on all major platforms.

How Flicknexs handles Ad Macros

Flicknexs supports ad macros within its SSAI (server-side ad insertion) workflow. The ad server resolves macros like device ID and video title before sending the final ad tag to the player. This keeps the client lightweight and ensures consistent data across all devices, including web, iOS, Android, and smart TV apps. You can configure which macros are available in your ad settings. The system validates syntax before deployment to prevent broken tags. This approach reduces player-side complexity and improves ad load times. For operators running FAST channels, this means you can serve dynamic ads without custom coding. See the Launch a FAST channel page for more details on setting up ad-supported linear streams.

Launch a FAST channel →

Done reading about Ad Macros?

Flicknexs ships it as part of a white-label streaming platform: web, mobile and TV apps, billing, ads, DRM and playout, on your own domain.

Launch a FAST channelStart Your OTT Free

Ad Macros FAQ

Client-side macros are resolved by the video player on the user's device. Server-side macros are resolved by the ad server before the tag reaches the player. Server-side is more secure and allows for better data accuracy, as the server has access to IP and geo data that the player may not.
Yes, if your ad server and player support them. Standard VAST defines a set of common macros. You can add custom ones for specific needs, like passing a user's subscription tier. Both the ad server and the player must be configured to recognize and handle the custom macro correctly.
Yes. The same macro syntax applies to audio ads. The player or server replaces the placeholders with relevant data, such as the audio track name or device type. This allows for contextual audio ad targeting, just like with video ads.
Check the ad tag in a browser or developer tools to see the final URL. If the macro is still present as text, the player or server did not resolve it. Verify the macro name against your platform's documentation. Test on multiple devices to rule out platform-specific issues.
The player typically skips the unresolvable ad slot to prevent playback errors. This keeps the viewer continues watching content without interruption. You should monitor your analytics dashboards to identify frequent macro failures. Fixing these issues maintains ad revenue integrity and prevents potential billing disputes with advertisers.
They allow dynamic data injection directly into the ad response. This enables precise targeting based on viewer context, device type, or geographic location. Using macros helps deliver relevant ads without requiring separate requests. This approach improves viewability and keeps the ad delivery process efficient for both publishers and buyers.

Further reading

Ad Macros: Definition, Syntax, and Streaming Use Cases