Substitution 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.

  • The win price macro should be in the seatbid.bid.burl field.

  • It may also be simultaneously present in the relevant seated.bid.media.ad.[video|audio|display].adm response field, but no more than 1 win price macro should be present in that field, otherwise BidSwitch records multiple impression events.

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. 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 placement.display.event.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