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

Total Impressions Macro¶

Some Suppliers support the ${total_imp} macro in DAAST and VAST markup. For those Suppliers, BidSwitch will append this macro to the VAST impression URL, which is filled with the total audience size when the Vast or Daast URL is played.

When trading DOOH, the usage of this macro may result in a different tally than calculations based upon the dooh.impmultiply request field. Both parties should agree on which number to base their billing and discrepancy counts to prevent mismatches. The following Suppliers currently support this macro:

AdScale (a.k.a Ströer)

Example VAST Usage

<Impression><![CDATA[http://x.bidswitch.net/imp/${AUCTION_PRICE}/BSWhttp_A_B_Bdsp1.com_Bimp_Cprice_R_I_WAUCTION__PRICE_X/foo//${TOTAL_IMP}]]></Impression>