Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Changes per TW-893.

...

Expand
titleExpand for bidrequest.imp attributes...


Info
Each impression object can contain one object from each video/native/banner object, but PubMatic considers only a maximum of 2.    


AttributeTypeDescriptionScope
idStringA unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).Required
tagidString

Identifier for specific ad placement or ad tag that was used to initiate the auction.

Info
  • You can also use as PubMatic ad placement id or ad id. You must maintain the mapping of your publisher ad id to the PubMatic ad id.
  • You must send PubMatic ad id here.
  • You can also use as a slotname for wrapper/prebid. PubMatic maintains mapping to derive the PubMatic ad id from the slotname.


Optional
banner ObjectA banner object is required if this impression is offered as a banner ad opportunity. Optional
native ObjectA Native object; required if this impression is offered as a native ad opportunityOptional
video ObjectA Video object required if this impression is offered as a video ad opportunity.Optional
instlInteger1 = the ad is interstitial or full screen, 0 = not interstitial.Optional
bidfloorFloatMinimum bid for this impression expressed in CPM.OptionalRecommended
bidfloorcur StringCurrency specified using ISO-4217 alpha codes.OptionalRecommended

iframebuster

String ArrayArray of exchange-specific names of supported iframe busters.Optional
secureIntegerFlag 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 non-secure HTTP support can be assumed.OptionalRecommended
pmp ObjectA PMP Object containing any private marketplace deals in effect for this impression.Optional
metric Object arrayAn array of the Metric object.Optional
ext ObjectPlaceholder for exchange-specific extensions to OpenRTGOptional

Banner

Expand
titleExpand for bidrequest.imp.banner attributes...


AttributeTypeDescriptionScope
wIntegerWidth of the impression in pixels.Required
hIntegerHeight of the impression in pixels.Required
battrInteger ArrayBlocked creative attributes.Optional
posIntegerAd position on screen.Optional
topframeIntegerIndicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.Optional
expdirInteger ArrayDirections in which the banner may expand.Optional
formatObject Array

Array of format objects representing permitted banner sizes. Banner.w and banner.h are considered as primary width and height.

Limitation: 4 objects max.

Recommended
apiInteger Array

List of supported API frameworks for the impression. If an API si not explicitly listed, it is assumed not to be supported.

Info

In OpenRTB 2.1-2.5, the api attribute is now also used in support of the Open Measurement SDK.

Add 7 to the array of supported API frameworks if you use Open Measurement.

See List 5.6 API Frameworks in the IAB OpenRTB Advisory for Open Measurement SDK to learn more.


OptionalRecommended
Format
Expand
titleExpand for bidrequest.imp.banner.format attributes…


AttributeTypeDescriptionScope
wIntegerWidth in device independent pixels (DIPS).Required
hIntegerHeight in device independent pixels (DIPS).Required


Code Block
languagexml
titleBidRequest.imp.banner.format sample JSON
linenumberstrue
collapsetrue
{
	"id": "6503ED1F-B749-4215-9721-0EA5A7054F2F",
	"at": 1,
	"imp": [{
		"id": "1",
		"tagid": "904294",
		"bidfloor": 0.300000,
		"secure": 1,
		"banner": {
			"w": 300,
			"h": 250,
			"format": [{
				"w": 300,
				"h": 250
			}],
			"topframe": 1,
			"battr": [1, 3, 6, 7, 8, 9, 11],
			"btype": [1, 2]
		},
		"ext": {
			"headerbidding": {
				"present": 1
			}
		}
	}],
	"site": {
		"id": "173321",
		"cat": ["IAB10", "IAB10-4", "IAB9-30", "IAB25", "IAB1", "IAB9-20", "IAB25-2", "IAB19", "IAB1-6", "IAB9"],
		"page": "https://sonidossumergidosblog.wordpress.com/tag/post-punk/",
		"domain": "sonidossumergidosblog.wordpress.com",
		"mobile": 1,
		"publisher": {
			"id": "156078"
		}
	},
	"device": {
		"ip": "200.106.117.237",
		"lmt": 0,
		"ua": "Mozilla/5.0 (Linux; Android 9; moto g(7) power) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.92 Mobile Safari/537.36",
		"carrier": "Telefonica del Peru",
		"make": "Motorola",
		"os": "Android",
		"osv": "2.0",
		"js": 1,
		"geo": {
			"country": "PER",
			"region": "lma",
			"city": "lima",
			"metro": "-1",
			"zip": "15000"
		},
		"geofetch": 0,
		"ext": {
			"xff": "10.100.129.33",
			"res": "-1x-1",
			"freq": 0,
			"pf": 2
		}
	},
	"user": {
		"id": "DB389E6A-8559-46FB-A0AD-999D51B017CB",
		"buyeruid": "1oKWGtqMrMmZx1A9VcdW",
		"geo": {
			"country": "per"
		},
		"eids": [{
			"source": "adserver.org",
			"uids": [{
				"id": "8bb26040-d46c-4a47-ab6e-df1e94215ae4",
				"ext": {
					"rtiPartner": "TDID"
				}
			}]
		}],
		"ext": {
			"eids": [{
				"source": "adserver.org",
				"uids": [{
					"id": "8bb26040-d46c-4a47-ab6e-df1e94215ae4",
					"ext": {
						"rtiPartner": "TDID"
					}
				}]
			}]
		}
	},
	"bcat": ["IAB5-2", "IAB25-3", "IAB25-2", "IAB26", "IAB25-5", "IAB25-4", "IAB9-9"],
	"source": {
		"fd": 1,
		"pchain": "5d62403b186f2ace:156078",
		"ext": {
			"schain": {
				"complete": 0,
				"ver": "1.0",
				"nodes": [{
					"asi": "pubmatic.com",
					"sid": "156078",
					"rid": "6503ED1F-B749-4215-9721-0EA5A7054F2F",
					"hp": 1
				}]
			}
		}
	}
}



Native

Expand
titleExpand for bidrequest.imp.native attrbutes...


AttributeTypeDescriptionScope
requestString

Request payload complying with the Native Ad Specification 1.1: https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf 

Required
verStringVersion of the Native Ad Specification to which request complies; best practice for efficient parsing.Optional
apiInterger array

List of supported API frameworks for the impression. If an API si not explicitly listed, it is assumed not to be supported.

Info

In OpenRTB 2.1-2.5, the api attribute is now also used in support of the Open Measurement SDK.

Add 7 to the array of supported API frameworks if you use Open Measurement.

See List 5.6 API Frameworks in the IAB OpenRTB Advisory for Open Measurement SDK to learn more.

If you are using Native ads with the eventtrackers object, see Specific Guidance for Native Ads in the IAB OpenRTB Advisory for Open Measurement SDK documentation.


Optional


Info
titleTo learn more about native request and response details see…

https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf.


Video

Expand
titleExpand for bidrequest.imp.video attrbutes......


AttributeTypeDescriptionScope
protocolInteger


Info
Deprecated in favor of protocols.

Supported video protocol. You must specify at least one supported protocol in either the protocol or protocols attribute.


protocolsInteger

Array of supported video protocols. You must specify a t least one supported protocol in either the protocol or protocols attribute.

Required
mimesString Array


Content MIME types supported for media files. Common video MIME types may include "video/mp4," while "application/javascript" applies to VPAID creatives.

Supported mime types:

  • video/mp4
  • application/x-shockwave-flash (used for VPAID - FLASH)
  • video/wmv
  • video/h264
  • video/webm
  • application/javascript (used for VPAID - JS)
  • video/ogg
  • video/flv (used for Flash Video)
  • video/3gpp
  • video/quicktime
  • video/mpeg
  • application/x-mpegURL
Required
linearityIntegerIndicates if the impression is linear or nar. 1=Linear/In-Stream and 2=Non-Linear/Overlay.Best Practice
mindurationIntegerMinimum video ad duration in secondsRequired
maxdurationInteger

Maximum video ad duration in seconds. 

Required
protocol
Video bid response protocols supported. (See Table 5.8 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf )
apiInteger Array

API frameworks supported (See Table 5.6 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf ).

Info

In OpenRTB 2.1-2.5, the api attribute is now also used in support of the Open Measurement SDK.

Add 7 to the array of supported API frameworks if you use Open Measurement.

See List 5.6 API Frameworks in the IAB OpenRTB Advisory for Open Measurement SDK to learn more.


Required (if VPAID inventory)
wIntegerWidth of the video player in pixels.Required
hIntegerHeight of the video player in pixels.Required
startdelayIntegerIndicates the start delay in seconds for pre-roll, mid-roll, or
post-roll ad placements. 
Best Practice (If In-Stream)
placementInteger

Placement type for the impression as specified by oRTB 2.5 (Table 5.9). Should be used to distinguish between in-stream and out-stream inventory. 

Possible integer values:

  • 1 - In-Stream   (Played before, during or after the streaming video content that the consumer has requested: Pre-roll, Mid-roll, Post-roll).
  • 2 - In-Banner   (Exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on  the page for its delivery.)
  • 3 - In-Article    (Loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message.)
  • 4 - In-Feed       (Found in content, social, or product feeds.)
  • 5 - Interstitial/Slider/Floating     (Covers the entire or a portion of screen area, but is always on screen while displayed - i.e. cannot be scrolled out of view).
Best Practice
maxbitrateIntegerMaximum bit rate in Kbps.Best Practice for mobile
playbackmethodInteger arrayDefines whether inventory is user-initiated or autoplay sound on/off. (See Table 5.9 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf )Best Practice
skipIntegerIndicates if the player will allow the video to be skipped, where 0 = no, 1 = yes.Optional
skipminIntegerVideos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.Optional
skipafterIntegerNumber of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.Optional
posIntegerAd position on the page. (See Table 5.4 in https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf)Optional
battrInteger arrayBlocked creative attributes.Optional
ext ObjectPlaceholder for exchange-specific extensions to OpenRTBOptional
Video.ext
AttributeTypeDescriptionScope
video_skippableIntegerIndicator for ability to skip video 0/1.Best Practice


PMP

Expand
titleExpand for bidrequest.imp.pmp attrbutes......


Warning

PubMatic must first turn on a publisher-level flag before you can start passing a deal object in the ad request. Contact your account manager to enable this flag.


AttributeTypeDescriptionScope
dealsObject ArrayArray of deal objects (50 max), that convey the specific deals applicable to an impression.Optional


Metric

Expand
titleExpand for bidrequest.imp.metric attrbutes......


AttributeTypeDescriptionScope
typeStringType of metric being presented using exchange-curated string names, which should be published to derived biddersRequired
valueFloatNumber representing the value of the metric. Probabilities must be in the range of 0.0 - 1.0.Required
vendorStringSource 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.Best Practice


Imp.ext

Expand
titleExpand for bidrequest.imp.ext attrbutes......


AttributeTypeDescriptionScope
pmZoneIdStringUsed to pass zone ID for reporting.Optional
viewabilityvendorsString arrayContains a list of viewability vendors supported by publishersOptional
testcridString
  • If bidrequest.test=1 and testcrid is valid, the testcrid creative passed will be served.
  • if bidrequest.test=1 and testcrid is absent, the creative in the DB configuration will be served.
  • if bidrequest.test=1 and testcrid is invalid 204 (no content), nothing will be served.
  • if bidrequest.test=0, the request will be treated as live and testcrid will not have any significance.
Optional



...

AttributeTypeDescriptionScope
uaStringBrowser user agent string.Optional
dntIntegerStandard "Do Not Track" flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not trackOptional
devicetypeIntegerThe general type of device. See List 5.17 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf.Required for CTV publishers
makeStringDevice make; for example, "Apple".Optional
modelStringDevice model; for example, "iPhone".Optional
osStringDevice operating system; for example, "iOS".Optional
osvStringDevice operating system version; for example, "3.1.2".Optional
jsIntegerSupport for JavaScript, where 0=no, 1=yes.Optional
languageStringBrowser language using ISO-639-1-alpha-2.Optional
geoObjectLocation of the device assumed to be the user's current location defined by a Geo object. This will be given lower priority in respect to user.geo object.Optional
IpStringIPv4 address closest to device as IPv6. Either of ip/ipv6 is required.Required
Ipv6StringIP address closest to device as IPv6. Either of ip/ipv6 is required.Required
ifaStringID sanctioned for advertiser use in the clear; that is, not hashed.OptionalRecommended
didsha1StringHardware device ID ; for example, IMEI; hashed via SHA1.Optional
didmd5StringHardware device ID; for example, IMEI; hashed via MD5.Optional
dpidsha1StringPlatform device ID (for example, Android ID), hashed via SHA1.Optional
dpidmd5StringPlatform device ID (for example, Android ID), hashed via MD5.Optional

...

AttributeTypeDescriptionScope
latFloatLatitude from -90.0 to +90.0, where negative is southHighly Recommended
lonFloatLongitude from -180.0 to +180.0, where negative is west.Highly Recommended
typeIntegerSource of location data; recommended when passing lat/lon.OptionalRecommended
countryStringCountry code using ISO-3166-1-alpha-3.Optional
regionStringRegion code using ISO-3166-2; 2-letter state code if USAOptional
metroStringGoogle metro code; similar to but not exactly Nielsen DMAs.Optional
cityStringCity using United Nations Code for Trade & Transport Locations. It must not be encoded.Optional
zipStringZip or postal codeOptional
utcoffsetIntegerLocal time as the number +/- of minutes from UTCOptional

...

AttributeTypeDescriptionScope
buyeruid StringBuyer-specific ID for the user as mapped by the exchange for the buyer; recommended when PubMatic user ID exists.OptionalRecommended
yob IntegerYear of birth as a 4-digit integer.Optional
genderStringGender, where "M" = male, "F" = female, "O" = known to be other (i.e., omitted is unknown).Optional
geoObjectLocation of the user's home base defined by a Geo object. This is not necessarily their current location. This will be given higher preference over device.geo  objectOptional
idStringExchange-specific ID for the user. At least one of id or buyerid is recommended. Buyerid will be preferred by PubMatic.Optional
eidsObject Array

An array of Extended ID objects.

Info
First 3 valid objects are used and the rest discarded


Optional
extObjectPlaceholder for exchange-specific extensions to OpenRTBOptional

...