Open RTB Request

The Open RTB request for native ads 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.

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"
    }
  ]
}