OpenRTB Request & Response Structure
For standard, native and video formats PubNative supports OpenRTB versions 2.x.
Bid Request Specifications
The bid request consists of the top-level bid request object, at least one impression object, and may
optionally include additional objects providing impression context.
BidRequest Object
The top-level object is denoted as "BidRequest". The top-level BidRequest object contains a series of subordinate objects that provide detailed data to potential buyers.
Attribute | Type | Description |
---|---|---|
id | string; required | Unique ID of the bid request, provided by the exchange. |
imp | object; required | Unique ID of the bid request, provided by the exchange. |
site | object | PubNative will send this for mobile websites. |
app | object | PubNative 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. |
test | integer; default | Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode. |
at | integer | Auction type, where 1 = First Price, 2 = Second Price PubNative 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. PubNative only allows bidding in USD |
bcat | string array | Blocked advertiser categories using the IAB content categories. DSP need to respect bcat to align with PubNative publishers and exchange wide settings |
badv | string array | Block list of advertisers by their domains (e.g., “ford.com”). Typically designated by publishers |
source | object | A Source object that provides data about the inventory source and which entity makes the final decision. |
regs | object | A Regs object that specifies any industry, legal, or governmental regulations in force for this request. |
Definition of the Source Object
Attribute | Type | Description |
---|---|---|
fd | integer; optional | Entity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source. |
pchain | string; recommended | Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0. |
ext.omidpn | string | Identifier of the Open Measurement SDK integration. The default value for PubNative’s Hybid SDK is “Pubnativenet”. |
ext.omidpv | string | Version of the Open Measurement SDK integration. |
ext.schain | object; recommended | This object represents both the links in the supply chain as well as an indicator whether or not the supply chain is complete. |
NOTE
Depending on the integration, PubNative will send pchain, omidpn, omipv fields and schain object under BidRequest.Source object, and/or under BidRequest.ext object.
Definition of the Source.ext.schain Object
Attribute | Type | Description |
---|---|---|
ver | string; required | The version of the supply chain specification in use |
complete | integer; required | Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app, or another medium of the inventory, where 0 = no, 1 = yes |
nodes | object array; required | Array of SupplyChainNode objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction. |
nodes.asi | string; required | Canonical domain name of the SSP, Exchange, Header Wrapper, etc system that bidders connect to. |
nodes.sid | string; required | The identifier associated with the seller or reseller account within the advertising system. |
nodes.rid | string | The OpenRTB RequestId of the request as issued by this seller. |
nodes.hp | integer | Indicates whether this node will be involved in the flow of payment for the inventory. |
Definition of the Regs Object
Attribute | Type | Description |
---|---|---|
coppa | integer | Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes. |
ext.gdpr | integer | Flag that indicates whether or not the request is subject to GDPR regulations 0 = No, 1 = Yes, omission indicates Unknown. |
ext.consent | string | When GDPR regulations are in effect this attribute contains the Transparency and Consent Framework’s Consent String data structure. |
ext.us_privacy | string | Communicates signals regarding consumer privacy under US privacy regulation. See US Privacy String specifications. |
Definition of the Impression Object
Attribute | Type | Description |
---|---|---|
id | string; required | A unique identifier for this impression within the context of the bid request. |
metric | object array | An array of Metric object. Details listed here. |
banner | object; required if banner ad | Banner object; Details are listed below. |
video | object; required if video ad | Video object; Details are listed below |
native | object; required if native ad | Native object; Details are listed below |
pmp | object | Contains any private marketplace deals in effect for this impression. Details are listed below |
displaymanager | string | Name of ad mediation partner, SDK technology, or player responsible for rendering ad. For PubNative’s Hybid SDK, “HyBid” value will be passed. |
displaymanagerver | string | Version of ad mediation partner, SDK technology, or player responsible for rendering ad. For PubNative’s Hybid SDK, relevant sdk version will be sent. |
instl | integer; default 0 | Indicates if the ad is interstitial or not. 1 = the ad is interstitial or full screen, 0 = not interstitial. |
tagid | string | Identifier for specific ad placement or ad tag that was used to initiate the auction. |
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 |
secure | integer | Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but nonsecure HTTP support can be assumed. |
rwdd | integer; default 0 | Indicates whether the user receives a reward for viewing the ad ad, where 0 = no, 1 = yes. |
ext | object | Placeholder for exchange-specific extensions. |
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 |
skadn | object | An object that provides the relevant fields used to control the SKOverlay. The attribute is only present if the SDK and OS versions (iOS 14 and above) support SKOverlay. More information and further details about support can be found here. |
Definition of the Metric Object
Attribute | Type | Description |
---|---|---|
type | string; required | Type of metric being presented using exchange curated string names, for example: “click_through_rate" |
value | float; required | Number representing the value of the metric. Probabilities must be in the range 0.0 – 1.0. |
vendor | string; recommended | Source of the value using exchange curated string names which should be published to bidders a priori. If the exchange itself is the source versus a third party, “EXCHANGE” is recommended. |
About Metric Object
We will send the Metric object in both BidRequest.Imp and BidRequest.Imp.ext objects.
Examples of type values that we will be populating for specific integrations are “click_through_rate" and "viewability"
Sample of CTR Viewability
"imp": [
{
"id": "12068b09-361d-4b00-9a18-e8fcb9cf1d2b",
"metric": [
{
"type": "click_through_rate",
"value": 0.00263,
"vendor": "EXCHANGE"
},
{
"type": "viewability",
"value": 1,
"vendor": "integralads.com"
}
Definition of the Banner Object
The presence of a "Banner" object as a subordinate of the Imp object indicates that this impression is offered
as a banner type impression.
Attribute | Type | Description |
---|---|---|
format | object array | Array of format objects representing the banner sizes permitted. |
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 |
Definition of the Video Object
The presence of a Video object as a subordinate of the Imp object indicates that this impression is offered
as a video type impression. This object represents an in-stream video impression.
Attribute | Type | Description |
---|---|---|
mimes | string array; required | Content MIME types supported. Popular MIME types may include “video/x-ms-wmv” for Windows Media and “video/x-flv” for flash video |
minduration | integer; recommended | Minimum video ad duration in seconds |
maxduration | integer; recommended | Maximum video ad duration in seconds |
protocols | integer array; recommended | Array of supported video bid response protocols. At least one supported protocol must be specified in either the protocol or protocols attribute. |
w | integer; recommended | Width of the video player in pixels. |
h | integer; recommended | Height of the video player in pixels. |
startdelay | integer; recommended | Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. |
linearity | integer | Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed. |
sequence | integer | If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives. |
battr | integer array | Blocked creative attributes. |
maxextended | integer | Maximum extended video ad duration if extension is allowed. If blank or 0, extension is not allowed. If -1, extension is allowed, and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxduration value. |
maxbitrate | integer | Maximum bit rate in Kbps. Exchange may set this dynamically or universally across their set of publishers |
boxingallowed | integer | Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes. Default = 1 |
playbackmethod | integer array | Allowed playback methods. If none specified, assume all are allowed. |
delivery | integer array | Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. |
companionad | object array | Array of Banner objects, if companion ads are available. PubNative will always pass "id", "w", "h", "pos", "battr", "mimes", "api" and "vcm" under companionads object. |
api | integer array | List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. |
companiontype | integer array | Supported VAST companion ad types. |
skip | integer; recommended | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. |
skipmin | integer; recommended | Default 0 Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable. |
skipafter | integer; default 0 | Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable. |
ext | object | Placeholder for exchange-specific extensions to OpenRTB. |
plcmt | integer | Video placement type for the impression. 1 = instream, 2 = companion, 3 = Interstitial, 4 = standalone |
mraidendcard | bool | A boolean custom extension to signal MRAID End Card support. "0" = MRAID end card is not supported "1" = MRAID end card is supported |
About Rewarded Video placements
Please note that if the placement is for Rewarded Video, the following parameters and values will be added to the Bid Request body:
- BidRequest.imp.rwdd = 1
- BidRequest.imp.video.ext.rewarded = 1
- BidRequest.imp.video.ext.videotype = "rewarded"
- BidRequest.imp.video.ext.skip = 0
- BidRequest.imp.video.skip = 0
Definition of the Native Object
The presence of a Native object as a subordinate of the Imp object indicates that this impression is offered
as a native type impression. This object represents a native type impression.
Attribute | Type | Description |
---|---|---|
request | string;required | Request payload complying with the Native Ad Specification. |
ver | string; required | Version of the Native Markup version in use. |
adunit | recommended | Ad unit in integer |
api | integer array | List of supported API frameworks for this impression. |
plcmtcnt | integer; optional | The number of identical placements |
seq | integer;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. |
Definition of the Asset Object
Attribute | Type | Description |
---|---|---|
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
Attribute | Type | Description |
---|---|---|
len | required | Maximum length of the text in the title element. Recommended to be 25 |
Definition of the Image Object
Attribute | Type | Description |
---|---|---|
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. PubNative 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. PubNative does not post process images, we allow images of any size. |
Definition of the Pmp Object
This object is the private marketplace container for direct deals. The actual deals are represented as a collection of Deal objects.
Attribute | Type | Description |
---|---|---|
private_auction | integer; required | Indicator of auction eligibility to seats named in the Direct Deals object, where 0 = all bids are accepted, 1 = bids are restricted to the deals specified and the terms thereof. |
deals | object | Array of Deal objects that convey the specific deals applicable to this impression |
Definition of the Deal Object
Attribute | Type | Description |
---|---|---|
id | string; required | Pubnative - specific app ID. |
bidfloor | float | Minimum bid for this impression expressed in CPM. |
at | integer | Optional override of the overall auction type of the bid request, where 1 = First Price, 2 = Second Price |
Definition of the App Object
Field | Scope | Type |
---|---|---|
id | string; recommended | Pubnative - specific app ID. |
name | string | App name in the relevant appstore |
bundle | string | A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is a numeric ID. |
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. |
Definition of the Publisher Object
Attribute | Type | Description |
---|---|---|
id | string | Exchange-specific publisher id. Corresponds to a seller_id of a seller in the Pubnative’s sellers.json file. |
name | string | Publisher name (may be aliased at the publisher’s request). |
domain | string | Highest level domain of the publisher |
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. |
lmt | integer; recommended | “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. |
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 |
h | integer | Physical height of the screen in pixels. |
w | integer | Physical width of the screen in pixels. |
ppi | integer | Screen size as pixels per linear inch. |
hwv | string | Hardware version of the device |
pxratio | float | The ratio of physical pixels to device independent pixels. |
js | integer | Support for JavaScript, where 0 = no, 1 = yes |
geofetch | integer | Indicates if the geolocation API will be available to JavaScript code running in the banner, where 0 = no, 1 = yes. |
language | string | Browser language using ISO-639-1-alpha-2. |
carrier | string | Carrier or ISP. “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) |
ext | object | Placeholder for exchange-specific extensions. |
Definition of the Device Ext Object
About Device Extension Object
The Device Extension object contains fields that can be used by buyers for "contextual app targeting". For more information about "Contextual App Targeting", please refer to this page.
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 |
Definition of Geo Device
Attribute | Type | Description |
---|---|---|
lat | float | Latitude from -90.0 to +90.0, where negative is south |
lon | float | Longitude from -180.0 to +180.0, where negative is west |
type | integer | Type - 1 - represents directly passed from device. 2 - Ip derived |
utcoffset | integer | Local time as the number +/- of minutes from UTC |
accuracy | integer | 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 |
lastfix | integer | The time accuracy of the location. The number of seconds since the location was retrieved. Format is in total number of seconds. |
ipservice | integer | Enrichment provider |
metro | string | Zip code of the device |
zip | string | ZIP or postal code |
Country | String | Country code using ISO-3166-1-alpha-3 |
Region | string | Region code using ISO-3166-2; 2-letter state code if USA |
City | string | City using United Nations Code for Trade & Transport Locations. See Appendix A for a link to the codes |
ext.isp | string | Internet Service Provider name |
ext.org | string | Internet Service Provider name. |
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. |
ext | object | Placeholder for exchange-specific extensions. |
Definition of User Ext Object
Field | Scope | Type |
---|---|---|
sessionduration | integer | The total duration of time a user has spent so far in a specific app session expressed in seconds. |
impdepth | integer | The count of impressions for a specific placement type in a given app session. The impression depth is reset once the session ends. |
agerating | string | App or screen content rating. |
eids | objects | Contains the Extended identifiers object. |
Bid Response Specifications
The bid response consists of the top-level bid response object and optional objects that depict the specific bids. The structure and contents of the Bid Response are the same as in the OpenRTB standard, for standard, native & video ad formats. The difference is how ad creative is returned.
An empty HTTP response, a malformed response or a response that contains no actual bids will be interpreted as no-bid.
For a Native Bid Response, all Demand Side integrations must include the 'native' node within the ADM attribute.
Definition of BidResponse Object
Attribute | Type | Description |
---|---|---|
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. PubNative accepts on USD. |
nbr | integer optional | Reason for not bidding. Refer to OpenRTB Spec |
Definition of Seat Bid Object
Attribute | Type | Description |
---|---|---|
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
About Bid Object
Bid object contains win notice url (nurl), billing notice url (burl) and loss notice url (lurl). For more information on:
Attribute | Type | Description |
---|---|---|
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. |
burl | string | Billing notice URL called by the PubNative when a winning bid becomes billable. |
nurl | string | Win notice URL called by the PubNative if the bid wins. Please check this page for proper implementation & further information. |
lurl | string | Loss notice URL called by the PubNative when a bid is known to have been lost. Please check this page for proper implementation & further information. |
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. |
apis | integer array | List of supported APIs for the markup. If an API is not explicitly listed, it is assumed to be unsupported. Refer to List: API Frameworks in AdCOM 1.0. |
api | integer | API required by the markup if applicable. Refer to List: API Frameworks in AdCOM 1.0. (A value(s) either in “api” as an integer, or in “apis” as an array should be sent in bid response) |
protocol | integer; recommended for video | Video response protocol of the markup if applicable. Refer to List: Creative Subtypes - Audio/Video in AdCOM 1.0. |
dealid | string | Reference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal. Required for PMP |
w | integer | Width of the creative in device independent pixels |
h | integer | Height of the creative in device independent pixels |
ext | object | Placeholder for specific extensions |
Definiton of Bid.ext.skadn (SKAdNetwork)
For more information about SKAdNetwork & SkOverlay please refer to the documentation here.
Attribute | Type | Description |
---|---|---|
version | string | Version of skadnetwork supported. Always "2.0" or higher. Dependent on both the OS version and the SDK version. |
network | string | Ad network identifier used in signature. Should match one of the items in the skadnetids array in the request (For example:"dsp1.skadnetwork") |
campaign | string | Campaign id compatible with Apple's spec. As of 2.0, should be an integer between 1 and 100, expressed as a string. (For example: "75") |
itunesitem | string | id of advertiser's app in Apple's app store. Should match BidResponse.seatbid.bid.bundle (For example: "5678") |
fidelities | Object array | Supports multiple fidelity types introduced in SKAdNetwork v2.2 |
nonce | string | An id unique to each ad response. Refer to Apple's documentation for the proper UUID format requirements. Note: With the release of SKAdNetowrk v2.2, this field is deprecated in favor of the BidResponse.seatbid.bid.ext.dkadn.fidelities .nonce (For example: "uaroa34u-a9de-01420004") |
signature | string | SKAdNetwork signature as specified by Apple. Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of the BidResponse.seatbid.bid.ext.skadn.fidelities. signature to support multiple fidelity-types. (For example: "MEQCIEQZRRyMyUXg==") |
timestamp | string | Unix time in milliseconds string used at the time of signature. Note: With the release of SKAdNetwork 2.2, this field is deprecated in favor of BidResponse.seatbid.bid.ext.skadn.fidelities. timestamp to support multiple fidelity-types. (For example: "1613406371") |
sourceapp | string | id of publisher's app in Apple's app store. Should match BidRequest.imp.ext.skad.sourceapp (For example: "123456789") |
sourceidentifier | string | A four-digit integer that ad networks define to represent the ad campaign. Used in SKAdNetwork 4.0+, replaces Campaign ID 'campaign'. DSPs must generate signatures in 4.0+ using the Source Identifier. Please refer to the SKAdNetwork 4 release notes for more details. |
productpageid | string | Product Page id to direct to on click |
skoverlay | object | SKOverlay auto present support |
Definition of Bid.ext.skadn.skoverlay (SKOverlay)
For more information about SKAdNetwork & SkOverlay please refer to the documentation here
Attribute | Type | Description |
---|---|---|
present | binary | Hybid SDK needs to present the SKOverlay (1 = Yes, 0 = No) |
delay | int; default 0 | Delay in seconds before showing the overlay (0-60) |
endcarddelay | int; default 0 | Delay in seconds before showing the overlay on top of the end card (0-60). Use -1 if you do not want to show the overlay on top of the end card |
autoclose | int; default 0 | Time in seconds to automatically dismiss the overlay (0-60). Value of 0 means no automatic dismiss |
dismissible | binary; default 0 | Should the SKOverlay be dismissable by the user |
pos | binary; default 1 | Position of the overlay; 0 = bottom, 1 = bottom raised |
Sample Request & Responses
Sample Banner 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",
"displaymanager": "HyBid",
"displaymanagerver": "2.0.0",
"tagid": "1328491",
"secure": 1
}
],
"app": {
"id": "1328764",
"name": "Countabc",
"bundle": "com.countabc",
"storeurl": "https://play.google.com/store/apps/details?id=com.countabc",
"cat": [
"IAB9"
],
"keywords": "games",
"ver": "10.1",
"publisher": {
"id": "1028",
"name": "Count LTD",
"domain": "https://countltd.com/support"
}
},
"device": {
"dnt": 0,
"ua": "Mozilla/5.0 (Linux; Android 5.0.2; LG-V500 Build/LRX22G; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/95.0.4638.74 Safari/537.36",
"ip": "8.8.8.8",
"geo": {
"lat": 40.2024,
"lon": -21.2939,
"country": "USA",
"region": "CA",
"city": "Mountain View",
"zip": "94040",
"type": 2
},
"carrier": "Mobile Carrier",
"language": "en",
"make": "Mobile",
"model": "Mobile Model",
"os": "Android",
"osv": "12",
"connectiontype": 2,
"devicetype": 1,
"ifa": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"gender": "m",
"keywords": "sports, paid user",
"ext":{
"sessionduration": 1439,
"impdepth": 123,
"agerating": "PG-13"
}
},
"source": {
"pchain": "d641df8625486a7b:1007950",
"ext": {
"schain": {
"ver": "1.0",
"complete": 1,
"nodes": [
{
"asi": "pubnative.net",
"sid": "1007950",
"rid": "2132da3ec6544048bf2d25c566d0dd49",
"hp": 1
}
]
},
"omidpn": "Pubnativenet",
"omidpv": "1.4.3"
}
},
"regs": {
"coppa": 0,
"ext": {
"gdpr": 0,
"consent": ""
}
},
"at": 2,
"tmax": 100,
"allimps": 0,
"cur": [
"USD"
],
"bcat": [
"IAB1-1",
"IAB22",
"IAB7"
]
}
Sample Banner Response
{
"id": "d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
"bidid": "pbnvrtb-10048",
"cur": "USD",
"seatbid": [
{
"id": "1UARoaQytm",
"seat": "512",
"bid": [
{
"impid": "1a430de0-b222-412e-4c05-d6ab8115825a",
"price": 0.07134,
"nurl": "http://platform.com/winnotice?impid=123;wp=${AUCTION_PRICE}",
"burl": "http://platform.com/burl?impid=123;wp=${AUCTION_PRICE}",
"lurl": "http://platform.com/bidloss?lossreason=${AUCTION_LOSS}",
"id": "pbnvrtb-1004844-d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
"adm": "<a href=\"http://platformserver.com/click?adid=creative3395&tracker=${CLICK_URL:URLENCODE}\"><img src=\"http://img1.pltfrm.com/impid=1a430d\"/></a>""iurl": "http://platform.com/pathtosampleimage/72c",
"adomain": [
"advertiserdomain.com"
],
"cat": ["IAB12"],
"attr": [
1,
2,
3,
4
],
"crid": "ce572c",
"cid": "creative3395"
}
]
}
]
}
Sample Video Request
{
"id": "958e3f27-90f9-4183-be4f-bd350f7cc170",
"imp": [
{
"id": "46600265-e3a4-44dd-7114-49d21405cacf",
"video": {
"mimes": [
"video/3gpp",
"video/3gpp2",
"video/mp4",
"video/quicktime",
"video/x-m4v"
],
"minduration": 1,
"maxduration": 60,
"protocols": [
2,
3,
5,
6,
7,
8
],
"w": 320,
"h": 480,
"linearity": 1,
"skip": 1,
"skipafter": 5,
"skipmin": 5,
"pos": 7,
"companionad": [
{
"w": 320,
"h": 480,
"id": "1",
"pos": 7,
"vcm": 1
}
],
"api": [
3,
5
],
"companiontype": [
1,
2,
3
]
},
"displaymanager": "HyBid",
"displaymanagerver": "2.0.0",
"instl": 1,
"tagid": "1328491",
"bidfloor": 23.53,
"bidfloorcur": "USD",
"secure": 1,
"rwdd": 0,
"ext": {
"hb": 0,
"skadn": {
"version": "3.0",
"sourceapp": "net.pubnative.demo",
"skadnetids": [
"abcdefg12345.skadnetwork"
],
"skadnetlist": {
"addl": [
"abcdefg12345.skadnetwork"
]
},
"skoverlay": [
"dismissible",
"delay",
"present",
"pos",
"endcarddelay",
"autoclose"
]
}
}
}
],
"app": {
"id": "1328764",
"name": "Countabc",
"bundle": "com.countabc",
"storeurl": "https://play.google.com/store/apps/details?id=com.countabc",
"cat": [
"IAB9"
],
"keywords": "games",
"ver": "10.1",
"publisher": {
"id": "1028",
"name": "Count LTD",
"domain": "https://countltd.com/support"
}
},
"device": {
"dnt": 0,
"ua": "Mozilla/5.0 (Linux; Android 5.0.2; LG-V500 Build/LRX22G; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/95.0.4638.74 Safari/537.36",
"ip": "8.8.8.8",
"geo": {
"lat": 40.2024,
"lon": -21.2939,
"country": "USA",
"region": "CA",
"city": "Mountain View",
"zip": "94040",
"type": 2
},
"carrier": "Mobile Carrier",
"language": "en",
"make": "Mobile",
"model": "Mobile Model",
"os": "Android",
"osv": "12",
"connectiontype": 2,
"devicetype": 1,
"ifa": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"gender": "m",
"keywords": "sports, paid user",
"ext": {
"sessionduration": 1439,
"impdepth": 123,
"agerating": "PG-13"
}
},
"source": {
"pchain": "d641df8625486a7b:1007950",
"ext": {
"schain": {
"ver": "1.0",
"complete": 1,
"nodes": [
{
"asi": "pubnative.net",
"sid": "1007950",
"rid": "2132da3ec6544048bf2d25c566d0dd49",
"hp": 1
}
]
},
"omidpn": "Pubnativenet",
"omidpv": "1.4.3"
}
},
"regs": {
"coppa": 0,
"ext": {
"gdpr": 0,
"consent": ""
}
},
"test": 0,
"at": 1,
"tmax": 1987,
"cur": [
"USD"
],
"badv": [
"blockedadv.com"
],
}
Sample Video Response
{
"id": "d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
"bidid": "pbnvrtb-10048",
"cur": "USD",
"seatbid": [
{
"bid": [
{
"impid": "1a430de0-b222-412e-4c05-d6ab8115825a",
"price": 0.07134,
"nurl": "http://platform.com/winnotice?impid=123;wp=${AUCTION_PRICE}",
"burl": "http://platform.com/burl?impid=123;wp=${AUCTION_PRICE}",
"lurl": "http://platform.com/bidloss?lossreason=${AUCTION_LOSS}",
"id": "pbnvrtb-1004844-d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
"adm": "<VASTAdTagURI><![CDATA[https://raw.githubusercontent.com/InteractiveAdvertisingBureau/VAST_Samples/master/VAST%203.0%20Samples/Inline_Companion_Tag-test.xml]]></VASTAdTagURI>",
"adomain": [
"advertiserdomain.com"
],
"cat": [
"IAB12"
],
"attr": [
1,
2,
3,
4
],
"apis": [
3,
5,
7
],
"protocol": 5,
"crid": "ce572c",
"cid": "creative3395",
"ext": {
"skadn": {
"version": "3.0",
"network": "abcdefg12345.skadnetwork",
"campaign": "53",
"itunesitem": "1382171002",
"fidelities": [
{
"fidelity": 0,
"nonce": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"signature": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
"timestamp": "1702313222"
}
],
"sourceapp": "123456789",
"sourceidentifier": "sourceidentifier",
"productpageid": "productpageid",
"skoverlay": {
"present": 1,
"delay": 5,
"endcarddelay": 15,
"autoclose": 20,
"dismissible": 1,
"pos": 1
}
}
}
}
]
},
{
"seat": "abc1abc"
}
]
}
Sample Native Request
{
"id": "958e3f27-90f9-4183-be4f-bd350f7cc170",
"imp": [
{
"id": "46600265-e3a4-44dd-7114-49d21405cacf",
"native": {
"request": "{\"ver\":\"1.1\",\"plcmtcnt\":1,\"assets\":[{\"id\":1,\"data\":{\"type\":12}},{\"id\":2,\"required\":1,\"title\":{\"len\":100}},{\"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\":150}}]}",
"ver": "1.1"
},
"displaymanager": "HyBid",
"displaymanagerver": "2.0.0",
"tagid": "BANNER",
"bidfloor": 0.923,
"bidfloorcur": "USD",
"secure": 1,
"rwdd": 0
}
],
"app": {
"id": "1328764",
"name": "Countabc",
"bundle": "com.countabc",
"storeurl": "https://play.google.com/store/apps/details?id=com.countabc",
"cat": [
"IAB9"
],
"keywords": "games",
"ver": "10.1",
"publisher": {
"id": "1028",
"name": "Count LTD",
"domain": "https://countltd.com/support"
}
},
"device": {
"dnt": 0,
"ua": "Mozilla/5.0 (Linux; Android 5.0.2; LG-V500 Build/LRX22G; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/95.0.4638.74 Safari/537.36",
"ip": "8.8.8.8",
"geo": {
"lat": 40.2024,
"lon": -21.2939,
"country": "USA",
"region": "CA",
"city": "Mountain View",
"zip": "94040",
"type": 2
},
"carrier": "Mobile Carrier",
"language": "en",
"make": "Mobile",
"model": "Mobile Model",
"os": "Android",
"osv": "12",
"connectiontype": 2,
"devicetype": 1,
"ifa": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"gender": "m",
"keywords": "sports, paid user",
"ext": {
"sessionduration": 1439,
"impdepth": 123,
"agerating": "PG-13"
}
},
"source": {
"pchain": "d641df8625486a7b:1007950",
"ext": {
"schain": {
"ver": "1.0",
"complete": 1,
"nodes": [
{
"asi": "pubnative.net",
"sid": "1007950",
"rid": "2132da3ec6544048bf2d25c566d0dd49",
"hp": 1
}
]
},
"omidpn": "Pubnativenet",
"omidpv": "1.4.3"
}
},
"regs": {
"coppa": 0,
"ext": {
"gdpr": 0,
"consent": ""
}
},
"ext": {
"hb": 1,
"schain": {
"ver": "1.0",
"complete": 1,
"nodes": [
{
"asi": "pubnative.net",
"sid": "1008838",
"rid": "e81f99d2174b4f42ba4a0fadca1d12f6",
"hp": 1
}
]
},
"omidpn": "pubnativenet",
"omidpv": "1.4.8",
"pchain": "d641df8625486a7b:1008838"
},
"test": 0,
"at": 1,
"tmax": 1987,
"cur": [
"USD"
],
"badv": [
"blockedadv.com"
],
}
Sample Native Response
For a Native Bid Response, all Demand Side integrations must include the 'native' node within the ADM attribute.
{
"id": "d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
"bidid": "pbnvrtb-10048",
"cur": "USD",
"seatbid": [
{
"id": "1UARoaQytm",
"seat": "512",
"bid": [
{
"impid": "1a430de0-b222-412e-4c05-d6ab8115825a",
"price": 0.03134,
"nurl": "http://platform.com/winnotice?impid=123;wp=${AUCTION_PRICE}",
"burl": "http://platform.com/burl?impid=123;wp=${AUCTION_PRICE}",
"lurl": "http://platform.com/bidloss?lossreason=${AUCTION_LOSS}",
"id": "pbnvrtb-1004844-d7470a5f-1a75-4bf6-4c82-50abd49e8bb8",
"adm": "{ \"native\": { \"assets\" : [ { \"id\" : 2, \"title\" : { \"text\" : \"This is a sample\" } }, { \"id\" : 3, \"img\" : { \"w\" : 120, \"h\" : 90, \"url\" : \"https://platformimages.com/id=213214\" } }, { \"id\" : 4, \"img\" : { \"w\" : 1066, \"h\" : 800, \"url\" : \"https://platformimages.com/id=213214\" } }}",
"adomain": [
"advertiserdomain.com"
],
"cat": [
"IAB12"
],
"attr": [
1,
2,
3,
4
],
"w": 0,
"h": 0,
"crid": "ce572c",
"cid": "creative3395"
}
]
}
]
}