- Technical Integration (Native)

Open RTB Request

The Open RTB request for native ads 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.
native	object; required	A Native 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":"46600265-e3a4-44dd-7114-49d21405cacf",
      "native":{
        "request":"{\"ver\":\"1.0\",\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"data\":{\"type\":12}},{\"id\":2,\"required\":1,\"title\":{\"len\":50}},{\"id\":3,\"required\":1,\"img\":{\"type\":1,\"w\":80,\"h\":80}},{\"id\":4,\"required\":1,\"img\":{\"type\":3,\"w\":1200,\"h\":627}},{\"id\":5,\"required\":0,\"data\":{\"type\":3}},{\"id\":6,\"required\":1,\"data\":{\"type\":2,\"len\":100}}]}",
        "ver":"1.0"
      },
      "bidfloor":0.01,
      "bidfloorcur":"USD"
    }
  ],......

Definition of the Native Object

Attribute	Type	Description
ver	string; required	Version of the Native Markup version in use.
adunit	recommended	integer
plcmtcnt	integer; optional	The number of identical placements
seq	optional	0 for the first ad, 1 for the second ad, and soon. Note this would generally NOT be used in combination with plcmtcnt - high case plcmtcnt>1, seq=0) r you are holding separate feed (in which case plcmtcnt=1, seq=>=1)
assets	object; required	Any objects bid response must comply with the array of elements expressed in the bid request. Must be passed as URL encoded string.

....
"native":{  
            "request":"{\"ver\":\"1.0\",\"plcmtcnt\":1,\"seq\":0,\"assets\":[{\"id\":1,\"required\":1,\"data\":{\"type\":12}},{\"id\":2,\"required\":1,\"title\":{\"len\":50}},{\"id\":3,\"required\":1,\"img\":{\"type\":1,\"w\":80,\"h\":80}},{\"id\":4,\"required\":1,\"img\":{\"type\":3,\"w\":1200,\"h\":627}},{\"id\":5,\"data\":{\"type\":3}},{\"id\":6,\"required\":1,\"data\":{\"type\":2,\"len\":100}}]}",
            "ver":"1.0"
         }
....

Definition of the Asset Object

Field	Scope	Type
id	integer; required	Unique asset ID, assigned by exchange. Typically a counter for the array.
required	integer; optional	Set to 1 if asset is required
title	object ;required	Title object for title assets.TitleObject definition.
img	object; required	Image object for image assets.See ImageObject definition.
data	object; required	Data object for brand name, description, ratings, prices etc. See DataObject definition.

Definition of the Title Object

Field	Scope	Type
len	required	Maximum length of the text in the title element. Recommended to be 25

Definition of the Image Object

Field	Scope	Type
type	integer; required	Type ID of the image element supported by the publisher. Pubnative supports 1,3 1- Icon 3- Banner
w	integer; recommended	Width of the image in pixels. In case of icon - 80 In case of banner - 1200 The above mentioned sizes are recommended. PN does not post process images, we allow images of any size.
h	integer; recommended	Height of the image in pixels. In case of icon - 80 In case of banner - 627 The above mentioned sizes are recommended. PN does not post process images, we allow images of any size.

Definition of the Data Object

Field	Scope	Type
type	integer; required	Type ID of the image element supported by the publisher.
len	integer; optional	Length of the text.

Data Asset Types

Type ID	Name	Description	Format
2	desc	Descriptive text associated with the product or service being advertised	Text
3	rating	Rating of the product being offered to the user. For example, an app's rating in an app store from 0-5	Number formatted as string
12	ctatext	CTA description - descriptive text describing a 'call to action' button to the destination URL	Text

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",
         "native":{  
            "request":"{\"ver\":\"1.0\",\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"required\":1,\"data\":{\"type\":12}},{\"id\":2,\"required\":1,\"title\":{\"len\":50}},{\"id\":3,\"required\":1,\"img\":{\"type\":1,\"w\":80,\"h\":80}},{\"id\":4,\"required\":1,\"img\":{\"type\":3,\"w\":1200,\"h\":627}},{\"id\":5,\"required\":0,\"data\":{\"type\":3}},{\"id\":6,\"required\":1,\"data\":{\"type\":2,\"len\":100}}]}",
            "ver":"1.0"
         },
         "bidfloor":0.01,
         "bidfloorcur":"USD"
      }
   ],
 "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"
      }
   },
   "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

Definition of native object

Field	Scope	Type
ver	string; required	Versions of the native markup in use
assets	array of objects; required	List of native ad's assets
link	required	Destination link. This is the default link object for the ad. Individual assets can also have a link object which applies if the asset is activated (clicked). If the asset doesn't have a link object, the parent link object applies
imptrackers[]	optional	Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers. Please refer to billing section for more details.
jstracker	optional	Optional JavaScript impression tracker. This is valid HTML, JavaScript is already wrapped in
ext	optional	This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

🚧
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. This is based on OpenRTB native v 1.1

The native object must be packed under the adm object.

The native object must be URL encoded.

The native should pass "ver" field as a string and not as an integer.

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": "{\"native\":{\"ver\":\"1.0\",\"assets\":[{\"id\":1,\"data\":{\"value\":\"Download\"}},{\"id\":2,\"title\":{\"text\":\"Game of War\"}},{\"id\":3,\"img\":{\"w\":80,\"h\":80,\"url\":\"http:\\/\\/cdn.abc.com\\/1028\\/80x80_war.jpg\"}}, {\"id\":4,\"img\":{\"w\":1200,\"h\":627,\"url\":\"http:\\/\\/cdn.abc.com\\/1028\\/1200x627SDS_game.jpg\"} },{\"id\":5,\"required\":0,\"data\":{\"type\":3}},{\"id\":6,\"data\":{\"value\":\"Join the ULTIMATE Battle for Domination of the Kingdom! PLAY FOR FREE\"}}],\"imptrackers\":[\"https://www.vizury.com/banners/images/common/mobile_notify.php?u=viz_a_ccffcc32-e049-4812-9cc2-92561bdb55c0&adid=903969&zid=9144&iid=68ebe66e1a3f48cbb3e98018ace937c8MP&ibid=M&ip=8.8.8.8&t=impr&p=${AUCTION_PRICE}&catid=&url=&eid=_mob&os=ios&auc_id=${AUCTION_ID}\",\"https://www.vizury.com/banners/images/common/mobile_notify.php?u=viz_a_ccffcc32-e049-4812-9cc2-92561bdb55c0&adid=903969&zid=9144&iid=68ebe66e1a3f48cbb3e98018ace937c8MP&ibid=M&ip=8.8.8.8&t=impr&p=${AUCTION_PRICE}&catid=&url=&eid=_mob&os=ios&auc_id=${AUCTION_ID}\",\"https://www.vizury.com/banners/images/common/mobile_notify.php?u=viz_a_ccffcc32-e049-4812-9cc2-92561bdb55c0&adid=903969&zid=9144&iid=68ebe66e1a3f48cbb3e98018ace937c8MP&ibid=M&ip=8.8.8.8&t=impr&p=${AUCTION_PRICE}&catid=&url=&eid=_mob&os=ios&auc_id=${AUCTION_ID}\"],\"link\":{\"url\":\"http:\\/\\/c.abc.com\\/ads\\/c.php?a=pbnvrtb&b=pbnvrtb1004844&c=4ace572c&d=1E2DFA89-496A-9931EF1FC3C33A41&e=&cts=1432158625&ct=0&nb=0&wp=${AUCTION_PRICE}&gf=http%3A%2F%2Fcdn.abc.com%2F1028%2F2015051 1_13_17_12_1200x627_Time03_logo_.jpg&ab=1&ni=0&ra=G0T0a0W00.1C00OG0003100000P004Qb0000000000n00000&seg=W1 0%3D&aid=1E2DFA89-496A-9931EF1FC3C33A41&campaignID=123395&adgroupID=66323&appid=667728512&creativeID=4ace572c&sscpa=43&countrycode=U S&impid=d7470a5f-1a75-4bf6-4c8250abd49e8bb8&tzofse=0&impid=2015052014509627587ddba4a3bb1174c19f0acdb0af5391857e&carrier=WIFI&cg=TEST&at= 2&bp=0.071396679621748&creativeID=4ace572c&cf=2\"}}}"
        }
      ]
    },
    {
      "seat": "abc1abc"
    }
  ]
}