You are here: Demand Partners > Real-time bidding > Macros

Macros for Demand Partners

Last updated on November 16, 2017

OpenX macrosFor OpenX, a command enclosed in curly braces {} that dynamically inserts attributes into your HTML or third-party ad creatives and click-through URLs when OpenX serves an ad. Other macros, like from your video player, may have alternate formatting. are commands that dynamically insert attributes into your HTML or third-party ad creatives and click-through URLs when OpenX serves an ad. To use OpenX macros, enclose each macro key in curly braces {} and insert it into the corresponding source code.

For example: {clickurl}

Note: OpenX will not replace macros that have been URL encoded. Additionally, if you use a macro for which OpenX is unable to find a replacement value, OpenX ignores the macro and leaves it in place in the ad creativeThe media asset associated with an ad, such as an image or video file. or click URL.

This page describes the following topics:

Supported macros

OpenX supports the following macros for OpenRTB buyers, which you can include in the ad markup field (adm) for each Bid object in your bid responseAfter evaluating a bid request, a real-time bidder’s communication to OpenX Ad Exchange, indicating if they’re interested in the impression, and if so, how much they’re willing to pay for it.. OpenX automatically and dynamically replaces each macro with the value specified in the following list before the ad is sent to the end-user. OpenRTB-specific macros are expressed as ${MACRO_NAME}.

Price macros

OpenX supports the following price macros:

Macro Is replaced with
${AUCTION_PRICE:OXCRYPT} The price of the won impressionA single display of an ad on a web page, mobile app, or other delivery medium. For deals, impression is a metric to relay the total number of ads that have served. See also billable impression, forecasted impressions. expressed as an encrypted value in CPI micros in the same currency as the bid. In adm, ${AUCTION_PRICE:OXCRYPT} is supported, but ${AUCTION_PRICE} is not.
{WINNING_PRICE} or {winning_price}

The winning price of the auction sent as an encrypted value in CPI micros of your account currency.

For example, a CPMCost per mille, a pricing method which calculates cost based on the number of impressions (per 1000). of $1 = 1,000 CPI micros = 1,000,000 CPM micros.

 

The 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. Your keys will be supplied during on-boarding.

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

OpenRTB-specific macros

OpenX supports the following OpenRTB macros (expressed in fields as ${MACRO_NAME}):

Macro Is replaced with
${AUCTION_BID_ID} The ID of the bid as specified in the BidResponse.bidid field.
${AUCTION_CURRENCY}

The currency for the corresponding winning auction price.

For example: "USD"

The advertiserIn OpenX, an account type that represents a business that runs advertising campaigns to display ads on websites.'s OpenX Ad Exchange account currency is used with this macro.

${AUCTION_ID} The ID of the bid requestWhen OpenX Ad Exchange receives an ad request, it sends a communication containing details about the impression to selected real-time bidders to solicit bids for it. as specified in the BidRequest.id field.
${AUCTION_IMP_ID} The ID of the impression as specified in the BidResponse.seatbid.bid.impid field .
${AUCTION_PRICE:OXCRYPT} The price of the won impression expressed as an encrypted value in CPI micros in the same currency as the bid. In adm (the ad markup field), ${AUCTION_PRICE:OXCRYPT} is supported but ${AUCTION_PRICE} is not.
${AUCTION_SEAT_ID} ID of the bidder seat for whom the bid was made.

Click macros

You must implement at least one OpenX click macro from the following table:

Macro Is replaced with
{clickurl}

The unencoded and time-sensitive URL for the selected ad that OpenX serves, which enables click tracking.

For example: http://ads.example.com/w/1.0/rc?ts=555YADAYADA555&r=

{clickurl_dbl_enc} or {clickurl_dbl_esc} The double-encoded and time-sensitive URL for the selected ad that OpenX serves, which enables click tracking.
{clickurl_enc}

The encoded and time-sensitive URL for the selected ad that OpenX serves, which enables click tracking.

For example: http%3A%2F%2Fads.example.com%2Fw%2F1.0%2Frc%3Fts%3D555YADAYADA555%26r%3D

Other macros

Price encrypting scheme

The price is encrypted using a custom encryption scheme designed to minimize size overhead while ensuring adequate security.

The encryption scheme uses a keyed HMAC-SHA1 algorithm to generate a secret pad based on the unique impression event ID. The encrypted price has a fixed length of 28 bytes. It is comprised of a 16-byte initialization vector, 8 bytes of ciphertext, and a 4-byte integrity signature. The encrypted price is web-safe base-64-encoded with padding characters omitted. Thus, the 28-byte encrypted price is encoded as a 38 character web-safe base 64 string.

The price is encrypted as:

  • <price xor HMAC-SHA1(encryption_key, initialization_vector)>

So decryption calculates:

  • HMAC-SHA1(encryption_key, initialization_vector)

And XORs with the encrypted price to reverse the encryption. The integrity stage takes 4 bytes of:

  • <HMAC-SHA1(integrity_key, price||initialization_vector)>

Where|| is concatenation.

For price decryption, use the code provided at the following repository:

https://github.com/openx/SSRTBPriceCrypter

How to insert OpenX Macros

You can manually insert OpenX macros into your HTML ads, third-party ads, and click URLs.

Feedback form