Protocol Version Differences¶

Note

This section covers the difference between 2.x and 4.x. For 5.x information see the 5.x Updating Overview section.
The differences between each protocol affect only the format and interpretation of the bid response. Bid requests work exactly the same.

The BidSwitch protocol has three major versions, 2.X, 4.X, and 5.x. Certain fields and the interpretation of data in them differ between each version. This section outlines the differences between 2.x and 4.x.

The bid response nurl field is interpreted differently, see the nurl Response Difference section for details.
Ensure that the protocol version field, which is used to define how the response will be interpreted by BidSwitch, is set to the correct protocol version. See the Bid Response Ext Object section for more details.
In 4.x the adm field is required for display ads, see the Bid Object section for more details.
The following bid extension fields are valid in 2.X, but not in 4.X. For more details, see the Deprecated 2.x Properties section.
- img_url
- js_url
- click_url

nurl Response Difference¶

The nurl bid response field is handled differently between each version. Use the table below to understand the expected response format for each version. For more information, see the Bid Object section.

nurl Version Differences¶
Version	Properties
2.x	The win notice URL. For banner impressions the ad markup should be returned via this URL. Ad markup should be in HTML format. For video impressions the URL should contain the URL of impression pixel. The URL may contain substitution macros, see the Macros section. For application banner inventory this field will be IGNORED, use `ext.js_url` instead.
4.x	The win notice URL. This field should not be used for submitting creative markup. The URL should contain the win price macro, see the Macros section. As this URL is called from the user’s browser, it should be SSL-compliant for requests with `imp.secure` set to `1`. This URL will be called by a server to server call if the bid request has the `ext.s2s_nurl` field value set to `1`.
5.x	The win notice URL. Similar to 4.x, except that the win price macro can only be used in one field per bid response. Either the `adm` or `nurl` field. See the 5.x Updating Overview or Bid Object section for details.

Deprecated 2.x Properties¶

The following fields are not valid in a 4.x response, but are part of the 2.x protocol. See the Bid Ext Object section for the latest protocol standards.

Bid Ext 2.X Objects¶
Field	Value	Description
img_url*	string	The URL of the creative image. In order to receive the user cookie and win price, this url should point to the Buyer handler and redirect to the actual creative location. The url may contain the win price macro, e.g. `${AUCTION_PRICE}`, but not the click macro. If this field is present, the `nurl` field of the bid response will be ignored.
click_url*	string	The creative click URL. Required if the `img_url` field is present.
js_url*	string	A Javascript-based win notice URL. For in-app inventory, the ad markup should be returned using this URL. For website or video inventory this field may be used as a substitute for the `nurl` field. Ad markup should be in JavaScript format. The URL may contain macros, see the Macros section for more details.

Valid Response Formats¶

For valid 4.x response examples, see the examples section in the 4.2 guide. If you wish to check for valid 2.x response formats see the 2.x guides, for example 2.6 or 2.5.

The following diff examples show how the expected JSON response has changed between version. The green represents the changes in 4.x, and the red shows version 2.x syntax.

Example Response diff

   {
      "id":"1234567890",
      "ext":{
-        "protocol":"2.5"
+        "protocol":"4.2"
      },
      "seatbid":[
         {
            "bid":[
               {
                  "id":"1",
                  "impid":"102",
                  "price":9.43,
                  "adid":"314",
                  "cid":"42",
                  "cat":[
                     "IAB12"
                  ],
+                 "adm":"<a href=\"http://adserver.com/click?adid=12345&tracker=${CLICK_URL:URLENCODE}\"><img src=\"http://image1.cdn.com/impid=102\"/></a>",
-                 "nurl":"http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}&click_url=${CLICK_URL:URLENCODE}",
+                 "nurl":"http://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}",
                  "iurl":"http://adserver.com/preview?crid=314",
                  "adomain":[
                     "advertiserdomain.com"
                  ],
                  "ext":{
                     "advertiser_name":"Coca-Cola",
                     "language":"en",
                     "cat":"IAB12",
-                    "img_url":"http://adserver.com/imp?impid=102&winprice=${AUCTION_PRICE}",
-                    "click_url":"http://adserver.com/click?impid=102",
                     "agency_name":"CC-advertising"
                  }
               }
            ]
            ],
+           "seat":"4"
         }
      ]
   }