Tech Specification for SSP Integration with Platform Inc DSP

Contents

1. Intro

2. Requests to DSP

2.1. Object: BidRequest

2.2. Object: Imp

2.3. Object: Site

2.4. Object: Publisher

2.5. Object: App

2.6. Object: Device

2.7. Bid Request Example

2.8. DSP Bid Response Example

3. User Synchronization



1. Intro

This specification describes SSP (Sell Side Platform) integration with Platform Inc DSP (Demand Side Platform). The DSP UI is developed in accordance with OpentRTB 2.3/ Native 1.0 protocol.

2. Requests to DSP

A request to DSP should be made in JSON format and contain HTTP header Content-Type: application/json. The OpenRTB version is passed in the header of a bid request by parameter  x-openrtb-version (e.g, x-openrtb-version: 2.3).

2.1. Object: BidRequest

A bid request to DSP (BidRequest) include obligatory objects id, imp, at, cur, site, app, device, user.

Object Type Description
id string bid request unique ID
imp object array type of the requested impression (Banner, Video or Native)
at integer auction type (1 - first price, 2 - second price plus)
cur string array allowed currencies for this bid request
site object details about the publisher’s website
app object details about the publisher’s app
device object details about the user’s device where the impression will be delivered
user object details about the user of the device (advertising audience)

2.2. Object: Imp

This object describes a type of the impression. One request (BidRequest) can contain a few Imp objects if all ad positions are being sold on a specific page.

Parameter Type Description
id string impression ID for this bid request
bidfloor float minimum bid for this impression (CPM)
banner object impression is a banner ad opportunity
native object impression is a native ad opportunity
video object impression is a video ad opportunity

2.3. Object: Site

Object Site should be included in case an ad is to be displayed on a website (not in an app).

Parameter Type Description
id string site ID on the exchange
cat* string array IAB content category of the site
domain string domain of the site (e.g., www.example.com)
page string URL of the webpage where the ad will be displayed (e.g., www.example.com/1234.html)
publisher object details about the publisher of the website

* - non-obligatory parameter

The full list of site categories (field cat of site object) can be found in List 5.1 of OpenRTB API Specification Version 2.3.1 available at http://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf

2.4. Object: Publisher

This object describes the publisher of the media where an ad will be displayed. 

Parameter Type Description
id string publisher ID on the exchange
name string publisher name (may be aliased at the publisher’s request)
cat* string array IAB categories list representing publisher’s content
domain string highest level domain of the publisher (e.g., publisher.com)

* - non-obligatory parameter

2.5. Object: App

Object App should be included if an ad impression is made in a mobile app. 

Parameter Type Description
id string app ID on the exchange
name string app name (may be aliased at the publisher’s request)
bundle string application bundle or package name (e.g., com.foo.myapp), unique ID across exchanges

2.6. Object: Device

Object Device provides details about the device through which the user is interacting.

Parameter Type Description
ua string browser user agent
geo* object location of the device (assumed to be the user’s current location)
ip string IP address of the device
devicetype integer type of the device (e.g., phone/ tablet)
model string device model (e.g., iPhone)
os string device operating system (e.g., iOS)

* -  non-obligatory parameter

The full list of the device types (field devicetype of device object) can be found in List 5.17 of OpenRTB API Specification Version 2.3.1 available at http://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf .

2.7. Bid Request Example

{" id":="" "81ce30c53c16e6ede735f123ef6e32361bfc7b21", <="" p="">

"at": 1, "cur": [ "USD" ],

"imp": [{"id": "1", "bidfloor": 0.03,

"banner": {"h": 250, "w": 300, "pos": 0}}],

"site": {"id": "102856",

"cat": [ "IAB3-1" ],

"domain": "www.example.com",

"page": "http://www.example.com/1234.html ",

"publisher": {"id": "8053", "name": "example.com",

"cat": [ "IAB3-1" ],

"domain": "example.com"}},

"device": {"ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2",

"ip": "123.145.168.11"},

"user": {"id": "25816b39711f9b5acf3b90e313ed29e51665613f"}}

2.8. DSP Response Example

{"id": "123456789", "bidid": "abc1123", "cur": "USD",

"seatbid": [{"seat": "512",

"bid": [{"id": "1",

"impid": "102",

"price": 7.41,

"nurl": "http://adserver.com/winnotice?impid=102",

"iurl": "http://adserver.com/pathtosampleimage",

"adomain": [ "advertiserdomain.com" ],

"cat": ["IAB9-30"],

"cid": "campaign111",

"crid": "creative112",

"adm": "response as a string",

"attr": [ 1, 2, 3, 4, 5, 6, 7, 12 ]}]}]}


Field price shows the price of the bid (price for 1000 impressions). Field nurl displays the win notice URL that has to be called to notify about the bid win.

Example:

"nurl":"http://rtb.adx1.com/log?key=sspname-4feedfd9-a141-4a3c-b368-c41946de51ca&action=impression&price=${AUCTION_PRICE}"

${AUCTION_PRICE} - field with the final price of the win bid (win price) for 1000 impressions. It is substituted by the macro on the SSP side when nurl is called. 

3. User synchronization

One-sided matching initiated by SSP includes the following steps:

  • SSP inputs the calling code of the DSP URL for an every separate user ID alongside with the ad displayed on the webpage (sspname.rtb.adx1.com/users/sync, where sspname corresponds to name/ID of the SSP in Platform Inc. DSP),
  • DSP receives its user ID when calling this URL and SSP user ID by a parameter in the URL,
  • DSP saves this matching on its side.

Still need help? Contact Us Contact Us