This specification describes SSP (Supply Side Platform) integration with PPCmate DSP.
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.5).
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) |
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 |
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.5 available at https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf.
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
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 |
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.21 of OpenRTB API Specification Version 2.5 available at https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf.
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"}}
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.
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 PPCmate 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.