Serving Impressions Win & Price Notification

Win Notification

For integrations not using the BidResponse.Seatbid.Bid.ext.burl parameter, VMX takes no explicit steps to notify a bidder of an auction win or impression served. However, a notification can be set up. If the bidder controls the ad server for the creative, record the ad call from the browser to track impressions. For creatives served by a third party (e.g. DFA), a separate (1x1) impression tracking pixel can be included with the creative html/javascript that initiates a separate call for win notification.

Win Price Notification & Macros

Basic Win Price Macro

${AUCTION_PRICE}

Settlement price using the same currency and units as the bid.

Price notification is accomplished via macro replacement while serving the ad. The substitution macro must be placed in the ad markup and is required to be included. The exchange performs the data substitution when the markup is passed in the “adm” attribute of the bid response. Bidders should include any of the available macros in either the ad call or an added tracking pixel.

Win Price Macro - AES Encrypted

We also support AES encryption based on 128-bit key in CBC mode without padding. One key per DSP is provided upon integration.

${AUCTION_PRICE:BASE64URL}

Settlement price using the same currency and units as the bid (is always in USD), AES encrypted per detail below.

The result is Base64 URL Safe encoded. A decoded result is an array of bytes, which consists of two parts: a 16 byte IV (Initialization Vector) followed by an encrypted price. The IV is not encrypted but simply appended. Use the IV value when proceeding with decryption (use it as the IV when initializing the AES Cipher, passed in as an IVParameterSpec object in Java Encryption API). To decrypt the price, use the shared 128-bit key.

In summary, we first pad with zeros from the left, then encrypt, then pad with a 16 byte IV on the left, then URL-Safe Base64 encode. Below is an end-to-end example.

Note: the final value cannot be reproduced because a random IV is always included.

Example Cipher: AES/CBC/NoPadding

Example Key: 23271E5CE4A96C03

Auction Price CPM: 1.12

Padded Price: 0000000000001.12

Padded Price Binary Array Form: [48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 48, 49, 46, 49, 50]

Block size (bits): 16

IV (1 block, random value): [​-67, 9, -53, 29, 65, 126, -51, -73, -65, -62, 35, -2, 37, 92, 122, 16​]

Encrypted Binary Array Form: [​-77, 49, 50, 115, 80, 84, 61, 58, 51, -23, -127, 69, 112, -48, -126, 61​]

Encrypted size (bytes): 16 Final Binary Array Form (append encrypted value after the IV): [122, 16​, ]

Incl. IV size (bytes): 32

Base 64 URL-Safe Encoded (macro replacement): vQnLHUF-zbe_wiP-JVx6ELMxMnNQVD06M-mBRXDQgj0

Decrypted Data: 0000000000001.12

Click Tracking Macro

Bidders wanting to record click data for reporting should include a click URL macro to all creatives. Add the macro ${CLICKURL} or ${CLICKURLENC} to the creative markup in the adm field (the URL is encoded and used as a parameter value). VMX will replace the macro with our own click tracking URL. Our click URL will automatically redirect to the original URL as the final parameter.

Creative Audit Calls

All creatives received within bid responses by VMX in the openRTB protocol are dynamically registered and reviewed. Besides the primary and secondary review, creatives could be further scrutinized to ensure consistent behavior of the ad and adherence to our strict standards. Be aware that during the review process creative content stored in our database is served multiple times on the browser by our creative testing engine. This could result in the client impression beacon being fired and received by the partner.

Test Identification

Bidders must remove and discard the test impressions from their platform revenue and budget calculations. Test impressions can easily be distinguished from the legitimate impressions as they do not have the price macro ${AUCTION_PRICE} (and variations) replaced by the actual price value, but would instead be replaced by the text ‘AUDIT’​.

Every time the creative is called for testing, the macro is replaced with the text AUDIT. Bidders should not count, or remove these calls, because they are only test impressions.

The test identification macro was implemented to help bidders recognize impressions sent from the creative tester. Any discrepancy between real and test impressions should be addressed and investigated by both the VMX and the bidder.

Examples

Instance when the impression beacon is fired by creative tester. Note the red text displays as AUDIT, indicating this call originated from the creative tester.

a=AUDIT​&t=FVPaWQ9MCZjZj0xJmZwPTEuMDEwMDMmZW09SEdKTVM0ej0mdHA9MCZ1PSUzQ2lmcmFtZSUyMH NyYyUzRCUyMmh0dHBzJTNBJT

Instance when the impression beacon is fired after an exchange auction occurred and when the ad is rendered. Note the word AUDIT displayed in red text indicates this call originated from the creative tester.

a=0.5335​&t=OQAaWQ9MCZjZj0xJmZwPTAuNTMzNSZlbT1PVUhNUzR6PSZ0cD0wJnU9JTNDc2NyaXB0JTIwdHlwZS UzRCUyMnRleHQlMkZqYXZhc2NyaXB0JTIyJTIwbGFuZ3VhZ2UlM0