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 an URI (Tag) which will allow the system to interrogate the Ad Server. The Ad tag usually contains what is often referred to as Macros, placeholders that broadpeak.io will replace with real values when requesting the Ad server.

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

Using Macros

When defined an Ad Server as source, you are given the possibility 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 personalization can be best achieved. This is done through these Macros.

System values

Some values can be retrieved from the system directly:
- 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.

Headers 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 defining the ADS configuration (Source->ADS), it is possible to map the information received in the Client/CDN request as header to Macro values into the defined ADS tag.

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

Example: we need to retrieve the value of the header "user-agent" in the client/CDN request and pass it to the Ad server under the Macro "user-agent". The ADS 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.
  • ⚠️ Capital letters should not be used in macros, only lowercase is accepted.

Query parameters

When defining 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 ADS tag.

Query parameter mapping to Query parameters

To retrieve "value" of the parameter "key" sent to broadpeak.io in the client/CDN request, you need to 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

📘

⚠️ Capital letters should not be used in macros, only lowercase is accepted.