PDF

Win Notifications

Last updated on September 27, 2018

Every Demand Partner’s integration with OpenX Ad Exchange requires two actions related to win notifications:

Passing a winning price macro in bid responses to track impressions and spend.
Decrypting the winning price of an auction.

Passing the Winning Price Macro

You pass the winning price macro via the BidResponse.seatbid.bid.adm field.

While you may still use the Bidresponse.seatbid.bid.nurl field, this may lead to discrepancies if not configured properly, and if nurl response time is greater than 80 ms. OpenX will not honor any discrepancy disputes based on nurl.

You can leverage either {winning_price}, {WINNING_PRICE}, or ${AUCTION_PRICE:OXCRYPT} macros within the BidResponse.seatbid.bid.adm field. These macros expand to an encrypted value in CPI micros of your account currency. For example, a CPM of $1 = 1,000 CPI micros = 1,000,000 CPM micros.

NOTE
${AUCTION_PRICE} macro does not work in the adm field. OpenX requires an encrypted version of the macro to be used in the adm field.

Below is an example of the BidResponse.seatbid.bid.adm field with a click URL macro and an ${AUCTION_PRICE:OXCRYPT} winning price macro appended.

...
"adm": "<img src=\"http://imagename.location.com?click={clickurl}&winning_price=${AUCTION_PRICE:OXCRYPT}\"/>",
...

For more information, see Macros for Demand Partners.

SSRTB Winning Price Decryption Tool

The winning price is passed as unpadded web-safe base-64 encoding (per RFC 3548). You must convert this to standard base-64 encoding and pad the result. The price is decrypted with the encryption key, and the integrity of the price is verified with the integrity bits and the integrity key.

OpenX emails the encryption and integrity keys to you during your onboarding and account setup. You also can copy them from the right-side Summary panel of your Real-time Bid Settings page.

The message format is: init_vector (16 bytes), encrypted_price (8 bytes), integrity (4 bytes)

To see an example of the encryption and decryption of this value, see GitHub code example.

You can compile the SSRTBPriceCrypter Tool to decrypt and encrypt {WINNING_PRICE}, {winning_price}, or ${AUCTION_PRICE:OXCRYPT} macros.

Below is an example of how to use the SSRTBPriceCrypter.jar file with the encryption/decryption keys that your PDM provides:

$ java -jar SsRtbPriceCrypter.jar
Please enter your encryption key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Please enter your integrity key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Enter 0) to Exit 1) to Encrypt 2) to Decrypt: 1
Please enter the price (in micros) to encrypt: 6090
Encrypted: AAABS6engEx9GHPnypcRzlzv8bBrbE2ISbevew

Enter 0) to Exit 1) to Encrypt 2) to Decrypt: 2
Please enter the encrypted string: AAABS6engEx9GHPnypcRzlzv8bBrbE2ISbevew
Price: 6090

Enter 0) to Exit 1) to Encrypt 2) to Decrypt: 1
Please enter the price (in micros) to encrypt: 1880
Encrypted: AAABS6epI8Er3WytOd6XudG1dfSmmaaKgMTUlA

Enter 0) to Exit 1) to Encrypt 2) to Decrypt: 2
Please enter the encrypted string: AAABS6epI8Er3WytOd6XudG1dfSmmaaKgMTUlA
Price: 1880