- Technical Integration (Standard)

OpenRTB Request

The Open RTB request for standard format is fully compliant with Open RTB 2.3 standards.

Bid Request Structure

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

Definition of the Impression Ext Object

Attribute	Type	Description
hb	integer	An integer value describing if the auction is “waterfall” or not. “1” = The auction is not waterfall “0” = The auction is waterfall

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 Ext Object

Attribute	Type	Description
inputlanguage	string	A string array containing the languages setup on the user's device keyboard. (i.e. “en-US, en” )
diskspace	int	An integer value describing the available disk space on the device in megabytes, where i.e. "18201" = device has 18201 MB of available disk space.
totaldisk	int	An integer value describing the total disk space on the device in megabytes, where i.e. "63989" = 63989 MB of total disk space.
ringmute	int	(Android only) An integer value describing the device sound setting during time of ad request describing if sound is set to ring or mute, where "0" = mute and "1" = ring.
charging	int	An integer value describing if the device is connected to a charger, where: "0" = unplugged and "1" = plugged into power outlet
headset	bool	A boolean value indicating if the device is connected to a headset, where: "1" = device is connected to any headset and "0" = no headset is connected
batterylevel	int	An integer passed describing percent battery remaining on the user's device, segmented into buckets, where 100-85% = 8 84-70% = 7 69-55% = 6 54-40% = 5 39-25% = 4 21-10% = 3 9-5% = 2 < 5% = 1
batterysaver	bool	A boolean value indicating if battery saver ("Low Power Mode" on iOS) has been enabled, where "1" = battery saver, "0" = not enabled
darkmode	bool	A boolean value indicating if dark mode is enabled on the device, where "1" = dark mode enabled, "0"= not enabled
airplane	bool	A boolean value indicating if airplane mode is enabled, where "1" = airplane mode enabled, "0" = not enabled
dnd	bool	Android only) A boolean value indicating if “do not disturb” setting is enabled, where "1" = do not disturb enabled, "0" = not enabled.
atts	int	(iOS 14 + only) An integer passed to represent the app's app tracking authorization status, where 0 = not determined 1 = restricted 2 = denied 3 = authorized
bluetooth	bool	A boolean value indicating if the device is connected to bluetooth where "1" = connected to bluetooth “0” = not connected to bluetooth

"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",
    "ext": {
        "airplane": 0,
        "batterylevel": 8, // 100-85% = 8 , 84-70% = 7, 69-55% = 6, 54-40% = 5, 39-25% = 4, 21-10% = 3, 9-5% = 2, < 5% = 1  
        "batterysaver": 1,
        "bluetooth": 1,
        "charging": 0,
        "darkmode": 0,
        "dnd": 0, // 0- Do Not Disturb disabled, 1- Do Not Disturb enabled
        "headset": 0, //0- No headset connected, 1- Headset connected
        "inputLanguage": [
            "en"
        ],
        "ringmute": 0, // 0- Mute, 1- Ring
        "diskspace": 1821, //MB of data
        "totaldisk": 128000 //MB of data
    }
},

Definition of Geo Device

Attribute	Description	Type
lat	Latitude from -90.0 to +90.0, where negative is south	Float
long	Longitude from -180.0 to +180.0, where negative is west	Float
type	Type - 1 - represents directly passed from device. 2 - Ip derived	Integer
utcoffset	Local time as the number +/- of minutes from UTC	integer
accuracy	Estimated location accuracy in meters; recommended when lat/lon are specified and derived from a device’s location services (i.e., type = 1). Note that this is the accuracy as reported from the device. Consult OS specific documentation (e.g., Android, iOS) for exact interpretation	Integer
lastfix	The time accuracy of the location. The number of seconds since the location was retrieved. Format is in total number of seconds.	Integer
ipservice	Enrichment provider	Integer
metro	Zip code of the device	String
zip	ZIP or postal code	string
Country	Country code using ISO-3166-1-alpha-3	String
Region	Region code using ISO-3166-2; 2-letter state code if USA	String
City	City using United Nations Code for Trade & Transport Locations. See Appendix A for a link to the codes	String
ext.isp	Internet Service Provider name	String
ext.org	Internet Service Provider name.	String

"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
        "utcoffset": 120,
        "accuracy": 400,
        "ipservice": 2,
        "ext": {
        	"isp":"Google",
        	"org":"Google"
        }
    },
    "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",
    "ext": {
        "airplane": 0,
        "batterylevel": 8, // 100-85% = 8 , 84-70% = 7, 69-55% = 6, 54-40% = 5, 39-25% = 4, 21-10% = 3, 9-5% = 2, < 5% = 1  
        "batterysaver": 1,
        "bluetooth": 1,
        "charging": 0,
        "darkmode": 0,
        "dnd": 0, // 0- Do Not Disturb disabled, 1- Do Not Disturb enabled
        "headset": 0, //0- No headset connected, 1- Headset connected
        "inputLanguage": [
            "en"
        ],
        "ringmute": 0, // 0- Mute, 1- Ring
        "diskspace": 1821, //MB of data
        "totaldisk": 128000 //MB of data
    }
},

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",
      "ext": {
        "airplane": 0,
        "batterylevel": 8,
        "batterysaver": 1,
        "bluetooth": 1,
        "charging": 0,
        "darkmode": 0,
        "dnd": 0,
        "headset": 0,
        "inputLanguage": [
            "en"
        ],
        "ringmute": 0,
        "diskspace": 1821,
        "totaldisk": 128000
    }  
   },
  "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"
    }
  ]
}