"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

Macros

The following Macros are supported by Buzz. These macros may be included in Creative Templates, the content of the Creatives or the click_url field of the Creative. Macros are case-sensitive and should be surrounded by double curly brackets on both sides to be properly recognized. For example, the macro FOO should be represented in the creative as {{FOO}}, not {{Foo}}.

Basic Macros

MacroExpansion
AD-IDThe universal creative identifier supported by Ad-ID
AGEThe age of the user as reported by the exchange
AUCTION_IDUnique id for every bid request. It is a joining key for all the events associated with the bid request such as impression, clicks, and activities.
BID_TIME_UTCTime stamp of the bid time in YYYY-MM-DD HH:MM:SS format, URL-escaped.
BUZZ_KEYThe Buzz Key
CACHEBUSTERRandom number
GENDERThe gender of the user as reported by the exchange
HEIGHTHeight of the Creative
IMPRESSION_URLURL to count an impression. This macro must be present in all creative templates.
MEDIA_HOSTHost the Creative will be served from
WIDTHWidth of the Creative

User Macros

Relating to user identification.

MacroExpansion
ANDROID_IDAndroid Device ID
DNTWhether the user has Do Not Track or Limit Ad Tracking set
IOS_IDiOS Device ID
IP_ADDRESSIP address of the device, base 64 encoded (will be pseudo-anonymized when subject to GDPR without explicit consent).
IP_ADDRESS_ESCIP address of the device, URL-escaped (will be pseudo-anonymized when subject to GDPR without explicit consent).
IP_ADDRESS_IPV6IP address of the device when IPV6 is present, always URL-escaped (will be pseudo-anonymized when subject to GDPR without explicit consent).
USER_IDDevice ID for mobile, cookie for desktop. This will populate with either a cookie on a desktop OR an iOS/Android ID for mobile (will be pseudo-anonymized when subject to GDPR without explicit consent).
USER_AGENTFull user agent of the device, base 64 encoded (will be blank when subject to GDPR without explicit consent).
USER_AGENT_ESCFull user agent of the device, URL-escaped (will be blank when subject to GDPR without explicit consent).
USER_ID_SHA1Device ID for mobile, hashed using the SHA1 algorithm for use with postback providers
LIVERAMP_IDLPerson-level Liveramp RampID. Use of this macro requires approval from Liveramp directly (will not work unless client has approval). Please reach out to your Beeswax CSM to learn more.

Campaign Object Macros

Objects relating to the campaign setup.

MacroExpansion
ACCOUNT_IDAccount ID for the impression
ADVERTISER_IDAdvertiser ID for the impression
ADVERTISER_ID_ALTAlternative advertiser ID for the impression
ADVERTISER_NAMEAdvertiser name (escaped)
CAMPAIGN_IDCampaign ID for the impression
CAMPAIGN_ID_ALTAlternative campaign ID for the impression
CAMPAIGN_NAMECampaign name (escaped)
CREATIVE_IDCreative ID for the impression
CREATIVE_ID_ALTAlternative creative ID for the impression
CREATIVE_NAMECreative name (escaped)
LINE_ITEM_IDLine Item ID for the impression
LINE_ITEM_ID_ALTAlternative line item ID for the impression
LINE_ITEM_NAMELine Item name (escaped)

Regulatory Macros

Relating to GDPR and related regulations.

MacroExpansion
GDPR_CONSENT_STRINGThe consent string on the bid request used for GDPR compliance.
IS_GDPRWhether the auction is subject to GDPR.
IS_GDPR_CONSENTEDWhether the auction is regulated by GDPR AND the customer has been granted consent by the end user
US_PRIVACY_STRINGThe US Privacy String on the bid request used for CCPA compliance.

Inventory/Content Macros

MacroExpansion
PAGEThe full URL of the page the ad was served on
DOMAINDomain the impression was served on
REFERRERDomain the user came from before landing on domain the impression was served on
REFERRER_URL_ESCEscaped version of the REFERRER macro (above)
SITE_IDSite ID that the impression was served on
SITE_NAMESite Name that the impression was served on
APP_BUNDLEMobile application bundle the impression was served on
APP_IDUnique ID of the app within the exchange
APP_NAMEMobile application name the impression was served on
APP_STORE_URLURL the mobile application on the app store
DEAL_IDThe private marketplace deal ID targeted for this impression
PLACEMENT_IDPlacement ID for the impression reported by the exchange.
PUBLISHER_IDPublisher ID for the impression reported by the exchange.
INVENTORY_SOURCEExchange inventory source (i.e. Rubicon, Mopub etc)
EXCHANGE_HANDLEThe exchange abbreviation for each inventory source (i.e. "rp" for Rubicon). Exchange handles are used in conjunction with exchange specific IDs in targeting (i.e. rp/12345 for a Rubicon specific site ID)
REWARDEDWhether the auction was for rewarded video
AUTOPLAY_BLOCKEDThe Blocked Attribute Field (battr) is used for conveying attributes that are blocked by the inventory source. ​
This macro will display a boolean result in the bid response:
1 if blocked
0 if not blocked

Location Macros

MacroExpansion
COUNTRY_CODETwo-character country code of the device/user.
LATThe latitude of the device/user (will be truncated to three decimal places when subject to GDPR without explicit consent).
LONGThe longitude of the device/user (will be truncated to three decimal places when subject to GDPR without explicit consent).
METRO_CODEThe metro code of the device/user. Metro code is the OpenRTB equivalent of DMA.
ZIP_CODEThe zip code of the device/user.
CITY_CODEThe city of the device/user, using United Nations Code for Trade and Transport locations, as defined in the oRTB spec for the geo.city object.
REGIONThe state/region of the device/user. In the US, this is the 2 letter state code (I.e. CT). For other countries this is the 2 letter country or region code (i.e. AU for Austrailia).

Mobile/Device Macros

MacroExpansion
DEVICE_MAKEThe device make that the ad was served on (i.e. Apple, Samsung)
DEVICE_MODELThe device model that the ad was served on (i.e. iPhone 6s, Galaxy S6)
DEVICE_TYPEThe type of device the impression was served on.
PLATFORM_OSOperating system of the device the ad was served on (i.e. iOS, Android)
PLATFORM_OS_VERSIONThe version of the operation system of the device the ad was served on (i.e. 17.0)
PLATFORM_CARRIERMobile carrier of the device the ad was served on (i.e. Verizon, AT&T)

Video Macros

MacroExpansion
EVENT_START_URLURL for tracking video starts
EVENT_Q1_URLURL for tracking first quartile video plays
EVENT_MID_URLURL for tracking video midpoints
EVENT_Q3_URLURL for tracking third quartile video plays
EVENT_COMPLETE_URLURL for tracking video completes
EVENT_SKIP_URLURL for tracking video skips
EVENT_MUTE_URLURL for tracking video mutes
EVENT_UNMUTE_URLURL for tracking video unmutes
EVENT_PAUSE_URLURL for tracking video pauses
EVENT_RESUME_URLURL for tracking video resumes
EVENT_FULLSCREEN_URLURL for tracking video fullscreen events
EVENT_CLOSE_URLURL for tracking close events
PLAYER_HEIGHTVideo content player height
PLAYER_WIDTHVideo content player width

URL Macros

NOTE: These macros cannot be included in the click_url field of the Creative. They may only be included in the creative_content or inside a Creative Template.

MacroExpansion
CLICK_URLClick-through URL, including both the CLICK_DESTINATION and CLICK_TRACKING components
CLICK_DESTINATIONResolves to the destination click URL, can include other macros when expanded
CLICK_TRACKING_URLTracking-only URL, will not redirect to destination page
CLICK_URL_ESCEscaped version of the CLICK_URL macro, for use when being redirected by another ad server
NUM_DEST_URL_ESCAPESNumber of escapes to be used by your ad server when escaping the final destination URL. Required by some 3rd party ad servers to correctly handle destination URL redirection.

Use this macro in conjunction with the CLICK_URL macro
NUM_DEST_URL_ESC_ESCAPESNumber of escapes to be used by your ad server when escaping the final destination URL. Required by some 3rd party ad servers to correctly handle destination URL redirection.

Use this macro in conjunction with the CLICK_URL_ESC macro