bidswitch protocol for suppliers
TRANSCRIPT
VERSION INFORMATION
1 Protocol Release Notes 21.1 24th September 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2 18 August 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3 28th May 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.4 14th April 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.5 30th March 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.6 25th February 2021 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.7 21st December 2020 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.8 19th November 2020 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.9 12th November 2020 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.10 15th September 2020 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.11 7th September 2020 - iOS 14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.12 v1.0 - June 2017 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Sensitive Categories and Rich Media 62.1 Supported Rich Media Frameworks . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Backward Compatibility 8
4 Data Compression 9
5 Macros 115.1 Win price macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.1.1 Encrypting the Win Price . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125.2 Supplier Click Tracking URL Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6 Supplier Bid Request 156.1 Impression Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.1.1 Impression Ext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196.1.2 SkAdNetwork Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206.1.3 skadnetlist object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216.1.4 Example Impression Object JSON . . . . . . . . . . . . . . . . . . . . . . . 21
6.2 Banner Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
i
6.2.1 Banner JSON Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246.3 Format Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.4 Video Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.4.1 Video Ext Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286.4.2 Video Object Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.5 Audio Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316.5.1 Audio Object Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.6 Native Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346.6.1 Native Object Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.7 Native Request Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356.7.1 Native Asset Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356.7.2 Native Asset Title Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366.7.3 Native Asset Image Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366.7.4 Native Asset Video Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376.7.5 Native Asset Video Object Extension . . . . . . . . . . . . . . . . . . . . . . 376.7.6 Native Asset Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376.7.7 Native Placement Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376.7.8 Event Tracker Request Object . . . . . . . . . . . . . . . . . . . . . . . . . . 386.7.9 Event Tracking Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386.7.10 Event Tracking Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386.7.11 Example Native Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.8 Private Marketplace Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416.8.1 Private Marketplace Object Example . . . . . . . . . . . . . . . . . . . . . . 41
6.9 Deals Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426.9.1 Deal Extension Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436.9.2 Deals Object Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.10 Device Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446.10.1 Device Ext Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.11 Geo Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486.11.1 Geo Object Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
6.12 Metric Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496.12.1 Metric JSON Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6.13 User Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496.13.1 User Ext Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516.13.2 Consented Provider Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 526.13.3 FloC Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536.13.4 Extended Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536.13.5 User Object Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
6.14 Ext Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566.15 ads.txt Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576.16 Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.16.1 Segment Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586.17 Source Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.17.1 Source Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596.17.2 SupplyChain Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606.17.3 Supply Chain Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616.17.4 Example Source JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.18 Site Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
ii
6.18.1 Site Ext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636.18.2 SSP Site Object Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.19 App Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646.19.1 App Ext Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.20 Content Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666.21 DOOH Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686.22 Publisher Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.22.1 Publisher Object Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696.23 Regulation Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.23.1 Regs Ext Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706.24 Required Fields per Buyer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716.25 Bid Request JSON Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.25.1 Banner Ad Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . 716.25.2 Native Ad Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 746.25.3 Video Ad Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 776.25.4 Audio Ad Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 796.25.5 DooH Request Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7 Supplier Bid Response 847.1 Seat Bid Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857.2 Response Bid Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
7.2.1 Bid Ext Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 887.2.2 SkAdNetwork Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897.2.3 SkAdNetwork Fidelities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907.2.4 Video Response Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
7.3 Native Response Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917.3.1 Native Assets Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927.3.2 Native Assets Title Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937.3.3 Native Assets Image Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 937.3.4 Native Asset Video Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947.3.5 Native Asset Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947.3.6 Native Link Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957.3.7 Native Response Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.4 Bid Response JSON Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967.4.1 Banner Bid Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967.4.2 Native Bid Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 967.4.3 Video Bid Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.4.4 BidSwitch No Bid Reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987.4.5 Audio Ad Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997.4.6 TV/DOOH Bid Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
8 BidSwitch Data Centres 1018.1 IP Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
9 Anomaly Detection 1029.1 Benefits of Anomaly Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
10 API Authorization 105
iii
10.1 Creating an API User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10510.2 Getting an API Auth Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
11 Discrepancy Reporting 10711.1 Disputing a Discrepancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
12 Glossary 108
13 SmartSwitch Overview 11013.1 SmartSwitch Traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11013.2 SmartSwitch and QPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
13.2.1 SmartSwitch Buyer Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . 11113.2.2 SmartSwitch Supplier Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . 112
13.3 QPS Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
14 Discrepancy API for Suppliers 11414.1 Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11414.2 Getting API Credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
14.2.1 Creating an API User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11514.2.2 Getting an API Auth Token . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
14.3 Uploading a Discrepancy Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11614.4 Uploading Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11714.5 Upload Report Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
14.5.1 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11714.5.2 Report Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11814.5.3 Report Data Values Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
14.6 Example Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11814.6.1 Zero Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11914.6.2 Hourly Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11914.6.3 Supplier Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12314.6.4 Minimal report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12414.6.5 Several days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
14.7 Upload Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
15 Supplier No Bid Reason 12715.1 Example Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12815.2 Enabling No Bid Reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
16 Supplier User Matching 12916.1 Bid Request Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12916.2 Supplier User Matching Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13016.3 Supplier Initiated User Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13116.4 Cookie Syncing Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13216.5 BidSwitch Initiated User Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13316.6 Supported Sync Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
17 Supplier First-Party User-Matching 13517.1 First-Party Cookie Syncing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13517.2 Direct-like User Syncing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
iv
17.2.1 URL Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13617.2.2 Supplier Initiated Direct Syncing . . . . . . . . . . . . . . . . . . . . . . . . 13617.2.3 Bid Request JSON Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 13717.2.4 Example Bid Request With UUID Sync . . . . . . . . . . . . . . . . . . . . 137
Index 139
v
BidSwitch Protocol for Suppliers, Release 1.0
This guide covers the latest version of the BidSwitch Supplier Protocol. It is based on the latestOpenRTB Protocol Specification V2.51, and helps Suppliers to integrate with BidSwitch, and thusaccess all of its connected Buyers.
For Suppliers who wish to integrate with BidSwitch, if you are fully compatible with this spec, youcan be integrated much more quickly than waiting for a bespoke integration to be developed.
1 http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf
VERSION INFORMATION 1
CHAPTER 1
PROTOCOL RELEASE NOTES
1.1 24th September 2021
Added support for the site|app.ext.inventorypartnerdomain bid request field. This field wasadded in the (app-)ads.txt v1.0.3 specification2 update. See the Site Object (page 62) or App Object(page 64) section for more details.
1.2 18 August 2021
Added support of the optional seatbid.bid.bundle field to response bid object; see Response BidObject (page 85) for details.
1.3 28th May 2021
Support updated for the SKAdNetwork3 protocol response extension to include the addition of thefidelities object. See the SkAdNetwork Extension (page 89) section for more details.
• seatbid.bid.ext.skadn.fidelities
• seatbid.bid.ext.skadn.fidelities.fidelity
• seatbid.bid.ext.skadn.fidelities.nonce
• seatbid.bid.ext.skadn.fidelities.timestamp
• seatbid.bid.ext.skadn.fidelities.signature
2 https://iabtechlab.com/ads-txt/3 https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/
skadnetwork.md
2
BidSwitch Protocol for Suppliers, Release 1.0
1.4 14th April 2021
Added support for passing the Federated Learning of Cohorts (FLOC) ID using the Google format,user.ext.floc, see the FloC Object (page 53) section for details.
1.5 30th March 2021
Added support for the following fields:
• site.ext.amp
• geo.accuracy
• geo.metro
1.6 25th February 2021
Updated support for the IAB SKAdNetwork Specification4, which resulted in the following bidrequest additions.
• imp.ext.skadn.versions,see the Impression Ext (page 19) section for more details
• imp.ext.skadn.skadnetlist
• imp.ext.skadn.skadnetlist.max
• imp.ext.skadn.skadnetlist.excl
• imp.ext.skadn.skadnetlist.addl
• device.ext.atts, see the Device Object Properties (page 44) section for more details
1.7 21st December 2020
• Support added for user.ext.eids. This is the Open RTB Extended User Identifiers5 com-munity extension. See the Extended Identifiers (page 53) section for details.
• Deprecated the user.ext.xuids field which duplicates the eids functionality, see the ExtendedIdentifiers (page 53) section for details
• Added support for the blocked apps bapp field, see the Supplier Bid Request (page 15) sectionfor details
4 https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/extensions/community_extensions/skadnetwork.md
5 https://github.com/InteractiveAdvertisingBureau/openrtb/tree/master/extensions/2.x_official_extensions
1.4. 14th April 2021 3
BidSwitch Protocol for Suppliers, Release 1.0
1.8 19th November 2020
Added the imp.pmp.deals.ext.buyer_wseat field. This specifies the Advertisers/Agencies thatshould have access to this deal in the DSP’s system, see the Deals Object (page 42) section for moredetails.
1.9 12th November 2020
Added fields to complete support for the IAB Tech Lab OTT/CTV Store Assigned App Identifica-tion Guidelines6 and the Guidelines for Identifier for Advertising (IFA) on CTV/OTT platforms7
• app.storeid see the App Object (page 64) section for more details
• device.ext.ifa_type see the Device Object Properties (page 44) section for more details
• device.ext.truncated_ip added to support Google’s Display & Video 360 OpenRTB Spec-ification8
1.10 15th September 2020
Added support for the content object, see Content Object (page 66). This object can be passed insite.content or app.content
1.11 7th September 2020 - iOS 14
The release adds support for iOS 14 based on the OpenRTB SKAdNetwork Extension9.
Bid Request Fields
• imp.ext.skadn See the imp-ext section for more details
• imp.ext.skadn.version
• imp.ext.skadn.sourceapp
• imp.ext.skadn.skadnetids
• imp.ext.skadn.skadnhsh
• device.ext.idfv See the device-obj for more details
• user.ext.impdepth See the user-obj for more details6 https://iabtechlab.com/wp-content/uploads/2020/08/IAB-Tech-Lab-OTT-store-assigned-App-Identification-Guidelines-2020.
pdf7 https://iabtechlab.com/wp-content/uploads/2018/12/OTT-IFA-guidelines.final_Dec2018.pdf8 https://developers.google.com/display-video/ortb-spec#supported-extension-for-device-object9 https://github.com/InteractiveAdvertisingBureau/openrtb
1.8. 19th November 2020 4
BidSwitch Protocol for Suppliers, Release 1.0
• user.ext.sessionduration
• device.ifa Updated validation to support Apple’s deprecation of the IDFA as part of iOS14, this field should be passed using all zeros, rather than removed or an empty string, as allzeros is the expected format, e.g. "00000000-0000-0000-0000-000000000000"
• See the In App iOS 1410 section for an iOS 14 bid request example
Bid Response Fields
• seatbid.bid.ext.skadn.version See the bid-ext-obj section for more details.
• seatbid.bid.ext.skadn.network
• seatbid.bid.ext.skadn.campaign
• seatbid.bid.ext.skadn.itunesitem
• seatbid.bid.ext.skadn.nonce
• seatbid.bid.ext.skadn.sourceapp
• seatbid.bid.ext.skadn.timestamp
• seatbid.bid.ext.skadn.signature
• See the resp-ios14 section for an iOS 14 response example
1.12 v1.0 - June 2017
Initial Release based on OpenRTB 2.5
10 https://protocol.bidswitch.com/standards/bid-request-examples.html#ios14-eg
1.12. v1.0 - June 2017 5
CHAPTER2
SENSITIVE CATEGORIES AND RICH MEDIA
For greater coverage of sensitive categories BidSwitch extends the standard IAB list with additionalcategories. These categories may be used in the following fields.
Table 1: Sensitive Categories FieldsBid Requests Bid Response
• bcat• site.cat• app.cat
seatbid.bid.cat
Table 2: BidSwitch Sensitive CategoriesID CategoryBSW1 AlcoholBSW2 GamblingBSW3 Tobacco and smokingBSW4 Firearms and weaponsBSW5 Sexual & Reproductive HealthBSW6 Ringtones & DownloadableBSW7 Drugs & SupplementsBSW8 Get Rich QuickBSW9 Free Gifts, Quizzes, & SurveysBSW10 NudityBSW11 Cosmetic Procedures & Body Modification
6
BidSwitch Protocol for Suppliers, Release 1.0
2.1 Supported Rich Media Frameworks
Table 3: Supported Rich Media FrameworksDescription ValueAny framework is accepted ALLAdcentric acAdinterax adAdform afAtlas atApivid avDoubleClick dcEyeblaster ebEyeReturn erEyeWonder ewFlashtalking ftKlipmart kmKpsule ksMediaMind mmMediaplex mpPiximedia pmPointRoll prPictela ptRockabox rbSmart Adserver saSilence Media smUnicast uiUndertone utViewpoint vpWeborama wo
2.1. Supported Rich Media Frameworks 7
CHAPTER3
BACKWARD COMPATIBILITY
• BidSwitch Supplier Spec 1.011
11 https://protocol.bidswitch.com/_downloads/56cd8b0510dc8e179c98a1e264ff8363/BidSwitch_supplier_spec_1.0.pdf
8
CHAPTER4
DATA COMPRESSION
BidSwitch supports JSON and Compressed JSON (gzip) as data formats for bid requests and bidresponses. It is recommended to use Compressed JSON to minimize the amount of data exchangedbetween you and BidSwitch as this reduces latency times between servers, and traffic listening costsfor all parties involved. Here is what BidSwitch has observed with gzip traffic:
• When enabled, gzip compression ratios tend to be in the range of x1.4 to x2.0 (depending onthe size of the request/response)
• There is no tangible extra CPU load due to compressing/decompressing traffic, i.e. there isno extra cost
You can enable this on your integration at anytime as no changes are needed on the BidSwitch side.
In order to set up Compressed JSON bid requests and and accept compressed responses, use thefollowing instructions:
1. Compress your HTTP request body with gzip
2. Add a Content-Encoding: gzip HTTP header to indicate that the request is compressed
3. Add an Accept-Encoding: gzip header to indicate that you can accept a compressed re-sponse
4. Please contact BidSwitch support at [email protected] to ensure all parties are awareof a change in the integration
Once set up, BidSwitch starts accepting bid requests in Compressed JSON and responds usingcompressed JSON. All such bid responses carry a Content-Encoding: gzip HTTP header indi-cating that the response is compressed. It is recommended that you check for this HTTP header todistinguish between JSON and Compressed JSON bid response formats, if it is present decompressthe HTTP body before further processing.
Note: BidSwitch may still respond with non-compressed content when it detects that the size ofa gzip compressed response would exceed the size of an uncompressed response. This may happen
9
BidSwitch Protocol for Suppliers, Release 1.0
for very short bid responses. In this case the Content-Encoding: gzip header is absent.
10
CHAPTER5
MACROS
5.1 Win price macro
In order for the exchange to convey certain information to the winning bidder (e.g., the settlementprice), some substitution macros can be inserted into the win notice URL. Prior to calling a winnotice URL, BidSwitch will search the specified URL for any of the defined macros and replacethem with the appropriate data.
Note: The substitution is simple in the sense that wherever a legal macro is found, it will bereplaced without regard to syntax correctness.
Table 1: Win Price Macro DescriptionValue Description${AUCTION_PRICE} Settlement price for the auction. The substituted value will be defined
in CPM. This macro should be used in the burl field, see the ResponseBid Object (page 85) section for usage details. As well as the burl field,its use is also supported in these fields:
• For Native Responses: seatbid.bid.burl, seatbid.bid.adm_native.jstracker or seatbid.bid.adm_native.imptracker
• For non-native Responses: seatbid.bid.burl or seatbid.bid.adm
11
BidSwitch Protocol for Suppliers, Release 1.0
5.1.1 Encrypting the Win Price
BidSwitch can process encrypted win price macros, and uses the same method as Google12. Toenable this for your integration, contact BidSwitch support to receive the integrity key and en-cryption key necessary for doing this. Both of these keys will be sent to you in web-safe base64strings and they should be web-safe decoded and then base64 decoded by your application.
skU7Ax_NL5pPAFyKdkfZjZz2-VhIN8bjj1rVFOaJ_5o= // Example Encryption key (e_key)arO23ykdNqUQ5LEoQ0FVmPkBd7xB5CO89PDZlSjpFxo= // Example Integrity key (i_key)
Encryption scheme
The price is encrypted using a custom encryption scheme that is designed to minimize size overheadwhile ensuring adequate security. The encryption scheme uses a keyed HMAC algorithm to generatea secret pad based on the unique impression event ID. The encrypted price has a fixed length of 28bytes, comprised of:
• 16-byte initialization vector
• 8-bytes of ciphertext
• 4-byte integrity signature
The encrypted price must be web-safe base64-encoded, according to RFC 354813, with paddingcharacters omitted. Thus, the 28-byte encrypted price is encoded as a 38 character web-safe base-64 string irrespective of the winning price paid.
# The encrypted format is:{initialization_vector (16 bytes)}{encrypted_price (8 bytes)}{integrity (4 bytes)}
# Example encrypted prices:WEp8wQAAAABnFd5EkB2k1wJeFcAj-Z_JVOeGzA # 100 CPI microsWEp8sQAAAACwF6CtLJrXSRFBM8UiTTIyngN-og # 1900 CPI microsWEp8nQAAAAADG-y45xxIC1tMWuTjzmDW6HtroQ # 2700 CPI micros
The price needs to be encrypted as <price xor HMAC(encryption_key,initialization_vector)> so decryption calculates HMAC(encryption_key,initialization_vector) and xor’s with the encrypted price to reverse the encryption. Theintegrity stage takes 4 bytes of <HMAC (integrity_key, price||initialization_vector)>where || is concatenation.
The following example code outlines this, with the following definitions:
• iv initialization vector (16 bytes - unique to the impression)
• e_key encryption key (32 bytes - provided by BidSwitch Support)
• i_key integrity key (32 bytes - provided by BidSwitch Support)
• price (8 bytes - in micros of account currency)12 https://developers.google.com/ad-exchange/rtb/response-guide/decrypt-price13 https://tools.ietf.org/html/rfc3548
5.1. Win price macro 12
BidSwitch Protocol for Suppliers, Release 1.0
• hmac(k, d) SHA-1 HMAC of data d, using key k
• a || b string a concatenated with string b
// example codepad = hmac(e_key, iv) // first 8 bytesenc_price = pad <xor> pricesignature = hmac(i_key, price || iv) // first 4 bytes
final_message = WebSafeBase64Encode( iv || enc_price || signature )
Once enabled, you can return the encrypted price to BidSwitch who can then return it to thewinning Buyer in the appropriate manner.
• You need to encrypt the value using SHA-1 HMAC. You can do this using a crypto librarythat supports SHA-1 HMAC, such as Openssl
• The encrypted value should be then encoded using web-safe BASE64
# <!-- Example billing URL (burl) which will have macro substituted -->https://adserver.com/winnotice?impid=102&winprice=${ AUCTION_PRICE}
# <!-- Example billing URL (e.g. burl) -->https://adserver.com/winnotice?impid=102&winprice=1.34
# <!-- Example encrypted billing URL (e.g burl) -->https://adserver.com/winnotice?impid=102&winprice=WEp8nQAAAAADG-y45xxIC1tMWuTjzmDW6HtroQ
5.2 Supplier Click Tracking URL Macro
If you require Buyers to include a click tracking macro in their creatives, Buyers will return thismacro in the adm field. You should replace this macro with your Supplier click tracking URL. If youdo not support click tracking macros and a Buyer replies with one in the adm field, BidSwitch willreplace it with an empty string.
Note: In the case of video and native inventory, click tracking is handled on the Supplier side andthe click macro is not used, nor is the adm field.
Table 2: Click Tracking MacroValue Type${CLICK_URL:URLENCODE} A placeholder for the Supplier click tracking URL in URL
encoded form. Required for bids to Suppliers that supportclick tracking. No more than one click tracking macro can beused in the bid.adm field. Only single-encoded click trackingURLs are supported.
If requested, the Supplier click URL should be inserted before the landing page in the creative. The
5.2. Supplier Click Tracking URL Macro 13
BidSwitch Protocol for Suppliers, Release 1.0
landing page URL should be single-escaped. For example, if the Buyer click-URL contains:
http://dsp.com/click?bc=dnJD723&sspclick=${ CLICK_URL:URLENCODE}
The macro is replaced by the Supplier and the user clicks the resulting URL
http://dsp.com/click?bc=dnJD723&sspclick=http%3A%2F%2Fssp.com%2Fclick%3Fic%3DbKk4%26lp%3D
The Buyer unescapes the sspclick parameter and redirects to the target URL while adding thelanding page at the end
http://ssp.com/click?ic=bKks3k4&lp=http%3A%2F%2Fadvertiser.com%2Fhomepage
Note: Some Suppliers may keep the / and : characters unencoded, thus the resulting click URLmay take a form such as the following
http://dsp.com/click?bc=dnJD723&sspclick=http://ssp.com%2Fclick%3Fic%3DbKk4%26lp%3D
5.2. Supplier Click Tracking URL Macro 14
CHAPTER6
SUPPLIER BID REQUEST
This is the top level object that is sent by the Supplier to BidSwitch. Each bid request sent shouldcontain the following fields.
Note:
• Fields marked with an asterisk (*) are optional.
• While individually none of the following fields are required, one of them is required to be ineach bid request: banner, video, audio, or native.
• While individually neither of the following fields is required, one of them must be in therequest: site, app.
Table 1: Bid Request Object PropertiesValue Type Descriptionid string Unique ID of the bid request, for example,
"b5ba5ed2-547e-4e86-8a84-34a440dad6db"imp array of ob-
jectsArray of objects representing the impressions offered, for moreinformation, see the Impression Object (page 17) section.
device object Device object with details about the device to which the im-pression will be delivered, for more information, see the DeviceObject Properties (page 44) section.
user* object User Object which describes the user, for more information, seethe User Object (page 49) section.
tmax* integer Maximum time in milliseconds the exchange allows for bids tobe received to avoid timeout, including internet latency, for ex-ample, 120.
15
BidSwitch Protocol for Suppliers, Release 1.0
cur* array ofstrings
Array of allowed currencies for bids on this bid request usingISO-421714 alpha codes, for example, ["USD", "EUR"]. Thedefault is ["USD"].
at* integer Auction type, the default value is 2.• 1: the first price auction.• 2: the second price auction.
source* object Indicates the entity responsible for the final impression sale de-cision.
site* object The Site Object (page 62) describing the site. Either Site orApp must be present.
app* object The App Object (page 64) describing the mobile application.Either Site or App must be present.
bcat* array ofstrings
Blocked Advertiser Categories, using the IAB taxonomy, andextended with additional sensitive categories listed in the Sen-sitive Categories and Rich Media (page 6) section. Creatives be-longing to at least one of the listed categories are not permittedfor bidding in the current bid request, for example ["IAB10-1","IAB25", "BSW3"]
badv* array ofstrings
Array of strings of blocked top-level domains of advertisers, forexample, ["mysite.com", "mysite2.com"]
bapp* array ofstrings
A list of applications blocked from being advertised, specifiedusing their their platform-specific identifiers, i.e. the app bun-dle ID. On Android, these should be app bundle and on iOSnumeric IDs e.g. ["com.app.example", "012987652"]
bseat* array ofstrings
An array of Buyer seats disallowed to bid on this auction, forexample ["58", "61", "99"]. If this field is present, the spec-ified seat IDs may be supplied using BidSwitch or Supplier tax-onomy.
• The wseat field takes precedence, so if you have the samevalue in both fields the request is sent to the Buyer.
• If you have set up multiple seat values for a Buyer as partof Seat Self-Management15, you should include all valuefor the Buyer in this field.
• If you send Agency Seat IDs as outlined in the AgencyMapping16 section, the request is passed to the Buyer andbidder enforcement is their responsibility.
wseat* array ofstrings
An array of Buyer seats allowed to bid on this auction, forexample [58, 61, 99]. If this field is present, the specified seatIDs may be supplied using BidSwitch or Supplier taxonomy.A bid request may contain multiple seat IDs using the Suppliertaxonomy.
14 https://www.iso.org/iso-4217-currency-codes.html15 https://protocol.bidswitch.com/features/agency-seat.html#ssp-spec-id16 https://protocol.bidswitch.com/features/agency-seat.html#agency-map
16
BidSwitch Protocol for Suppliers, Release 1.0
allimps* integer A flag to indicate if the Supplier can verify that the impressionsoffered represent all of the impressions available in context (e.g.,all on the web page, all video spots such as pre/mid/post roll)to support road-blocking.
• 0 = no or unknown• 1 = yes, the impressions offered represent all that are
available.
regs* object A regulations object that specifies any industry, legal, or gov-ernmental regulations in force for this request, for more infor-mation, see the Regulation Object (page 69) section.
ext* object Ext Object used for Supplier specific properties, for more infor-mation, see the Ext Object (page 56) section.
6.1 Impression Object
Note: Fields marked with asterisk (*) are optional.
6.1. Impression Object 17
BidSwitch Protocol for Suppliers, Release 1.0
Table 2: Impression Object PropertiesValue Type Descriptionid string ID of the impression being shown, unique within the bid request,
for example "1"banner* object The Banner Object (page 23) describes the ad properties. Re-
quired for banner impressions. One of these objects should bepresent in the request: banner, video, audio, or native.
video* object The Video Object (page 26) describes the ad properties. Re-quired for video impressions.
audio* object The Audio Object (page 31) describes the ad properties. Re-quired for audio impressions. One of these objects should bepresent in the request: banner, video, audio, or native.
native* object The Native Object (page 34) describes the ad properties. Re-quired for native impressions. One of these objects should bepresent in the request: banner, video, audio, or native.
bidfloor* float Bid floor in CPM as set by the Supplier, for example, 0.01080bidfloorcur* string Bid floor currency specified using ISO-4217 alpha codes, the
default is, "USD".instl* integer Specifies if the ad is an interstitial.
• 0 = not interstitial, the default value.• 1 = the ad is interstitial or full screen
tagid* string Identifier for specific ad placement or ad tag that was used toinitiate the auction.
secure* integer Specifies if the page is SSL compliant:• 0: for insecure pages, the default value.• 1: for secure pages. Creative assets for secure pages
should be SSL-compliant.
iframebuster* array ofstrings
Array of names of supported iframe busters, for example,["dc", "rb"], for more information, see the srmf section.
6.1. Impression Object 18
BidSwitch Protocol for Suppliers, Release 1.0
Table 3: Impression Object PropertiesValue Type Descriptionpmp* object The Private Marketplace Object (page 41), used for direct deals
between Buyers and Suppliers.displaymanager* string Name of the ad mediation partner, SDK technology, or native
player responsible for rendering the ad (typically video or mo-bile), for example, "SOMA"
displaymanagerver* string Version of the ad mediation partner, SDK technology, or nativeplayer responsible for rendering the ad (typically video or mo-bile), for example, "1.1"
metric* array of ob-jects
The object that is associated with an impression as an array ofmetrics, see the Metric Object (page 49) section.
exp* integer Impression expiry timeout, in seconds, the default is "300". Animpression will be considered expired if it is registered laterthan imp.exp seconds after the auction.
ext* object Impression extensiton object, see Impression Ext (page 19)
6.1.1 Impression Ext
Table 4: Impression Object PropertiesValue Type Descriptionwopv str Passes the WhiteOps MediaGuard Prediction ID, e.g. “abc-123”skadn* object Apple Ad Network Object, this will be used to pass app data
from iOS 14 and newer releases. See SkAdNetwork Extension(page 20)
ssai* int Indicates if server-side ad insertion (e.g., stitching an ad intoan audio or video stream) is in use and the impact of this onasset and tracker retrieval. It can take the following values:
• 0 = status unknown• 1 = all client-side (i.e., not server-side)• 2 = assets stitched server-side but tracking pixels fired
client-side• 3 = all server-side.
6.1. Impression Object 19
BidSwitch Protocol for Suppliers, Release 1.0
6.1.2 SkAdNetwork Extension
Table 5: skadn Extension PropertiesValue Type Descriptionversion* str Version of skadnetwork supported. Always "2.0" or
higher. Dependent on both the OS version and theSDK version., e.g. "2.0" https://developer.apple.com/documentation/storekit/skadnetwork
versions* array of strings An array of strings containing the supported skadnet-work versions. Always "2.0" or higher. Dependent onboth the OS version and the SDK version.
sourceapp* str ID of publisher app in Apple’s App Store. Shouldmatch “app.bundle”
skadnetids* array of string A subset of SKAdNetworkItem entries inthe publisher app’s info.plist that arerelevant to the DSP, e.g. ["cDkw7geQsH.skadnetwork", "qyJfv329m4.skadnetwork"]https://developer.apple.com/documentation/bundleresources/information_property_list
skadnetlist* object An object containing the IAB Tech Lab (IABTL) listdefinition. See the skadnetlist object (page 21) table fordetails. You can also find out more about the IABTLList from their release blog post17 and at https://tools.iabtechlab.com/skadnetwork
17 https://iabtechlab.com/blog/register-now-for-iab-tech-lab-skadnetwork-id-list/
6.1. Impression Object 20
BidSwitch Protocol for Suppliers, Release 1.0
6.1.3 skadnetlist object
Table 6: skadnetlist PropertiesValue Type Descriptionmax* integer A list of IABTL IDs containing the max entry ID
on the list up to which you wish to include. Theskadnetids associated with all IABTL IDs numericallylower than this are included as subset of SKAdNet-workItem entries in the publisher app’s info.plistthat are relevant to the DSP, e.g. 42.
excl* array of integers A list of IABTL registration IDs to be excluded, i.e.those numerically lower than the max value but whichshould not be included, e.g. [12, 14]
addl* array of strings A list of raw lowercase SKAdNetworkItem en-tries in the publisher app’s info.plist thatare relevant to the DSP, e.g. ["cDkw7geQsH.skadnetwork", "qyJfv329m4.skadnetwork"]https://developer.apple.com/documentation/bundleresources/information_property_listNote: The intention of this field is to replace theskadn.skadnetids field, it is also recommended thatthis list not exceed 10.
6.1.4 Example Impression Object JSON
{"imp":[
{"id":"1","metric":[
{"type":"viewability","value":0.85
}],"bidfloor":0.426,"banner":{
"w":300,"h":250,"pos":1,"topframe":0,"expdir":[
1,3
]}
}(continues on next page)
6.1. Impression Object 21
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
]}
6.1. Impression Object 22
BidSwitch Protocol for Suppliers, Release 1.0
6.2 Banner Object
Note: Fields marked with an asterisk (*) are optional.
Table 7: Banner Object PropertiesValue Type Descriptionw integer Width of the impression in pixels, for example, 300h integer Height of the impression in pixels, for example 250battr* array of inte-
gersBlocked creative attributes as defined in the OpenRTB protocol,for example, [1, 23]
btype* array of inte-gers
Blocked banner ad types as defined in the OpenRTB protocol,for example, [4, 21]
pos* integer Ad Position as defined in the OpenRTB protocol, for example,1
topframe* integer Indicates if the banner is in the top frame as opposed to aniframe.
• 0 = no• 1 = yes.
mimes* array ofstrings
Specifies the content MIME types supported, com-mon MIME types include "text/html", "application/x-shockwave-flash", and "image/gif". For example:[ "video/mp4", "image/jpg"]
expdir* array of inte-gers
Possible expansion directions for an expandable ad, for example,[2,5]. This can take the following values:
• 1: Left• 2: Right• 3: Up• 4: Down• 5: Full screen
If the field is not present, expandable creatives are not allowed.
Table 8: Banner Object PropertiesValue Type Descriptionformat* array or ob-
jectsAn array of format objects, see Format Object (page 25), de-noting the alternative sizes that may be used for bidding. Ifone of the alternative ad sizes is used in the bid response, thenthe seatbid.bid.h and seatbid.bid.w fields are required inthe bid response.
api* array of inte-gers
List of supported API frameworks for this impression as definedin the OpenRTB, for example [3, 5]. If an API is not explicitlylisted, it is assumed not to be supported.
6.2. Banner Object 23
BidSwitch Protocol for Suppliers, Release 1.0
6.2.1 Banner JSON Example
{"banner":{
"id":"abc123","w":300,"h":250,"pos":1,"topframe":0,"btype":[
2,3
],"mimes":[
"text/html","application/x-shockwave-flash"
],"format":[
{"h":50,"w":300
}]
}}
6.2. Banner Object 24
BidSwitch Protocol for Suppliers, Release 1.0
6.3 Format Object
Table 9: Format Object PropertiesValue Type Descriptionh integer Height of the impression in pixels, for example 500w integer Width of the impression in pixels, for example 340
{"format":[{
"w":300,"h":250
}]}
6.3. Format Object 25
BidSwitch Protocol for Suppliers, Release 1.0
6.4 Video Object
Note: Fields marked with an asterisk (*) are optional.
Table 10: Video Object PropertiesValue Type Descriptionmimes array of
stringsContent MIME types supported.
minduration integer Minimum video ad duration in seconds, for example, 2maxduration integer Maximum video ad duration in seconds, for example, 15linearity* integer Indicates if the impression must be linear or nonlinear, for ex-
ample, 1. If none is specified, it is assumed all are allowed• 1: Linear/In-stream• 2: Non-Linear/Overlay
placement* integer Placement type for the impression, for example 2. Note:Though not required, this is an important field for some Buyers,not explicitly setting it will result in lower demand. This fieldcan take the following values:
• 1: In-stream. Played before, during or after the streamingvideo content that the consumer has requested (e.g., Pre-roll, Mid-roll, Post-roll).
• 2: In-banner. Exists within a web banner that leveragesthe banner space to deliver a video experience as opposedto another static or rich media format. The format relieson the existence of display ad inventory on the page forits delivery.
• 3: In-article. Loads and plays dynamically betweenparagraphs of editorial content; existing as a standalonebranded message.
• 4: In-feed. Found in content, social, or product feeds.• 5: Interstitial/Slider/Floating. Covers the entire or a por-
tion of screen area, but is always on screen while displayed(i.e. cannot be scrolled out of view). Note that a full-screen interstitial (e.g., in mobile) can be distinguishedfrom a floating/slider unit by the imp.instl field.
playbackend* integer The event that causes playback to end, for example 2. Thisfield can take the following values:
• 1: On Video Completion or when Terminated by User.• 2: On Leaving Viewport or when Terminated by User.• 3: On Leaving Viewport Continues as a Floating/Slider
Unit until Video Completion or when Terminated by User.
6.4. Video Object 26
BidSwitch Protocol for Suppliers, Release 1.0
Table 11: Video Object PropertiesValue Type Descriptionprotocols array of inte-
gersAccepted video bid response protocols as defined in OpenRTB,for example [6,8]. As BidSwitch only serves video using VASTwrappers, the valid response integers are 5, 6, or 8 for the re-quest to be eligible for bidding.
pos* integer Ad Position as defined in OpenRTB, for example 1w* integer Width of the player in pixels, for example, 600h* integer Height of the player in pixels, for example 400startdelay* integer Indicates the start delay in seconds. If the start delay value
is greater than 0, then the position is mid-roll and the valueindicates the start delay.
• > 0: Mid-Roll (value indicates start delay in second)• 0: Pre-roll• -1: Generic mid-roll• -2: Generic post-roll
battr* array of inte-gers
Blocked creative attributes as defined in OpenRTB, for exam-ple, [6]
minbitrate* integer Minimum bit rate in Kbps, for example 680maxbitrate* integer Maximum bit rate in Kbps, for example 990api* array of inte-
gersList of supported API frameworks for this impression as definedin OpenRTB, for example, [1,2]. If an API is not explicitlylisted, it is assumed not to be supported.
maxextended* integer Maximum extended video ad duration if extension is allowed.• Blank or 0, extension is not allowed.• -1, extension is allowed, and there is no time limit im-
posed.• Greater than 0, then the value represents the num-
ber of seconds of extended play supported beyond themaxduration value.
boxingallowed* integer Indicates if letter-boxing of 4:3 content into a 16:9 window isallowed:
• 0 = no• 1 = yes.
playbackmethod* array of inte-gers
Allowed playback methods as defined in the OpenRTB, for ex-ample [1, 2]. If none are specified, it is assumed all are al-lowed.
delivery* array of inte-gers
Supported delivery methods (e.g., streaming, progressive) as de-fined in OpenRTB. If none specified, assume all are supported,for example, [1, 2]
6.4. Video Object 27
BidSwitch Protocol for Suppliers, Release 1.0
Table 12: Video Object PropertiesValue Type Descriptionsequence* integer If multiple ad impressions are offered in the same bid request,
the sequence number will allow for the coordinated delivery ofmultiple creatives, for example, 2.
companionad* object array Array of Banner objects if companion ads are available. See theBanner Object (page 23) section for more information.
companiontype* array of inte-gers
List of allowed companion ad types, for example [1, 2] Possi-ble values:
• 1: Static Resource• 2: HTML Resource• 3: iframe Resource
skip* integer Indicates if the player will allow the video to be skipped, where0 = no, 1 = yes.
6.4.1 Video Ext Object
Table 13: Video Ext Object PropertiesValue Type Descriptionrewarded* integer Indicates whether the ad is being rendered as part of a rewarded
/ incentivised user experience, where:• 0 = non-rewarded• 1 = rewarded• If omitted, non-rewarded can be assumed
6.4.2 Video Object Example
{"id":"1","bidfloor":0.03,"video":{
"w":640,"h":480,"pos":1,"startdelay":0,"minduration":5,"maxduration":30,"maxextended":30,"minbitrate":300,"maxbitrate":1500,"skip":1,"api":[
(continues on next page)
6.4. Video Object 28
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
1,2
],"protocols":[
6,8
],"mimes":[
"video/x-flv","video/mp4","application/x-shockwave-flash","application/javascript"
],"linearity":1,"boxingallowed":1,"playbackmethod":[
1,3
],"delivery":[
2],"battr":[
13,14
],"companionad":[
{"id":"1234567893-1","w":300,"h":250,"pos":1,"battr":[
13,14
],"expdir":[
2,4
]},{
"id":"1234567893-2","w":728,"h":90,"pos":1,"battr":[
13,14
]}
(continues on next page)
6.4. Video Object 29
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
],"companiontype":[
1,2
]}
}
6.4. Video Object 30
BidSwitch Protocol for Suppliers, Release 1.0
6.5 Audio Object
Note: Fields marked with an asterisk (*) are optional.
Table 14: Audio Object PropertiesValue Type Descriptionmimes array of
stringsContent MIME types supported, for example ["audio/mp4","audio/mpeg"]
minduration* integer Minimum audio ad duration in seconds, for example, 2maxduration* integer Maximum audio ad duration in seconds, for example, 15protocols array of inte-
gersAccepted audio bid response protocols as defined in OpenRTB,for example [9,10]
startdelay* integer Indicates the start delay in seconds, or generic values below:• 0: Pre-roll• -1: Generic mid-roll• -2: Generic post-roll
battr* array of inte-gers
Blocked creative attributes as defined in OpenRTB, for exam-ple, [6]
minbitrate* integer Minimum bit rate in Kbps, for example 32maxbitrate* integer Maximum bit rate in Kbps, for example 320api* array of inte-
gersList of supported API frameworks for this impression as definedin the OpenRTB guide, for example, [1,2]. If an API is notexplicitly listed, it is assumed not to be supported.
maxextended* integer Maximum extended audio ad duration if extension is allowed.• Blank or 0, extension is not allowed.• -1, extension is allowed, and there is no time limit im-
posed.• Greater than 0, then the value represents the number of
seconds of extended play supported beyond the maxdura-tion value.
delivery* array of inte-gers
Supported delivery methods (e.g., streaming, progressive) as de-fined in OpenRTB. If none specified, assume all are supported,for example, [1, 2]
maxseq* integer The maximum number of ads that can be played in an ad pod,for example, 1
feed* integer Type of audio feed, for example, 1sequence* integer If multiple ad impressions are offered in the same bid request,
the sequence number will allow for the coordinated delivery ofmultiple creatives, for example, 2
6.5. Audio Object 31
BidSwitch Protocol for Suppliers, Release 1.0
Table 15: Audio Object PropertiesValue Type Descriptionstitched* integer Indicates if the ad is stitched with audio content or delivered
independently, for example, 1nvol* integer Volume normalization mode as defined in OpenRTB, for exam-
ple, 1companionad* array of ob-
jectsArray of Banner objects if companion ads are available. See theBanner Object (page 23) section for more information.
companiontype* array of inte-gers
Supported DAAST companion ad types, for example [1, 2]Possible values:
• 1: Static Resource• 2: HTML Resource• 3: iframe Resource
6.5.1 Audio Object Example
{"id": "1","bidfloor": 0.03,
"audio": {"startdelay": 0,"minduration": 5,"maxduration": 30,"maxextended": 30,"minbitrate": 300,"maxbitrate": 1500,"api": [
1,2
],"protocols": [
9,10
],"mimes": [
"audio/aac","audio/mp4","audio/mpeg"
],"delivery": [
2],"battr": [
13,14
],"companionad": [
(continues on next page)
6.5. Audio Object 32
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
{"id": "1234567893-1","w": 300,"h": 250,"pos": 1,
"battr": [13,14
],"expdir": [
2,4
]},{"id": "1234567893-2","w": 728,"h": 90,"pos": 1,"battr": [
13,14
]}],"companiontype": [
1,2
]}
}
6.5. Audio Object 33
BidSwitch Protocol for Suppliers, Release 1.0
6.6 Native Object
Note: Fields marked with an asterisk (*) are optional.
Table 16: Native ObjectValue Type Descriptionrequest_native object Contains the Native Request Object (page 35) object.battr* array of inte-
gersBlocked creative attributes as defined in OpenRTB., for exam-ple, [1, 3]
api* array of inte-gers
List of supported API frameworks for this impression as definedin OpenRTB, for example [2,3,5]. If an API is not explicitlylisted, it is assumed not to be supported.
6.6.1 Native Object Example
{"native":{
"request_native":{"ver":"1.2","layout":1,"adunit":4,"assets":[
{"id":1,"required":1,"title":{
"len":25}
}]
},"api":[
3],"battr":[
13,14
]}
}
6.6. Native Object 34
BidSwitch Protocol for Suppliers, Release 1.0
6.7 Native Request Object
Note: Fields marked with asterisk (*) are optional.
Table 17: Native Request ObjectValue Type Descriptionver string Version of the Native Markup in use, for example, "1.2". Note:
It must be 1.2layout* integer The Layout ID of the native ad unit as described in OpenRTB
Native specification, for example, 3adunit* integer The Ad unit ID of the native ad unit as described in OpenRTB
Native specification.plcmttype* integer The design/format/layout of the ad unit being offered. See
the Native Placement Type (page 37) for a list of supportedplacement types
plcmtcnt* integer The number of identical placements in this Layout, for example,1
seq* integer 0 for the first ad, 1 for the second ad, and so on. This is notthe sequence number of the content in the stream.
eventtrackers* array of ob-jects
Specifies what type of event tracking is supported, see EventTracker Request Object (page 38). Required by some Buyers,see Required Fields per Buyer (page 71)
privacy* integer Set to 1 when the native ad supports a buyer-specific privacynotice, set to 0 otherwise.
assets array of ob-jects
An array of Asset Objects. Any bid must comply with thisarray of elements. See the Native Asset Object section belowfor more details.
6.7.1 Native Asset Object
Table 18: Native Asset Object PropertiesValue Type Descriptionid integer Unique asset id, for example 2required* integer Set to 1 if asset is required (exchange will not accept a bid
without it), default is 0.title ** object Native title object, see the Native Asset Title Object section
below for more details.img ** object Native image object, see the Native Asset Image Object below
for more details.video ** object Native video object, see the Native Asset Video Object below
for more details.data ** object Native asset data object, see the Native Asset Data Object
below section for more details.
6.7. Native Request Object 35
BidSwitch Protocol for Suppliers, Release 1.0
Note: (**) There may only be exactly one of the fields marked with double asterisk in each assetobject.
6.7.2 Native Asset Title Object
Table 19: Native Asset Title ObjectValue Type Descriptionlen integer Maximum length of the text in the title element, for example,
30
6.7.3 Native Asset Image Object
The image asset object may contain the exact image size, the minimum image size, or both. If onlythe exact image size is specified then the image in the bid response should have the correspondingsize. If the minimum size is specified then the image asset in the bid response should comply withthe following restrictions.
• The size of the image should be equal to or larger than the minimum specified
• The image asset in the bid response should contain the w and h fields.
Note: It is recommended that the aspect ratio of the image should be close to the one specifiedby the exact size or by the minimum size; the acceptable aspect ratio deviation is from 0.8 * (𝑤/ℎ)to 1.25 * (𝑤/ℎ)
Table 20: Native Asset Image ObjectValue Type Descriptiontype* integer Image asset type, for example 3. Takes the following values:
• 1 Icon• 2 Logo (Logo image for the brand/app)• 3 Main (Large image preview for the ad)
w* integer Width of the image in pixels, for example, 300wmin* integer The minimum requested width of the image in pixels, for ex-
ample, 100h* integer Height of the image in pixels, for example, 250hmin* integer The minimum requested height of the image in pixels, for ex-
ample, 100mimes* array of
stringsWhitelist of content MIME types supported, for example,["image/gif"] If blank, assume all types are allowed.
6.7. Native Request Object 36
BidSwitch Protocol for Suppliers, Release 1.0
6.7.4 Native Asset Video Object
Table 21: Native Asset Video ObjectValue Type Descriptionmimes array of
stringsContent MIME types supported, for example, ["video/mpeg","video/mp4"]
minduration integer Minimum video ad duration in seconds, for example, 2maxduration integer Maximum video ad duration in seconds, for example 15protocols array of inte-
gersAccepted video bid response protocols as defined in OpenRTB,for example, [2,5]
ext object Extension object, see Native Asset Video Object Extension(page 37)
6.7.5 Native Asset Video Object Extension
Table 22: Native Asset Video Object Extension PropertiesValue Type Descriptionplaybackmethod* array of inte-
gersAllowed playback methods as defined in the OpenRTB, for ex-ample [1, 2]. If none are specified, it is assumed all are al-lowed.
6.7.6 Native Asset Data Object
Table 23: Native Asset Data ObjectValue Type Descriptiontype integer Data asset type as described in OpenRTB Native specification,
for example, 1len* integer Maximum length of the text in the element’s response, for ex-
ample, 25
6.7.7 Native Placement Type
Table 24: Native Placement Type OptionsValue Description1 In the feed of content, for example as an item inside the organic
feed/grid/listing/carousel.2 In the atomic unit of the content, i.e. in the article page or single image page3 Outside the core content, for example in the ads section on the right rail, as a banner-
style placement near the content, etc.4 Recommendation widget, most commonly presented below the article content.500+ To be defined by the exchange
6.7. Native Request Object 37
BidSwitch Protocol for Suppliers, Release 1.0
6.7.8 Event Tracker Request Object
Table 25: Event Tracker Request ObjectValue Type Descriptionevent integer Type of event available for tracking. See the Event Tracking Types
(page 38)methods array of inte-
gersArray of the types of tracking available for the given event. Seethe Event Tracking Methods (page 38) table
ext* object This object is a placeholder that may contain custom JSON agreedto by the parties to support flexibility beyond the standard definedin this specification
6.7.9 Event Tracking Types
Table 26: Event Tracking TypesValue Type Description1 Impression Impression2 viewable-
mrc50Visible impression using MRC definition at 50% in view for 1 sec-ond.
3 viewable-mrc100
Visible impression using MRC definition at 100% in view for 1second, i.e. GroupM standard
4 viewable-video50
Visible impression for video using MRC definition at 50% in viewfor 2 seconds.
500+ exchange spe-cific
6.7.10 Event Tracking Methods
Table 27: Event Tracking MethodsValue Type Description1 img Image-pixel tracking – The URL provided in the response will be
inserted as a 1x1 pixel at the time of the event.2 js Javascript-based tracking – The URL provided in the response will
be inserted as a js tag at the time of the event.500+ exchange spe-
cificCould include custom measurement companies such as Moat, Dou-bleVerify, IAS, etc – in this case additional elements will often bepassed.
6.7. Native Request Object 38
BidSwitch Protocol for Suppliers, Release 1.0
6.7.11 Example Native Request
{"native":{
"request":{"plcmtcnt":1,"plcmttype":2,"privacy":1,"context":1,"contextsubtype":12,"eventtrackers":[
{"event":1,"methods":[
1,2
]},{
"event":2,"methods":[
1]
}],"assets":[
{"id":1,"data":{
"type":12},"required":1
},{
"title":{"len":50
},"id":2,"required":1
},{
"id":3,"img":{
"w":80,"h":80,"type":1
},"required":1
},{
"id":4,"img":{
(continues on next page)
6.7. Native Request Object 39
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"w":1200,"h":627,"type":3
},"required":1
},{
"data":{"type":3
},"id":5,"required":0
},{
"id":6,"data":{
"len":100,"type":2
},"required":1
},{
"id":7,"video":{
"mimes":["video/mpeg","video/mp4"
],"minduration":2,"protocols":[
2,5
],"maxduration":2,"ext":{
"playbackmethod":[1,2
]}
},"required":1
}],"ver":"1.2"
}}
}
6.7. Native Request Object 40
BidSwitch Protocol for Suppliers, Release 1.0
6.8 Private Marketplace Object
Note: Fields marked with an asterisk (*) are optional.
Table 28: Private Marketplace Object PropertiesValue Type Descriptionprivate_auction* integer A value of 1 indicates that only bids submitted inside pmp.deals
will take part in the auction. A value of 0 indicates that bidswithout deal information may also be considered for serving.
deals array of ob-jects
Array of Deal objects, for more information, see the Deals Ob-ject (page 42) section.
6.8.1 Private Marketplace Object Example
{"pmp":{
"private_auction":1,"deals":[
{"id":"deal-1","wseat":[
"58"],"bidfloor":2.5,"at":1
},{
"id":"deal-2","bidfloor":2,"at":2
}]
}}
6.8. Private Marketplace Object 41
BidSwitch Protocol for Suppliers, Release 1.0
6.9 Deals Object
Note: Fields marked with an asterisk (*) are optional.
Table 29: Deal Object PropertiesValue Type Descriptionid string Deal id, for example, "AA-1234"wseat* array of
stringsArray of Buyer seats allowed to bid on this Direct Deal, forexample, [58, 99]. If present, the allowed seat IDs may besupplied using the BidSwitch or Supplier taxonomy.
• The BidSwitch taxonomy uses the Buyer ID as the singleseat ID value.
• The seat in the Supplier taxonomy may represent thewhole Buyer or some entity on the Buyer side (e.g.agency)
• A bid request may contain multiple seat IDs in the Sup-plier taxonomy.
• The bid response should contain the appropriate seatvalue corresponding to one of values of the wseat field,see the Seat Bid Object (page 85) section.
bidfloor* float Deal price in CPM. If it’s a fixed price deal as set using deals.at = 3 then this field sets the the exact price of the deal, oth-erwise this is the bid floor of the deal, for example, 1.3
bidfloorcur* string Bid floor currency specified using ISO-421718 alpha codes, forexample, "USD"
at* integer Auction type.• 1 for first price auction.• 2 for second price auction.• 3 for fixed price deal.
18 https://www.iso.org/iso-4217-currency-codes.html
6.9. Deals Object 42
BidSwitch Protocol for Suppliers, Release 1.0
6.9.1 Deal Extension Object
Table 30: Deal Ext Object PropertiesValue Type Descriptionbuyer_wseat* array of
stringsSpecifies the Advertisers/Agencies that should have access tothis deal in the Buyer’s system. You should use their seat IDwith the Buyer, e.g. ["agency-123", "advertiser-456"].Note: To obtain the correct Seat ID for an agency at a partic-ular Buyer you will need to contact the agency. You may alsofind more information about this in the buyers field descriptionof the dpa section.
6.9.2 Deals Object Example
{"pmp":{
"private_auction":1,"deals":[
{"id":"deal-1","wseat":[
"58"],"bidfloor":2.5,"at":1,"ext":{
"type":3,"buyer_wseat":[
"abc-123"]
}},{
"id":"deal-2","bidfloor":2,"at":2
}]
}}
6.9. Deals Object 43
BidSwitch Protocol for Suppliers, Release 1.0
6.10 Device Object Properties
Note: Fields marked with an asterisk (*) are optional.
(**) Required for in-app requests.
6.10. Device Object Properties 44
BidSwitch Protocol for Suppliers, Release 1.0
Table 31: Device Object PropertiesValue Type Descriptiongeo object Geo Object as derived from the device’s location services, or
supplied by the Supplier if the device IP is missing. For moreinformation, see the Geo Object Properties (page 48) section.
ip string Specifies the IPv4 address closest to the device.• Semi-Required One of IP or IPv6 required• Required for almost all requests, any containing invalid
IP addresses will be discarded based on IP Validation e.g.87.224.77.0
• Note: This field is only optional for Connected TV in-ventory
ipv6* string Semi-Required One of IP or IPv6 required. IP address inIPv6, for example, fe80:0:0:0:200:f8ff:fe21:67cf
ua* string Browser or application user agent string, for example,"Mozilla/5.0 (Windows NT 6.3; WOW64; rv:35.0)Gecko/20100101Firefox/35.0"
language* string Alpha-2/ISO 639-1 code of browser language, for example, encarrier* string Carrier or ISP derived from the IP address, for example, WIFIconnectiontype* integer Connection type as defined in OpenRTB, for example, 2didsha1* string Hardware device ID (e.g., IMEI); hashed via SHA1, for example,
CCF6DC12B98AEB2346AFE1BEE7860DF01FDE158Bdidmd5* string Hardware device ID (e.g., IMEI); hashed via MD5.
93D05D4D69DEE2BC6645D9F0A0C1938Cdpidsha1* string Platform device ID (e.g., Android ID); hashed via SHA1, for
example, CCF6DC12B98AEB2346AFE1BEE7860DF01FDE158Bdpidmd5* string Platform device ID (e.g., Android ID); hashed via MD5, for
example, 93D05D4D69DEE2BC6645D9F0A0C1938Cifa** string The ID for Advertisers (IFA) in clear text (i.e. not hashed),
for example Apple’s IDFA or Android’s Advertising ID. Note:This field is required for in-app requests.The Apple IDFA is usually uppercase, and the Android Adver-tiser ID is usually lowercase. For example:
• Android "035911ea-467d-4056-903b-65cf44f5633b"• iOS "30255BCE-4CDA-4F62-91DC-4758FDFF8512"• iOS 14 00000000-0000-0000-0000-000000000000, with
Apple’s deprecation of the IDFA as part of iOS 14, thisfield should be passed using all zeros, rather than removedor an empty string, as all zeros are the expected format.
Note: This fields can use UUIDv4 or UUIDv5 formats. If pass-ing synthetic IFAs, you should use either the v4 or v5 implemen-tation of RFC 412219 to generate them. There’s a number ofonline tools for checking the version if you need to troubleshootUUID issues, e.g. UUID / GUID Validator20
make* string Device make, for example, Apple
6.10. Device Object Properties 45
BidSwitch Protocol for Suppliers, Release 1.0
mccmnc* string Mobile carrier as the concatenated MCC-MNC code (e.g.,"310-005" identifies Verizon Wireless CDMA in the USA). Re-fer to https://en.wikipedia.org/wiki/Mobile_country_code forfurther examples. Note: that the dash between the MCC andMNC parts is required to remove parsing ambiguity
model* string Device mode, for example, iPhoneos* string Device operating system, for example, iOSosv* string Device operating system version, for example, 3.1.2h* integer Physical height of the screen in pixels, for example, 750w* integer Physical width of the screen in pixels, for example, 1334pxratio* float The ratio of physical pixels to device independent pixels, for
example, 1.0dnt* integer Do not track.
• 0: do not track is set to false• 1: do not track is set to true in the browser, for example,0
lmt* integer Limit Ad Tracking. Signal commercially endorsed (e.g., iOS,recommended Android):
• 0: tracking is unrestricted,• 1: tracking must be limited per commercial guidelines, for
example, 0
devicetype* integer Device type as defined by OpenRTB, for example, 4js* integer 1 if the device supports JavaScript; otherwise 0.flashver* string Flash version detected, for example, 10.1
19 https://tools.ietf.org/html/rfc412220 https://www.freecodeformat.com/validate-uuid-guid.php
6.10. Device Object Properties 46
BidSwitch Protocol for Suppliers, Release 1.0
6.10.1 Device Ext Object Properties
Table 32: Device Ext Object PropertiesValue Type Descriptionatts* int (iOS Only) An integer passed to represent the app’s app track-
ing authorization status, can contain the following values.• 0 = not determined• 1 = restricted• 2 = denied• 3 = authorized
dooh* object Passes the DOOH Object (page 68) for Digital out of Homeinventory, required to indicate DooH inventory
truncated_ip* integer Indicates whether the IP address in the device.ip field is trun-cated. 1 = truncated 0 = not truncated. It is assumed nottruncated and required if the IP address is truncated. If notdeclared the bid request might be classified as invalid traffic, byGoogle. This is a field only for Google, see the Display & Video360 OpenRTB Specification21
ifa_type* string Indicates the origin of the device.ifa field, whether it was pro-vided from the device itself or generated by a publisher or Sup-plier in the supply chain. Takes the following values from theGuidelines for Identifier for Advertising (IFA) on CTV/OTTplatforms22
• "aaid" Android TV• "rida" Roku• "afai" Amazon Fire• "idfa" Apple tvOS• "msai" Xbox/Microsoft• "dpid" Generic device platform ID• "ppid" Publisher provided ID• "sspid" SSP provided ID• "sessionid" Short-lived session ID (frequency capping
only)
idfv* str Passes the ID for Vendor (IDFV23).A persistent unique identifier for each app on a device thatidentifies the device to the app’s vendor. The value of thisproperty is the same for apps that come from the same ven-dor running on the same device. A different value is returnedfor apps on the same device that come from different ven-dors, and for apps on different devices regardless of vendor,e.g. "1F277D46-12BF-482A-9085-B4F811DD6E4D"
21 https://developers.google.com/display-video/ortb-spec#supported-extension-for-device-object22 https://iabtechlab.com/wp-content/uploads/2018/12/OTT-IFA-guidelines.final_Dec2018.pdf23 https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor
6.10. Device Object Properties 47
BidSwitch Protocol for Suppliers, Release 1.0
6.11 Geo Object Properties
The information provided in the Geo Object is based on MaxMind database24, except latitude andlongitude values.
Note: Fields marked with an asterisk (*) are optional.
Table 33: Geo Object PropertiesValue Type Descriptionaccuracy* int Estimated location accuracy in meters.lat* float Latitude from -90 to 90. South is negative, for example, 52.35lon* float Longitude from -180 to 180. West is negative, for example, 4.
9167type* integer Source of location data as defined by OpenRTB, for example, 1country* string Country using ISO-3166-125 Alpha-2, for example NLregion* string Region using ISO-3166-2 region codes, for example, NYcity* string City name.metro* string Google metro code; similar to but not exactly Nielsen DMAs.zip* string Zip/postal code, for example, "90210"utcoffset* integer Local time as the number +/- of minutes from UTC, for exam-
ple, -240
6.11.1 Geo Object Example
{"geo": {
"country": "US","region": "NY","city": "City Name","zip": "10601","utcoffset": -240
}}
24 https://www.maxmind.com/en/geoip2-services-and-databases25 https://www.iso.org/iso-3166-country-codes.html
6.11. Geo Object Properties 48
BidSwitch Protocol for Suppliers, Release 1.0
6.12 Metric Object
Note: Fields marked with an asterisk (*) are optional.
Table 34: Metric Object PropertiesValue Type Descriptiontype string The type of metric being presented. Currently BidSwitch only
supports using viewability as the metric typevalue float A decimal number representing the value of the metric being
supplied• viewability probability is in the range 0.0 – 1.0.
vendor* string Source of the value declared by the Supplier
6.12.1 Metric JSON Example
{"metric":[
{"type":"viewability","value":0.85
}]
}
6.13 User Object
Note: Fields marked with asterisk (*) are optional.
6.12. Metric Object 49
BidSwitch Protocol for Suppliers, Release 1.0
Table 35: User Object PropertiesValue Type Descriptionid* string Your unique ID for this userbuyeruid* string The BidSwitch ID for this user. For in-app traffic the
lowercase IDFA, or Android ID is used. For example,"38f72eaf-5d6f-4143-824f-deaf753d7239"
keywords* string Comma separated list of keywords, interests, or intent, for ex-ample, Cars, sports, vacation
yob* integer Year of birth as a 4-digit integer, for example, 1977gender* string Specifies the user gender, for example, "F"
• "M" = Male• "F" = Female• "O" = Known to be other, or omitted if unknown
data* array of ob-jects
Additional data. Each data object represents a different datasource, for more information, see the Data Object (page 58)section.
ext* object See User Ext Object (page 51)
6.13. User Object 50
BidSwitch Protocol for Suppliers, Release 1.0
6.13.1 User Ext Object
Table 36: User Ext Object PropertiesValue Type Descriptioneids* array of ob-
jectsContains the Extended identifiersobject, see the Extended Identi-fiers (page 53) section for details
floc* object Cohort ID that is common toa large cohort of users withsimilar browsing habits. Cur-rently the cohort ID is simulatedby the exchange (as opposed toby the browser). When simu-lated cohort ID is provided, tra-ditional pseudonymous cookie-based user identifiers or deviceadvertising identifiers would notbe populated. Experimental fea-ture; may be subject to change.See https://github.com/WICG/floc for more background onFLoC.
Note: In the event FLOC is be-ing used there should be no user.id or user.buyerid present.
impdepth* int The count of impressions for aspecific placement type in a givenapp session. The impressiondepth is reset once the sessionends, e.g 2
sessionduration* int The total duration of time a userhas spent so far in a specific appsession expressed in seconds. Forexample, a user has been playingWord Game for 45 seconds, e.g.45
6.13. User Object 51
BidSwitch Protocol for Suppliers, Release 1.0
consented_providers_settings* object Passes a set of IDs correspondingto providers for whom the pub-lisher has provided user consentusing Google vendor list. Seethe Consented Provider Settings(page 52)
consent* string The binary encoding scheme thatis passed in base64 URL/web safeformat known as daisybit, e.g."Y29uc2VudCBkYXRh"The data stored in the consentstring is divided into 3 parts:metadata, the purposes for whichthe user has given consent, andto which vendors this consent wasgiven.The Supplier should pass this in-formation to Buyers to ensurethey can bid appropriately intheir responses. For more infor-mation see the following links:
• https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework
• https://gdpr-info.eu/• http://gdpr-demo.
labs.quantcast.com/user-examples/cookie-workshop.html
• https://vendor-list.consensu.org/v2/vendor-list.json
6.13.2 Consented Provider Settings
Table 37: Consented ProvidersValue Type Descriptionconsented_providers array of inte-
gersSet of IDs corresponding to providers for whom the pub-lisher has provided user consent using Google vendor list.A mapping of provider ID to provider name is postedat https://storage.googleapis.com/adx-rtb-dictionaries/providers.csv
6.13. User Object 52
BidSwitch Protocol for Suppliers, Release 1.0
6.13.3 FloC Object
Table 38: FloC Object PropertiesValue Type Descriptionid string The value of a cohort ID – a string identifier that is common to
a large cohort of users with similar browsing habits.type integer Identifies the method of generating the cohort ID, see this
Google whitepaper for more details: Evaluation of Cohort Al-gorithms for the FloC API26
• FLOC_TYPE_UNKNOWN = 0; Default value thatshould not be used.
• SIMULATED_AFFINITY_CLUSTERING_CENTROID_VERTICAL= 2; FLoC simulated using affinity hierarchical clusteringwith centroids and feature extraction based on Topiccategories as described in the whitepaper.
• SIMULATED_SIMHASH_SORTING_LSH_DOMAIN_ONE_HOT= 3; FLoC simulated using SortingLSH clustering algo-rithm and Domain One-hot encoding feature extractionas described in the whitepaper. FLoC simulatedusing a k Random Centers locality-sensitive hash func-tion as described in github.com/google/ads-privacy/blob/master/proposals/FLoC/k-random-centers.md withDomain TF-IDF feature extraction as described in thewhitepaper.
• KCENTER_DOM_FILTERED_TFDIF = 4;
{"user":{
"ext":{"floc":{
"id":"str123","type":3
}}
}}
6.13.4 Extended Identifiers
Supports the official Open RTB community extension for passing multiple third party user identi-fiers, see the official Extended Identifiers27 spec for more details.
This object passes any additional User IDs a Supplier, Consent Management Platform (CMP), DataManagement Platform (DMP), or BidSwitch may have for a user. There is a number of identity
26 https://github.com/google/ads-privacy/blob/master/proposals/FLoC/FLOC-Whitepaper-Google.pdf27 https://github.com/InteractiveAdvertisingBureau/openrtb/tree/master/extensions/2.x_official_extensions
6.13. User Object 53
BidSwitch Protocol for Suppliers, Release 1.0
solutions that provide IDs for users that are not based on 3rd party data, and many of these solutionproviders extend their first-party data as offerings that can be used to offset the decline of 3rd partycookies.
BidSwitch and many of our partners support these offerings and have build systems to collate, map,and make these IDs available to Buyers, who can use them to improve the robustness of targetedadvertising. When the appropriate consent is in place (e.g CCPA, GDPR) BidSwitch passes alland any correctly set ID in this field. The following IDs are the most commonly sent throughBidSwitch, but if you are looking for a particular ID in requests, you should check the source valueto identify it. You can find a more extensive list of possible IDs on the Prebid User ID Modulepage28
• The TradeDesk ID known as the Unified ID 2.0 and passed as "uidapi.com", is based on aSingle-Sign On (SSO) email validation service for publisher site access.
• The TradeDesk ID known as the Unified ID 1.0 and passed as "adserver.org".You canread more about that here https://www.thetradedesk.com/us/about-us/industry-initiatives/unified-id-solution-2-0/unified-id-solution-1-0
• The LiveIntent ID, passed as "liveintent.com", is built and authenticated dailythrough consent-based email, you can read more about here https://www.liveintent.com/identity-solutions/
• The ID5 ID, passed as "id5-sync.com", enables publishers to create and distribute a sharedfirst-party identifier, you can read more about that here https://www.id5.io/
• The prebid managed SharedID, passed using "sharedid.org", see https://prebid.org/product-suite/sharedid/ for more details
• The LiveRamp ID, passed as "liveramp.com", associates anonymous device IDs and otheronline customer IDs from publishers, platforms, or data providers with an IdentityLink(IDL) single person-based identifier. You can read more about it here https://liveramp.com/our-platform/identity-resolution/
Note:
• The LiveRamp ID is encrypted and only enabled for certain Buyers that have the businesscontracts in place to decrypt and use this ID, contact [email protected] if you are aLiveRamp partner.
• The LiveIntent ID is only available to certain Buyers to whom LiveIntent wish to grant usagerights.
28 https://docs.prebid.org/dev-docs/modules/userId.html
6.13. User Object 54
BidSwitch Protocol for Suppliers, Release 1.0
Table 39: eids Object PropertiesValue Type Descriptionsource string (Required) Source or technology provider responsible for the set of
included IDs. Expressed as a top-level domain. BidSwitch includesthe following IDs when available.
• The Trade Desk backed Unified ID passed using "adserver.org" for v1.0 and as "uidapi.com" for v2.0.
• id5 passed using "id5-sync.com"• The LiveIntent ID passed using "liveintent.com"• IDL passed using "liveramp.com"• SharedID passed using "sharedid.org"
uids array of ob-jects
(Required) Passes the User IDs matched from the given provider.
uids Object
Table 40: uids Object PropertiesValue Type Descriptionid string (Required) The User ID with this provider.atype int (Optional) The type of user agent the match is from.
• 1 An ID which is tied to a specific web browser or device(cookie-based, probabilistic, or other).
• 2 In-app impressions, which will typically contain a type ofdevice ID (or rather, the privacy-compliant versions of deviceIDs).
• 3 A person-based ID, i.e., that is the same across devices.• 500+ Vendor-specific codes.
6.13.5 User Object Example
{"user":{
"id":"45asdf987656789adfad4678rew656789","buyeruid":"1234567890","keywords":"sports, entertainment","yob":1976,"gender":"F","ext":{
"ug":1,"cookie_age":15,"consent":"Y29uc2VudCBkYXRh","consented_providers_settings":{
(continues on next page)
6.13. User Object 55
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"consented_providers":[1791
]},"eids":[
{"source":"adserver.org","uids":[
{"id":"zzz","atype":1
},{
"id":"DB700403-9A24-4A4B-A8D5-8A0B4BE777D2","atype":2
}]
},{
"source":"liveintent.com","uids":[
{"id":"IPl4zj44RhezVyNE83bYfogYRN6W8LaCy3USy8dPQ==","atype":3
}]
},{
"source":"liveramp.com","uids":[
{"id":"0db20294a3908612bc7e732c2022095391074cf3"
}]
}]
}}
}
6.14 Ext Object
Note: Fields marked with asterisk (*) are optional.
6.14. Ext Object 56
BidSwitch Protocol for Suppliers, Release 1.0
Table 41: Ext Object PropertiesValue Type Descriptiondsp_uuids* object key-value user ID pairs to support direct-like user syncs, see
the Supplier First-Party User-Matching (page 135) sectionfor more details.
google_query_id* string This represents a unique ID for the overall query. Inthe event that there are multiple call-outs for a query,all call-out requests for that query will contain the samegoogle_query_id, see more here: https://developers.google.com/authorized-buyers/rtb/openrtb-guide#bidrequestextIt is highly recommended to include this ID if you are sell-ing Exchange Bidding Dynamic Allocation (EDBA) sourcedinventory through BidSwitch to Google DV360.
ads_txt* object Contains the ads.txt information about the Supplier, see theads.txt Object (page 57) and BidSwitch and Ads.txt29 sec-tions for more details.
{"ext":{
"dsp_uuids":{"77":"xyz"
}}
}
6.15 ads.txt Object
Table 42: Ads.txt Object PropertiesValue Type Descriptionstatus int Indicates what information the ads.txt file contained regarding this
Suppliers selling relationship with the publisher:• 1 = direct• 2 = reseller• 3 = unauthorized
pub_id string Exchange-specific publisher ID, e.g “abc-123”. Note: Do not useany of the following symbols in the publisher ID, as doing so maycause issues:, # % $ @ * & ? ! ` ~ " ' / \ | ( ) { } [ ]+ = ^
auth_id* string Passes the TAG ID if present in the ads.txt file, e.g. 8765jfhfg09jsupplier_domain*string Passes the Supplier’s domain listed in the publisher’s ads.txt file,
e.g. "openx.com"
29 https://protocol.bidswitch.com/features/ads-txt.html#ads-txt
6.15. ads.txt Object 57
BidSwitch Protocol for Suppliers, Release 1.0
6.16 Data Object
Note: Fields marked with asterisk (*) are optional.
Table 43: Data Object PropertiesValue Type Descriptionid * string Exchange-specific ID for the data provider, for example
"BSW001"name string Exchange-specific name for the data provider, for example
"domain-origin"segment array of ob-
jectsArray of Segment objects that contain the actual data values.
6.16.1 Segment Object
Table 44: Segment Object PropertiesValue Type Descriptionid* string ID of the data segment specific to the data provider, for exam-
ple, "Seg123"name string Name of the data segment specific to the data provider, for
example, "status"value* string String representation of the data segment value, for example,
"verified"
{"data":[
{"name":"domain-origin","segment":[
{"name":"status","value":"verified"
},{
"name":"domain","value":"abcd.com"
}]
}]
}
6.16. Data Object 58
BidSwitch Protocol for Suppliers, Release 1.0
6.17 Source Object
Note: Fields marked with an asterisk (*) are optional.
Table 45: Source Object PropertiesValue Type Descriptionfd integer Indicates the entity responsible for the final impression sale de-
cision, using the following values:• 0 = The exchange behind BidSwitch• 1 = An upstream source (usually header bidder)
For example a bid request containing ext.ssp='rubicon' andsource.fd=0 implies that the auction is run at Rubicon SSP.If the same request has source.fd=1 then the auction is run ata header bidder upstream from Rubicon SSP.Note: The BidSwitch platform never acts as the decisionmaker.
tid string (Recommended) Transaction ID that must be common acrossall participants in this bid request (e.g., potentially multipleexchanges).
pchain* string Payment ID chain string containing embedded syntax describedin the TAG Payment ID Protocol v1.0.
ext* object Contains additional fields, see Source Extension (page 59)
6.17.1 Source Extension
Table 46: Source Extension Object PropertiesValue Type Descriptionomidpn string Identifier of the OM SDK integration, the IAB Open Measure-
ment specification on Github30
omidpv string Version of the OM SDK integration.schain object Contains the supplychain object, as fully described here on the
IAB Github Page31:The SupplyChain object is composed primarily of a set of nodeswhere each node represents a specific entity that participates inthe selling of a bid request. The entire chain of nodes frombeginning to end would represent all sellers who were paid foran individual bid request.
30 https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/OpenRTB%20support%20for%20OMSDK.md
31 https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md
6.17. Source Object 59
BidSwitch Protocol for Suppliers, Release 1.0
6.17.2 SupplyChain Object
Table 47: schainValue Type Descriptioncomplete int (Required) Flag indicating whether the chain contains all
nodes leading back to the source of the inventory, where 0 =no, 1 = yes.
nodes array of ob-jects
(Required) Array of objects in the order of placing in thechain. The original source of the request is first and the fi-nal seller of the request last, see Supply Chain Nodes (page 61)
ver str (Required) Version of the supply chain specification in use.Currently "1.0" is the only option.
6.17. Source Object 60
BidSwitch Protocol for Suppliers, Release 1.0
6.17.3 Supply Chain Nodes
Table 48: supply chain nodeValue Type Descriptionasi string (Required) The canonical domain name of the SSP, Exchange,
Header Wrapper, etc system that bidders connect to. This maybe the operational domain of the system, if that is different thanthe parent corporate domain, to facilitate WHOIS and reverseIP lookups to establish clear ownership of the delegate system.This should be the same value as used to identify sellers in anads.txt file if one exists.
sid string (Required) The identifier associated with the seller or reselleraccount within the advertising system. This must contain thesame value used in transactions (i.e. OpenRTB bid requests)in the field specified by the SSP/exchange. Typically, in Open-RTB, this is publisher.id. For OpenDirect it is typically thepublisher’s organization ID.Should be limited to 64 charactersin length.
hp int (Required) Indicates whether this node will be involved in theflow of payment for the inventory.When set to 1, the advertising system in the asi field pays theseller in the sid field, who is responsible for paying the previousnode in the chain.When set to 0, this node is not involved in the flow of paymentfor the inventory.For version 1.0 of SupplyChain, this property should always be1. It is explicitly required to be included as it is expected thatfuture versions of the specification will introduce non-paymenthandling nodes. Implementers should ensure that they supportthis field and propagate it onwards when constructing Supply-Chain objects in bid requests sent to a downstream advertisingsystem.
rid string The OpenRTB RequestId of the request as issued by this seller.name* string The business name of the entity represented by this node. This
value is optional and should NOT be included if it exists in theadvertising system’s sellers.txt file.
domain* string The business domain name of the entity represented by thisnode. This value is optional and should NOT be included if itexists in the advertising system’s sellers.txt file.
6.17.4 Example Source JSON
{"source":{
"fd":1,(continues on next page)
6.17. Source Object 61
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"ext":{"schain":{
"complete":0,"ver":"1.0","nodes":[
{"asi":"reseller.com","sid":"aaaaa","rid":"BidRequest4","hp":1
}]
}}
}}
6.18 Site Object
Note: Fields marked with an asterisk (*) are optional.
6.18. Site Object 62
BidSwitch Protocol for Suppliers, Release 1.0
Table 49: Site Object PropertiesValue Type Descriptionpublisher object Publisher object, for more information, see the Publisher Object
(page 68) section.id string An exchange specific identifier.name* string Site name (may be masked by publisher request), for example,
"Test Site"domain* string Domain of the site, used for advertiser side blocking.
"testsite.com"content* object Passes the content object, see the Content Object (page 66)
section for detailscat* array of
stringsArray of IAB content categories for the site, ["IAB1","IAB2-3"]. Based on the IAB taxonomy, and extended withadditional sensitive categories listed in the Sensitive Categoriesand Rich Media (page 6) section.The content categories specified can be extended usingBidSwitch Sensitive Categories and Rich Media (page 6).
page* string URL of the page where the impression will be shown. "http://testsite.com/main.asp"
ref* string Referrer URL that caused navigation to the current page, forexample, "http://testsite.com/main.asp"
privacypolicy* integer Indicates if the site has a privacy policy.• 0 = No• 1 = Yes.
mobile* integer Mobile-optimized signal.• 0 = No• 1 = Yes.
ext* object Site extension object
6.18.1 Site Ext
Table 50: Site Extension Object PropertiesValue Type Descriptionamp bool Indicates if the site is AMP (Accelerated Mobile Pages) opti-
mised, where 1 = Yes and 0 = Noinventorypartnerdomainstring A pointer to the domain of the partner (of the site/app owner)
with ownership of some portion of ad inventory on the site/app.The partner’s ads.txt or app-ads.txt file will be hosted here.This directive was added in the (app-)ads.txt v1.0.3 specifica-tion32 update.
32 https://iabtechlab.com/ads-txt/
6.18. Site Object 63
BidSwitch Protocol for Suppliers, Release 1.0
6.18.2 SSP Site Object Example
{"site":{
"id":"abc35123","name":"Site ABCD","domain":"siteabcd.com","cat":[
"IAB2-1","IAB2-2"
],"page":"http://siteabcd.com/page.htm","ref":"http://referringsite.com/referringpage.htm","privacypolicy":1,"ext":{
"inventorypartnerdomain":"examplepartnerdomain.com"},"publisher":{
"id":"abc2345","name":"Publisher A"
}}
}
6.19 App Object
Note: Fields marked with an asterisk (*) are optional.
6.19. App Object 64
BidSwitch Protocol for Suppliers, Release 1.0
Table 51: App Object PropertiesValue Type Descriptionpublisher object Publisher object, for more information, see the Publisher Object
(page 68) section.id string The application ID.name* string Application name, for example, "Test App"domain* string The domain of the app, for example, "mygame.example.com"cat* array of
stringsArray of IAB content categories for the publisher site, for exam-ple, ["IAB1", "IAB2- 3"]. Based on the IAB taxonomy, and ex-tended with additional sensitive categories listed in the SensitiveCategories and Rich Media (page 6) section.
content* object Passes the content object, see the Content Object (page 66) sectionfor details
bundle* string Application bundle or package name, for example, "com.example.mygame"
paid* integer Specifies if the App is a free or paid version.• 0 = The app is free,• 1 = The app is a paid version.
storeurl* string App store’s URL for the mobile application, for example "http://media-apps.cc/android"
storeid* string The ID of the app in an app store (e.g., Apple iTunes, GooglePlay).
ver* string Application version, for example "1.1"privacypolicy* integer Indicates if the app has a privacy policy.
• 0 = No• 1 = Yes.
6.19.1 App Ext Object
Table 52: App Extension Object PropertiesValue Type Descriptioninventorypartnerdomain string A pointer to the domain of the partner (of the
site/app owner) with ownership of some portionof ad inventory on the site/app. The partner’sads.txt or app-ads.txt file will be hosted here.This directive was added in the (app-)ads.txt v1.0.3specification33 update.
33 https://iabtechlab.com/ads-txt/
6.19. App Object 65
BidSwitch Protocol for Suppliers, Release 1.0
6.20 Content Object
Table 53: Content Object PropertiesValue Type Descriptionid* string ID uniquely identifying the content.episode* integer Episode number.title* string Content title e.g., Lost Kingdom - SE02 EP03season* string Content season e.g., "Season 3"artist* string Artist credited with the contentgenre* string Genre that best describes the content, e.g., rock, pop, etc. You
may need to discuss with your trading partners about aligningaround a particular taxonomy. There’s a few taxonomies fordefining the genre, the IAB Content taxonomy being the moststandard one at the moment.
• Google have their own which you can download from theirDisplay & Video 360 OpenRTB Specification34
• The IAB CONTENT TAXONOMY35
• An audio taxonomy is also being worked on by variousentities, this page will be updated when a standard isfinalised
album* string Album to which the content belongs; typically for audio.isrc* string International Standard Recording Code conforming to ISO-
3901.url* string A single URL of the content, for buy-side contextualization or
review.cat* array of
stringsArray of content categories using IDs from the IAB taxonomy.
prodq* integer Production quality: 1 Professionally Produced, 2 Prosumer 3User Generated (UGC)
context* integer Type of content• 1 Video (i.e., video file or stream such as Internet TV
broadcasts)• 2 Game (i.e., an interactive software game)• 3 Music (i.e., audio file or stream such as Internet radio
broadcasts)• 4 Application (i.e., an interactive software application)• 5 Text (i.e., primarily textual document such as a web
page, eBook, or news article)• 6 Other (i.e., none of the other categories applies)• 7 Unknown
rating* string Content rating (e.g., MPAA).urating* string User rating of the content (e.g., number of stars, likes, etc.).
6.20. Content Object 66
BidSwitch Protocol for Suppliers, Release 1.0
mrating* integer Media rating per IQG guidelines. Refer to List: Media Ratings.• 1 All Audiences• 2 Everyone Over Age 12• 3 Mature Audiences
keywords* string Comma separated list of keywords describing the content.live* integer Indication of live content, where 0 = not live, 1 = live (e.g.,
stream, live blog).Note: This may also be passed as livestream due to the dif-ference between Open RTB 2.5 and 3.0.
srcrel* integer Source relationship, where 0 = indirect, 1 = direct.len* integer Length of content in seconds; typically for video or audio.lang* string Content language using ISO-639-1-alpha-2.
Note: This may also be passed a language due to the differ-ence between Open RTB 2.5 and 3.0.
embed* integer Indicator of whether or not the content is embedded off-sitefrom the the site or app described in those objects (e.g., anembedded video player), where 0 = no, 1 = yes.
producer* object Details about the content producer. Refer to Object: Producer.data* array of ob-
jectsAdditional user data. Each Data object represents a differentdata source, see the data-obj
Listing 1: Content Object Example
{"content":{
"cat":["IAB-1","IAB-2"
],"contentrating":"MPAA","context":1,"episode":1,"genre":"comedy","id":"472759950","language":"en","len":15,"live":1,"prodq":1,"series":"string","title":"Law & Order Criminal Intent S03 - Ep18 Ill-Bred HD Watch","url":"https://forums.watchuseek.com/showthread.php","userrating":"4.1"
}}
34 https://developers.google.com/display-video/ortb-spec#content-object35 https://iabtechlab.com/standards/content-taxonomy/
6.20. Content Object 67
BidSwitch Protocol for Suppliers, Release 1.0
6.21 DOOH Object
The presence of this object in a request signals that it is for Digital-out-of-Home (DOOH) inventory,in such cases the following applies.
• You should use the site or app object to pass the publisher ID.
• A value is not expected in device.ip or device.ipv6, making that field optional
Table 54: DOOH Object PropertiesValue Type Descriptionaudience* float Expected number of people reached by the ad opportunity, e.g.
10.5impmultiply float The impmultiply field is designed to be used when calculating
the billable media cost by the Buyer and on the invoice. Itshould not be used to multiply the bid price in the bid response.Suppliers should only receive a bid price based on CPM values.For example, if the Buyer wins 3000 bids at a clearing price of$1.50 CPM and impmultiply=4 each, then the invoiced amountis $18 (1.50 / 1000 * 4 * 3000).
Note: Fields marked with an asterisk (*) are optional.
Suppliers should make sure their Buyers are basing any billing calculations on the same multiplierand/or rounding to the same number of decimal places.
{"device":{
"ext":{"dooh":{
"audience":1.56,"impmultiply":1.34
}}
}}
6.22 Publisher Object
Table 55: Publisher Object PropertiesValue Type Descriptionid string Exchange-specific publisher ID.name* string Publisher name, for example "AAP"cat* array of string Array of IAB content categories for the publisher. ["IAB1",
"IAB2-3"]
6.21. DOOH Object 68
BidSwitch Protocol for Suppliers, Release 1.0
Note: Fields marked with an asterisk (*) are optional and may not be sent in each request.
6.22.1 Publisher Object Example
{"publisher":{
"id":"abc123","name":"Publisher A"
}}
6.23 Regulation Object
Table 56: Regulation Object PropertiesValue Type Descriptioncoppa integer Flag indicating whether or not this request falls under the
COPPA regulations established by the USA FTC:• 0 = No.• 1 = Yes.
ext* object See the Regs Ext Object (page 70)
6.23. Regulation Object 69
BidSwitch Protocol for Suppliers, Release 1.0
6.23.1 Regs Ext Object
Table 57: Regs Ext Object PropertiesValue Type Descriptiongdpr* integer Indicates whether the request falls under GDPR regulations:
• 0 = No• 1 = Yes• Under OpenRTB conventions for optional attributes,
omission indicates UnknownIf consent is given, you should check if the user.ext.consentfield is present to ascertain what form of consent was given, seethe User Ext Object (page 51) section
us_privacy* string Passes the user privacy status for requests which fall underCCPA36 regulations. The string uses 4 characters, e.g. "1YN-",passed in the following order.
1. Version Number The IAB CCPA Specification versionthat applies to this string, passed as an integer. Currentlyonly 1 is available.
2. Explicit Notice (N = No, Y = Yes, - = Not Applicable)Indicates whether explicit notice has been provided tothe user as required by 1798.115 (d) of the CCPA andwhether they have had the opportunity to opt-out of thesale of their data pursuant to 1798.120 and 1798.135 ofthe CCPA.
3. Opted-Out (N = No, Y = Yes, - = Not Applicable)Indicates whether the user has opted-out of the saleof their personal information pursuant to 1798.120 and1798.135.
4. LSPA (N = No, Y = Yes, - = Not Applicable)Indicates whether the publisher is a signatory to the IABLimited Service Provider Agreement (LSPA) and that thepublisher declares the transaction should be treated as a“Covered Opt Out Transaction” or a “Non Opt Out Trans-action” as defined in the agreement.
{"regs":{
"ext":{"gdpr":1,"us_privacy":"1YN-"
}}
}
36 https://iabtechlab.com/standards/ccpa/
6.23. Regulation Object 70
BidSwitch Protocol for Suppliers, Release 1.0
6.24 Required Fields per Buyer
Some Buyers request or require certain fields be sent to them that are above and beyond the normalIAB specification. This usually indicates fields that they deem important and thus including themwill increase their interest in your inventory.
Table 58: Recommended Fields per BuyerBuyer Required or Recommended fieldsDV360
• native.request.eventtrackers.event with value 1• native.request.eventtrackers.methods with value 1• native.request.plcmttype (recommended)• See the Native Request Object (page 35) section for more
details.
Note: This table of fields does not include those fields that are required as part of this protocol.
6.25 Bid Request JSON Examples
6.25.1 Banner Ad Request Example
{"id": "c6987c2b-edb4-4b7b-b8cf-157af1d485e3","regs": {
"ext": {"gdpr": 1
}},"site": {
"id": "ed2265d8","ref": "http://ad32.answers.com/click.php?source=fb¶m4=fb-us-de-red¶m3=www.
→˓answers.com%2Farticle%2F31029589%2Finsanely-useful-life-hacks-to-make-everything-→˓easier¶m1=tattoo¶m2=67660042¶m5=10153631993521186¶m6=6049542139960&→˓adt=4342",
"publisher": {"name": "www.answers.com","id": "946353442_12535"
},"name": "www.answers.com","cat": [
"IAB24"],"domain": "answers.com","page": "http://www.answers.com/article/31029589/insanely-useful-life-hacks-to-make-
→˓everything-easier?paramt=null¶m4=fb-us-de-red¶m1=tattoo¶m2=67660042&s=8"(continues on next page)
6.24. Required Fields per Buyer 71
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
},"wseat": [
"165","16"
],"source": {
"fd": 0},"ext": {
"dsp_uuids": {"77": "xyz"
}},"user": {
"id": "5e29eb00-c30a-416e-9d2a-2e18901f0916","buyeruid": "CAESEHL-9O4oJOAiC1Y0O2EHTcE","ext": {
"consent": "Y29uc2VudCBkYXRh"}
},"device": {
"pxratio": 0,"language": "en","mccmnc": "310-005","w": 1920,"geo": {
"country": "US","lon": -80.237,"city": "City Name","lat": 26.638,"zip": "33414","region": "FL","type": 2
},"os": "Windows","devicetype": 2,"h": 1080,"ip": "73.139.39.18","js": 1,"ua": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0","dnt": 0
},"tmax": 75,"cur": [
"USD"],"imp": [
{"bidfloor": 3.213,"metric": [
{
(continues on next page)
6.25. Bid Request JSON Examples 72
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"type": "viewability","value": 0.85
}],"id": "1","banner": {
"pos": 1,"h": 600,"battr": [
1,3,5,6,8,9,10,14,15,16
],"w": 160,"format": [
{"h": 300,"w": 300
},{
"h": 350,"w": 300
}],"btype": [
1]
},"exp": 300,"tagid": "25108","bidfloorcur": "USD","secure": 0,"instl": 0
}],"bcat": [
"IAB25-3","BSW1","BSW2","BSW10","BSW4","IAB26"
],"at": 2
}
6.25. Bid Request JSON Examples 73
BidSwitch Protocol for Suppliers, Release 1.0
6.25.2 Native Ad Request Example
{"id": "129ca6dd-5403-4476-a4a6-555d6a538bc4","app": {
"id": "pubnative_1009429","publisher": {
"name": "","id": "pubnative_1005292"
},"storeurl": "https://play.google.com/store/apps/details?id=com.leo.appmaster","bundle": "com.leo.appmaster","cat": [
"IAB3"],"name": "PG_lock_pic"
},"wseat": [
"167"],"source": {
"fd": 0},"user": {
"id": "45asdf987656789adfad4678rew656789","buyeruid": "1234567890","keywords": "sports, entertainment","yob": 1976,"gender": "F","ext": {
"ug": 1,"cookie_age": 15,"consent": "Y29uc2VudCBkYXRh"
}},"device": {
"connectiontype": 3,"model": "Micromax A096","mccmnc": "310-005","language": "en","geo": {
"country": "IN","lon": 85.1167,"city": "Patna","lat": 25.6,"zip": "800002","region": "34","type": 2
},"ifa": "793ff4b0-d077-4002-aeb6-b8ea64dd4b2b","osv": "5.0.2","os": "Android",
(continues on next page)
6.25. Bid Request JSON Examples 74
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"carrier": "Airtel","devicetype": 1,"ip": "223.176.12.242","ua": "Dalvik/2.1.0 (Linux; U; Android 5.0.2; Micromax A096 Build/LRX21M)","dnt": 2
},"tmax": 80,"cur": [
"USD"],"imp": [
{"bidfloor": 0.324,"id": "1","native": {
"request": {"plcmtcnt": 1,"plcmttype": 2,"privacy": 1,"context": 1,"contextsubtype": 12,"assets": [
{"id": 1,"data": {
"type": 12},"required": 1
},{
"title": {"len": 50
},"id": 2,"required": 1
},{
"id": 3,"img": {
"w": 80,"h": 80,"type": 1
},"required": 1
},{
"id": 4,"img": {
"w": 1200,"h": 627,"type": 3
(continues on next page)
6.25. Bid Request JSON Examples 75
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
},"required": 1
},{
"data": {"type": 3
},"id": 5,"required": 0
},{
"id": 6,"data": {
"len": 100,"type": 2
},"required": 1
}],"ver": "1.2"
}},"exp": 1800,"bidfloorcur": "USD","ext": {},"instl": 0
}],"bcat": [
"IAB25-3","BSW1","BSW2","BSW10","BSW4","IAB26"
],"ext": {
"wt": 112,"clktrkrq": 0,"is_secure": 0,"ads_txt": {
"status": 2,"auth_id": "1kjgh7653","pub_id": "537120563","supplier_domain": "example.com"
}},"at": 2
}
6.25. Bid Request JSON Examples 76
BidSwitch Protocol for Suppliers, Release 1.0
6.25.3 Video Ad Request Example
{"regs": {
"ext": {"gdpr": 1
}},"id": "75c0238c-3b52-4b87-957a-817f83e853f1","site": {
"id": "adaptv_","publisher": {
"name": "","id": "tv4182"
},"cat": [
"IAB1"],"page": "http://kissasian.com"
},"wseat": [
"126"],"source": {
"fd": 0},"user": {
"id": "b457c658-ffdc-415c-8d91-30d864f4a5f5","buyeruid": "7bcb7e7c-eff0-43ad-8522-b5c9251f0d43","ext": {
"consent": "Y29uc2VudCBkYXRh"}
},"device": {
"language": "en","mccmnc": "310-005","geo": {
"country": "US","lon": -75.15,"city": "Philadelphia","lat": 39.94,"zip": "19147","region": "PA","type": 2
},"lmt": 0,"os": "Other","devicetype": 6,"ip": "73.141.79.240","ua": "Mozilla/5.0 (PlayStation 4 3.55) AppleWebKit/537.78 (KHTML, like Gecko)"
},"tmax": 120,
(continues on next page)
6.25. Bid Request JSON Examples 77
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"cur": ["USD"
],"imp": [
{"bidfloor": 0.02268,"metric": [
{"type": "viewability","value": 0.85
}],"id": "1","instl": 0,"exp": 300,"bidfloorcur": "USD","secure": 0,"video": {
"protocols": [2,5
],"placement": 2,"playbackend": 1,"minduration": 5,"skip": 1,"playbackmethod": [
3],"maxduration": 60,"startdelay": 0,"linearity": 1,"mimes": [
"video/mp4"]
}}
],"bcat": [
"IAB25-3","BSW1","BSW2","BSW10","BSW4","IAB26"
],"at": 2
}
6.25. Bid Request JSON Examples 78
BidSwitch Protocol for Suppliers, Release 1.0
6.25.4 Audio Ad Request Example
{"id": "1234534625253","wseat": [
"58"],"source": {
"fd": 0},"imp": [
{"id": "1","secure": 1,"audio": {
"startdelay": 0,"minduration": 5,"maxduration": 30,"maxextended": 30,"minbitrate": 300,"maxbitrate": 1500,"api": [
1,2
],"protocols": [
9,10
],"mimes": [
"audio/aac","audio/mp4","audio/mpeg"
],"delivery": [
2],"battr": [
13,14
],"companionad": [
{"id": "1234567893-1","w": 300,"h": 250,"pos": 1,"battr": [
13,14
],"expdir": [
(continues on next page)
6.25. Bid Request JSON Examples 79
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
2,4
]},{
"id": "1234567893-2","w": 728,"h": 90,"pos": 1,"battr": [
13,14
]}
],"companiontype": [
1,2
]}
}],"site": {
"id": "google_234563","domain": "siteabcd.com","page": "https://siteabcd.com/page.htm","ref": "http://google.com/?q=siteabcd","publisher": {
"id": "google_25"}
},"device": {
"ip": "64.124.253.1","mccmnc": "310-005","geo": {
"country": "US","region": "NY","city": "White Plains","zip": "10601"
},"ua": "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; rv:1.9.2.16) Gecko/
→˓20110319 Firefox/3.6.16","language": "en"
},"ext": {
"dsp_uuids": {"77": "xyz"
}},"user": {
"id": "45asdf987656789adfad4678rew656789",
(continues on next page)
6.25. Bid Request JSON Examples 80
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"buyeruid": "1234567890","cur": [
"USD"]
}}
6.25.5 DooH Request Example
{"id": "1234534625253","wseat": [
"58"],"site": {
"id": "dooh-screens","publisher": {
"name": "motorway-ad-walls","id": "ourdoors-4182"
}},"imp": [
{"id": "06d690d1-bac0-43fa-9257-f6d62d984231","bidfloor": 15,"exp": 360,"video": {
"mimes": ["video/x-flv","video/mp4"
],"placement": 2,"playbackend": 1,"skip": 0,"minduration": 30,"maxduration": 30,"protocols": [
3,6,7
],"w": 640,"h": 480
},"pmp": {
"private_auction": 1,"deals": [
{"id": "deal-1","wseat": [
(continues on next page)
6.25. Bid Request JSON Examples 81
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"58"],"bidfloor": 2.5,"bidfloorcur": "USD","at": 3
}]
}}
],"device": {
"ifa": "035911ea467d03b65cf44f5633b","mccmnc": "310-005","ip": "64.124.253.1","geo": {
"lat": 35.012344,"lon": -115.12345,"country": "US","region": "NY","city": "White Plains","zip": "10601"
},"devicetype": 6,"ext": {
"dooh": {"audience": 19.5,"impmultiply": 1
}}
},"user": {
"id": "45asdf987656789adfad4678rew656789","data": [
{"id": "6","name": "Data Provider 1","segment": [
{"name": "M","value": "15"
},{
"name": "F","value": "9"
},{
"name": "M65+","value": "8.1"
},{
"name": "TOTAL",
(continues on next page)
6.25. Bid Request JSON Examples 82
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"value": "19.5"}
]},{
"name": "demographic","segment": [
{"id": "12341318394918","name": "auto intenders"
}]
}]
},"tmax": 150,"exp": 300,"cur": "USD","source": {
"fd": 0},"ext": {
"wt": 1,"clktrkrq": 0,"is_secure": 0,"ssp": "rubicon","tgroup": [
123,456,321,765
],"ads_txt": {
"status": 2,"auth_id": "1kjgh7653","pub_id": "537120563","supplier_domain": "example.com"
}}
}
6.25. Bid Request JSON Examples 83
CHAPTER7
SUPPLIER BID RESPONSE
This is the top level object that is sent by BidSwitch to the Supplier. Each bid request sent shouldcontain the following fields.
Table 1: Bid Response Object PropertiesValue Type Descriptionid string Specifies the ID of the bid request to which this is a response
to, for example, "d7d1e107-fe7c-4a57-9592-d1d41fa702d9"seatbid array of ob-
jectsAn array of Seat Bid objects, see the Seat Bid Object (page 85)section. The length of the array can be either 1+ (for yes-bid)or 0 (for no-bid).
cur* string Sets the bidding currency using ISO-421737 alphabetic codes.If not provided USD is assumed, "USD"
nbr* integer Returns a reason why the impression was not forwarded to anyBuyers. A No Bid Reason response if different to a No BidResponse. See the Supplier No Bid Reason (page 127) sectionfor details.
37 https://www.iso.org/iso-4217-currency-codes.html
84
BidSwitch Protocol for Suppliers, Release 1.0
7.1 Seat Bid Object
Table 2: seatbid Object PropertiesValue Type Descriptionbid array of ob-
jectsArray of Bid Objects, see Response Bid Object (page 85).
seat* string ID of the bidder seat on whose behalf this bid is made. Thevalue should match one of the values supplied in the wseatfield of the bid request and it is REQUIRED if the wseat fieldis present in bid request. For example, "34"
Note: Fields marked with asterisk (*) are optional.
7.2 Response Bid Object
Note:
• (*) Fields marked with an asterisk are optional.
• While individually neither of the following fields is required, one of them must be in theresponse: adm, adm_native.
7.1. Seat Bid Object 85
BidSwitch Protocol for Suppliers, Release 1.0
Table 3: Bid Object PropertiesValue Type Descriptionid string A bidder generated ID for the bid object, used for tracking and
debugging purposes, for example 3.impid string The ID of the impression object (imp) from the bid request to
which this bid response applies, for example "1"price float The bid price as a float value, expressed as CPM. All prices
assumed to be in USD if the cur parameter is omitted, forexample 1.23
protocol* integer The Video response protocol of the markup if applicable, see theVideo Response Protocols (page 91) table for the valid values.Note: This field is required in video responses.
adm* string Used to pass creative markup for display (banner), video, oraudio ads. One of either adm or adm_native should be presentin the response.
• This field can contain the win price macro.• This field is not used for native bid responses.
<a href=\"http://adserver.com/click?adid=125\"> <imgsrc=\"http://image1.cdn.com/impid=102\"/></a>
adm_native* object Used for native bid responses, see the Native Response Ob-ject (page 91) for the data it contains. One of either adm oradm_native should be present in the response.
burl string The Billing notice URL called by the exchange using a server-to-server call when a winning bid becomes billable basedon exchange-specific business policy (e.g., typically delivered,viewed, etc.).”This field should contain the win price macro, see the Macros(page 11) section."burl":"https://adserver.com/winnotice?impid=102&winprice=${AUCTION_PRICE}"
iurl* string Sample image URL (without cache busting) for content check-ing. REQUIRED when bidding on on banner bid requests."http://adserver.com/preview?impid=102"
language* string The Alpha-2 ISO 639-138 code for the creative’s language, forexample, ja. The nonstandard code "xx" may also be used ifthe creative has no linguistic content (e.g., a banner with justa company logo).
adomain array ofstrings
Advertiser’s primary or top-level domain for advertiser check-ing. This can be a list of domains if there is a rotating creative.Note that some Suppliers allow only one domain. To those Sup-pliers BidSwitch only sends the first domain from the list, forexample, ["advertiser.com"]
bundle* string A platform-specific application identifier intended to be uniqueto the app and independent of the exchange. On Android, thisshould be a bundle or package name (e.g., com.foo.mygame)
7.2. Response Bid Object 86
BidSwitch Protocol for Suppliers, Release 1.0
Value Type Descriptioncat* array of
stringsArray of IAB content categories, for example, ["IAB1","IAB2-3"]. Based on the IAB taxonomy, and extended withadditional sensitive categories listed in the Sensitive Categoriesand Rich Media (page 6) section.
cid* string Campaign ID or similar that is used by the Buyer to track andorganize their campaigns, for example, 102.
crid string Creative ID to assist with ad quality checking, for example“3021”
attr* array of inte-gers
Creative attributes as defined in the OpenRTB protocol, forexample, [1,3].
dealid* string Reference to the deal.id from the bid request, if this bidpertains to a private marketplace direct deal, for example,"AA-1234"
h* integer The height of the creative in pixels when an alternative ad sizeis used, relevant for banner ads only. 250
w* integer The width of the creative in pixels when an alternative ad sizeis used, relevant for banner ads only. 300
ext* object This field can be used to supply information about the creativeagency for whom the Buyer is working, see the Bid Ext Objectsection below for details.
38 https://www.iso.org/iso-639-language-codes.html
7.2. Response Bid Object 87
BidSwitch Protocol for Suppliers, Release 1.0
7.2.1 Bid Ext Object
Table 4: Bid Ext Object PropertiesValue Type Descriptionadvertiser_name* string The name of the advertiser serving the creative, for
example, "Coca-Cola"agency_name* string The name of the agency representing the advertiser,
for example, "CCA"agency_id* string ID of the agency representing the advertiser, for
example, “123”third_party_buyer_token string This is a Google specific response field, the to-
ken is used to identify end third-party buyer in-formation if the exchange as an Open Bidderis an intermediary. This is obtained from thethird-party buyer and must be passed to Googleunaltered in the bid response. You can readmore about it here https://developers.google.com/authorized-buyers/rtb/response-guide
data* array of object Returns arbitrary data from the Buyer, each objectcan take data.name and data.value to describethe data, see the Data Response Object39 for moredetails.
skadn* object Apple Ad Network Object, this will be used to passapp data from iOS 14 and newer releases. See SkAd-Network Extension (page 89)
39 https://protocol.bidswitch.com/ssp-protocol/ssp-response-data.html#ssp-response-data-ext
7.2. Response Bid Object 88
BidSwitch Protocol for Suppliers, Release 1.0
7.2.2 SkAdNetwork Extension
Table 5: skadn Ext Object PropertiesValue Type Descriptionversion* str Version of SKAdNetwork desired. Must be “2.0” or above.
From SKAdNetwork v2.2 onwards, this should be used in thefidelities object.
network* str Ad network identifier used in signature. Should match one ofthe items in the imp.ext.skadnetids array in the request
campaign* str Campaign ID compatible with Apple’s spec. As of 2.0, thisshould be an integer between 1 and 100, expressed as a string,e.g. "45"
fidelities* array of ob-jects
Supports multiple fidelity types introduced in SKAdNetworkv2.2, see the SkAdNetwork Fidelities (page 90) object for de-tails.
Note: From SKAdNetwork v2.2 onwards, this object wrapssome of the other fields in this table into it. As a result,nonce, version, timestamp and signature should be used inthe fidelities object and considered deprecated in this ob-ject.
itunesitem* str ID of advertiser’s app in Apple’s app store. Should match theapp.bundle request field e.g "880047117"
nonce* str An ID unique to each ad response (GUID/UUID) e.g."beeeb65e-b3de-02420004". From SKAdNetwork v2.2 on-wards, this should be used in the fidelities object.
sourceapp* str ID of publisher’s app in Apple’s app store, this should matchthe imp.ext.skadn.sourceapp value
timestamp* str Unix time in millis string used at the time of signature.From SKAdNetwork v2.2 onwards, this should be used in thefidelities object.
signature* str SKAdNetwork signature as specified by Apple e.g."MEQCIEQZRRyMyUXg==". From SKAdNetwork v2.2 on-wards, this should be used in the fidelities object.
7.2. Response Bid Object 89
BidSwitch Protocol for Suppliers, Release 1.0
7.2.3 SkAdNetwork Fidelities
Table 6: Fidelities Object PropertiesValue Type Descriptionversion* str Version of SKAdNetwork desired. Must be “2.0” or above.nonce* str An ID unique to each ad response (GUID/UUID) e.g.
"beeeb65e-b3de-02420004"timestamp* str Unix time in millis string used at the time of signaturesignature* str SKAdNetwork signature as specified by Apple e.g.
"MEQCIEQZRRyMyUXg=="
{"ext":{
"advertiser_name":"Coca-Cola","agency_name":"CC-advertising","data":[
{"name":"TUV","value":"ABC123"
}],"skadn":{
"network":"cDkw7geQsH.skadnetwork","campaign":"45","itunesitem":"880047117","sourceapp":"123456789","fidelities":[
{"timestamp":"1594406341","signature":"2RmFS7daRzSVZRVZ8RyMyUXg==","nonce":"473b1a16-b4ef-43ad-9591-fcf3aefa82a7","version":"2.2"
}]
}}
}
7.2. Response Bid Object 90
BidSwitch Protocol for Suppliers, Release 1.0
7.2.4 Video Response Protocols
Table 7: Video Response ProtocolsValue Type1 VAST 1.02 VAST 2.03 VAST 3.04 VAST 1.0 Wrapper5 VAST 2.0 Wrapper6 VAST 3.0 Wrapper7 VAST 4.08 VAST 4.0 Wrapper9 DAAST 1.010 DAAST 1.0 Wrapper
7.3 Native Response Object
Note: Fields marked with an asterisk (*) are optional.
7.3. Native Response Object 91
BidSwitch Protocol for Suppliers, Release 1.0
Table 8: Native Object PropertiesValue Type Descriptionassets array of ob-
jectsList of native ad assets.
link object The native-link-obj. This is the default link object for the ad.Individual assets can also have a link object which applies if theasset is activated (clicked). If the asset has no link object, theparent link object applies.
imptrackers ** array ofstrings
An array of impression tracking URLs, expected to return a 1x1image or 204 response, for example, ["http://adserver.com/native?impid=102"]Note: This field can contain the win price macro, see theMacros (page 11) section for more details
ver* string Version of the Native Markup version in use, for example, "1.2".
jstracker* string Optional JavaScript impression tracker. This should be validHTML with JavaScript already wrapped in <script> tags. Itwill be executed at impression time where it can be supported.Note: This field can contain the win price macro, see theMacros (page 11) section for more details
eventtrackers* array of ob-jects
Array of tracking objects to run with the ad, in response to thedeclared supported methods in the request. The link see EventTracker Request Object (page 38) for details.
privacy* string If support for this was indicated in the request, sets the URL ofa page informing the user about the buyer’s targeting activity,e.g https://www.example.com/privacy-notice
7.3.1 Native Assets Object
Note:
• (*) There may be exactly one of the fields marked with asterisk in one asset object.
• (**) The link object is optional and may not be present in each response.
7.3. Native Response Object 92
BidSwitch Protocol for Suppliers, Release 1.0
Table 9: Native Asset Object PropertiesValue Type Descriptionid integer A unique asset ID, must match one of the asset IDs in the bid
request, for example, 1.required* integer Set to 1 if the asset is required (bidder requires it to be dis-
played), default is 0, for example, 1.title* object Title object for a title asset, see Native Assets Title Object
below.img* object Image object for an image asset, see Native Assets Image Object
below.video* object Video object for a video asset, see Native Asset Video Object
below.data* object Data object for a data asset, see Native Asset Data Object
below.link ** object Link object for a call to action.
• The link object applies if the asset item is activated(clicked).
• If there is no link object on the asset, the parent link ob-ject on the bid response applies. See Native Link Objectbelow.
7.3.2 Native Assets Title Object
Table 10: Native Asset Title Object PropertiesValue Type Descriptiontext* string The text associated with the title element. "Our product is
the best!"
7.3.3 Native Assets Image Object
Table 11: Native Asset Image Object PropertiesValue Type Descriptionurl string (Required) URL of the image asset, for example, "http://
adserver.com/image?impid=102".h integer (Recommended) Height of the image in pixels, for example,
250.w integer (Recommended) Width of the image in pixels, for example,
300.
7.3. Native Response Object 93
BidSwitch Protocol for Suppliers, Release 1.0
7.3.4 Native Asset Video Object
Table 12: Native Asset Video Object PropertiesValue Type Descriptionvasttag string Vast XML, use the following example to format your VAST
XML response.
<?xml version="1.0" encoding="UTF-8"?><VAST version="2.0">
<Ad id="12345"><InLine>
<AdSystem version="1.0">SpotXchange</AdSystem><AdTitle><![CDATA[Sample VAST]]> </AdTitle><Impression>http://sample.com</Impression><Description><![CDATA[A sample VAST feed]]> </Description><Creatives>
<Creative sequence="1" id="1"><Linear>
<Duration>00:00:30</Duration><TrackingEvents /><VideoClicks>
<ClickThrough><![CDATA[http://sample.com/openrt btest]]></ClickThrough>
</VideoClicks><MediaFiles>
<MediaFile delivery="progressive" bitrate="256"width="640" height="480" type="video/mp4"><![CDATA[http://sample.com/video.mp4]]></MediaFile>
</MediaFiles></Linear>
</Creative></Creatives>
</InLine></Ad>
</VAST>
7.3.5 Native Asset Data Object
Table 13: Native Asset Data Object PropertiesValue Type Descriptionvalue string The formatted string of data to be displayed. Can contain a
formatted value such as “5 stars” or “$10” or “3.4 starsout of 5”.
7.3. Native Response Object 94
BidSwitch Protocol for Suppliers, Release 1.0
7.3.6 Native Link Object
Table 14: Native Link Object PropertiesValue Type Descriptionurl string Landing URL of the clickable link, for example, "http://
advertiser.com/"clicktrackers* array of
stringsClick tracker URLs to be activated when the URL is clicked,for example, ["http://adserver.com/click?impid=102"]
7.3.7 Native Response Example
{"seatbid":[
{"bid":[
{"adm_native":{
"ver":"1.2","jstracker":"<html></head><body></body><script src='./jquery.js'></script></
→˓html>","link":{
"url":"http://adserver.com/click?impid=102"},"imptrackers":[
"http://adserver.com/native?impid=102"],"assets":[
{"id":1,"required":1,"title":{
"text":"A test Native Ad"}
}]
}}
]}
]}
7.3. Native Response Object 95
BidSwitch Protocol for Suppliers, Release 1.0
7.4 Bid Response JSON Examples
7.4.1 Banner Bid Response
{"id": "1234567890","seatbid": [
{"bid": [
{"id": "1","impid": "102","price": 9.43,"crid": "314","cid": "42","language": "en","burl":"https://adserver.com/imp?impid=102&winprice=${AUCTION_PRICE}","adm": "<a href=\"http://adserver.com/click?adid=12345&tracker=${CLICK_
→˓URL:URLENCODE}\"><img src=\"http://image1.cdn.com/impid=102\"/></a>","iurl": "http://adserver.com/preview?crid=314","adomain": [
"advertiserdomain.com"],"ext": {
"advertiser_name": "Coca-Cola","agency_name": "CC-advertising","agency_id": "abcd1234"
}}
],"seat": "4"
}]
}
7.4.2 Native Bid Response
{"id":"1234567890","seatbid":[
{"bid":[
{"id":"1","impid":"102","price":9.43,"crid":"314","cid":"42","language":"en",
(continues on next page)
7.4. Bid Response JSON Examples 96
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"burl":"https://adserver.com/imp?impid=102&winprice=${AUCTION_PRICE}","adomain":[
"advertiserdomain.com"],"ext":{
"advertiser_name":"Coca-Cola","agency_name":"CC-advertising","agency_id":"abcd1234"
},"adm_native":{
"ver":"1.2","jstracker":"<html></head><body></body><script src='./jquery.js'></script></
→˓html>","privacy":"https://www.example.com/privacy-notice","link":{
"url":"http://adserver.com/click?impid=102"},"imptrackers":[
"http://adserver.com/native?impid=102"],"assets":[
{"id":1,"required":1,"title":{
"text":"A test Native Ad"}
}]
}}
],"seat":"58"
}]
}
7.4. Bid Response JSON Examples 97
BidSwitch Protocol for Suppliers, Release 1.0
7.4.3 Video Bid Response
{"cur":"USD","id":"e9c3e120-ffcb-4300-9c98-644cb26f95df","seatbid":[
{"bid":[
{"crid":"3","adm":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"2.0\"><Ad␣
→˓id=\"e1081d52_a3d9353a3f5711e795201cdbeb920001\"><Wrapper><AdSystem>BidSwitch<\/→˓AdSystem><VASTAdTagURI><![CDATA[http:\/\/adsrv.com\/vast\/7drQU9ksr]]><\/VASTAdTagURI>→˓<Error><![CDATA[http:\/\/gce-sc.bidswitch.net\/vast_error\/gdmj4t2_3wJg\/]]><\/Error>→˓<Impression><![CDATA[http:\/\/gce-sc.bidswitch.net\/imp\/${AUCTION_PRICE}\/mj4t2_3wJg\/→˓]]><\/Impression><Creatives><\/Creatives><\/Wrapper><\/Ad><\/VAST>",
"language": "en","protocol":3,"burl":"https://adserver.com/imp?impid=102&winprice=${AUCTION_PRICE}","adomain":[
"nokia.com"],"cid":"11","ext":{
"advertiser_name":"Nokia"},"id":"1c3ff810-3623-4b04-8396-9e7ca071cb72","impid":"1","price":4.079077199308326
}],"seat":"1"
}]
}
7.4.4 BidSwitch No Bid Reason
{"id":"1234567890","seatbid":[
],"nbr":4
}
7.4. Bid Response JSON Examples 98
BidSwitch Protocol for Suppliers, Release 1.0
7.4.5 Audio Ad Response
{"cur":"USD","id":"e9c3e120-ffcb-4300-9c98-644cb26f95df","seatbid":[
{"bid":[
{"crid":"3tre445","adm":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"2.0\"><Ad␣
→˓id=\"e1081d52_a3d9353a3f5711e795201cdbeb920001\"><Wrapper><AdSystem>BidSwitch<\/→˓AdSystem><VASTAdTagURI><![CDATA[http:\/\/adsrv.com\/vast\/7drQU9ksr]]><\/VASTAdTagURI>→˓<Error><![CDATA[http:\/\/gce-sc.bidswitch.net\/vast_error\/gdmj4t2_3wJg\/]]><\/Error>→˓<Impression><![CDATA[http:\/\/gce-sc.bidswitch.net\/imp\/${AUCTION_PRICE}\/mj4t2_3wJg\/→˓]]><\/Impression><Creatives><\/Creatives><\/Wrapper><\/Ad><\/VAST>",
"burl":"https://adserver.com/imp?impid=102&winprice=${AUCTION_PRICE}","adomain":[
"example.com"],"cid":"11","language": "en","ext":{
"advertiser_name":"Nokia","agency_name": "CC-advertising","agency_id": "abcd1234"
},"id":"1c3ff810-3623-4b04-8396-9e7ca071cb72","impid":"1","price":4.079077199308326
}],"seat":"1"
}]
}
7.4.6 TV/DOOH Bid Response
{"cur":"USD","id":"e9c3e120-ffcb-4300-9c98-644cb26f95df","seatbid":[
{"bid":[
{"adid":"3","burl":"https://adserver.com/imp?impid=102&winprice=${AUCTION_PRICE}
→˓","nurl":"http://adserver.com/winnotice?impid=102",
(continues on next page)
7.4. Bid Response JSON Examples 99
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"adm":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><VAST version=\"2.0\→˓"><Ad id=\"12345\"><InLine><AdSystem version=\"1.0\">SpotXchange</AdSystem><AdTitle><!→˓[CDATA[Sample VAST]]></AdTitle><Impression>http://sample.com</Impression><Description>→˓<![CDATA[A sample VAST feed]]></Description><Creatives><Creative sequence=\"1\" id=\"1\→˓"><Linear><Duration>00:00:30</Duration><TrackingEvents /><VideoClicks><ClickThrough><!→˓[CDATA[http://sample.com/openrt btest]]></ClickThrough></VideoClicks><MediaFiles>→˓<MediaFile delivery=\"progressive\" bitrate=\"256\" width=\"640\" height=\"480\" type=\→˓"video/mp4\"><![CDATA[http://sample.com/video.mp4]]></MediaFile></MediaFiles></Linear>→˓</Creative></Creatives></InLine></Ad></VAST>",
"adomain":["example.com"
],"cid":"11","language":"en","ext":{
"advertiser_name":"Example. Inc"},"id":"1c3ff810-3623-4b04-8396-9e7ca071cb72","impid":"1","price":4.079077199308326
}],"seat":"1"
}]
}
7.4. Bid Response JSON Examples 100
CHAPTER8
BIDSWITCH DATA CENTRES
Table 1: BidSwitch Data CentresGeo Data Centre HostnameUS East GCE Berkeley County, South
Carolinaus-east.bidswitch.net
US West Amazon California us-west.bidswitch.net, for the IPrange, search for us-west-1 in the AWSlist
APAC GCE Northeastern Asia-Pacific apac-jp.bidswitch.netEurope AWS Frankfurt eu.bidswitch.net
8.1 IP Values
Google Cloud Engine (GCE) To find the actual range of IP Addresses, use the instructionson this page: Where can I find Compute Engine IP ranges?40, and see also Google CloudPlatform zones41.
Amazon Web Services (AWS) To find the actual IP range search for relevant region speci-fied above within each DC, e.g eu-central-1 in the following the list: https://ip-ranges.amazonaws.com/ip-ranges.json
40 https://cloud.google.com/compute/docs/faq#find_ip_range41 https://cloud.google.com/compute/docs/regions-zones/
101
CHAPTER9
ANOMALY DETECTION
BidSwitch processes massive volumes of data, and while doing so employs anomaly detection to spotdeviations from the norm when applied to domains, publishers, user agent data, and other metrics.These deviations are then investigated to try and ascertain if any fraud is involved in generatingthese anomalies, and if so, learn to spot whatever new tricks are being used. The process of ensuringhigher quality trading on the network, follows these three concepts.
Blocking Rules Basic rules that filter out the most obviously suspicious traffic based on factorsuch as the following:
• External Services: Sites with swinging traffic patterns are blocked, as this signals thattraffic is being pumped through bots. This is based on reliable external traffic analysisproviders such as similarweb.com42
• Mismatching Data: For example, if a user’s data differs between the bid request andimpression calls.
• No Publisher Information: All traffic with an empty publisher_ID field is blocked,see the pub-obj section for how to include this information. You can also check theBidSwitch Policies43.
• Sudden Spikes If a surge in activity is seen in one particular parameter, such as certainUUIDs (universally unique identifier) displaying very high frequency usage.
Expert Blacklisting This is an ongoing process that involves people investigating and developingsolutions to potential problems discovered on the network. Experts examine logs and data sets;then analyse these against expected results to identify bad actors, and if necessary blacklistthem.
The Anomaly Detection Engine This is a sophisticated tool built on machine learning tech-nology that processes the complete set of incoming bid logs. Every update to the AnomalyDetection Engine goes through an expert audit, and an extensive set of QA procedures.
42 https://www.similarweb.com/43 http://www.bidswitch.com/policies/
102
BidSwitch Protocol for Suppliers, Release 1.0
Every bid request is filtered through the Anomaly Detection Engine, which is synced in real-time against a database of prior records. All bids are confirmed as acceptable before the bidrequest is sent to a Buyer. If a request fails these criteria a No Bid Reason is returned to theSupplier, see the Supplier No Bid Reason (page 127) section. This means that pre-bid frauddetection is in place.
Table 1: Common Ad Fraud MethodsType DescriptionBots Software that runs automated tasks repetitively, at a much higher rate than
would be possible for a human alone. Usually designed to generate fake im-pressions or serve unseen ads in the background of a real users computer.This method can be difficult to detect and generally problematic because botscan be retargeted or even whitelisted as a real audience.
Ad Stacking While a user only sees one ad, the publisher may be serving multiple ads, or1x1 pixel ads simultaneously. These types of ads register as an impression butare never actually seen.
Spoof Sites Sites built mainly for the purpose of serving ads. Spoof sites are often part ofa larger network of sites created to avoid triggering suspicion around a singlesite collecting very large amounts of revenue.Spoof sites are becoming increasingly sophisticated and often include 1-2 layersof real content that could be considered worthy of real traffic.
Spoof Domain Domains created to replicate premium, well known sites. Advertisers can beduped into thinking they are buying high quality inventory from a recognizedsite when they are not. This can also impact publishers who will appear tohave more inventory than they do, decreasing their prices.
9.1 Benefits of Anomaly Detection
For BidSwitch
• A higher quality network is a more attractive place for Buyers and Suppliers to do business
• The size, scope, and historic nature of BidSwitch’s data across many Buyers and Suppliersallows us to detect irregularities other fraud vendors cannot, placing BidSwitch as a marketleader in fraud detection.
For Buyers
• Not buying low quality or fraudulent impressions
• Higher quality of bids received within QPS limits
9.1. Benefits of Anomaly Detection 103
BidSwitch Protocol for Suppliers, Release 1.0
For Suppliers
• Increased prices on real ads. With fraud in the system publishers will appear to have moreinventory than they do, decreasing their prices on real inventory.
• Suppliers can take actions to clean up fraud coming from their inventory using the informationsent in No Bid Responses, see the Supplier No Bid Reason (page 127) section.
9.1. Benefits of Anomaly Detection 104
CHAPTER 10
API AUTHORIZATION
To connect to BidSwitch using the API, use the following steps.
• Create an API user in your myBidSwitch UI account.
• Using this user’s credentials, get your API token by making a POST request to the BidSwitchauthorization endpoint.
10.1 Creating an API User
To create a user profile that can receive API Tokens, use the following steps:
1. From the BidSwitch UI, select Users → Add User
2. From the User Role dropdown menu, select API Account.
10.2 Getting an API Auth Token
To get your API token, make a HTTP POST request to the following URL. The response will containyour access token.
https://uauth.iponweb.com/oauth2/token/
The POST request must contain the following fields
grant_type=passwordscope=service_id=api.bidswitch.comusername=<USERNAME> <!-- Your BidSwitch UI login -->password=<PASSWORD> <!-- Your Bidswitch UI password -->
105
BidSwitch Protocol for Suppliers, Release 1.0
Authorization Response
{"token_type": "Bearer","scope": "service_id=api.bidswitch.com","access_token": "<your token>","expires_in": 3600
}
Equivalent request via curl command:
$ curl --request POST --data "grant_type=password" --data "username=<username>" --data→˓"password=<password>" \
--data "scope=service_id=api.bidswitch.com" https://uauth.iponweb.com/oauth2/→˓token/
10.2. Getting an API Auth Token 106
CHAPTER 11
DISCREPANCY REPORTING
The Discrepancy Reporting API is used to upload a daily report about the previous day’s activityso that differences between the numbers reported by BidSwitch and those of the reporting Buyer orSupplier can be monitored. Use the information in the following sections to set up your discrepancymonitoring with BidSwitch.
• Buyer Discrepancy Reporting API
• Supplier Discrepancy Reporting API (page 114)
11.1 Disputing a Discrepancy
The attached PDF outlines the Discrepancy Resolution44 process.
44 https://docs.bidswitch.com/_static/discrepancy-reporting.pdf
107
CHAPTER 12
GLOSSARY
Addressable TV While addressable TV is technically a form of Programmatic TV , its household-level and real-time targeting are major distinguishing factors. Advertisers can buy audiencesinstead of programs, similar to the programmatic display and video buying processes utilizedon desktop and mobile devices.
Auto-Deal A bid request routed directly to a Buyer by a Supplier as part of a private deal rela-tionship, see the Setting up Auto-Deals45 section for more details.
BidStream This refers to all of the bid requests flowing through the system. Within BidSwitch,Buyers can configure their BidStream settings so that they focus on the types of bid requeststhey want to receive.
Broadcast Deal
Non-exclusive deal A bid request that is sent to all connected partners.
CPM (Cost-per-thousand) Media term describing the cost of 1,000 impressions.
Creative The media asset associated with an ad, such as an image or video file.
DAAST Digital Audio Ad Serving Template
Data Centre A data centre is a facility used to house computer systems and associated compo-nents, see the BidSwitch Data Centres (page 101) for a list of ours.
Day-part
Day-parting Day-parting means splitting the day into prime and non-prime time slots. The actualtimes vary depending on the Supplier and inventory type.
Deal ID The ID assigned to a programmatic ad transaction used by both the Buyer and Supplierto transact on prearranged terms, see the Private Marketplaces & Deal IDs46 section.
45 https://protocol.bidswitch.com/support/private-deals.html#auto-deals46 https://protocol.bidswitch.com/support/private-deals.html#pmp-deals
108
BidSwitch Protocol for Suppliers, Release 1.0
DOOH Digital out-of-home advertising or out-of-home media is advertising that reaches the con-sumers while they are outside their homes, for example, digital billboard displays, bus shelters,or telephone booth advertising.
Exclusive Deal
Deal Seats The seats (Buyers) allowed to bid on a bid request, as part of an Exclusive Deal.
Geotargeting
Geographic Targeting A method that enables advertisers to show an ad specifically to visitorsbased on zip code, area code, city, DMA, state, and/or country derived from user-declaredregistration information or inference-based mechanism.
Impression This is a single display of an online ad (creative) to a user’s web-enabled device.Each time an advertisement loads into a user’s screen, the ad server may count that as oneimpression. For more information on how impressions are tracked, see the Impression Deliveryand Tracking47 section.
Linear Television The traditional broadcast system in which a viewer watches a scheduled TVprogramme at the time it’s broadcast, and on the channel it’s originally presented on.
Nonlinear Television A non-traditional means of viewing TV content that enables “time-shifting”(not watching during the scheduled broadcast) using streaming, DVR, video-on-demand, over-the-top (OTT) or mobile TV technology.
Over-The-Top (OTT) The delivery of TV content via the Internet. Users are not required tosubscribe to a traditional cable or satellite providers to watch TV programmes. Devices piggyback on an existing network.
Private Deal
PMP A Private Marketplace deal in which the Buyer and Supplier arrange a one-to-one deal. Seethe Private Marketplaces & Deal IDs48 section for details.
Programmatic TV The use of Set-Top-Box data to inform the purchase process.
QPS Queries Per Second (QPS), see the QPS Overview (page 112) section for details.
SmartSwitch SmartSwitch optimises a Buyer‘s bidstream by analyzing bid request parameters,see the SmartSwitch Overview (page 110) section for details.
User Group Used to categorise users based on their perceived value to a Buyer, for more infor-mation see the smart-switch section.
User Syncing The process of matching Supplier cookie IDs with their matching Buyer cookie IDs,or vice versa. See the following sections for more details:
• Supplier User Matching (page 129) | Supplier First-Party User-Matching (page 135)
• user-match
VAST Video Ad Serving Template
47 https://protocol.bidswitch.com/support/imp-tracking-markup-delivery.html#imp-track-deliver48 https://protocol.bidswitch.com/support/private-deals.html#pmp-deals
109
CHAPTER 13
SMARTSWITCH OVERVIEW
SmartSwitch optimises a Buyer’s BidStream by analyzing bid request parameters such as Country,Device, Native, and others. Using these parameters and overlaying the data on impressions thatwere won/bid on, SmartSwitch is able to detect a Buyer’s specific buying pattern and optimisethe type of bidstream traffic it receives. For more information on the parameters used, see thebsw_proto section.
SmartSwitch also uses u-Predict models to estimate the probability of a bid request sent to a Buyerreceiving a winning bid. To learn more, see the u-Predict site49.
By combining the traffic that matches both criteria: desired traffic with higher win probability, aBuyer receives a much higher quality of traffic as defined by their own buying preferences.
• SmartSwitch Traffic (page 110)
• SmartSwitch and QPS (page 111)
– Buyer Benefits (page 111)
– Supplier Benefits (page 112)
• QPS Overview (page 112)
13.1 SmartSwitch Traffic
SmartSwitch sends the traffic that is most valuable to a Buyer, and that can be broken down intothe following groups.
• High Quality: Traffic that the Buyer bids on and wins most often.
• Low Quality: Traffic that the Buyer does not consider well priced, and for which it has alow win rate. A segment of traffic that is considered low quality is sent to verify SmartSwitchassumptions.
49 http://www.iponweb.com/core-framework/u-predict/
110
BidSwitch Protocol for Suppliers, Release 1.0
13.2 SmartSwitch and QPS
Listening to the the full BidSwitch bidstream would overwhelm most Buyers and result in over-loading a Buyer’s servers. As well as incurring increased costs just to be able to listen to moretraffic, without SmartSwitch Buyers would also listen to a lot more random traffic thus reducingthe quality.
The goal of SmartSwitch is to ensure that the best bids reach a Buyer within its QPS settings. Formore information about QPS, see the QPS Overview (page 112) section. Use the following tableand charts to understand the benefits of SmartSwitch.
13.2.1 SmartSwitch Buyer Benefits
Table 1: SmartSwitch Features and BenefitsSmartSwitch Disabled SmartSwitch EnabledRandom inventory is sent to the Buyer based ona subset of the total bidstream
Optimised inventory is sent to the Buyer, whichclosely aligns with their buying pattern
Lower relative levels of desired inventory avail-able to the Buyer versus the amount of trafficlistened to
Increased levels of desired inventory sent to theBuyer within their listening capacity
Lower bid/win ratio due to inventory not match-ing the Buyer’s bidding parameters as closely aspossible
Higher bid/win ratio because traffic matches theBuyer’s bidding strategy
Lower Buyer ROI on servers and other infras-tructure costs
Better ROI due to increased efficiency of infras-tructure usageMachine learning quickly responds to anychanges in a Buyer’s buying pattern, and re-aligns bids sent to match the Buyers wishesAny new inventory will be immediately routedto a Buyer if considered optimal
13.2. SmartSwitch and QPS 111
BidSwitch Protocol for Suppliers, Release 1.0
13.2.2 SmartSwitch Supplier Benefits
• Routes traffic to Buyers most interested in the inventory type you’re selling.
• Increases the amount of interested Buyers potentially bidding on each impression, and withan increased number of bidders, theoretically a higher clearing price.
• Screens all Bid Requests and returns a No Bid Reason should some traffic be flagged aspotentially fraudulent, enabling Suppliers to clean up their network of possible bad actors, seethe Supplier No Bid Reason (page 127) and Anomaly Detection (page 102) sections for moredetails.
13.3 QPS Overview
QPS (Queries Per second) in BidSwitch refers to the maximum absolute limit placed on trafficreceived from a Supplier or sent to a Buyer per data centre.
Note: The QPS settings do not set the actual amount of traffic that BidSwitch sends to a Buyer.It is the maximum traffic that a Buyer could receive, and BidSwitch will not send more than themaximum QPS value.
Traffic Composition Buyers receive two types of traffic from BidSwitch: biddable traffic andlearning traffic.
The learning traffic is sent to detect changes in the Buyer’s buying preferences. If a Buyerstarts buying more from a specific traffic segment, then BidSwitch sends more traffic fromthat segment. This also works vice-versa, if a Buyer stops buying from a particular traffic
13.3. QPS Overview 112
BidSwitch Protocol for Suppliers, Release 1.0
segment, BidSwitch sends less traffic of that type. For more detailed information about traffictypes, see the SmartSwitch Overview (page 110) section.
Influencing Traffic Volumes The real influence on traffic volumes sent to a Buyer is the amountand type of traffic that the Buyer buys. The more traffic that a Buyer buys in a particularsegment, the more of that traffic will be sent to focus bidding on what is desired, see theSmartSwitch Overview (page 110) section for more information.
Important: It is highly recommended that you set the maximum QPS value in accordance withthe real capacity of your servers. Otherwise, if you start buying in large volumes, BidSwitch willstart sending the maximum amount of QPS which could overload your servers.
Further Reading You can find a number of case studies and FAQs about SmartSwitch in theSmartSwitch PDFs section.
13.3. QPS Overview 113
CHAPTER 14
DISCREPANCY API FOR SUPPLIERS
The Discrepancy Reporting API is used to upload a daily report about the previous day’s activityso that differences between the numbers reported by BidSwitch and the reporting Supplier can bemonitored. Use the information in the following sections to set up your discrepancy monitoringwith BidSwitch.
• Process Overview (page 114)
• Getting API Credentials (page 115)
• Uploading a Discrepancy Report (page 116)
• Uploading Script (page 117)
• Upload Report Format (page 117)
• Example Reports (page 118)
• Upload Response (page 125)
14.1 Process Overview
1. Get your API Access Token. This requires creating an API user in the myBidSwitch UI, seethe Getting API Credentials (page 115) section for details.
2. Using this Token, make a HTTP POST request to the BidSwitch discrepancy endpoint. Thepost request should contain your platform type and partner ID in the URL, and be in JSON.See the Uploading a Discrepancy Report (page 116) section for details.
Note:
• If you upload several reports during one day, only the last one uploaded is going to be pro-cessed. So if you need to do this, use the Several Days report format.
• An Uploading Script (page 117) is available.
114
BidSwitch Protocol for Suppliers, Release 1.0
14.2 Getting API Credentials
To get access credentials for the Discrepancy Reporting API, you need to create an API UserAccount in the myBidSwitch UI, using the following information.
14.2.1 Creating an API User
To create a user profile that can receive API Tokens, use the following steps:
1. From the BidSwitch UI, select Users → Add User
2. From the User Role dropdown menu, select API Account.
14.2.2 Getting an API Auth Token
To get your API token, make a HTTP POST request to the following URL. The response will containyour access token.
https://uauth.iponweb.com/oauth2/token/
The POST request must contain the following fields
grant_type=passwordscope=service_id=api.bidswitch.comusername=<USERNAME> <!-- Your BidSwitch UI login -->password=<PASSWORD> <!-- Your Bidswitch UI password -->
Authorization Response
{"token_type": "Bearer","scope": "service_id=api.bidswitch.com","access_token": "<your token>","expires_in": 3600
}
Equivalent request via curl command:
$ curl --request POST --data "grant_type=password" --data "username=<username>" --data→˓"password=<password>" \
--data "scope=service_id=api.bidswitch.com" https://uauth.iponweb.com/oauth2/→˓token/
14.2. Getting API Credentials 115
BidSwitch Protocol for Suppliers, Release 1.0
Note: API Authorization using https://api.bidswitch.com/discrepancy-check/v1.0/loginis deprecated. Updated authorization steps are described in the API Authorization (page 105)section. The Uploading Script (page 117) is updated accordingly.
14.3 Uploading a Discrepancy Report
To upload your discrepancy report, use the following information.
• Make a HTTP POST request to the following appropriate link
• Specify the endpoint using only lowercase
• Ensure you include the HTTP headers with the required credentials and information
<!-- Supplier Endpoint All Lowercase -->https://api.bidswitch.com/discrepancy-check/v1.0/ssp/<ssp-name>/upload-report/
Report Upload HTTP Headers
'Authorization':'Bearer <your-token>''Accept':'application/json''Content-Type':'application/json'
Example of uploading by curl:
# Syntax$ curl -H "Accept:application/json" -H 'Authorization:Bearer <Your token here>' \
-H 'Content-Type:application/json' -d @report.json \https://api.bidswitch.com/discrepancy-check/v1.0/ssp/<'ssp-name'>/upload-report/
# Supplier Example$ curl -H "Accept:application/json" -H 'Authorization:Bearer CI6IkpXVCJ9.→˓eyJhdWQiOiJwdWJsaWNfY2xpZW50IiwiaXNzIjoidWF1dGgiLCJqdGkiOiJORlhvblRRSyIsImtsc2RmYXNkZmthZG1mbDthc2RuZmFzaztkamZuYXN→˓' \
-H 'Content-Type:application/json' -d @report.json \https://api.bidswitch.com/discrepancy-check/v1.0/ssp/abc/upload-report/
Example Response:
{"status": "success","handled": [["2016-08-06", "2016-08-14", "2016-08-07"]]
}
14.3. Uploading a Discrepancy Report 116
BidSwitch Protocol for Suppliers, Release 1.0
14.4 Uploading Script
Using the Uploading Script
Pass the following arguments when calling the script from the command-line. You can downloadthe Uploading Script here.
• platform_type: ssp
• platform_name: SSP Name
• data.json: the JSON report
# Syntax Example$ upload.py -u <username>:<password> -p <platform_type>:<platform_name> -d <data.json>
# Supplier Upload Example$ python upload.py -u ssp_dummy:123456 -p ssp:adrtbdummy -d ./yesterday.json
14.5 Upload Report Format
The post request requires the following data in JSON. Usually you need to upload the full reportfrom the previous day, which contains the complete data.
14.5.1 Reports
Table 1: Reports ObjectField Type Validator Descriptionreports Array of ob-
jectsRequired Array of reports. The reports are created using the
report object format, see the Report Object (page 118)for more details.
14.4. Uploading Script 117
BidSwitch Protocol for Suppliers, Release 1.0
14.5.2 Report Object
Table 2: Report Object ParametersField Type Validator Descriptionseat String Optional
(SuppliersOnly)
When a Supplier wants to check for discrepancies witha particular Buyer, they can specify the Buyer nameusing this field.Note: This field is only used when uploading a Sup-plier report, see the Supplier Reports (page 123) ex-ample.
timezone String Required Sets the timezone of the report, the valid options beingthose in the pytz.all_timezones list.
currency String Required Sets the currency used in the report, the valid optionsbeing one of the following: [ 'USD', 'EUR', 'JPY'].
data Array of ob-jects
Required Specifies the date to which the report figures refer, andthe report data values. See the Report Data ValuesObject (page 118) for more details.
• Keys: date using the following format"%Y-%m-%d"
• Values: list of the Report Data Values Object(page 118)
14.5.3 Report Data Values Object
Table 3: Report Data Values ObjectField Type Validator Descriptionhour String Optional Value is from range 00-23. If this field is absent, it is
assumed that the report is for the full day.imps Integer Required The total number of impressions.cost Float Required The final cost for delivered impressions.bids Integer Optional. Field for Supplier reports. The total number of bid
requests sent by the Supplier to BidSwitch. This in-cludes all bid types such as requests ending in an erroror timeout, no bids, yes bids, and incorrect responses.
timeouts Integer Optional. Field for Supplier reports. The number of bid requestsending in a timeout.
14.6 Example Reports
Zero Reports (page 119) | Hourly Report (page 119) | Supplier Reports (page 123) | Minimal report(page 124) | Several days (page 124)
14.6. Example Reports 118
BidSwitch Protocol for Suppliers, Release 1.0
14.6.1 Zero Reports
It must contain {"imps":0,"cost":0}, which means there was no trading. If you don’t have datafor reporting just skip sending reports for that day.
{"reports":[
{"data":{
"2016-08-05":[{
"imps":0,"cost":0
}]
},"currency":"USD","timezone":"UTC"
}]
}
14.6.2 Hourly Report
This is considered the best practice reporting format, which splits reports by hours and containsbids, timeouts, imps, and cost.
Note: "hour" is represented as a string and must contain 2 digits.
{"reports" : [
{"timezone" : "UTC","currency" : "USD","data" : {
"2016-08-05" : [{
"timeouts": 26887,"imps": 895,"bids": 419746,"cost": 16.6,"hour": "00"
},{
"timeouts": 292712,"imps": 1442,"bids": 496269,"cost": 32.59,"hour": "01"
(continues on next page)
14.6. Example Reports 119
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
},{
"timeouts": 523600,"imps": 736,"bids": 264686,"cost": 8.74,"hour": "02"
},{
"timeouts": 431437,"imps": 299,"bids": 346682,"cost": 16.93,"hour": "03"
},{
"timeouts": 207841,"imps": 778,"bids": 104816,"cost": 10.71,"hour": "04"
},{
"timeouts": 510346,"imps": 398,"bids": 538113,"cost": 41.47,"hour": "05"
},{
"timeouts": 475965,"imps": 2320,"bids": 259689,"cost": 40.1,"hour": "06"
},{
"timeouts": 226502,"imps": 2242,"bids": 522407,"cost": 8.9,"hour": "07"
},{
"timeouts": 117024,"imps": 464,"bids": 91400,"cost": 28.71,"hour": "08"
},{
(continues on next page)
14.6. Example Reports 120
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"timeouts": 434858,"imps": 1142,"bids": 179587,"cost": 32.67,"hour": "09"
},{
"timeouts": 43211,"imps": 2223,"bids": 276447,"cost": 16.61,"hour": "10"
},{
"timeouts": 310415,"imps": 1649,"bids": 51621,"cost": 12.66,"hour": "11"
},{
"timeouts": 430663,"imps": 249,"bids": 474692,"cost": 36.81,"hour": "12"
},{
"timeouts": 310470,"imps": 774,"bids": 222399,"cost": 1.24,"hour": "13"
},{
"timeouts": 427396,"imps": 1706,"bids": 144780,"cost": 4.2,"hour": "14"
},{
"timeouts": 290821,"imps": 1492,"bids": 121281,"cost": 37.24,"hour": "15"
},{
"timeouts": 45520,"imps": 1209,
(continues on next page)
14.6. Example Reports 121
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"bids": 3909,"cost": 16.51,"hour": "16"
},{
"timeouts": 232909,"imps": 2184,"bids": 55060,"cost": 43.22,"hour": "17"
},{
"timeouts": 504859,"imps": 1145,"bids": 221379,"cost": 41.09,"hour": "18"
},{
"timeouts": 327505,"imps": 11,"bids": 138869,"cost": 37.56,"hour": "19"
},{
"timeouts": 512344,"imps": 1360,"bids": 492131,"cost": 30.65,"hour": "20"
},{
"timeouts": 315876,"imps": 552,"bids": 461330,"cost": 32.76,"hour": "21"
},{
"timeouts": 258491,"imps": 722,"bids": 341752,"cost": 8.0,"hour": "22"
},{
"timeouts": 399477,"imps": 2263,"bids": 515451,"cost": 32.97,
(continues on next page)
14.6. Example Reports 122
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"hour": "23"}
]}
}]
}
14.6.3 Supplier Reports
You may use the "seat" field to split your report by Buyer.
{"reports":[
{"data":{
"2015-11-27":[{
"timeouts":24450,"bids":1943830,"hour":"00","imps":83922,"cost":3234
},{
"hour":"23","imps":83922,"cost":3234,"timeouts":24450,"bids":1943830
}]
},"currency":"JPY","timezone":"US/Pacific","seat":"123"
},{
"currency":"JPY","data":{
"2015-11-27":[{
"cost":3234,"imps":83922,"hour":"00","bids":1943830,"timeouts":24450
},{
"timeouts":24450,(continues on next page)
14.6. Example Reports 123
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
"bids":1943830,"hour":"23","imps":83922,"cost":3234
}]
},"timezone":"EST","seat":"456"
}]
}
14.6.4 Minimal report
{"reports":[
{"timezone":"UTC","currency":"USD","data":{
"2015-11-26":[{
"imps":83922,"cost":3234
}]
}}
]}
14.6.5 Several days
If you missed uploading reports for several days, you can upload several days worth of reports atonce.
{"reports":[
{"timezone":"UTC","currency":"USD","data":{
"2015-11-26":[{
"imps":83922,"cost":3234.22
}(continues on next page)
14.6. Example Reports 124
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
],"2015-11-27":[
{"imps":93922,"cost":823.42
}],"2015-11-28":[
{"imps":92,"cost":6.223
}]
}}
]}
14.7 Upload Response
If you upload successfully, you will receive a 200 OK response with a dated results list as shown inthe following example. If your upload is in the wrong format, you will get an error status.
Successful Response
{"handled":[
["123 2015-11-27","123 2015-11-26"
],[
"456 2015-11-26"]
],"status":"success"
}
Error Response
{"errors":[
["<index of report>","<error text>"
(continues on next page)
14.7. Upload Response 125
BidSwitch Protocol for Suppliers, Release 1.0
(continued from previous page)
]],"status":"error"
}
Other Possible Responses
You may also receive one of the following HTTP status codes:
• 401 Unauthorized: If you don’t have access to the Buyer or Supplier details, or you don’thave the permission to upload, ensure that you have configured your account to use an APIToken. You need an API account to upload reports.
• 404 Not Found: If the <ssp-name> is not found in our system.
• 500 Internal Server Error: If another unexpected error occurred.
14.7. Upload Response 126
CHAPTER 15
SUPPLIER NO BID REASON
Suppliers can receive two kinds of No Bid Responses (NBRs) from BidSwitch.
• A Buyer No Bid Response, which is usually an empty 204 response indicates that only oneparticular Buyer did not bid on the offer. See the no-bid-resp section for an example of thiskind of response.
• A BidSwitch No Bid Reason, which contains the nbr field indicates that the particular BidRequest was not forwarded to any Buyers due to it failing impression anomaly checks.
• The No Bid Reasons sent by BidSwitch conform with those outlined in the Open RTB Spec-ification50, sections 5.22 and 7.1.
A BidSwitch No Bid Reason can occur for a number of different reasons, including suspected fraud-ulent activity like bot traffic or traffic coming from a known bad actor IP, site/publisher blocking,or invalid request elements. BidSwitch will continue to add more nuanced NBRs as time goes on.
By returning this information to Suppliers, it allows them to address potential problems in theirsystem. If a No Bid Reason is triggered, BidSwitch responds with a HTTP 200 response and oneof the following codes in the nbr field depending on what has been identified as the problem. Formore information you can also download the No Bid Reason Fact Sheet.
50 https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-4-FINAL.pdf
127
BidSwitch Protocol for Suppliers, Release 1.0
Table 1: BidSwitch No Bid ReasonsCode OpenRTB Descrip-
tionBidSwitch Usage
0 Unknown Error Not used1 Technical Error Not used2 Invalid request Bid requests that are treated as bad by BidSwitch, except for
in-app requests with no IFA, which use #83 Known Web Spider Not used4 Suspected non-
human trafficThe bid request was identified to be from a bot or other non-human activity
5 Cloud, Data centre,or Proxy IP
The bid request was blocked because of its IP
6 Unsupported Device Not used7 Blocked Publisher or
SiteThe Publisher ID, Site ID, Site Domain, App Domain, AppBundle, or App Name have been blocked in BidSwitch
8 Unmatched User In-app bid requests without an IFA. This does not apply tocookie-less website bid requests.
15.1 Example Response
{"id":"1234567890","seatbid":[
],"nbr":4
}
15.2 Enabling No Bid Reason
• To receive a No Bid Reason, you need to support the nbr field in bid responses.
• To enable No Bid Reasons on your BidSwitch account, contact [email protected].
15.1. Example Response 128
CHAPTER 16
SUPPLIER USER MATCHING
As the Supplier and BidSwitch sit between the end-user and the Buyer, user matching is importantas it allows a Buyer to know the potential value of a user, and thus make calculated decisions toserve the most appropriate advertisements. Additionally, it can increase CPM and media spend toSuppliers . It is therefore in both parties best interests to sync their cookies appropriately. Use theinformation int he following sections to get the most out of user matching.
• Bid Request Fields (page 129)
• Supplier User Matching Flow (page 130)
• Supplier Initiated User Sync (page 131)
• Cookie Syncing Best Practices (page 132)
• BidSwitch Initiated User Sync (page 133)
16.1 Bid Request Fields
User matching, or cookie syncing, is the process of matching an Supplier cookie ID to a Buyer cookieID. BidSwitch has an integrated user matching functionality to facilitate this between Buyers andSuppliers .
When receiving a bid request from a Supplier, BidSwitch expects both the BidSwitch User ID andSupplier User ID to be sent in the buyeruid and id fields of the user-obj.
129
BidSwitch Protocol for Suppliers, Release 1.0
Table 1: Supplier Buyer User MatchingSupplier to BidSwitch Bid Request BidSwitch to Buyer Bid Request
{"user":{
"id":"ssp-cookie-1234","buyeruid":"bsw-cookie-54321",}
}
{"user":{
"id":"bsw-cookie-54321","buyeruid":"DSP-cookie-5678",
}}
16.2 Supplier User Matching Flow
Process
1. The user lands on a page, which runs a Supplier tag
2. The Supplier tag runs on the page and drops a cookie to the user browser (e.g.SSP_cookie_1234)
3. The Supplier tag redirects to a BidSwitch cookie sync pixel
4. BidSwitch drops a cookie to the users browser (e.g. BSW_cookie_54321)
5. BidSwitch redirects to a randomly selected Buyer pixel from amongst the Buy-ers listening to the Supplier’s traffic
16.2. Supplier User Matching Flow 130
BidSwitch Protocol for Suppliers, Release 1.0
6. The Buyer drops its cookie (e.g. DSP_cookie_9876) and redirects to BidSwitchwith its cookie
7. BidSwitch stores the Buyer cookie ID (DSP_cookie_9876)
8. The Supplier receives the BidSwitch cookie ID (BSW_cookie_54321)
9. The Supplier matches the BidSwitch cookie ID with its cookie ID, and storesthem in their database.
Note: Please note that the majority of Suppliers will store the cookie syncing in the user’s browsercache. But for clarification we use the database in the diagram.
When all parties have synced their cookies, bid requests from the Supplier to BidSwitch will containthe BidSwitch cookie ID. BidSwitch will then match and retrieve the Buyer cookie ID from theBidSwitch database and send it to the correct Buyer. This enables the Buyer to use their cookieID and bid intelligently.
16.3 Supplier Initiated User Sync
Suppliers should sync users using the BidSwitch user sync URL. Once synced, BidSwitch redirectsthe user to the Supplier’s sync URL, this endpoint is completely up to the Supplier and you cancheck what link BidSwitch is syncing with on the UI Settings page. This URL can also contain anumber of macros, which BidSwitch will fill with values if it is applicable and has those values, e.g.{CCPA}, see the Supported Sync Macros (page 133) section for more details.
Supplier Initiated Cookie Sync Endpoint
## Syntaxhttp://x.bidswitch.net/sync?ssp=${ SSP_NAME} &user_id=${ SSP_UID}
## Examplehttp://x.bidswitch.net/sync?ssp=sspname&user_id=user12345
## User sync with GDPR consenthttp://x.bidswitch.net/sync?ssp=sspname&user_id=1235AB&gdpr=1&gdpr_→˓consent=Y29uc2VudCBkYXRh
## User sync with US Privacy consent - HTTPShttps://x.bidswitch.net/sync?ssp=sspname&user_id=1235ABC&expires=30&us_privacy=1YYN
Note: Fields marked with asterisk (*) are optional.
16.3. Supplier Initiated User Sync 131
BidSwitch Protocol for Suppliers, Release 1.0
Table 2: HTTP Request ParametersValue Type Descriptionssp_id string The ID assigned to the Supplier by BidSwitch, for example,
sspname.gdpr* string Indicates if GDPR applies to this sync. GDPR=0 does not apply
GDPR=1 applies. If this field is not supplied, the callee shouldperform a geoIP lookup as GDPR applies for EU IP addresses.
gdpr_pd* int Indicates whether generic URL parameters contain personaldata, 0 for no, 1 indicates personal data
gdpr_consent* string A URL-safe base64-encoded GDPR consent string. Only mean-ingful if gdpr=1. Encodes the purposes to which the user con-sented and the vendors to whom the user gave that consent, asobtained from the CMP JS API or OpenRTB. BidSwitch sup-ports the v1.1 and v2.0 consent string formats. For each versionthe content of this macro differ slightly
• v1.1 gdpr_consent is filled, which will match the userconsent string
• v2.0 gdpr_consent_GVL-ID is filled, which will match theuser consent string and append the Global Vendor ListID for the vendor expecting the call.
Note: If BidSwitch does not have consent to process this userit will not sync the user. Only meaningful if gdpr=1.
us_privacy* string Passes the CCPA compliant US Privacy string that indicateswhether the user has “opted-in” or “opted-out” of the sale oftheir data, e.g. us_privacy=1NNY. For more information, seethe ccpa section.
user_id* string The Supplier user ID. This is the value normally passed in theuser.id field in OpenRTB bid requests.Note: This parameter is highly recommended for browsers thatdo not support 3rd party cookies, e.g. Safari and IOS_App
16.4 Cookie Syncing Best Practices
While it is also the responsibility of Buyers to play an active part in the cookie syncing process,BidSwitch strongly recommends the following Supplier practices to maximise ROI.
• If there is any cookie logic, ensure that BidSwitch is set with a high priority.
• Aim to cookie sync user data with BidSwitch once per day.
• Set the BidSwitch cookie expiration date to more than 30 days. Ideally closer to 365 days.This will prevent BidSwitch from storing a lot of expired user IDs and increase the sync ratewith the Supplier.
16.4. Cookie Syncing Best Practices 132
BidSwitch Protocol for Suppliers, Release 1.0
16.5 BidSwitch Initiated User Sync
When BidSwitch initiates a user sync with a Supplier, the process flows in the following manner.
1. The user lands on a page, which runs a Buyer tag.
2. Running this Buyer tag drops a cookie to the user browser e.g. DSP_cookie_9876, whichredirects to BidSwitch.
3. BidSwitch stores the Buyer cookie ID, e.g. DSP_cookie_9876.
4. BidSwitch then redirects to a sync pixel belonging to a Supplier connected to the Buyer.
5. The Supplier receives the BidSwitch cookie ID for this user, e.g. BSW_cookie_54321.
6. The Supplier matches the BidSwitch cookie ID with its cookie ID, and stores them in theirdatabase.
16.6 Supported Sync Macros
When you provide your sync URL to BidSwitch, it can contain the following macros that BidSwitchwill replace with values if it has them, e.g. ${US_PRIVACY} will be replaced by the CCPA string forthat user, e.g. 1NNY
16.5. BidSwitch Initiated User Sync 133
BidSwitch Protocol for Suppliers, Release 1.0
Listing 1: Supplier Sync URL examples with macros
example-ssp.com/sync?userid=${ UUID} &gdpr=${ GDPR} &gdpr_consent=${ GDPR_CONSENT} &us_→˓privacy=${ US_PRIVACY}
Table 3: Sync URL macrosValue Description${UUID} Returns the User ID for example abc-456. The User ID can be
a maximum of 50 characters.${GDPR} Indicates if GDPR applies to this sync. GDPR=0 does not apply
GDPR=1 applies.${GDPR_CONSENT} Returns the GDPR consent string associated with the user.
BidSwitch supports the v1.1 and v2.0 consent string formats.For each version the format of this macro differ slightly
• v1.1 ${gdpr_consent} is filled, which will match the userconsent string
• v2.0 ${gdpr_consent_GVL-ID} is filled, which will matchthe user consent string. See the gdpr section for moredetails.
Note: If BidSwitch does not have consent to process this userit will not sync the user. Only meaningful if gdpr=1.
${GDPR_PD} Indicates whether generic URL parameters contain personaldata, 0 for no, 1 indicates personal data
${US_PRIVACY} Passes the CCPA compliant US Privacy string that indicateswhether the user has “opted-in” or “opted-out” of the sale oftheir data, e.g. 1NNY. For more information, see the ccpa sec-tion.
16.6. Supported Sync Macros 134
CHAPTER 17
SUPPLIER FIRST-PARTY USER-MATCHING
In the standard BidSwitch supplier user matching scenario, when sending bid requests to Buyers,BidSwitch uses the cookie ID stored in the browser cookie to map the Buyer user IDs for this user.
One of the limitations of this process is that certain platforms, such as Safari, do not support3rd party user syncing, which prevents BidSwitch from dropping a cookie to a user’s browser. Toimprove user syncing on such platforms, BidSwitch offers two solutions.
• First-Party Cookie Syncing (page 135)
• Direct-like User Syncing (page 136)
Note: Suppliers only need to implement one of these options, not both.
17.1 First-Party Cookie Syncing
First-party cookie syncing means that suppliers pass their cookie syncing events to BidSwitch whilethey have access to the browser as a first party, thereby matching users through events such asclicks for those receiving the supplier’s cookie for the first time.
To do this, direct the user’s browser to the following BidSwitch endpoint, where ${landing_page}is the URL-encoded URL of the page the user will be redirected to.
# http endpointhttp://x.bidswitch.net/clk?lp=${ landing_page}
# https endpointhttps://x.bidswitch.net/clk?lp=${ landing_page}
# Example encoded URLhttps://x.bidswitch.net/clk?lp=https%3A%2F%2Fmy.site.com%3Fmypage.html
135
BidSwitch Protocol for Suppliers, Release 1.0
17.2 Direct-like User Syncing
Direct-like user syncing allows Buyers and suppliers to match their UUIDs directly, bypassing theBidSwitch User ID in the middle.
Once suppliers know the UUIDs used by their buying partners on BidSwitch, then this informationcan be included in the bid request to enable Buyers make better bid pricing decisions.
• When BidSwitch receives a supplier initiated sync request with a Buyer UUID, it analyses itand tries to drop a cookie to the user’s browser.
• If this fails, BidSwitch redirects the sync request to the Buyer, enabling the direct sync process,and returns the Buyer’s matching UUID to the Supplier.
• Once the supplier knows the matching Buyer UUIDs for their user IDs, they should includethis information in the bid request. BidSwitch then sends it to Buyers so they can make moreinformed bid pricing decisions.
For Suppliers to enable this feature, a number of changes need to be made to their integration withBidSwitch.
Note: If a supplier does not have a large pool of Buyer UUIDs to sync directly, in a limited 3rdparty cookie environment like Safari, then supporting this functionality will bring limited value.
17.2.1 URL Parameters
For suppliers to support this new functionality, they need to ensure that they support these addi-tional parameters in their sync endpoint URL.
• bsw_uuid : Sets the BidSwitch User ID. When using the direct user syncing method this fieldwill always be empty.
• dsp_uuid : Sets the Buyer’s User ID of the user being synced
• dsp_id : Sets the Buyer ID with whom the supplier is syncing
some.ssp.com/sync?bsw_uuid=${ UUID} &dsp_uuid=${ DSP_UUID} &dsp_id=${ DSP_ID}
Once these parameters are supported, suppliers should contact [email protected] to have thisactivated on their connection, and to have their user sync URL updated in their myBidSwitch UI.
17.2.2 Supplier Initiated Direct Syncing
Once these changes are complete, suppliers must include the user ID they wish to sync withBidSwitch in the user sync URL, as in the following example.
x.bidswitch.net/sync?ssp=somessp&user_id=XYZ
17.2. Direct-like User Syncing 136
BidSwitch Protocol for Suppliers, Release 1.0
BidSwitch will then sync with one of its connected Buyers and respond to the sync request withthe ${DSP_ID} and ${DSP_UUID} information. Sending this to the supplier’s user sync URL.
some.ssp.com/sync?bsw_uuid=&dsp_uuid=ABC&dsp_id=77
Suppliers should store this Buyer-related data so that they can forward it to BidSwitch during bidrequests.
Note: BidSwitch initiated user syncs work in the same manner and sync data to the SuppliersUser Sync URL.
17.2.3 Bid Request JSON Changes
BidSwitch expects the bid_request.ext.dsp_uuids field in the bid request JSON.
{"ext":{
"dsp_uuids":{"dsp1_id":"dsp1_uuid","dsp1_id":"dsp2_uuid",
}}
}
17.2.4 Example Bid Request With UUID Sync
If the Supplier does not have a match with BidSwitch for a certain user, then the user.buyeruidfield is left empty, and the direct syncing approach shall be used to sync the Buyer UUIDs. In thisscenario, the Supplier should enrich the bid request with the Buyer UUIDs for that user, using thefollowing examples.
Step 1
During syncing, BidSwitch will have returned the Buyer UUIDs to the user sync URL, as in thefollowing example.
some.ssp.com/sync?bsw_uuid=&dsp_uuid=XYZ&dsp_id=77
some.ssp.com/sync?bsw_uuid=&dsp_uuid=ABC&dsp_id=41
some.ssp.com/sync?bsw_uuid=&dsp_uuid=IKL&dsp_id=42
17.2. Direct-like User Syncing 137
BidSwitch Protocol for Suppliers, Release 1.0
Step 2
When sending the bid request to BidSwitch, the Supplier should include the UUIDs that matchtheir user in ext section. See lines 12-13 that specify the Supplier’s UUID, and lines 36-40 thatmatch this user directly to the given Buyers.
{"cur": [
"USD"],"device": {
"devicetype": 2,"language": "en","ua": "Mozilla\/5.0 (Windows NT 6.3; WOW64) AppleWebKit\/537.36 (KHTML, like Gecko)␣
→˓Chrome\/52.0.2743.116 Safari\/537.36","ip": "24.68.173.116"
},"at": 2,"user": {
"id": "53C0C0D66E6521B101749B59F00222A8"},"site": {
"publisher": {"id": "123"
},"page": "http:\/\/www.somepage.com\/","id": "123"
},"imp": [
{"banner": {
"api": [3,4,5
],"h": 90,"w": 728
},"id": "1"
}],"ext" : {
"dsp_uuids" : {"77" : "XYZ","42" : "IKL","41" : "ABC"
}},"id": "reqid"
}
17.2. Direct-like User Syncing 138
INDEX
AAddressable TV, 108Auto-Deal, 108
BBidStream, 108Broadcast Deal, 108
CCPM, 108Creative, 108
DDAAST, 108Data Centre, 108Day-part, 108Day-parting, 108Deal ID, 108Deal Seats, 109DOOH, 109
EExclusive Deal, 109
GGeographic Targeting, 109Geotargeting, 109
IImpression, 109
LLinear Television, 109
NNon-exclusive deal, 108
Nonlinear Television, 109
OOver-The-Top (OTT ), 109
PPMP, 109Private Deal, 109Programmatic TV, 109
QQPS, 109
SSS, 109
UUser Group, 109User Syncing, 109
VVAST, 109
139