Ad Macros

Consideration for data to be sent to the Ad Server for personalized ad insertion

When defining an Ad Server as Source in broadpeak.io, it is necessary to set a URI (Ad Tag) which will allow the system to question the Ad Server. The Ad Tag usually contains what are often called Macros, placeholders that broadpeak.io will replace with actual values when requesting the Ad Server.

The Ad Tag and the necessary Macros will be provided by the Ad Technology partner that acts as your Ad Server or SSP.

Using Macros

When setting an Ad Server as source, you have the option to enter the Ad Tag coming from the Ad Technology provider of your choice. You can enter a URL and some query parameters also called Macros.

Part of the concept of targeting requires the Ad Technology provider to retrieve dynamic values so that personalization can best be achieved. This is done via these Macros.

System Values

Some values can be retrieved directly from the system:
- Cachebuster value: $MMVAR_CACHE_BUSTER
- Live break Duration in seconds: $_MMVAR_LIVEAR_SLOTDURATION
- Client IP: $MAP_REMOTE_ADDR
- Live break Duration in ms: ${_MMVAR_LIVEAR_SLOTDURATION}000
- Signal ID: $_MMVAR_LIVEAR_SIGNALID

Example:

?max_pod_duration=$_MMVAR_LIVEAR_SLOTDURATION&cb=$MMVAR_CACHE_BUSTER&ip=$MAP_REMOTE_ADDR

Or

?pmxd=${_MMVAR_LIVEAR_SLOTDURATION}000&cb=$MMVAR_CACHE_BUSTER

Values from the Client Request

Some values can be directly retrieved from the client/CDN request query parameters or headers.

Header values

By default, the following headers are forwarded from the Client/CDN request to the Ad Server:

  • X-Forwarded-For: The client IP can be retrieved from here if the CDN is configured to pass it over.
  • User-Agent: The user-agent of the device if provided by the CDN in the request.

Header value mapping to Query parameters

When setting the Ad Server configuration (Source->Ad Server), it is possible to map the information received in the Client/CDN request as header to Macro values into the defined Ad Server Tag.

To retrieve the "value" of the header "header" sent to broadpeak.io in the client/CDN request, you must use the following variable scheme: $http_header

Example: we need to retrieve the value of the "user-agent" header in the client/CDN request and pass it to the Ad Server under the "user-agent" Macro. The Ad Server Tag configuration should contain the following:

?user-agent=$http_user_agent

๐Ÿ“˜

  • Headers that contain a dash - character should transform the dash in underscore _ as done for user-agent above.
  • โš ๏ธ Uppercase letters should not be used in macros, only lowercase letters are accepted.

Query parameters

When setting the Ad Server configuration, it is possible to map the information received in the Client/CDN request as query parameter to Macro values into the defined Ad Server Tag.

Query parameter mapping to Query parameters

To retrieve the "value" of the "key" parameter sent to broadpeak.io in the client/CDN request, you must use the following variable scheme: $arg_key

Example: we need to retrieve the value of the query parameter "user" in the client/CDN request and pass it to the Ad Server under the query parameter "user_id". The Ad Server Tag configuration should contain the following macro:

user_id=$arg_user

๐Ÿ“˜

โš ๏ธ Uppercase letters should not be used in macros, only lowercase letters are accepted.