Passing Macros in Bid Responses

Demand Partners

Last updated on September 27, 2018

on this page

• Supported Macros
  • Price macros
  • OpenRTB-specific macros
  • Click macros (at least one is required)
  • Other macros
• Price Encrypting Scheme
• How to Insert OpenX Macros

OpenX macros 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 creative or click URL.

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 response. 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:

OpenRTB-specific macros

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

Click macros

Implement at least one click macro from the following table. OpenX requires click macros to provide valid performance data that helps you purchase more effective inventory.

NOTE

The number of characters in the tracking URL that is returned when a user clicks an ad has been reduced, making this information easier to use and integrate.

Other macros

See additional supported macros. OpenX also supports the following macros, which you can use as needed:

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 the 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 GitHub repository.

How to Insert OpenX Macros

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

Inserting an OpenX macro into a URL

The following example shows how to manually insert a macro into a click-tracking URL:

http://example.com/click?src=ox&pageurl={techno.page_url_enc.market}

In this case, OpenX automatically replaces {techno.page_url_enc.market} with the URL where OpenX serves the creative.

Manually inserting an OpenX macro for cachebusting

Insert a random number into an ad tag so that the end user’s browser won’t reuse an ad that has already been displayed and cached. This is called cachebusting. This technique helps maximize your inventory, and helps minimize discrepancies between publisher and marketer delivery reports.

Use the following example as a reference for inserting a macro into an ad tag for cachebusting.

<img src="http://example.com/img.gif?cb={random}"/>

OpenX automatically replaces {random} with a random, ten-digit, alphanumeric string.

Manually inserting an OpenX macro in a third-party click URL

If you are using an unsupported third-party ad tag, use the following example as a reference for inserting a macro into a third-party click URL.

Consider the following existing third-party ad tag:

<a href="http://click_url.com/index.html">
                <img src="http://example.com/img.gif?cb=[replace_with_random_number]"></a>

When creating your ad in the OpenX UI, enter the value of the href link in the Click Tracking URL field and then replace the URL with {clickurl}. You can also use the {random} macro for cachebusting:

<a href="{clickurl}"><img src="http://example.com/img.gif?cb={random}"></a>

The output of the tag that is now using the {clickurl} and {random} macros:

<a href="http://ox-d.servedbyopenx.com/ma/1.0/rc?ai=e61725-1767-428e0-9654&ts=1hfeh348efhshdihfhsur">
                <img src="http://example.com/img.gif?cb=QZR9823492"></a>