When we engage in discussions about Dynamic Ad Insertion with our customers and partners, we often encounter terms like ‘macro’, ‘ ad tag’, ‘avail’, and ‘opportunity’. Some might view these terms as mere jargon, but the truth is, their names are not as important as their practical application in your campaigns. Despite the complexity these terms might imply, using them effectively is well within your reach.

This post explores how ad macros function within SSAI frameworks and provides practical examples of their use in boosting ad personalization.

Introduction to Ad Macros in SSAI

Server-side ad Insertion (SSAI) seamlessly integrates advertisements with video content on the server, streamlining the delivery to viewers’ devices. This method mitigates issues like ad blocking and buffering, which are common in client-side ad insertion. At the heart of SSAI’s personalized advertising capabilities are Ad Macros—tokens that dynamically insert specific viewer or environmental data into streaming requests.

It’s important to understand that Ad Tags and Ad Macros are not interchangeable terms. Ad Macros are parameters used within Ad Tag URLs. The correct and unambiguous term should be Ad Tag Macro. This distinction is crucial for a comprehensive understanding of the topic.

How Ad Macros Work

First, what is a macro, you might ask? Primarily famous for creating automation in basic programs like Excel for non-developers, a macro is much more than that. By definition, a macro is a pre-set piece of code that injects dynamic values into a program. Consequently, you can almost draw a parallel with variables in programming languages that serve similar functions as placeholders that are dynamically resolved with actual values.

In the mainstream eye, macros are often associated with software like Excel.

In advertising, a macro performs a similar function within an ad tag, inserting real-time data as needed. Take, for instance, the “lat” macro (we will come back later with more examples), which automatically inputs the user’s latitude into the ad tag. This capability allows advertisers to tailor their campaigns more precisely by using up-to-date information about the user, such as their geographical location, device type, and other relevant factors.

To summarize, ad macros are placeholders that are automatically replaced with dynamic data during the ad insertion process. This data can be about the viewer (like location or device type), their viewing behavior (such as the type of content being watched), or other data types. For example:

  • [[DEVICE]]: This macro can be replaced with the kind of device the viewer uses, such as ‘mobile’ or ‘desktop’, allowing for device-specific ad formats.
  • [[USER_ID]]: This macro might be replaced with a unique identifier for the viewer, enabling personalized ad sequences based on previous viewing habits or interactions.
  • [[CONTENT_GENRE]]: Here, the macro could be replaced with the genre of the content being viewed, such as ‘sports’ or ‘comedy’, to deliver genre-specific advertisements.

Ad macros are not just placeholders but the key to delivering advertisements tailored to the viewer’s streaming session. This power of ad macros ensures that the ads are relevant and highly effective, increasing viewer engagement and satisfaction.

In almost all Dynamic Ad Insertion cases, ad macros are passed as query parameters on the ad tag (though, in some cases, they can be passed as HTTP headers). The query parameter name is the ad server’s choice.

Please note that I use the notation [[ABC]] for ad macros in this blog post. Depending on the ad server or context, you might see [[ABC]], %%ABC%%, or even ${ABC}. The specific syntax doesn’t matter; it’s a matter of choice rather than a rule, as there are no universally accepted conventions. Ultimately, macros’ naming, writing, and wrapping are inconsequential because they function similarly in all cases. The special wrapping characters make it easy to recognize these placeholders as macros.

Examples of Ad Macros in Action

To understand the power of ad macros in Dynamic Ad Insertion, consider these practical scenarios:

  1. Localized Advertising: An ad request includes the macro [[GEO_LOCATION]], replaced by the viewer’s current city, “Austin.” Advertisers can serve ads specific to Austin, such as local event promotions or regional product launches.
  2. Behavioral Targeting is a powerful strategy that uses [[CONTENT_GENRE]] to deliver ads based on the viewer’s interests and preferences. For instance, if a viewer watches cooking shows, the [[CONTENT_GENRE]] macro can be replaced with ‘cooking’. Advertisers could use this information to push ads for cooking gadgets, grocery delivery services, or new cooking shows. This approach enhances the relevance of the ads and increases the likelihood of viewer engagement.
  3. Sequential Advertising is another tactic that uses [[USER_ID]] to ensure that a viewer does not repeatedly see the same ad. Instead, they see a sequence of advertisements that tell a story or gradually introduce more product features. This approach enhances engagement and retention by keeping viewers curious about the ad sequence’s next steps.
sequential ads
Instead of repetitive ads, we prefer sequential ads, like we see a lot on mobile.

What about Privacy and Ad Macros?

Regarding privacy, Ad Macros play an important role in ensuring compliance with regulations like the California Consumer Privacy Act (CCPA) or General Data Protection Regulation (GDPR).

  • For CCPA, the [[US_PRIVACY]] macro is designed to encapsulate a user’s disclosures and selections regarding the handling of their consumer data privacy. This macro is essential for advertisers to respect and adhere to the privacy choices of their viewers, as mandated by the CCPA. We advise you to visit this IAB page for a more detailed understanding.
  • For GDRP, the handling of consent strings depends on how a service provider implements them. At its most basic (macro [[GDPR]]), the implementation might use “0” to indicate no consent and “1” for consent. However, it is strongly advised to employ a Consent Management Platform (CMP) that adheres to the Transparency and Consent Framework (TCF) to generate and deliver a TCF consent string from the user’s device ([[CONSENT]]). You can refer to the IAB’s documentation here: TCF Implementation Guidelines for detailed recommendations and implementation guidelines.
GDPR and CCPA are two different regulations, but both of them are to protect the privacy of individuals

More ad macros?

We gave some examples above of ad macros, like [[DEVICE]], but of course, many more macros can be used in SSAI flows to carry information to Ad Servers and SSP.

We can group them into three categories (check here for a list more exhaustive):

  • User-based or Session-based:
    • When a viewer watches something, and the request hits the SSAI service, values such as the client_ip and user_agent for their session are populated. These are coming from the user itself.
    • Here is a non-exhaustive list of user-based macros:
      • cachebuster: This term is a technique that stops a browser from caching and reusing an already displayed ad. Inserting a random number into the URL ensures that each execution results in a fresh request to the ad server.
      • avail_duration_ms or avail_duration_secs: Represents the duration of an ad break opportunity.
      • client_ip: Specifies the originating I.P. address of the request.
      • consent: The string used under GDPR to document user consent.
      • copaa: Indicates whether the request complies with the Children’s Online Privacy Protection Act.
      • id: A unique numeric code that identifies the ongoing playback session in that particular service.
      • uuid: Stands as a unique identifier for each playback session across all integrated systems.
      • longitude: This value represents the player’s longitudinal coordinates and is utilized to target ads geographically.
      • latitude: Specifies the player’s latitudinal coordinates and is also used for geotargeting purposes.
      • break_id: A string used as an identifier for specific ad breaks, commonly in spot ad insertions.
  • Player-based:
    • This is all the information related to the viewer’s application to watch the video content.
    • Here is a non-exhaustive list:
      • app_bundle: Identifies the bundle I.D. associated with the app.
      • app_category: Describes the category under which the app is listed.
      • app_name: The name of the application.
      • app_store_url: The URL for the app’s page on an app store.
      • device_model: Categorizes the model of the device being used.
      • device_make: Specifies the make of the device being used.
      • Device_os: Specifies the O.S. of the device being used.
      • did: The identifier for the device.
      • gdpr: basic gdpr consent
      • is_lat: The “Limit Ad Tracking” setting allows users to opt out of targeted advertising based on their behavior.
      • referer: Refers to the webpage URL where the video player is embedded.
      • us_privacy: The privacy string defined by the IAB for the U.S. market (related to CCPA).
      • user_agent: A header from the initialization request of the player’s session detailing the device type, operating system version, and player version.
      • User_gender: gender of the user
      • User_yob: year of the birth of the user
  • Contextual-based
    • This is all about the content being watched. Sharing data could help advertisers contextualize their ads better in the user experience.
    • Here is a non-exhaustive list (self-explanatory):
      • content_id
      • content_genre
      • content_title
      • content_season
      • content_series
      • content_categories
    • Please note that the IAB shared some guidelines on the content taxonomy for content_categories HERE .
The IAB Content Taxonomy provides a common language for describing content or the aboutness of a webpage, application, or video. There are three levels of categorization. Here is an example based on Events and Attractions.

Implementation and Best Practices for Using Ad Macros in SSAI

How does it work?

As explained above, Ad Macros data is typically exchanged via HTTP headers and query parameters in Dynamic Ad Insertion, which is true with Client-Side Ad Insertion (CSAI) and Server-Side Ad Insertion (SSAI).

However, SSAI (Server-Side Ad Insertion) offers a distinctive approach compared to CSAI (Client-Side Ad Insertion). In CSAI, the player directly calls the ad server and resolves macros at the point of the ad request, streamlining the process within the client environment. However, SSAI has a different flow: the “passe-through” mechanism. This involves passing playback session information from the server to the ad server, ensuring that ad requests are seamlessly integrated into the video stream server-side. This mechanism is the real differentiator in SSAI workflows, requiring careful handling and thoughtful implementation to ensure ad delivery is smooth, synchronized, and free from client-side interruptions or ad-blocking issues. By embedding ads server-side, SSAI enhances the viewing experience with uninterrupted content flow and consistent ad performance across different devices and platforms.

Here are the steps to ensure that real-time data is dynamically inserted into the ad tags before sending them to the ad server via the SSAI.

  • First, the system (on the client side) captures relevant data from the viewer or the content they engage with. This data could include geographical location, device type, or viewing preferences.
  • Once this information is collected, it is formatted into query parameters. These parameters are attached to the streaming request URL using specific macros that hold dynamic values. For example, a macro such as [[DEVICE]] in the ad request URL might be replaced with iOS or Android, depending on the viewer’s device.
  • Then, the player requests the video through the streaming URL. This goes to the CDN, which forwards all the queries to the SSAI.
  • The SSAI system then calls to retrieve a VAST (Video Ad Serving Template) ad using the filled-in ad macro queries and other data from the HTTP headers. The ad server processes these parameters, tailoring the ad content based on the real-time data provided, such as serving a location-specific advertisement or customizing the ad format for a particular type of device.
  • After the Ad Server’s decision, the VAST call is answered with the creatives selected for this viewer. The SSAI service then includes the suitable ads in the feed.

How to optimize it?

Here are some topics of attention if you want to optimize your campaigns:

  • Precision in Data Usage: To maintain the ads’ relevance, ensure that the data replacing the macros is as accurate and timely as possible.
  • Compliance and Privacy: Use macros responsibly, respecting privacy laws and regulations. Secure handling of viewer data is paramount to maintaining trust and legal compliance.
  • Continuous Testing and Optimization: Collaborating with your Ad Server, regularly test and refine ad macros to adapt to changing viewer behaviors and preferences. This iterative process helps maintain high engagement and conversion rates. Using A/B testing could help you better understand your system’s efficiency.
This is where having people dedicated to Adops makes a difference. If you need introductions to some of the best in the market, ask us!

Ad Macros in broadpeak.io

This knowledge center article explains in more detail how to configure the Ad Macros in broadpeak.io and this one how we pass the information to the ad server.

It is based on the five following steps:

  1. Define the Ad Server as a Source: When you create your Ad Server, you’ll initially set a URI, commonly referred to as an Ad Tag, which contains placeholders known as macros. These macros hold spots within the Ad Tag that broadpeak.io will dynamically replace with actual values when requesting the Ad Server.
  2. Swapping macros with dynamic variables: You can include various macros in the Ad Tag that might relate to system values or client-requested values. System values can consist of information like cachebuster value or live break duration, while client-requested values might include data from headers such as IP addresses or user-agent information.
  3. Macro Replacement in Query Parameters: When configuring your streaming URL, you’ll append query parameters using macros to the base URL.
  4. Data Forwarding: After receiving the streaming request and during the ad request, broadpeak.io either replaces these dynamic variables with the actual data captured from the viewer’s session (HTTP headers) or predefined values or gathers the information coming from the query themselves. These populate what’s sent to the ad server via the VAST request, ensuring that each ad request is tailored to the current viewing context and enhancing the ads’ relevance.
  5. Handling Ad Responses: Once the ad server receives the request, it processes the included parameters to deliver targeted advertising content back to broadpeak.io, stitching these ads into the main content stream.
Look at how broadpeak.io remaps the information before sending it to the ad server.

Conclusion

Ad macros are a powerful component of Server-Side Ad Insertion systems, enabling highly personalized and effective advertising that resonates with viewers. By understanding and utilizing these macros, publishers can significantly enhance the relevance of their ads, leading to better viewer experiences, higher fill rates, and improved ad performance. As monetization becomes increasingly essential in CTV, platforms will fight for advertisers. Consequently, mastering the art of ad macros within SSAI will be crucial for any successful digital advertising strategy.

Mathias Guille
https://linkedin.com/in/mathiasguille
Mathias Guille is the Vice President Cloud Platform at Broadpeak. He leads the strategic development of Broadpeak’s cloud platform, including the building of the company’s infrastructure in the cloud and in public datacenters, the design of Broadpeak’s platform on top of the infrastructure and the shaping of the company’s applications to accommodate SaaS offerings.