OpenRTB 2.5 Specifications

3.2 Object Specification

The subsections that follow define each of the objects in the bid request model. Several conventions are used throughout:

  • Attributes are “required” if their omission would technically break the protocol.
  • Some optional attributes are denoted “recommended” due to their elevated business importance.
  • Unless a default value is explicitly specified, an omitted attribute is interpreted as “unknown”.

3.2.1 Object: BidRequest

The top-level bid request object contains a globally unique bid request or auction ID. This ID attribute is required as is at least one impression object (Section 3.2.4 – IAB OpenRTB 2.5).

Other attributes in this top-level object establish rules and restrictions that apply to all impressions being offered. There are also several subordinate objects that provide detailed data to potential buyers. Among these are the Site and App objects, which describe the type of published media in which the impression(s) appear. These objects are highly recommended, but only one applies to a given bid request depending on whether the media is browser-based web content or a non-browser application, respectively.

Field Scope Type Default Description Smaato Mapping
id required string Unique ID of the bid request, provided by the exchange. Random alphanumeric value.
imp required objects array An array of imp objects representing the impressions offered. At least 1 Imp object is required. Imp object
site recommended for websites object Details via a site object about the publisher’s website. Only applicable and recommended for websites. Site object
app recommended for native apps object Details via an app object about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps. App object
device recommended object Details via a device object about the user’s device to which the impression will be delivered. Device object
user recommended object Details via a user object about the human user of the device; the advertising audience. User object
test optional integer 0 Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode N/A
at optional integer 2

Auction type, where 1 = First Price (can be used if publisher and DSP both support it) and 2 = Second Price plus. Exchange-specific auction types can be defined using values greater than 500.

None – if Line Item is Preferred Deal

2 (Second Price Auction) – in other cases

tmax optional integer

Maximum time in milliseconds to submit a bid to avoid timeout. It is mapped to the remaining time until the auction is timed out. 

Note: This value is commonly communicated offline.

N/A
wseat optional string array Whitelist of buyer seats (e.g., advertisers, agencies) allowed to bid on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. Omission implies no seat restrictions. White list of demand partners Line Item seat IDs
bseat optional string array Block list of buyer seats (e.g., advertisers, agencies) restricted from bidding on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. At most, only one of wseat and bseat should be used in the same request. The omission of both implies no seat restrictions. N/A
allimps optional integer 0 Flag to indicate if the exchange can verify that the impressions offered to 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 to represent all that is available. 0
cur optional string array The array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies. N/A
wlang optional string array White list of languages for creatives using ISO-639-1-alpha-2. Omission implies no specific restrictions, but buyers would be advised to consider language attribute in the device and/or content objects if available. N/A
bcat optional string array Blocked advertiser categories using the IAB content categories.

It contains a combination of 3 sources of blocked categories:

  1. Blocked categories from publisher Line Item
  2. Blocked categories from a global level
  3. Blocked categories from Configuration in Database (OpenRTBBlockedIabCategories property)
badv optional string array

Block list of advertisers by their domains.

Please Note: badvlists also come from global and line item settings, similar to bcat. The only difference is that bcat has an additional configuration value of OpenRTBBlockedIabCategories.

Blocked domains from publisher Line Item e.g. company1.com, company2.com.
bapp optional string array

Blocklist of applications by their platform-specific exchange independent application identifiers. On Android, these should be bundle or package names (e.g., com.foo.mygame). On iOS, these are numeric IDs.

Please Note: bapp lists also come from global and line item settings, similar to bcat. The only difference is that bcat has an additional configuration value of OpenRTBBlockedIabCategories.

Blocked applications from publisher Line Item
source optional object A source object that provides data about the inventory source and which entity makes the final decision. Source object
regs optional object A regs object that specifies any industry, legal, or governmental regulations in force for this request. Regulations object
ext optional object Placeholder for exchange-specific extensions to OpenRTB. Bid Request Extension object

3.2.2 Object: Source

This object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. The primary purpose of this object is to define post-auction or upstream decisioning when the exchange itself does not control the final decision. A common example of this is header bidding, but it can also apply to upstream server entities such as another RTB exchange, a mediation platform, or an ad server combines direct campaigns with 3rd party demand decisioning.

Field Scope Type Default Description Smaato Mapping
fd recommended Integer The entity is responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source. N/A
tid recommended string Transaction ID that must be common across all participants in this bid request (e.g., potentially multiple exchanges). N/A
pchain recommended string Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0.

In case Smaato starts the chain we send <Smaato Intermediary ID>:<Hashed Publisher ID>

In the case where Smaato reviews the, pchain, we append Smaato a tag to it and propagate

ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.3 Object: Regs

This object contains any legal, governmental, or industry regulations that apply to the request. The coppa flag signals whether or not the request falls under the United States Federal Trade Commission’s regulations for the United States Children’s Online Privacy Protection Act (“COPPA”).

Field Scope Type Default Description Smaato Mapping
coppa optional integer Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes. 0 or 1
ext optional object Exchange-specific extensions to OpenRTB.

Contains a flag that signals if a request is or is not subject to GDPR:

  • 0 = No
  • 1 = Yes

3.2.4 Object: Imp 

This object describes an ad placement or impression being auctioned. A single bid request can include multiple Imp objects, a use case for which might be an exchange that supports selling all ad positions on a given page. Each Imp object has a required ID so that bids can reference them individually.

The presence of Banner (Section 3.2.6), Video (Section 3.2.7), and/or Native (Section 3.2.9) objects subordinate to the Imp object indicates the type of impression being offered. The publisher can choose one such type which is the typical case or mix them at their discretion. However, any given bid for the impression must conform to one of the offered types.

Field Scope Type Default Description Smaato Mapping
id required string A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).

id can be more than 1.

In the case of Interstitial Multi-Ad Format, Smaato can send

  1. One impression object with banner and video
  2. Two impression objects, one with banner and another with video
  3. Two bid requests

In the second case, there are two impression objects.

metric optional object array An array of metric objects, e.g. see OpenRTB 2.5 Specifications Viewability score if enabled for inventory and DSP
banner required for banner impressions object A banner object required if this impression is offered as a banner ad opportunity. banner object
video required for video impressions object A video object required if this impression is offered as a video ad opportunity. video object
audio required for audio impressions object An audio object required if this impression is offered as an audio ad opportunity N/A
native required for native impression object A native object required if this impression is offered as a native ad opportunity. Native object
pmp optional object A pmp object containing any private marketplace deals in effect for this impression. Pmp object
displaymanager recommended for video and native apps string The name of the ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad Servers to customize ad code by the partner. Recommended for video and/or apps. This value is SOMA. SOMA stands for Smaato Open Mobile Advertising.
displaymanagerver recommended for video and native apps string The version of the ad mediation partner, SDK technology, or player responsible for rendering the ad(typically video or mobile). Used by some ad servers to customize ad code by the partner. Recommended for video and/or apps. If the ad request comes thru an SDK, the SDK version will be denoted; otherwise, this field will be empty.
instl optional integer 0 1 = the ad is interstitial or full screen, 0 = not interstitial.

1 if publisher requests for either

  1. Interstitial video
  2. Rewarded video
  3. Fullscreen banner
tagid optional string An identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer. The ad request’s Adspace ID (or placement ID) is transmitted here.
bidfloor optional float 0 The minimum bid for this impression expressed in CPM. It can be sent depending on the DSP configuration. It is mapped to the SPX line item floor price.
bidfloorcur optional string USD Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange. Smaato only transacts on USD.
clickbrowser optional integer Indicates the type of browser opened upon clicking the creative in an app, where 0 = embedded, 1 = native. Note that the Safari View Controller in iOS 9.x devices is considered a native browser for purposes of this attribute. N/A
secure optional int 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 non-secure HTTP support can be assumed.
  • if publisher request is secure (e.g. dfp request)
  • 0 for non secure request
iframebuster optional string array The array of exchange-specific names of supported iframe busters. N/A
exp optional integer Advisory as to the number of seconds that may elapse between the auction and the actual impression.  N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB. Impression Extension object

3.2.5 Object: Metric

 This object is associated with an impression as an array of metrics. These metrics can offer insight into the impression to assist with decisioning such as average recent viewability, click-through rate, etc. Each metric is identified by its type, reports the value of the metric, and optionally identifies the source or vendor measuring the value.

Field Scope Type Default Description Smaato Mapping
type required string Type of metric being presented using exchange curated string names which should be published to bidders a priori. One type is supported: “viewability”
value required float The number representing the value of the metric. Probabilities must be in the range of 0.0 – 1.0. Viewability value
vendor recommended string 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. Viewability vendor
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.6 Object: Banner

This object represents the most general type of impression. Although the term “banner” may have a very specific meaning in other contexts, here it can be many things including a simple static image, an expandable ad unit, or even in-banner video (refer to the Video object in Section 3.2.7 for the more generalized and full-featured video ad units). An array of Banner objects can also appear within the Video to describe optional companion ads defined in the VAST specification.

The presence of a Banner as a subordinate of the Imp object indicates that this impression is offered as a banner type impression. At the publisher’s discretion, that same impression may also be offered as video, audio, and/or native by also including as Imp subordinates objects of those types. However, any given bid for the impression must conform to one of the offered types.

Field Scope Type Default Description Smaato Mapping
w recommended integer Width in device independent pixels (DIPS). If no format objects are specified, this is an exact width requirement. Otherwise, it is a preferred width.
  • 0 for Native Ad requests
  • Otherwise, they are mapped to either normalized or effective banner dimension size
h recommended integer Height in device independent pixels (DIPS). If no format objects are specified, this is an exact height requirement. Otherwise, it is a preferred height.
  • 0 for Native Ad requests
  • Otherwise, they are either normalized or effective banner dimension size
format recommended object array The array of format objects representing the banner sizes permitted. If none are specified, then the use of the h and w attributes is highly recommended. Array with single format object
wmax DEPRECATED integer NOTE: Deprecated in favor of the format array. Maximum width in device independent pixels (DIPS). N/A
hmax DEPRECATED integer NOTE: Deprecated in favor of the format array. Maximum height in device independent pixels (DIPS). N/A
wmin DEPRECATED integer NOTE: Deprecated in favor of the format array. Minimum width in device independent pixels (DIPS). N/A
hmin DEPRECATED integer NOTE: Deprecated in favor of the format array. Minimum height in device independent pixels (DIPS). N/A
id recommended when subordinate to a video object string Unique identifier for this 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. N/A
btype optional integer array All types are allowed Blocked banner ad types. Refer to Banner Ad Types.

All the following values:

  1. XHTMLTextAd
  2. XHTMLBannerAd
  3. XHTMLJavaScriptAd

Except for supported creative type by ad type. Refer to the mapping of supported ad types in Banner Ad Types.

battr optional integer array All types are allowed

Blocked creative attributes. Refer to Creative Attributes.

Please Note: battr lists also come from global and line item settings, similar to bcat. The only difference is that bcat has an additional configuration value OpenRTBBlockedIabCategories.

battr values come from:

  1. Line Item
  2. Request parameter in case of E2E
  3. PAX
pos optional integer Ad position on the screen. Refer to Ad Position.

Ad Position from Adspace.

Refer to Ad Position.

mimes optional string array All types are allowed Content MIME types supported. Popular MIME types may include “application/x-shockwave-flash”, “image/jpg”, and “image/gif”. Are from publisher request format and dsp supported mimes settings.

If the banner ad is supported then MIMEs supported are:

  • image/jpeg
  • image/png
  • image/gif

If the javascript ad is supported then MIMEs supported are:

  • text/javascript
  • application/javascript
topframe optional integer Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes N/A
expdir optional integer array Not expandable

Directions in which the banner may expand. Refers to the Expandable Direction.

N/A
api optional integer array List of supported API frameworks for this banner. (See Table 6.4 API Frameworks).  If an API is not explicitly listed it is assumed not to be supported.

For Video and Rich media requests:

  • mraid1=MRAID-1
  • mraid2=MRAID-1, MRAID-2
  • mraid3=MRAID-1, MRAID-2, MRAID-3
vcm optional integer Relevant only for banner objects used with a video object in an array of companion ads. Indicates the companion banner rendering mode relative N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.7 Object: Video

This object represents an in-stream video impression. Many of the fields are non-essential for minimally viable transactions but are included to offer fine control when needed. Video in OpenRTB generally assumes compliance with the VAST standard. As such, the notion of companion ads is supported by optionally including an array of Banner objects (refer to the Banner object in Section 3.2.6) that define these companion ads.

The presence of a Video as a subordinate of the Imp object indicates that this impression is offered as a video type impression. At the publisher’s discretion, that same impression may also be offered as banner, audio, and/or native by also including as Imp subordinates objects of those types. However, any given bid for the impression must conform to one of the offered types.

Field Scope Type Default Description Smaato Mapping
mimes required string array Content MIME types supported. Popular MIME types may include “video/x-ms-wmv” for Windows Media and “video/x-flv” for Flash Video.

iOS with VPAID2:

  • video/3gpp,
  • video/mov,
  • video/mp4,
  • video/mpv,
  • application/javascript

iOS without VPAID2:  

  • video/3gpp,
  • video/mov,
  • video/mp4,
  • video/mpv

Others with VPAID2:  

  • video/mp4,
  • video/3gpp,
  • application/javascript

Others without VPAID2:

  • video/mp4,
  • video/3gpp
minduration required integer Minimum video ad duration in seconds.

Set at 5 by default.

It can be overridden by E2E request parameters.

maxduration required integer Maximum video ad duration in seconds.

Set at 60 by default.

It can be overridden by Ex2Ex request parameters.

protocols recommended integer array The array of supported video protocols. At least one supported protocol must be specified in either the protocol or protocols attribute. We send values 2 (for VAST 2.0) and 5 (for VAST Wrapper 2.0).
protocol DEPRECATED integer NOTE: Deprecated in favor of protocols. Supported video protocol. Refer to Video Bid Response Protocols. At least one supported protocol must be specified in either the protocol or protocols attribute.

VAST version 2: Smaato sends VAST 2.0, VAST 2.0 wrapper

VAST version 3: Smaato sends VAST 2.0, VAST 2.0 wrapper, VAST 3.0, VAST 3.0 wrapper

VAST version 4: Smaato sends VAST 2.0, VAST 2.0 wrapper, VAST 3.0, VAST 3.0

(see Open RTB protocols list)

w recommended integer Width of the video player in device independent pixels (DIPS).
  • 0 if native ad requested
  • if not a native ad contains banner width, then see SOMA Banner Dimension
h recommended integer Height of the video player in device independent pixels (DIPS).
  • 0 if Native Ad requested
  • if not a Native ad contains banner height see SOMA Banner Dimension
startdelay recommended integer Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to Video Start Delay for additional generic values.
  • 0 (pre-roll), when  videotype=instream-pre
  • 1 (mid-roll), when videotype=instream-mid
  • -2 (post-roll), when videotype=instream-post
placement optional integer Placement type for the impression
  • InstreamMid = In-Stream
  • InstreamPost = In-Stream
  • InstreamPre = In-Stream
  • Interstitial = Interstitial
  • Rewarded = Interstitial
  • Outstream = In-Article
linearity optional integer Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed. Refer to Video Linearity. Default set to LinearInStream (‘1’). Can be overridden by API parameter ‘linearity’
skip optional integer Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. If a bidder sends markup/creative that is itself skippable, the Bid object should include the attr array with an element of 16 indicating skippable video.

Flag from Adspace if video is skippable or not.

  • 0 – a player can NOT allowvideo skip 
  • 1 – a player can allow to skip video
skipmin optional integer 0 Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable. N/A
skipafter optional integer 0 Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable. N/A
sequence optional integer

If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.

 

N/A
battr optional integer array Assume all types are allowed

Blocked creative attributes. Refer to Creative Attributes.

battr values come from:

  1. Line Item
  2. Request parameter in case of E2E
  3. PAX
maxextended optional integer Extension not allowed

Maximum extended ad duration if an extension is allowed.

  • If blank or 0, an extension is not allowed.
  • If -1, an 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 max duration value.
N/A
minbitrate optional integer 250 Minimum bit rate in Kbps.

Set at 250 by default.

It can be overridden by Ex2Ex request parameters.

maxbitrate optional integer 4000 Maximum bit rate in Kbps.

Set at 4000 by default.

It can be overridden by Ex2Ex request parameters.

boxingallowed optional integer 1 Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes. N/A
playbackmethod optional integer array All Playback methods that may be in use. If none are specified, any method may be used. Refer to Video Playback Methods. Only one method is typically used in practice. As a result, this array may be converted to an integer in a future version of the specification. N/A
playbackend optional integer   The event that causes playback to end. N/A
delivery optional integer array All Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. Refer to Content Delivery Methods. N/A
pos optional integer  Ad position on the screen. Refer to Ad Position.

Ad Position from Adspace

See Ad Position.

companionad optional objects array The array of Banner objects if companion ads are available. Mapped to a list of companion ad dimensions from SPX.
api optional integer array List of supported API frameworks for this impression. (See Table 6.4 API Frameworks).  If an API is not explicitly listed it is assumed not to be supported. List of APIs from Adspace video
companiontype optional integer array Supported VAST companion ad types. Refer to VAST Companion Types. Recommended if companion Banner objects are included via the companionad array.

Mapped to a list of companion ad types from SPX.

ext optional object Place holder for exchange-specific extensions to OpenRTB. It contains information if video type is rewarded or Outstream. In other cases, SOMA doesn’t send ext object.

3.2.8 Object: Audio

This object represents an audio type impression. Many of the fields are non-essential for minimally viable transactions but are included to offer fine control when needed. Audio in OpenRTB generally assumes compliance with the DAAST standard. As such, the notion of companion ads is supported by optionally including an array of Banner objects (refer to the Banner object in Section 3.2.6) that define these companion ads.

The presence of Audio as a subordinate of the Imp object indicates that this impression is offered as an audio type impression. At the publisher’s discretion, that same impression may also be offered as banner, video, and/or native by also including as Imp subordinates objects of those types. However, any given bid for the impression must conform to one of the offered types.

Field Scope Type Default Description Smaato Mapping
mimes required string array Content MIME types supported (e.g., “audio/mp4”). N/A
minduration recommended integer Minimum audio ad duration in seconds. N/A
maxduration recommended integer Maximum audio ad duration in seconds. N/A
protocols recommended integer array The array of supported audio protocols. N/A
startdelay recommended integer Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. N/A
sequence optional integer Integer. N/A
battr optional integer array Blocked creative attributes. N/A
maxextended optional integer Maximum extended 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. N/A
minbitrate optional integer Minimum bit rate in kbps. N/A
maxbitrate optional integer Maximum bit rate in kbps. N/A
delivery optional integer array List of supported API frameworks for this impression. Refer to List 5.6 in the OpenRTB specification. If an API is not explicitly listed, it is assumed not to be supported. N/A
companiontype optional integer array Supported DAAST companion ad types. Refer to List 5.14 in the OpenRTB specification. Recommended if companion Banner objects are included via the companionad array. N/A
maxseq optional integer The maximum number of ads that can be played in an ad pod. N/A
feed optional integer Type of audio feed. Refer to List 5.16 in the OpenRTB specification. N/A
stitched optional integer Indicates if the ad is stitched with audio content or delivered independently, where 0 = no, 1 = yes. N/A
nvol optional integer Volume normalization mode. Refer to List 5.17 in the OpenRTB specification. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.9 Object: Native

This object represents a native type impression. Native ad units are intended to blend seamlessly into the surrounding content. As such, the response must be well-structured to afford the publisher fine-grained control over rendering. The Native Subcommittee has developed a companion specification to OpenRTB called the Dynamic Native Ads API. It defines the request parameters and response markup structure of native ad units. This object provides the means of transporting request parameters as an opaque string so that the specific parameters can evolve separately under the auspices of the Dynamic Native Ads API. Similarly, the ad markup served will be structured according to that specification.

The presence of a Native as a subordinate of the Imp object indicates that this impression is offered as a native type impression. At the publisher’s discretion, that same impression may also be offered as banner, video, and/or audio by also including as Imp subordinates objects of those types. However, any given bid for the impression must conform to one of the offered types.

Field Scope Type Default Description Smaato Mapping
request required String Request payload complying with the Native Ad Specification. For more details see Native.request below.
ver recommended String 1.1 The version of the dynamic native ads API to which request complies; highly recommended for efficient parsing. We’ll send the value according to the latest standard; currently 1.1.
api optional array of integer None List of supported API frameworks for this banner. (See Table 6.4 API Frameworks). If an API is not explicitly listed, it is assumed not to be supported.

Depends on the MRAID version that the publisher is requesting:

  • MRAID 1 –> [3]
  • MRAID 2 –> [3, 5]
battr optional array of integer All types are allowed Blocked creative attributes. See Table 5.3 Creative Attributes. If blank, assume all types are allowed.

battr values come from:

  1. Line Item
  2. Request parameter in case of E2E
  3. PAX
ext optional object Placeholder for exchange-specific extensions to OpenRTB. Not mapped to any value

3.2.10 Object: Format

Field Scope Type Description Smaato Mapping
w recommended integer Width in device independent pixels (DIPS).  
h recommended integer Height in device independent pixels (DIPS).  
wratio optional integer Relative width when expressing size as a ratio N/A
hratio optional integer Relative height when expressing size as a ratio. N/A
wmin optional integer The minimum width in device independent pixels (DIPS) at which the ad will be displayed the size is expressed as a ratio. N/A
ext optional Object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.11 Object: Pmp

This object is the private marketplace container for direct deals between buyers and sellers that may pertain to this impression. The actual deals are represented as a collection of Deal objects. Refer to Section 7.3 for more details.

Field Scope Type Default Description Smaato Mapping
private_auction optional integer 1

Indicator of auction eligibility to seats named in a “direct deal” object;

  • when 0 = then all bids are accepted
  • when 1 = then bids are restricted to the deals specified and the terms thereof.
Always 1 – private auction
deals optional objects array An array of deal objects that convey the specific deals applicable to this impression. See Direct Deals Object
ext optional object This object is a placeholder that may contain custom JSON agreed by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification. N/A

3.2.12 Object: Deal

This object constitutes a specific deal that was struck a priori between a buyer and a seller. Its presence with the Pmp collection indicates that this impression is available under the terms of that deal. Refer to Section 7.3 for more details.

Field Scope Type Default Description Smaato Mapping
id required string A unique identifier for the direct deal. Deal ID
bidfloor optional float 0 Bid floor for this impression (in CPM of bidfloorcur). Floor price
bidfloorcur optional string USD If bid floor is specified and multiple currencies supported per bid request, then currency should be specified here using ISO-­-4217 alphabetic codes. Note, this may be different from bid currency returned by bidder, if this is allowed on an exchange. USD
at optional integer Auction type. If “1”, then first price auction. If “2”, then second price auction. If “3”, the passed bidfloor indicates the a priori agreed upon deal price. Additional auction types can be defined as per the exchange’s business rules.
  • SecondPrice(2) for PrivateExchange
  • AgreedDealPrice(3) for PreferredDeal
wseat optional string array The array of buyer seats allowed to bid on this  Direct Deal. Seats are an optional feature of an exchange. For example,  (“4”,”34”,”82”,”45”) indicates that only advertisers using these exchange seats are allowed to bid on this direct deal. White list of demand partners seats IDs
wadomain optional string array The array of advertiser domains allowed to bid on this Direct Deal. For example, (“advertiser1.com”,”advertiser2.com”) indicates that only the listed advertisers are allowed to bid on this direct deal. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.13 Object: Site

This object should be included if the ad supported content is a website as opposed to a non-browser application. A bid request must not contain both a Site and an App object. At a minimum, it is useful to provide a site ID or page URL, but this is not strictly required.

Field Scope Type Default Description Smaato Mapping
id recommended string Exchange-specific site ID. Application ID of the ad request.
name optional string Site name (may be masked at publisher’s request). Adspace name.
domain optional string Domain of the site, used for advertiser side blocking. For example, “foo.com”. Mapped to the domain page url from SPX
cat optional string array Array of IAB content categories of the site.  Array of IAB categories.
sectioncat optional string array Array of IAB content categories that describe the current section of the site.  N/A
pagecat optional string array Array of IAB content categories that describe the current page or view of the site.  N/A
page optional string URL of the page where the impression will be shown. Mapped to referer from header or publisher request
ref optional string Referrer URL that caused navigation to the current page. Mapped to referer from header or publisher request
search optional string Search string that caused navigation to the current page. Query string
mobile optional integer Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes N/A
privacypolicy optional integer Specifies whether the site has a privacy policy. “1” means there is a policy. “0” means there is not. N/A
publisher optional object Details about the publisher of the site. See Publisher Object
content optional object Details about the content within the site. N/A
keywords optional string Comma-separated list of keywords about the site. Alternate Representation: string array. Keyword list.
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.14 Object: App

This object should be included if the ad supported content is a non-browser application (typically in mobile) as opposed to a website. A bid request must not contain both an App and a Site object. At a minimum, it is useful to provide an App ID or bundle, but this is not strictly required.

Field Scope Type Default Description Smaato Mapping
id recommended string Application ID on the exchange. Application ID
name optional string Application name (may be masked at publisher’s request). App name (blank if hidden).
bundle optional 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. Bundle ID.
domain optional string The domain of the application (e.g., “mygame.foo.com”). URL
storeurl optional string For QAG 1.5 compliance, an app store URL for an installed app should be passed in the bid request. App store URL.
cat optional string array The array of IAB content categories for the overall application. Array of IAB categories.
sectioncat optional string array The array of IAB content categories for the current subsection of the app.  N/A
pagecat optional string array The array of IAB content categories for the current page/view of the app. N/A
ver optional string Application version. N/A
privacypolicy optional integer Indicates if the app has a privacy policy, where 0 = no, 1 = yes. N/A
paid optional integer “1” if the application is a paid version; else “0” (i.e., free). N/A
publisher optional object Details about the publisher. See Publisher Object
content optional object Details about the content N/A
keywords optional string List of keywords describing this app in a  comma separated string. Alternate Representation: string array. Keyword list.
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.15 Object: Publisher

This object describes the publisher of the media in which the ad will be displayed. The publisher is typically the seller in an OpenRTB transaction.

Field Scope Type Default Description Smaato Mapping
id optional string Publisher ID on the exchange. Publisher ID.
name optional string Publisher name (may be masked at publisher’s request). Publisher name (blank if hidden).
cat optional string array The array of IAB content categories for the publisher.  N/A
domain optional string Publisher’s highest level domain name, for example “foopub.com”. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB N/A

3.2.16 Object: Content

This object describes the content in which the impression will appear, which may be syndicated or non-syndicated content. This object may be useful when syndicated content contains impressions and does not necessarily match the publisher’s general content. The exchange might or might not have knowledge of the page where the content is running, as a result of the syndication method. For example, there might be a video impression embedded in an iframe on an unknown web property or device.

Field Scope Type Default Description Smaato Mapping
id optional string The unique ID used to identify the content N/A
episode optional integer Content episode number (typically applies to video content). N/A
title optional string Content title.
Video examples: “Search Committee” (television) or “A New Hope” (movie) or “Endgame” (made for web)
Non-­‐video example:  “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article)
N/A
series optional string Content series.
Video examples: “The Office” (television) or “Star Wars” (movie) or “Arby ‘N’ The Chief” (made for web)
Non-­‐video example: “Ecocentric” (Time magazine blog)
N/A
season optional string Content season. e.g., “Season 3” (typically applies to video content). N/A
artist optional string Artist credited with the content. N/A
genre optional string Genre that best describes the content (e.g., rock, pop, etc). N/A
album optional string Album to which the content belongs; typically for audio. N/A
isrc optional string International Standard Recording Code conforming to ISO3901. N/A
producer optional string Details about the content producer. N/A
url optional string Original URL of the content, for buy-­‐side contextualization or review. N/A
cat optional string array The array of IAB content categories for the content.  N/A
prodq optional integer Production quality. N/A
videoquality optional integer Video quality per the IAB’s classification. See Table 6.14 Video Quality. N/A
context optional string Specifies the type of content (game, video, text, etc.).  See Table 6.13  Content Context. N/A
contentrating optional string Content rating (e.g., MPAA) N/A
userrating optional string User rating of the content (e.g., number of stars, likes, etc.). N/A
qagmediarating optional integer Media rating of the content, per QAG guidelines. See Table 0 QAG Media Ratings for list of possible values. N/A
keywords optional string Comma separatedlist of keywords describing the content. ALTERNATE Representation: string array.       N/A
livestream optional integer Is content live? E.g., live video stream, live blog.“1” means content is live. “0” means it is not live. N/A
sourcerelationship optional integer 1 for “direct”; 0 for “indirect” N/A
len optional integer Length of content (appropriate for video or audio) in seconds. N/A
language optional string Language of the content. Use alpha-­‐2/ISO 639-­‐1 codes. N/A
embeddable optional integer From QAG Video Addendum. If content can be embedded (such as an embeddable video player) this value should be set to “1”.  If content cannot be embedded, then this should be set to “0”. N/A
data optional object array Additional content data. Each data object represents a different data source. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.17 Object: Producer

This object defines the producer of the content in which the ad will be shown. This is particularly useful when the content is syndicated and may be distributed through different publishers and thus when the producer and publisher are not necessarily the same entity.

Field Scope Type Default Description Smaato Mapping
id optional string Content producer or originator ID. Useful if the content is syndicated, and may be posted on a site using embed tags. N/A
name optional string Content producer or originator name (e.g., “Warner Bros”). N/A
cat optional string array The array of IAB content categories for the content producer.  N/A
domain optional string URL of the content producer. N/A
ext optional object This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification. N/A

3.2.18 Object: Device

This object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data. The device can refer to a mobile handset, a desktop computer, set-top box, or another digital device.

Field Scope Type Default Description Smaato Mapping
ua recommended string Browser user agent string. User-agent string.
geo recommended if IP is not supplied object Geography as derived from the device’s location services (e.g., cell tower triangulation, GPS) or IP address.  See Geo Object. See Geo Object
lmt recommended integer “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. 0 for unrestricted tracking, 1 for restricted tracking according to Apple/Google guidelines.
ip recommended if geo object is not supplied string IPv4 address is closest to the device. IPv4 address.
devicetype optional integer Return the device type being used. See Table  6.16 Device Type. Mapped to values from WURFL. They can be overridden by Ex2Ex publisher request values.
make optional string Device make (e.g., “Apple”). Device make (e.g., “Apple”)
model optional string Device model (e.g., “iPhone 5s”) Device model (e.g., “iPhone 5s”)
os optional string Device operating system (e.g., “iOS”). Device operating system (e.g., “iOS”).
osv optional string Device operating system version (e.g., “3.1.2”). Device operating system version (e.g., “3.1.2”).
hwv optional string

Hardware Version of Device in the Device Object (e.g. iPhone Xs would have the Xs in the hwv field.)

Hardware version of the device (e.g., “5s” for iPhone 5s).

All OpenRTB 2.4 and 2.5 connectors split the hardware version from the current device model into the dedicated field hwv

For Apple devices (iPhone and iPad)

    • Send model as before (e.g iPhone Xs)
    • String after iPhone or iPad should be sent in the field hwv
h optional integer Physical height of the screen in pixels. Mapped to values from WURFL. They can be overridden by Ex2Ex publisher request values.
w optional integer The physical width of the screen in pixels. Mapped to values from WURFL. They can be overridden by Ex2Ex publisher request values.
pxratio optional float The ratio of physical pixels to device-independent pixels. Mapped to values from WURFL. They can be overridden by Ex2Ex publisher request values.
js optional integer “1” if the device supports JavaScript; else “0”. Always set to “1”
language optional string Browser language; use alpha-­‐2/ISO 639-­‐1 codes. Device language
carrier optional string Carrier or ISP derived from the IP address. Should be specified using Mobile Network Code (MNC) MCC or MNC value.
connectiontype optional integer Return the detected data connection type for the device. Mapped to OpenRTB connection types, depends on connection type or carrier
ifa optional string Native identifier for advertisers; an opaque ID assigned by the device or browser for use as an advertising identifier. (e.g. Apple’s IFA, Android’s Advertising ID, etc)

The value depends on the device’s operation system:

  • IDFA for iPhone
  • GoogleAdId for Android
  • WpId (Windows Phone ID) for Windows Phone or Mobile
didsha1 optional string SHA1 hashed device ID; IMEI when available, else MEID or ESN. OpenRTB’s preferred method for device ID hashing is SHA1. Mapped to hashed IMEI.
didmd5 optional string MD5 hashed device ID; IMEI when available, else MEID or ESN. Should be interpreted as case insensitive. Mapped to hashed IMEI.
dpidsha1 optional string SHA1 hashed platform-­‐specific ID (e.g., Android ID or UDID for iOS). OpenRTB’s preferred method for device ID hash is SHA1. Mapped to hashed androidid.
dpidmd5 optional string MD5 hashed platform-­‐specific ID (e.g., Android ID or UDID for iOS). Should be interpreted as case insensitive. Mapped to hashed androidid.
ext optional object This object is a placeholder that may contain custom JSON agreed to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification. N/A

3.2.19 Object: Geo

This object encapsulates various methods for specifying a geographic location. When subordinate to a Device object, it indicates the location of the device which can also be interpreted as the user’s current location. When subordinate to a User object, it indicates the location of the user’s home base (i.e., not necessarily their current location). The lat/lon attributes should only be passed if they conform to the accuracy depicted in the type attribute. For example, the centroid of a geographic region such as postal code should not be passed.

Field Scope Type Default Description Smaato Mapping
lat optional float Latitude from -90.0 to +90.0, where negative is south. latitude
lon optional float Longitude from -180.0 to +180.0, where negative is west. longitude
type optional integer Source of location data; recommended when passing lat/lon. Refer to Location Type. type = ip
accuracy optional 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. N/A
lastfix optional integer Number of seconds since this geolocation fix was established. Note that devices may cache location data across multiple fetches. Ideally, this value should be from the time the actual fix was taken. Not mapped.
ipservice optional integer Service or provider used to determine geolocation from IP address if applicable (i.e., type = 2). ipservice = maxmind
country optional string Country using ISO-­‐3166-­‐1 Alpha-­‐3. See IPLocationService
region optional string Region using ISO 3166-­‐2. See IPLocationService
regionfips104 optional string Region of a country using FIPS 10-­‐4 notation (alternative to ISO 3166-­‐2). N/A
metro optional string Metro codes are similar to, but not the same as, Nielsen DMAs. Metro code (See IPLocationService)
city optional string City code using the United Nations Code for Trade and Transport Locations unece.org/cefact/locode/ City (See IPLocationService)
zip optional string Zip/postal code. ZIP code.
utcoffset optional integer Local time as the number +/- of minutes from UTC. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB N/A

3.2.20 Object: User

This object contains information known or derived about the human user of the device (i.e., the audience for advertising). The user id is an exchange artifact and may be subject to rotation or other privacy policies. However, this user ID must be stable long enough to serve reasonably as the basis for frequency capping and retargeting.

Field Scope Type Default Description Smaato Mapping
id recommended (or buyeruid) string Unique consumer ID of this user on the exchange. Not mapped.
buyeruid recommended (or id) string Buyer’s user ID for this user as mapped by exchange for the buyer. N/A
yob optional integer Year of birth as a 4-­‐digit integer. Year of birth.
gender optional string Gender as “M” male, “F” female, “O” Other. (Null indicates unknown). F, M, O or null for unknown.
keywords optional string A comma-separated list of keywords of consumer interests or intent. Alternate Representation: string array. Keyword list
customdata optional string If supported by the exchange, this is custom data that the bidder had stored in the exchange’s cookie. The string may be in base85 cookie safe characters and be in any format. This may useful for storing user features. Note: Proper JSON encoding must be used to include “escaped” quotation marks. Smaato Cookie User ID.
geo optional object Home geo for the user (e.g., based off of registration data); this is different from the current location of the access device (that is defined by the geo object embedded in the Device Object); see Device Object. geo (lat,long,type=user provided)
data optional objects array Additional user data. Each Data object represents a different data source. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB Contains user consent that specifies what is allowed (purposes, demand partners IDs).

3.2.21 Object: Data

The data and segment objects together allow additional data about the related object (e.g., user, content) to be specified. This data may be from multiple sources whether from the exchange itself or third parties as specified by the id field. A bid request can mix data objects from multiple providers. The specific data providers in use should be published by the exchange a priori to its bidders.

Field Scope Type Default Description Smaato Mapping
id optional string Exchange specific ID for the data provider. N/A
name optional string Data provider name. N/A
segment optional objects array The array of segment objects. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.22 Object: Segment

Segment objects are essentially key-value pairs that convey specific units of data. The parent Data object is a collection of such values from a given data provider. The specific segment names and value options must be published by the exchange a priori to its bidders.

Field Scope Type Default Description Smaato Mapping
id optional string ID of a data provider’s segment applicable to the user. N/A
name optional string Name of a data provider’s segment applicable to the user. N/A
value optional string String representation of the data segment value. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

 

Extension Objects

Object: BidRequestExtension

Field Scope Type Description Smaato Mapping
carriername optional String Custom field with the SOMA internal carriername (that is the name we obtain from the soma database or the GeoIPCache Not the carriername we log) Carrier Name
lineitemids optional array Eligible open auction Line Items ID Open Auction Line Item IDs

Object: ImpressionExtension

Field Scope Type Description Smaato Mapping

strictbannersize

optional integer

Custom field with the following values:

  • 1 if the banner size to be treated strictly
  • 0 (default value) if the DSP can return ads smaller than a banner size
  • For standard ads, value is 1 or 0.
  • The default is 0.
  • For native ads, this value is 0.

Object: RegsExtension

Field Scope Type Description Smaato Mapping

gdpr

optional integer

A flag when the bid request is or is not subject to gdpr .

Supports 2 different scenarios:

  • O = not subject to gdpr
  • 1 = subject to gdpr

Object: UserExtension

The user consent string is optional but highly recommended if the request is subject to GDPR regulations. 

Field Scope Type Description Smaato Mapping

consent

optional string

The user gives consent to the ad providers.

Contains user consent that specifies what is allowed
(purposes, demand partners IDs).

 

 

4. Bid Response Specifications

RTB responses contain bids that reference specific impressions within a bid request. Bids are in essence an offer to buy. The bid response consists of the top-level bid response object and optional objects that depict the specific bids. An empty HTTP response constitutes a no-bid and is, in fact, the most bandwidth friendly form of this signal although returning a response with a “no-bid reason” is encouraged. A malformed response or a response that contains no actual bids will also be interpreted as no-bid.

4.1 Object Model

Following is the object model for the bid response. The top-level object (i.e., in JSON the unnamed outer object) is denoted as BidResponse in the model. A bid response may contain bids from multiple “seats” (i.e., the buying entity upstream from the actual bidder). In fact, a response may contain multiple bids from the same seat; typically but not necessarily from different campaigns. This can improve the seat’s chances of winning since most exchanges enforce various block lists on behalf of their publishers.

Referring to the figure, the actual response objects are shown on the left, specifically the BidResponse top level object the seat specific SeatBid collections of Bid objects. The other objects shown are those objects from the bid request to which response objects related. Specifically, BidResponse includes the BidRequest ID for positive tracking purposes, and since a request can include multiple impressions Bid includes the ID of the Imp for which the bid is an offer to purchase. If a bid is made under the terms of a private marketplace deal, the Bid also includes the ID of the specific Deal object.

Not shown in the model figure is an extensions object. This is an object of undefined structure that can be added to any other object to convey bidder-specific extensions to the standard. Bidders using these objects are responsible for publishing their extensions to their exchanges.

4.2 Object Specifications

The subsections that follow define each of the objects in the bid response model. Several conventions are used throughout:

  • Attributes are “required” if their omission would technically break the protocol.
  • Some optional attributes are denoted “recommended” due to their elevated business importance.
  • Unless a default value is explicitly specified, an omitted attribute is interpreted as “unknown”.

4.2.1 Object: Bid Response

This object is the top-level bid response object (i.e., the unnamed outer JSON object). The id attribute is a reflection of the bid request ID for logging purposes. Similarly, bidid is an optional response tracking ID for bidders. If specified, it can be included in the subsequent win notice call if the bidder wins. At least one seatbid object is required, which contains at least one bid for an impression. Other attributes are optional.

To express a “no-bid”, the options are to return an empty response with HTTP 204. Alternately if the bidder wishes to convey to the exchange a reason for not bidding, just a BidResponse object is returned with a reason code in the nbr attribute.

Field Scope Type Default Description
id required string Identifier of the bid request.
seatbid optional objects array The array of seatbid objects.
bidid optional string Bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross-­‐reference.
cur optional string Bid currency using ISO-­‐4217 alphabetic codes; default is “USD”.
customdata optional string This is an optional feature that allows a bidder to set data in the exchange’s cookie. The string may be in base85 cookie safe character and be in any format. This may be useful for storing user features. Note: Proper JSON encoding must be used to include “escaped” quotation marks.
nbr optional integer Reason for not bidding. See Table 6.19  NoBid Reason Codes.
ext optional object Placeholder for exchange-specific extensions to OpenRTB

4.2.2 Object: Seat Bid

A bid response can contain multiple SeatBid objects, each on behalf of a different bidder seat and each containing one or more individual bids. If multiple impressions are presented in the request, the group attribute can be used to specify if a seat is willing to accept any impressions that it can win (default) or if it is only interested in winning any if it can win them all as a group.

Field Scope Type Default Description
bid required objects array The array of bid objects; each bid object relates to an imp object in the bid request. Note that, if supported by an exchange, one imp object can have many bid objects.
seat optional string Identifier of the bidder seat on whose behalf this bid is made.
group optional integer “1” means impressions must be won-­-lost as a group; default is “0”.
ext optional object Placeholder for exchange-specific extensions to OpenRTB

4.2.3 Object: Bid

A SeatBid object contains one or more Bid objects, each of which relates to a specific impression in the bid request via the impid attribute and constitutes an offer to buy that impression for a given price.

Field Scope Type Default Description
id required string ID for the bid object chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat.
impid required string The ID of the impression object to which this bid applies.
price required float Bid price in CPM. WARNING/Best Practice Note: Although this value is a float, OpenRTB strongly suggests using integer math for accounting to avoid rounding errors.
adid optional string Identifier that references the ad to be served if the bid wins.
nurl optional string Win notice URL. Note that ad markup is also typically, but not necessarily, returned via this URL.
burl optional string Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (eg. viewed). Substitution macros may be included.
lurl optional string Loss notice URL called by the exchange when a bid is known to have been lost. Substitution macros may be included. Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in ${AUCTION_PRICE} macros being removed.
adm optional string Actual ad markup. XHTML if a response to a banner object, or VAST XML if a response to a video object, or JSON if the response is a Native object. Supersedes the win notice if the markup is included in both.
adomain optional string array Advertiser’s primary or top-­level domain for advertiser checking. This can be a list of domains if there is a  rotating creative. However, exchanges may mandate that only one landing domain is allowed.
iurl optional string Sample image URL (without cache busting) for content checking.
cid optional string Campaign ID or similar that appears within the ad markup.
crid optional string Creative ID for reporting content issues or defects. This could also be used as a reference to a creative ID that is posted with an exchange.
api optional integer API required by the markup if applicable. See Table API Frameworks.
bundle optional 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.
attr optional integer array An Array of creative attributes. See Table 5.3 Creative Attributes.
cat optional string array IAB content categories of the creative.
dealid optional string A unique identifier for the direct deal associated with the bid. If the bid is associated and in response to a dealid in the Request object it is required in the response object.
h optional   Height of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields it is recommended that the response bid contains this field to signal the size of the Ad chosen.
w optional   Width of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin optional fields it is recommended that the response bid contains this field to signal the size of the Ad chosen.
ext optional object

Placeholder for exchange-specific extensions to OpenRTB.

Contains advertiser information. For example,

"ext": {
    "advertiserName": "nameOfAdvertiser",
    "agencyName": "nameOfAgency",
    "agencyId": "idOfAgency"
}
tactic optional String Tactic ID to enable buyers to label bids for reporting to the exchange the tactic through which their bid was submitted. The specific usage and meaning of the tactic ID should be communicated between buyer and exchanges a priori.
protocol optional integer Video response protocol of the markup if applicable. Refer to List 5.8.
qagmediarating optional integer Creative media rating per IQG guidelines. Refer to List 5.19.
language optional String Language of the creative using ISO-639-1-alpha-2. The nonstandard code “xx” may also be used if the creative has no linguistic content (e.g., a banner with just a company logo).
wratio optional integer The relative width of the creative when expressing size as a ratio. Required for flex ads.
hratio optional integer The relative height of the creative when expressing size as a ratio. Required for flex ads.
exp optional integer Advisory as to the number of seconds the bidder is willing to wait between the auction and the actual impression.

Please Note: For each bid, the nurl attribute contains the win notice URL. If the bidder wins the impression, the exchange calls this notice URL to inform the bidder of the win and to convey certain information using substitution macros (see Section 4.4) such as the clearing price. The win notice return or the adm attribute can be used to serve markup (see Section 4.3). In either case, the exchange will also apply the aforementioned substitution to any macros found in the markup.

4.3 Ad Serving Options

The fulfillment of an RTB transaction within the scope of this OpenRTB specification lies in the delivery of markup. Depending on the impression and other ad type constraints, this markup can be XHTML, HTML5, XHTML or HTML5 with embedded JavaScript, a VAST document for video, a Native ad unit structure, and potentially other formats in the future.

The OpenRTB specification does not require any processing of the ad markup by the exchange other than macro substitution (refer to Section 4.4) and delivery to the supply-side. There are, however, multiple standard methods for transferring markup from the bidder to the exchange. The method used is at the discretion of the bidder, but an OpenRTB compliant exchange is expected to support all methods as defined in the subsections that follow.

Further details about Section 4.3 & 4.4 can be found in the IAB OpenRTB 2.5 Specifications.

Ad Served on the Win Notice

    • Reduced Bandwidth Costs: Serving ad markup only upon winning can save large amounts of bandwidth usage, the costs for which can be large at high volumes or when sending multiple bids per bid response.
    • Additional Bidder Flexibility: Bidders may typically know the ad they will serve at the time of bid, but this provides an additional optional decision point after the clearing price has been established.

Ad Served in the Bid

    • Reduced Risk of Forfeiture: A forfeit is the scenario in which a bidder wins, but forfeits due to failure to serve the ad markup. The risk of an additional HTTP failure (e.g., calling the win notice) is mitigated by this method.
    • Potential Concurrency: The exchange can choose to return that ad markup and call the win notice concurrently, thereby improving user experience.

5.0 Enumerated Lists Specification

All reference lists are actively maintained by the IAB on the OpenRTB website. As such, implementers should ensure they are working from the latest lists and enumerations.

5.1 Content Categories

Standard IDs have been adopted to easily support the communication of primary and secondary categories for various objects. This OpenRTB table has values derived from the IAB Tech Lab Content Taxonomy. To view the IAB Tech Lab Content Taxonomy, please view the Smaato Taxonomy page.

5.2 Banner Ad Types

The following table indicates the types of ads that can be accepted by the exchange unless restricted by publisher site settings.

Value Description
1 XHTML text ad. (usually mobile)
2 XHTML banner ad.  (usually mobile)
3 JavaScript ad; must  be valid XHTML (i.e., script  tags included).
4  Iframe

5.3 Creative Attributes

The following table specifies a standard list of creative attributes that can describe an ad being served or serve as restrictions of thereof.

Value Description
1 Audio ad (autoplay)
2 Audio ad (user initiated)
3 Expandable (automatic)
4 Expandable (user initiated -­ click)
5 Expandable (user initiated – ­rollover)
6 In-­banner video ad (auto play)
7 In-­Bbanner video ad (user initiated)
8 Pop (e.g., over, under, or upon exit)
9 Provocative or suggestive imagery
10 Shaky, flashing, flickering, extreme animation, smileys
11 Surveys
12 Text only
13 User interactive (e.g., embedded games)
14 Windows dialog or alert style
15 Has audio on/off button
16 An ad can be skipped (e.g., skip button on pre-roll video)

5.4 Ad Position

The following table specifies the position of the ad as a relative measure of visibility or prominence. This OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should keep in sync with updates to the IQG values as published on IAB.com. Values “4” – “7” apply to apps per the mobile addendum to IQG version 2.1

Value Description
0 Unknown
1 Above the fold
2

DEPRECATED position since it may or may not be immediately visible depending on screen size and resolution

3 Below the fold
4 Header
5 Footer
6 Sidebar
7 Fullscreen

5.5 Expandable Direction

The following table lists the directions in which an expandable ad may expand, given the positioning of the ad unit on the page and constraints imposed by the content.

Value Description
1 Left
2 Right
3 Up
4 Down
5 Fullscreen

5.6 API Frameworks

The following table is a list of API frameworks supported by the publisher.

Value Description
1 VPAID  1.0
2 VPAID  2.0
3 MRAID-­1
4 ORMMA
5 MRAID-2

5.7 Video Linearity

The following table indicates the options for video linearity. “In-stream” or “linear” video refers to preroll, post-roll, or mid-roll video ads where the user is forced to watch ad in order to see the video content. “Overlay” or “non-linear” refer to ads that are shown on top of the video content.

This OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should keep in sync with updates to the IQG values.

Value Description
1 Linear/In­stream
2 Non-­linear/Overlay

5.8 Protocols: Video Bid Response

The following table lists the options for the various bid response protocols that could be supported by an exchange.

Value Description
1 VAST 1.0
2 VAST 2.0
3 VAST 3.0
4 VAST 1.0 Wrapper
5 VAST 2.0 Wrapper
6 VAST 3.0 Wrapper

5.9 Video Placement Types

The following table lists the various types of video placements derived largely from the IAB Digital Video Guidelines.

Value Description
1 In-Stream
Played before, during or after the streaming video content that the consumer has requested (e.g., 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 onscreen while displayed (i.e. cannot be scrolled out of view). Note that a full-screen interstitial (e.g., in mobile) can be distinguished from a floating/slider unit by the imp.instl field.

5.10 Video Playback Methods

The following table lists the various playback methods.

Value

Description
1 Auto-­play sound on (Initiates on Page Load with Sound On)
2 Auto-­play sound  off (Initiates on Page Load with Sound Off by Default)
3 Click-­to-play (Initiates on Click with Sound On)
4 Mouse-­over (Initiates on Mouse-Over with Sound On)

5.12 Video Start Delay

The following table lists the various options for the video or audio start delay. If the start delay value is greater than 0, then the position is mid-roll and the value indicates the start delay.

Value Description
> 0 Mid-Roll
0 Pre-­Roll
-1 Generic Mid-­Roll
-2 Generic Post-­Roll

5.13 Production Quality

The following table lists the options for content quality. These values are defined by the IAB; refer to www.iab.com/wp-content/uploads/2015/03/long-form-video-final.pdf for more information.

Value Description
0 Unknown
1 Professionally Produced Content
2 Prosumer (between “professional” and “consumer” developed quality)
3 User-Generated Content (UGC)

5.14 VAST Companion Types

The following table lists the options to indicate markup types allowed for companion ads that apply to video and audio ads. This table is derived from VAST 2.0+ and DAAST 1.0 specifications. Refer to www.iab.com/guidelines/digital-video-suite for more information.

Value Description
1 Static Resource
2 HTML Resource
3 iframe Resource

5.15 Content Delivery Methods

The following table lists the various options for the delivery of video or audio content.

Value Description
1 Streaming
2 Progressive

5.17 IQG Media Ratings

Value Description
1 All Audiences
2 Everyone over 12
3 Mature audience

5.18 Content Context

The following table lists the various options for indicating the type of content being used or consumed by the user in which the impression will appear. This OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should keep in sync with updates to the IQG values.

Value Description
1 Video (a video file or stream that is being viewed by the user, including streaming broadcasts)
2 Game (an interactive software game that is being played by the user)
3 Music (an audio file or stream that is being listened by the user, including Internet radio broadcasts)
4 Application (a software application that the user is interacting with)
5 Text (a primarily textual document that is being read or viewed by the user, including web pages, ebooks, or new articles)
6 Other (the content type that the user is consuming does not fit into one of the categories described above)
7 Unknown

5.20 Location Type

The following table lists the options to indicate how the geographic information was determined.

Value Description
1 GPS/Location Services
2 IP Address
3 User provided  (e.g.,  registration  data)

5.21 Device Type

The following table lists the type of device from which the impression originated.

OpenRTB version 2.2 of the specification added distinct values for Mobile and Tablet. It is recommended that any bidder adding support for 2.2 treat a value of 1 as an acceptable alias of 4 & 5.

This OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should
keep in sync with updates to the IQG values.

Value Description
1 Mobile/Tablet
2 Personal Computer
3 Connected TV
4 Phone
5 Tablet
6 Connected Device
7 Set Top Box

5.22 Connection Type

The following table lists the various options for the type of device connectivity

Value Description
0 Unknown
1 Ethernet
2 WIFI
3 Cellular Network – Unknown Generation
4 Cellular Network – 2G
5 Cellular Network – 3G
6 Cellular Network – 4G

5.23 IP Location Service

Value Description
1 Ip2Location
2 Neustar
3 MaxMind

5.24 NoBid  Reason Codes

The following table lists the options for a bidder to signal the exchange as to why it did not offer a bid for the impression.

Value Description
0 Unknown Error
1 Technical Error
2 Invalid Request
3 Known Web spider
4 Suspected  Non-­Human Traffic
5 Cloud, Datacenter, or Proxy IP
6 Unsupported Device
7 Blocked Publisher or Site
8 Unmatched User

Native API Version 1.1 Documentation

Request

Field Scope Type Default Description Smaato Mapping
ver optional String  1.1 Request payload complying with the Native Ad Specification. 1.1
context
recommended integer   The context in which the ad appears. See Table of Context IDs below for a list of supported “context types” The context in which the ad appears.
contextsubtype optional integer   A more detailed context in which the ad appears. See Table of Context SubType IDs below for a list of supported context subtypes. Not yet applicable.
plcmttype
recommended integer 1 The design/format/layout of the ad unit being offered. Currently always 1.
plcmtcnt
optional   1 The number of identical placements in this Layout. Refer to Section 8.1 Multiplacement Bid Requests for further details. Currently always 1.
seq
optional   0 0 for the first ad, 1 for the second ad, and so on. Note: This would generally NOT be used in combination with plcmtcnt. Either you are auctioning multiple identical placements (in which case plcmtcnt>1, seq=0) or you are holding separate auctions for distinct items in the feed (in which case plcmtcnt=1, seq=>=1). Currently always 0.
assets
required objects array   An array of asset objects. Any bid response must comply with the array of elements expressed in the bid request. See Native assets
layout recommended in 1.0, to be deprecated integer   The layout ID of the native ad unit. N/A
adunit recommended in 1.0, to be deprecated integer   The ad unit ID of the native ad unit. N/A

Assets

Field Scope Type Default Description Smaato Mapping
id required integer   Unique asset ID, assigned by
the Exchange. Typically a counter for the array.
  • TITLE(1),
  • MAIN_IMAGE(2),
  • ICON(3),
  • DESCRIPTION(4),
  • CTA_TEXT(5);
required optional integer   title object = 1 (required)img object = 1 (required) video object = not supported yetdata object = 1 (required) Always 1.
title * recommended object   Title object for title assets. See TitleObject definition. See Title Object
img * recommended object   Image object for image assets.See ImageObject definition. See Image object
video * recommended object   Not yet applicable. Not yet applicable.
data * recommended object    

See Data object. 

type and len are from SPX settings. Default are type=DESC len=140 , type=CTATEXT len=15 and type=RATING

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 N/A

*Each asset object may contain only one of title, image, data or video.

Title Object

 Field Scope Type Default Description Smaato Mapping
id required integer   The maximum length of the text in the title element. Recommended to be 25, 90, or 140. 140 by default.
ext optional object   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. N/A

Image Object

 Field Scope Type Default Description Smaato Mapping
type optional integer   Type ID of the image element supported by the publisher. The publisher can display this information in an appropriate format. 1: Icon3: Main
w optional integer   Width of the image in pixels. N/A
wmin recommended integer   The minimum requested width of the image in pixels. This option should be used for any rescaling of images by the client. Either w or wmin should be transmitted. If only w is included, it should be considered an exact requirement.

Values for:

  • Icon: 50
  • Image: 200
h optional integer   Height of the image in pixels. N/A
hmin recommended integer   The minimum requested height of the image in pixels. This option should be used for any rescaling of images by the client.  Either h or hmin should be transmitted. If only h is included, it should be considered an exact requirement.

Values:

  • Icon: 50
  • Image: 200
mimes optional arrays of string   Whitelist of content MIME types supported. Popular MIME types include, but are not limited to “image/jpg”  “image/gif”. Each implementing Exchange should have their own list of supported types in the integration docs.  See Wikipedia’s MIME page for more information and links to all IETF RFCs.If blank, assume all types are allowed. N/A
 ext optional object   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. N/A

Data Object

 Field Scope Type Default Description Smaato Mapping
type required integer   Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format. See the Data Asset Types table for commonly used examples.
  • 2 for desc
  • 12 for ctatext

Example of Native ad request

{
    "ver": "1.1",
    "context": 1,
    "plcmttype": 1,
    "plcmtcnt": 1,
    "seq": 0,
    "assets": [
        {
            "id": 1,
            "required": 1,
            "title": {
                "len": 140
            }
        },
        {
            "id": 2,
            "required": 1,
            "image": {
                "type": 3,
                "wmin": 200,
                "hmin": 200
            }
        },
        {
            "id": 3,
            "required": 1,
            "image": {
                "type": 1,
                "wmin": 50,
                "hmin": 50
            }
        },
        {
            "id": 4,
            "required": 1,
            "data": {
                "type": 2
            }
        },
        {
            "id": 5,
            "required": 1,
            "data": {
                "type": 12
            }
        }
    ]
}

Reference Lists/Enumerations

Modified: October 15, 2019 at 2:17 pm