5.x Updating Overview

Use the information in the following sections to understand the slight differences between each version of the v5.x protocol.

v5.3

Using the burl Field

Display

  • The burl field is only valid from v5.2 onwards.

  • The burl should contain the ${AUCTION_PRICE} macro.

  • The ${AUCTION_PRICE} macro should be a part of a valid URL.

  • If the burl field is given, the nurl field becomes optional. Both fields are called, unless the Bid Request specifies a s2s notification only by setting the imp.ext.s2s_nurl field set to 1.

  • If the Bid Request sets the imp.ext.s2s_nurl field value to 1, only the burl field will be called. Therefore, use the burl field to pass the win price macro.

  • It is allowed to respond with a non-secure burl for secure bid requests.

  • When using the ${AUCTION_PRICE} macro in the burl field, it may be simultaneously present in either the adm or nurl field, not both. Using ${AUCTION_PRICE} in the nurl and adm at the same time is not allowed. If using either of these fields, you should NOT omit the ${AUCTION_PRICE} macro in the burl field.

  • No more than one win price macro can be used in the adm field, otherwise BidSwitch records multiple impression events.

Video/Native

Video and Native use the same logic as Display.

  • If the Bid Request specifies a s2s notification only, using ext.s2s_nurl set to 1, then only one of either the nurl or burl fields may be used. As it is an s2s call only, if the the burl field is given, the nurl field is ignored. Therefore, you should set the ${AUCTION_PRICE} macro in the field that will be called.

  • If the Bid Request does not explicitly set an s2s call, then nurl, burl, or both can be used and both will be called. In this scenario, both fields can contain the ${AUCTION_PRICE} macro.

"burl":"http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}",

v5.0 and v5.1

The main difference between 5.x and previous versions (v2.x and v4.x) is that it allows the adm bid response field to contain the win price macro, ${AUCTION_PRICE}. This simplifies the protocol by removing some extended fields, making it more compliant with OpenRTB standards, and also letting Buyers know the clearing price at the time the creative markup is formed by placing the price macro in the iframe source URL.

Upgrading to this version from v2.x will also grant users access to features added in v4.x of the protocol such as native, audio, and programmatic TV.

There is a number of usage limitations around the price macro being placed in the adm field:

  • No more than one win price macro can be used in the adm field, otherwise BidSwitch records multiple impression events.

  • The ${AUCTION_PRICE} should be a part of a valid URL.

  • The ${AUCTION_PRICE} should be present in only one of either the adm field or nurl field, never both.

Note

Only one price macro per bid response is allowed. You should not use it in the adm and nurl fields simultaneously.

URL Formatting

The price macro must be placed within a valid URL and located in the src attribute of an HTML tag (e.g. <iframe>, <script> or <img>). Use the following examples to ensure you use the correct syntax.

# valid URLs
"adm": "<iframe src=\"http://dsp.com/imp?bc=12345aaabbb&price=${AUCTION_PRICE}\"><\/iframe>"
"adm": "<script src=\"http://dsp.com/js_imp?bc=12345aaabbb&price=${AUCTION_PRICE}\"><\/script>

# invalid URL
"adm":"<img src=\"http://cdn.com/img?id=123\" onclick=\"impfn(${AUCTION_PRICE})\"/>"

Server to Server Restriction

Including the price macro in the adm field is not allowed for bid requests that use server to server impression notification. These are marked with the ext.s2s_nurl = 1 flag.

For server to server notifications, it is required to provide the win price macro in the nurl field, or from v5.2 onwards the burl field.

Upgrading from 4.x

The 5.x protocol is fully compatible with v4.x, so to upgrade you only need to set the bid response ext.protocol field to “5.3”

{
  "id": "1234567890",
  "ext": {
    "protocol": "5.3"
  },
}

  • If you are currently using the 4.x protocol, then no other changes are required.

Note

  • In the case of expired impressions or price errors, BidSwitch forwards impression calls originating from the adm field to the Buyer with a clearing price of zero. If the impression call originates from the nurl field then BidSwitch responds with a 1x1 pixel.

  • You still have the option of using the nurl field to send the impression clearing price as supported in 4.x versions.

Upgrading from 2.x

Upgrading Context

  • The seatbid.bid.iurl response field is required for banner bids starting from version 4.0, so it has to be supported to migrate properly from 2.x to 5.x

  • In 2.x, BidSwitch was building the actual ad markup using the parameters provided in the Buyer Bid Response (nurl field etc), whereas in 5.x the Buyer is fully responsible for the Ad Markup and BidSwitch keeps its interference to a minimum

Upgrading Steps

To upgrade your implementation to 5.x and start its feature, use the following steps.

  1. Set the bid response ext.protocol field to "5.3"

  2. Move the impression/ad serving URL from whichever of the following valid 2.x fields it is currently used in (nurl | ext.js_url | ext.img_url) to the adm field

  3. Wrap it with the appropriate HTML tag. Examples using the <iframe>, script and img tags are given below.

Example 1:

Replacing the nurl field with adm and wrapping the impression link with the <iframe> tag.

Note

If you wrap the the impression URL using an <iframe> tag, then you should also define the frame width and height, as in the above example. This is to ensure better rendering of the ad on the user’s device.

{
   "seatbid": {
      "bid": {
-         "nurl": "http://dsp.com/imp?bc=12345aaabbb&price=${AUCTION_PRICE}"
+         "adm": "<iframe src=\"http://dsp.com/imp?bc=12345aaabbb&price=${AUCTION_PRICE}\ "height=\"300\" width=\"300\"><\/iframe>"
      }
   },
   "ext": {
-      "protocol": "2.6"
+      "protocol": "5.3"
   }
}
Example 2:

Replacing the ext.js_url field with adm and wrapping the impression link with the <script> tag.

{
   "seatbid":{
      "bid":{
-       "ext":{
-            "js_url":"http://dsp.com/js_imp?bc=12345aaabbb&price=${AUCTION_PRICE}"
-         }
+       "adm": "<script src=\"http://dsp.com/js_imp?bc=12345aaabbb&price=${AUCTION_PRICE}\"><\/script>"
    }

      }
   },
   "ext":{
-      "protocol": "2.6"
+      "protocol": "5.3"
   }
}
Example 3:

Replacing the ext.img_url field with adm and wrapping the impression link with the <img> tag.

{
   "seatbid":{
      "bid":{
-         "ext":{
-            "img_url":"http://dsp.com/img_imp?bc=12345aaabbb&price=${AUCTION_PRICE}",
-            "click_url":"http://dsp.com/click?bc=12345aaabbb"
-        }
+         "adm": "<a href=\"http://dsp.com/click?bc=12345aaabbb\">
+                 <img src=\"http://dsp.com/img_imp?bc=12345aaabbb&price=${AUCTION_PRICE}\"/><\/a>"
      }
   },
   "ext":{
-      "protocol": "2.6"
+      "protocol": "5.3"
   }
}

Note

  • In the case of expired impressions or price errors, BidSwitch forwards impression calls originating from the adm field to the Buyer with a clearing price of zero. If the impression call originates from the nurl field then BidSwitch responds with a 1x1 pixel.

  • You still have the option of using the nurl field to send the impression clearing price as supported in 4.x versions.

  • Click tracking is also different from v2.x to v5.x, to learn more about it see the Supplier Click Tracking URL Macro section.