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 in CPM. This macro should be used in the burl field, see the Response Bid Object section for usage details. As well as the burl field, its use is also supported in these fields: For Native Responses: seatbid.bid.burl, seatbid.bid.adm_native.jstracker or seatbid.bid.adm_native.imptracker For non-native Responses: seatbid.bid.burl or seatbid.bid.adm

Encrypting the Win Price

BidSwitch can process encrypted win price macros, and uses the same method as Google. To enable this for your integration, contact BidSwitch support to receive the integrity key and encryption key necessary for doing this. Both of these keys will be sent to you in web-safe base64 strings and they should be web-safe decoded and then base64 decoded by your application.

skU7Ax_NL5pPAFyKdkfZjZz2-VhIN8bjj1rVFOaJ_5o=  // Example Encryption key (e_key)
arO23ykdNqUQ5LEoQ0FVmPkBd7xB5CO89PDZlSjpFxo=  // Example Integrity key (i_key)

Encryption scheme

The price is encrypted using a custom encryption scheme that is designed to minimize size overhead while ensuring adequate security. The encryption scheme uses a keyed HMAC algorithm to generate a secret pad based on the unique impression event ID. The encrypted price has a fixed length of 28 bytes, comprised of:

• 16-byte initialization vector

• 8-bytes of ciphertext

• 4-byte integrity signature

The encrypted price must be web-safe base64-encoded, according to RFC 3548, with padding characters omitted. Thus, the 28-byte encrypted price is encoded as a 38 character web-safe base-64 string irrespective of the winning price paid.

# The encrypted format is:
{initialization_vector (16 bytes)}{encrypted_price (8 bytes)}{integrity (4 bytes)}

# Example encrypted prices:
WEp8wQAAAABnFd5EkB2k1wJeFcAj-Z_JVOeGzA  # 100 CPI micros
WEp8sQAAAACwF6CtLJrXSRFBM8UiTTIyngN-og  # 1900 CPI micros
WEp8nQAAAAADG-y45xxIC1tMWuTjzmDW6HtroQ  # 2700 CPI micros

The price needs to be encrypted as <price xor HMAC(encryption_key, initialization_vector)> so decryption calculates HMAC(encryption_key,initialization_vector) and xor’s with the encrypted price to reverse the encryption. The integrity stage takes 4 bytes of <HMAC (integrity_key, price||initialization_vector)> where || is concatenation.

The following example code outlines this, with the following definitions:

• iv initialization vector (16 bytes - unique to the impression)

• e_key encryption key (32 bytes - provided by BidSwitch Support)

• i_key integrity key (32 bytes - provided by BidSwitch Support)

• price (8 bytes - in micros of account currency)

• hmac(k, d) SHA-1 HMAC of data d, using key k

• a || b string a concatenated with string b

// example code
pad = hmac(e_key, iv)  // first 8 bytes
enc_price = pad <xor> price
signature = hmac(i_key, price || iv)  // first 4 bytes

final_message = WebSafeBase64Encode( iv || enc_price || signature )

Once enabled, you can return the encrypted price to BidSwitch who can then return it to the winning Buyer in the appropriate manner.

• You need to encrypt the value using SHA-1 HMAC. You can do this using a crypto library that supports SHA-1 HMAC, such as Openssl

• The encrypted value should be then encoded using web-safe BASE64

# <!-- Example billing URL (burl) which will have macro substituted -->
https://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}

# <!-- Example billing URL (e.g. burl) -->
https://adserver.com/winnotice?impid=102&winprice=1.34

# <!-- Example encrypted billing URL (e.g burl) -->
https://adserver.com/winnotice?impid=102&winprice=WEp8nQAAAAADG-y45xxIC1tMWuTjzmDW6HtroQ

Supplier Click Tracking URL Macro

If you require Buyers to include a click tracking macro in their creatives, Buyers will return this macro in the adm field. You should replace this macro with your Supplier click tracking URL. If you do not support click tracking macros and a Buyer replies with one in the adm field, BidSwitch will replace it with an empty string.

Note

In the case of video and native inventory, click tracking is handled on the Supplier side and the click macro is not used, nor is the adm field.

Click Tracking Macro

Value	Type
${CLICK_URL_ENC}	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.

If requested, the Supplier click URL 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_ENC}

The macro is replaced by the Supplier 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