OpenRTB Request
The Open RTB request for standard format is fully compliant with Open RTB 2.3 standards.
Bid Request Structure
- Sample Request
- Sample Response
| Attribute | Type | Description |
|---|---|---|
| id | string | Unique ID of the bid request, provided by the exchange. |
| imp | object | Unique ID of the bid request, provided by the exchange. |
| site | object | PN will send this for mobile websites. |
| app | object | PN will send this for apps only |
| device | object | Details via a Device object about the user’s device to which the impression will be delivered. |
| user | object | Details via a User object about the human user of the device; the advertising audience. |
| at | integer | Auction type, where 1 = First Price, 2 = Second Price Plus. PN conducts a second price auction. |
| tmax | integer | Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline. |
| wseat | array | Whitelist of buyer seats allowed to bid on this impression. Seat IDs must be communicated between bidders and the exchange a priori. Omission implies no seat restrictions. |
| allimps | integer; default 0 | Flag to indicate if Exchange can verify that the impressions offered 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. |
| cur | string array | Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. PN only allows bidding in USD |
| bcat | string array | Blocked advertiser categories using the IAB content categories. DSP need to respect bcat to align with PN publishers and exchange wide settings |
| badv | Block list of advertisers by their domains (e.g., “ford.com”). Typically designated by publishers |
Definition of the Impression Object
| Attribute | Type | Description |
|---|---|---|
| id | string; required | A unique identifier for this impression within the context of the bid request. |
| banner | object; required | A Banner object; Details below |
| bidfloor | float | Minimum bid for this impression expressed in CPM. |
| bidfloorcur | string; default “USD” | Currency specified using ISO-4217 alpha codes. Pubnative only support USD |
......
"imp": [
{
"id": "87d13330-0f03-4f30-9c75-6f2362c05893",
"banner": {
"w": 300,
"h": 250
},
"tagid": "1",
"bidfloor": 0.02,
"bidfloorcur": "USD"
}
],......
Definition of the Banner Object
| Attribute | Type | Description |
|---|---|---|
| w | integer; required | Width of the impression in pixels. If neither wmin nor wmax are specified, this value is an exact width measurement. Otherwise it is a preferred width. |
| h | integer; recommended | Height of the impression in pixels. If neither hmin nor hmax are specified, this value is an exact height measurement. Otherwise it is a preferred height |
| wmax | integer; optional | Maximum width of the impression in pixels. If included along with a w value, then w should be interpreted as a recommended or preferred width. |
| hmax | integer; optional | Maximum height of the impression in pixels If included along with a h value, then h should be interpreted as a recommended or preferred height. |
| wmin | integer; optional | Minimum width of the impression in pixels. |
| hmin | integer; optional | Minimum height of the impression in pixels. |
| id | string; optional | Unique identifier for the banner object. Recommended when Banner objects are used with a Video object to represent an array of companion ads. Values usually start at 1 and increase with each object; should be unique within an impression. |
| btype | integer array ; optional | Blocked banner ad types. |
| battr | integer array ; optional | Blocked creative attributes. |
| pos | integer ; optional | Ad position on screen. |
| mimes | string array ; optional | Content MIME types supported. Popular MIME types may include “application/x-shockwave-flash”, “image/jpg”, and “image/gif”. |
| topframe | integer ; optional | Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes. |
| expdir | integer array ; optional | Directions in which the banner may expand |
| api | integer array ; optional | List of supported API frameworks for this impression |
| ext | object ; optional | Placeholder for exchange-specific extensions to OpenRTB |
....
"banner": {
"w": 728, "h": 90, "pos": 1,
"btype": [ 4 ],
"battr": [ 14 ],
"api": [ 3 ]
}
....
Definition of the App Object
| Field | Scope | Type |
|---|---|---|
| id | string; recommended | Pubnative - specific app ID. |
| name | string | Pubnative - specific App name |
| bundle | string | Application bundle or package name (e.g., com.foo.mygame); |
| storeurl | string | App store URL for an installed app; |
| cat | string array | Array of IAB content categories of the app. |
| ver | string | Application version |
| publisher | object | Details about the Publisher |
| keywords | string | Comma separated list of keywords about the app. |
"app":{
"id":"1004844",
"name":"Countabc",
"bundle":"com.foo.mygame",
"storeurl":"https://play.google.....",
"cat":[
"IAB18"
],
"keywords":"shopping",
"ver":"10.1",
"publisher":{
"id":"1028",
"name":"Count LTD",
}
},
Definition of the Device Object
| Field | Scope | Type |
|---|---|---|
| ua | string; recommended | Browser user agent string. |
| geo | object; recommended | Location of the device assumed to be the user’s current. geo.type - Possible values 1,2 1- Geo info generated from GPS system 2- Geo info generated from IP address. |
| dnt | integer; recommended | Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track. |
| ip | string; recommended | IPv4 address closest to device. |
| devicetype | integer | The general type of device. |
| make | string | Device make (e.g., “Apple”). |
| model | string | Device model (e.g., “iPhone”). |
| os | string | Device operating system (e.g., “iOS”). |
| osv | string | Device operating system version |
| hwv | string | Hardware version of the device |
| carrier | string | Carrier or ISP (e.g., “VERIZON”). “WIFI” is often used in mobile to indicate high bandwidth (e.g., video friendly vs. cellular). |
| connectiontype | integer | Network connection type. 0 -Unknown, 1- Ethernet, 2 - WIFI, 3 -Cellular Network – Unknown Generation |
| devicetype | integer | The general type of device |
| ifa | string | ID sanctioned for advertiser use in the clear (i.e., not hashed) |
"device":{
"dnt":2,
"ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1_2 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12B440 Safari/600.1.4",
"ip":"8.8.8.8",
"geo":{
"lat":0,
"lon":0,
"country":"USA",
"region":"CA",
"city":"Mountain View",
"zip":"94040",
"type":2 // 1- GPS, 2- IP address
},
"carrier":"Google",
"language":"en",
"make":"Apple",
"model":"iphone",
"os":"iOS",
"osv":"8",
"connectiontype":2, // 0 -Unknown, 1- Ethernet, 2 - WIFI, 3 -Cellular Network – Unknown Generation
"devicetype":1, // 1 - Mobile/Tablet
"ifa":"1E2DFA89-47FD-9941-DF1FC4E6484C"
},
Definition of the User Object
| Field | Scope | Type |
|---|---|---|
| id | string; recommended | Exchange-specificID for the user. |
| gender | string | Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown). |
| keywords | object | Comma separated list of keywords, interests, or intent. |
.....
"user":{
"id":"78550233-77fc-5ba8-8bff-f6a1809344eb",
"gender":"m",
"keywords":"sports, paid user",
},
.....
Sample Bid Request
{
"id":"4fc8acc7-6bb2-489d-7547-d3291547f17c",
"imp":[
{
"id":"46600265-e3a4-44dd-7114-49d21405cacf",
"banner": {
"w": 320, "h": 50,
"pos": 1,
"btype": [ 4 ],
"battr": [ 14 ],
"api": [ 3 ]
},
"bidfloor":0.01,
"bidfloorcur":"USD"
}
],
"app":{
"id":"1004844",
"name":"Countabc",
"bundle":"628677149",
"storeurl":"https://itunes.apple.com/....",
"cat":[
"IAB18"
],
"keywords":"shopping",
"ver":"10.1",
"publisher":{
"id":"1028",
"name":"Count LTD"
}
},
"device":{
"dnt":1,
"ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1_2 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12B440 Safari/600.1.4",
"ip":"8.8.8.8",
"geo":{
"lat":0,
"lon":0,
"country":"USA",
"region":"CA",
"city":"Mountain View",
"zip":"94040",
"type":2
},
"carrier":"Google",
"language":"en",
"make":"Apple",
"model":"iphone",
"os":"iOS",
"osv":"8",
"connectiontype":2,
"devicetype":1,
"ifa":"1E2DFA89-47FD-9941-DF1FC4E6484C"
},
"user":{
"id":"78550233-77fc-5ba8-8bff-f6a1809344eb",
"gender":"m",
"keywords":"sports, paid user"
},
"at":2,
"tmax":100,
"allimps":0,
"cur":[
"USD"
],
"bcat":[
"IAB1-1",
"IAB18",
"IAB1",
"IAB14",
"IAB24",
"IAB17",
"IAB15",
"IAB22",
"IAB20",
"IAB13",
"IAB9-7",
"IAB1",
"IAB12",
"IAB6",
"IAB3",
"IAB3",
"IAB14-1",
"IAB5",
"IAB7"
]
}
OpenRTB Response
The structure and contents of the Bid Response are the same as in the OpenRTB standard. The difference is how ad creative is returned.
BidResponse Object
| Field | Scope | Type |
|---|---|---|
| id | string; required | ID of the bid request to which this is a response. |
| seatbid | object array | Array of seatbid objects; 1+ required if a bid is to be made. |
| bidid | string | Bidder generated response ID to assist with logging/tracking. |
| cur | string; default “USD | Bid currency using ISO-4217 alpha codes. PN accepts on USD. |
| nbr | integer optional | Reason for not bidding. Refer to OpenRTB Spec |
Definition of Seat Bid Object
| Field | Scope | Type |
|---|---|---|
| bid | object array; required | Array of 1+ Bid objects (Section 4.2.3) each related to an impression. Multiple bids can relate to the same impression |
| seat | string | ID of the bidder seat on whose behalf this bid is made. |
| group | integer; default 0 | 0 = impressions can be won individually; 1 = impressions must be won or lost as a group. |
Definition of the Bid Object
| Field | Scope | Title |
|---|---|---|
| id | string; required | Bidder generated bid ID to assist with logging/tracking. |
| impid | string; required | ID of the Imp object in the related bid request. |
| price | float; required | Bid price expressed as CPM although the actual transaction is for a unit impression only. Note that while the type indicates float, integer math is highly recommended when handling currencies (e.g., BigDecimal in Java). |
| adid | string | ID of a preloaded ad to be served if the bid wins. |
| nurl | string | Win notice URL called by the exchange if the bid wins; optional means of serving ad markup.Please check Billing section for proper implementation. |
| adm | string; required | means of conveying ad markup in case the bid wins |
| adomain | string array, required | Advertiser domain for block list checking (e.g., “ford.com”). This can be an array of for the case of rotating creatives. Exchanges can mandate that only one domain is allowed.Required for standard size ad formats. |
| bundle | string | Bundle or package name (e.g., com.foo.mygame) of the app being advertised, if applicable; intended to be a unique ID across exchanges. |
| iurl | string | URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking. |
| cid | string | Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. |
| crid | string | Creative ID to assist with ad quality checking. Needs to be unique per creative and cant not be re cycled. |
| cat | string array | IAB content categories of the creative |
| attr | integer array | Set of attributes describing the creative. |
| dealid | string | Reference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal. Required for PMP |
Important checks
DSP´s integrating with PN ad server MUST keep in mind following points -
- Build your bidder to comply with the PubNative OpenRTB 2.3 spec.
- Impression trackers must be packed inside the adm object.
- Passing nurl is mandatory.
- Impressions confirmation window on PN ad server is 1hour. So we recommend DSP to have the same on their end to avoid discrepancies. In case of any questions please contact your Account Manager
Sample Response
{
"id": "d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
"bidid": "pbnvrtb-10048",
"cur": "USD",
"seatbid": [
{
"bid": [
{
"impid": "1a430de0-b222-412e-4c05-d6ab8115825a",
"price": 0.071396679621748,
"nurl": "http://pubnative-east.com/ads/notify.php?siteid=pbnvrtb1004844&adid=4ace572c&deviceid=1E2DFA89-496A-9931-EF1FC3C33A41&earnings=${AUCTION_PRICE}&impid=d7470a5f1a75-4bf6-4c8250abd49e8bb8&ip=8.8.8.8&countryCode=US&apikey=pbnvrtb&device=iPhone&os=8.1&mach=&ni=0&appid=667728512&adG roup=GameofWar_FireAge_iPhone_US&ourprice=0.071396679621748&adom=&seg=W10%3D&adgroupID=66323&campaignID=1 23395&creativeID=4ace572c¬ifyid=bd471f8e191410c8cc80d7469758ad9d&nb=0&rc=&ra=G0T0a0W00.1C00OG0003100000P0 04Qb0000000000n00000&sp=&ssrv=www1011&tzofse=0&impid=2015052014509627587ddba4a3bb1174c19f0acdb0af5391857e &carrier=WIFI&cg=TEST&at=2&bp=0.071396679621748&creativeID=4ace572c&aid=1E2DFA89-496A-9931EF1FC3C33A41&cf=2",
"id": "pbnvrtb-1004844-d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
"iurl": "http://platform.com/promote/mock/72c",
"adomain": [ "advertiserdomain.com" ],
"attr": [ 1, 2, 3, 4 ],
"crid": "ce572c",
"cid": "3395",
"adm": "<iframe src=\"http://mobile123.info/kroznik-us-160530/320x50?networkId=42&publisherId=appcoach_1105_32466__com.forshared\" width=\"320\" height=\"50\" frameBorder=\"0\" scrolling=\"no\" style=\"border:0\"></iframe><img src='http://rtb-useast.ezmob.com/imp?i=E1G2aNMWXt4_0' alt=' ' style='display:none'><img src='http://rtb2.vashoot.com/imp?i=QNmodXd5aqs_0' alt=' ' style='display:none'><img src=\"http://us-e-node14.rtbadtrading.com/?t=win&b=${AUCTION_PRICE}&ob=0.46282&ds=4&cd=c73b0900340f2bb58f0b477269ddb8fa\" border=\"0\" width=\"1\" height=\"1\"><div style=\"display:none\"><img src=\"http://tr.pubnative.net/impression?aid=1004319&t=S5dFwqxKcQI5eWkc67nNhAaoHHW2XqtzJF_HeadIZMxuB9Kkx-AuPM1Rhp18r4jcNsVxs-mEFClFwT8E_pfJ5903CS7LaOj1Eodi4LZr2ETIDx5G8cI3zYFssNWSSlh32891pZWAQJgi603H3dGVjFyytRiNv1uGnr2WKJuTU6jYsm2MJkv3XGu6zohIfcUMCLeoYA0mMEp1HEmfSlSNwzqsfob9wFm3SJOhEybwWNA_lTVJPzi6yrSYPO67m9MxsJQPGMbCnGjb1byobcJgE1YQjvAm8yvUKqdyGFQQt4Pfv3kMXqwKeUPFEteaqU8uQV_MFmWsPmBLBVOBXxolTbDQ7Yqfa2bVd0V8DXGj4tW6Ei_DsgbaE1JRKQqFghAxdTx4I9vyXNlhDvsAJKs2e1GhEiVwjA_QwK0LgWox9oByzz6-MKHesTU48hc44ktyv-RpgI0CbPi7s6cOraUqngUk3SwkoylYvtVjluwpWeX77MDEKekLJMH1bRSILq8kV4j8i8vBahs1fcXBYZw2ar6da4jrLMJd-J5ITZ5PiisLggSnvUuPvWN-cwZMsHNEL_AMKCTLR4sxuVTppMsPt-K1IlwjRc-Qeoa8o6VV_lnPxjneA1xmITklj_IAMQRhJqvroRIUSzTFB3NyS7hDiAY8cCW1CbKaKkCYJD63LJvEj-gWSxK3r7GAFm2IkLHXTwgkMd5SWQOwb2qnTT0f_o4DrojR35XB7ummTYm6-fegpQjS27HDgLIXXcDk3lw-_c9OXJH6rjzHufuwdm_tYo0sXxv9ievD0w9uJo0Bbzo8ojp2Wo4IJgWqZhvoChtGHi0&tl=835&ap=${AUCTION_PRICE}&px=1\"/></div>"
}
]
},
{
"seat": "abc1abc"
}
]
}