Dynamic Macros (Real-Time Custom Values)

Stinger supports the ability to pass dynamic variables into Creatives in real time through a Bidding Agent or Augmentor. This is an advanced use case, and can be very valuable when the bidding system needs to effect the display or behavior of the creative itself.

Examples of how you can use dynamic variables include:

• Loading a dynamic image into the creative after rendering
• Passing a variable from the bidding agent or augmentor into the click URL so you can track your bidding decisions in your site analytics
• Changing text within the creative in real-time, such as airline destination codes or discount pricing.

This document describes how to execute dynamic variables in each stage of your implementation.

Set-Up

First, it is important to realize that dynamic macros can only be executed in conjunction with a custom Bidding Agent or Augmentor.

Second, you must ask the Beeswax team to enable your Buzz instance to allow dynamic macros.

Buzz DYNAMIC Macros

Once your Buzz instance is enabled, you will able to use special Macros in your creatives that are intended to be replaced in real-time by your bidding agent. These macros are in the format:

{{DYNAMIC:<NAME>:STRING}}

For example, if you wanted to pass the airline flight number into your creative, you might include a macro like this:

{{DYNAMIC:FLIGHT:STRING}}

Unlike custom macros, the type should always be STRING.

The macro itself will most commonly be included in the creative_content or creative_content_tag fields of the Creative, but they are also allowed in the click_url, scripts and pixels fields, as well as the Creative Templates and Creative AddOns objects.

There is a maximum of five DYNAMIC macros per creative, including all fields listed above.

Bidding Agent or Augmentor Implementation

The values for the dynamic macros are provided in real-time from your bidding agent or augmentor. See the "dynamic_macro" message in the request.proto for more details.

Constraints of dynamic macros:

• Up to 5 dynamic macros per creative are accepted from your bidding agent or augmentor, any macros above 5 will be ignored
• The dynamic macro "name" from your bidding agent or augmentor is case-insensitive (i.e. a name “foo” and a name of “FOO” will be treated as the same "name").
• Values cannot include other Beeswax macros or other dynamic macros (i.e. a value from your bidding agent of “foo{{USER_ID}}” is not valid).
• Dynamic macros are not supported for HTML5 creatives hosted in Beeswax.

Handling macros without values:

There are two ways to handle dynamic macros without values. Firstly, you can simply not respond with the "name" and "value" fields from your bidding agent or augmentor. In this case the macro will not expand and will appear as {{DY:}}. Secondly, you can respond with the "name" field but leave the "value" field blank. In this case the macro will expand to an empty string.

Correctly escaping dynamic macros values when used within URLs

If you are placing dynamic macros within URLs, you should handle the escaping of dynamic macro values differently: