Macros

Win price macro

In order for the exchange to convey certain information to the winning bidder (e.g., the settlement price), some substitution macros can be inserted into the win notice URL. Prior to calling a win notice URL, BidSwitch will search the specified URL for any of the defined macros and replace them with the appropriate data.

Note

The substitution is simple in the sense that wherever a legal macro is found, it will be replaced without regard to syntax correctness.

Win Price Macro Description
Value Description
${AUCTION_PRICE}

Settlement price for the auction. The substituted value will be defined as CPM. See the Bid Object section for usage details. This macro can be used, but with restrictions per protocol version.

  • In version 4.x, the win price macro should be used in nurl field, and the click tracking macro may be used in the adm field
  • In version 5.x, the win price can be used in the adm or nurl field, with restrictions. See the 5.x Updating Overview section for details.
  • In version 5.2, the win price can also be used in the burl field, with certain restrictions. See the Using the burl Field section for details.
Valid Use of Win Price Macro Quick Reference
  v4.x v5.0 & v5.1 v5.2 & v5.3
Browser Notification nurl nurl | adm nurl | adm
u2s or Browser Notification nurl nurl | adm (nurl | adm) + burl
s2s notification only, specified in the Bid Request using imp.ext.s2s_nurl = 1 nurl nurl nurl | burl **

Note

  • Please see the field descriptions in the Bid Object section for more precise details about each, and the 5.x Updating Overview and Using the burl Field sections for more details.
  • ** As it is an s2s call only, if the the burl field is given, the nurl field is ignored. Therefore, you should set the ${AUCTION_PRICE} macro in the field that will be called. See the Using the burl Field section for complete details.

Supplier Click Tracking URL Macro

Some Suppliers require the Buyer to add a Supplier click URL macro to all creatives for click reporting. Buyers wishing to bid on such bid requests should add the click tracking macro to the creative markup in the adm field. The Supplier will replace the macro with the Supplier click tracking URL. If the Supplier doesn’t support click tracking macros, then BidSwitch will replace the tracking macro with an empty string.

Note

  • This is a strict requirement if the bid request contains ext.clktrkrq field and is strongly recommended in other cases.
  • In the case of video and native inventory, click tracking is handled on the Supplier side and the click macro is not used, as well as the adm field.
Click Tracking Macro
Value Type
${CLICK_URL:URLENCODE} A placeholder for the Supplier click tracking URL in URL encoded form. Required for bids to Suppliers that support click tracking. No more than one click tracking macro can be used in the bid.adm field. Only single-encoded click tracking URLs are supported.

The Supplier click URL (if present) should be inserted before the landing page in the creative. The landing page URL should be single-escaped. For example, if the Buyer click-URL contains

http://dsp.com/click?bc=dnJD723&sspclick=${CLICK_URL:URLENCODE}

The macro is replaced and the user clicks the resulting URL

http://dsp.com/click?bc=dnJD723&sspclick=http%3A%2F%2Fssp.com%2Fclick%3Fic%3DbKk4%26lp%3D

The Buyer unescapes the sspclick parameter and redirects to the target URL while adding the landing page at the end

http://ssp.com/click?ic=bKks3k4&lp=http%3A%2F%2Fadvertiser.com%2Fhomepage

Note

Some Suppliers may keep the / and : characters unencoded, thus the resulting click URL may take a form such as the following

http://dsp.com/click?bc=dnJD723&sspclick=http://ssp.com%2Fclick%3Fic%3DbKk4%26lp%3D

True Price Macro

The true price macro can used in the win notice URL. This macro will indicate whether the Bid Response was processed by True Price, and it should be used in conjunction with the ${AUCTION_PRICE} macro.

True Price Macro
Value Type
${AUCTION_TP_MODE}

A placeholder which BidSwitch will populate with information indicating if True Price processed the Bid Response. The field can be populated with the following values:

  • 1 No True Price processing applied to this Bid Response. This is considered the control group used to benchmark its effectiveness
  • 2 True Price treated this Bid Response
  • An empty string. Indicates that the response did not go through True Price. This is returned if you used the ext.true_price_opt_out field to bypass True Price, see the Bid Response Ext Object section for more details.
# syntax to include in Bid Response
http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}&trueprice=${AUCTION_TP_MODE}

# Example Return
http://adserver.com/winnotice?impid=102&winprice=4&trueprice=2