OpenRTB 2.4 Specifications

Here you will find the IAB’s object specifications as well as the Smaato mapping examples for OpenRTB 2.4.

3.2 Object Specifications

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.2 – IAB OpenRTB 2.4). 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 The 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 The indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode N/A
at optional integer 2 An auction type, where 1 = First Price, 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. This value is commonly communicated offline. N/A
wseat optional string array A 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. N/A
allimps optional integer 0 A 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 An 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
bcat optional string array Blocked advertiser categories using the IAB content categories. 

It contains the combination of two sources of blocked categories.

  • Blocked categories from publisher line item
  • Blocked categories from configuration in database (OpenRTBBlockedIabCategories property)
badv optional string array A block list of advertisers by their domains. Blocked domains from publisher line item (e.g., company1.com, company2.com)
bapp optional string array A 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. N/A
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: Imp (Impression)

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.3), Video (Section 3.2.4), and/or Native (Section 3.2.6) 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 rises increments). Since we always have one unique impression object, this value is always 1.
banner required for banner impressions object A banner object is 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 a 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 ad mediation partner, SDK technology, or player responsible for rendering ads (typically video or mobile). Used by some ad servers to customize ad code by a partner. Recommended for video and/or apps. If the ad request comes through 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. This field is only set for incoming Ad requests on API version 5.0.2 and above. 1 for Interstitial/full-screen ads, 0 for all others.
tagid optional string The 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. N/A
bidfloorcur optional string USD Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by the 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 A 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 An 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.3 Object: Banner

This object represents the most general type of impression. Although the term “banner” may have a very specific meaning in other contexts, where 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.4 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 The 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 if Native Ad requested
  • if not a Native ad contains banner width see SOMA Banner Dimension
h recommended integer The 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 if Native Ad requested
  • if not a Native ad contains banner height see SOMA Banner Dimension
format recommended object array An array of format objects representing the banner sizes permitted. If none are specified, then the use of the height (h)/width (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 The 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; they should be unique within an impression. N/A
btype optional integer array All types are allowed The blocked banner ad types. Refer to Banner Ad Types.

All the following values:

  1. XHTMLTextAd
  2. XHTMLBannerAd
  3. XHTMLJavaScriptAd

Except 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 The blocked creative attributes. Refer to Creative Attributes.

Contains the combination of two sources of blocked attributes:

  • Blocked attributes from publisher Line Item
  •  comma-separated list as the SOMA configuration propertyOpenRTBBlockedAttributes(default value is: 1,3,5,6,8,9)
pos optional integer The 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 The content MIME types supported. Popular MIME types may include “application/x-shockwave-flash”, “image/jpg”, and “image/gif”. Ad types (context: ValidAdTypes) that are not blocked. Refer to the mapping of supported ad types in Banner Ad Types
If the text ad is supported then MIMEs supported are:

  • text/html
  • text/plain

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

The directions in which the banner may expand. Refer to the Expandable Direction.

 

N/A
api optional integer array The 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]
ext optional object The placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.4 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.3) 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.

As per IAB specs, Smaato regards VAST impression event as the official signal that the impression is billable. Hence your Vpaid creative must trigger the <AdImpression> to signal an impression to the video player.

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

For iOS we send:

  • video/3gpp
  • video/mov
  • video/mp4
  • video/mp

For all other OSs, we send:

  • video/3gpp
  • video/mp4

When the api field has a value 2 meaning the incoming bid request is VPAID compatible then the following MIME type will be sent:

  • “application/javascript”
minduration required integer The minimum video ad duration in seconds 5 by default.
maxduration required integer The maximum video ad duration in seconds 60 by default.
protocols recommended integer array An array of supported video protocols. Refer to Video Bid Response Protocols. At least one supported protocol must be specified in either the protocol or protocols attribute. We send values 2,3,5,6,7 depending on the Protocol version
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. N/A
w recommended integer The width of the video player in device independent pixels (DIPS).
  • 0 if Native Ad requested
  • if not a Native ad contains banner width see SOMA Banner Dimension
h recommended integer The 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. This field is only set for incoming Ad requests on API version 5.0.2 and above. 0 (pre-roll), when videotype=instream-pre
-1 (mid-roll), when videotype=instream-mid
-2 (post-roll), when videotype=instream-post
linearity optional integer It indicates if the impression must be linear, nonlinear, etc. If none are 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.

1, when the publisher will intend to provide the skip option

0, when the publisher will intend to not provide the skip option

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.

Contains the combination of two sources of blocked attributes:

  • Blocked attributes from publisher Line Item
  •  comma-separated list as the SOMA configuration propertyOpenRTBBlockedAttributes(default value is: 1,3,5,6,8,9)
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 Any bitrate accepted Minimum bit rate in kbps. 250
maxbitrate optional integer Any bitrate accepted Maximum bit rate in kbps. 4000
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
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  The ad position on the screen. Refer to Ad Position.

Ad Position from Adspace

See Ad Position.

companionad optional objects array An array of Banner objects if companion ads are available. Contains the Banner Object
api optional integer array The 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. Contains 2 when the API Frameworks supported by the inventory is VPAID 2.0
companiontype optional integer array Supported VAST companion ad types. Refer to VAST Companion Types. Recommended if companion Banner objects are included via the companion ad array. Contains an array of VAST Companion Types
ext optional object Placeholder for exchange-specific extensions to OpenRTB. This field is only set for incoming Ad requests on API version 5.0.2 and above. It contains information if video type is outstream or rewarded. In other cases, SOMA won’t send an ext object.

3.2.6 Object: Native

This object represents a native type impression. Native ad units are intended to blend seamlessly into the surrounding content (e.g., a sponsored Twitter or Facebook post). 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 The 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 the 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 The 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. Default value is: 1,3,5,8,9 (globally set in the exchange) – see Table 5.3 Creative Attributes.
ext optional object A placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.7 Object: Format

This object represents an allowed size (i.e., height and width combination) for a banner impression. These are typically used in an array for an impression where multiple sizes are permitted.

Field Scope Type Description Smaato Mapping
w recommended integer The width in device independent pixels (DIPS).  
h recommended integer The height in device independent pixels (DIPS).  
ext optional Object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.8 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 An exchange-specific site ID. “Application ID” (ID of the website) of the ad request.
name optional string The site name (may be masked at publisher’s request). Web page/property name.
domain optional string The domain of the site, used for advertiser side blocking. For example, “example.com”.  
cat optional string array An array of IAB content categories of the site.  Array, IAB categories.
sectioncat optional string array An array of IAB content categories that describe the current section of the site.  N/A
pagecat optional string array An array of IAB content categories that describe the current page or view of the site.  N/A
page optional string The URL of the page where the impression will be shown. N/A
ref optional string The referrer URL that caused navigation to the current page. Referrer URL
search optional string A search string that caused navigation to the current page. Query string
mobile optional integer This 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

A comma-separated list of keywords about the site.

Alternate Representation: string array.

Keyword list.
ext optional object A placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.9 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 An application ID on the exchange. Application ID
name optional string An 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 An array of IAB content categories for the overall application.   Array, IAB categories.
sectioncat optional string array An array of IAB content categories for the current subsection of the app.   N/A
pagecat optional string array An array of IAB content categories for the current page/view of the app.   N/A
ver optional string The 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

Aist 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.10 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 A publisher ID on the exchange. Publisher ID.
name optional string The publisher name (may be masked at publisher’s request). Publisher name (blank if hidden).
cat optional string array An array of IAB content categories for the publisher.  N/A
domain optional string The publisher’s highest level domain name, for example, “example.com”. N/A
ext optional object A placeholder for exchange-specific extensions to OpenRTB N/A

3.2.11 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 An ID uniquely identifying 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
url optional string Original URL of the content, for buy-­‐side contextualization or review. N/A
cat optional string array Array of IAB content categories for the content.   N/A
videoquality optional integer Video quality per the IAB’s classification. See Table 6.14 Video Quality. N/A
keywords optional string Comma separated list of keywords describing the content. ALTERNATE Representation: string array.       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
context optional integer Specifies the type of content (game, video, text, etc.).  See Table 6.13 Content Context. N/A
livestream optional integer Is content live? E.g., live video stream, live blog.“1” means the content is live. “0” means it is not live. N/A
sourcerelationship optional integer 1 for “direct”; 0 for “indirect” N/A
producer optional object See Producer Object N/A
len optional integer Length of content (appropriate for video or audio) in seconds. N/A
qagmediarating optional integer Media rating of the content, per QAG guidelines. See Table 0 QAG Media Ratings for a list of possible values. 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
language optional string Language of the content. Use alpha-­‐2/ISO 639-­‐1 codes. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.12 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 An 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.13 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 other 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. Always 1 (for mobile/tablet).
make optional string Device makes (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 the device (e.g., “5S” for iPhone 5S). Hardware version of the device, e.g. “5s” for iPhone 5s
h optional integer Physical height of the screen in pixels N/A
w optional integer The physical width of the screen in pixels N/A
pxratio optional float The ratio of physical pixels to device independent pixels. N/A
js optional integer “1” if the device supports JavaScript; otherwise “0”. “1” if the device supports JavaScript; else “0”.
language optional string Browser language; use alpha-­‐2/ISO 639-­‐1 codes. N/A
carrier optional string Carrier or ISP (e.g., “VERIZON”). “WIFI” is often used in mobile to indicate high bandwidth (e.g., video friendly vs. cellular).
connectiontype optional integer Return the detected data connection type for the device. ‘WLAN only’ or Connection, Carrier & Name (if detected).
ifa optional string A 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
  • google add for Android
didsha1 optional string SHA1 hashed device ID; IMEI when available, else MEID or ESN. OpenRTB’s preferred method for device ID hashing is SHA1. hashed Device ID
didmd5 optional string MD5 hashed device ID; IMEI when available, else MEID or ESN. Should be interpreted as case insensitive. hashed Device ID
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. hashed Device ID
dpidmd5 optional string MD5 hashed platform-­‐specific ID (e.g., Android ID or UDID for iOS). Should be interpreted as case insensitive. hashed Device ID
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.14 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./long. Refer to the Location Type.

1 (GPS Location Service)

2 (IP)

3 (User Provided)

accuracy optional integer Estimated location accuracy in meters; recommended when lat./long. 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. The number of seconds.
ipservice optional integer Service or provider used to determine geolocation from IP address if applicable (i.e., type = 2). See IPLocationService
country optional string A 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 Pass the metro code. Metro codes are similar to but not exactly the same as Nielsen DMAs. Metro code (See IPLocationService)
city optional string City using United Nations Code for Trade and Transport Locations (http://www.unece.org/cefact/locode/service/location.htm). 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.15 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. N/A
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 N/A

Object: User.ext

The user consent string is optional but highly recommended if the request is subject to GDPR regulations (i.e., Regs.ext.gdpr = 1). The default sense of consent under GDPR is “opt-out” and as such, an omitted consent string in a request subject to GDPR would need to be interpreted as equivalent to the user fully opting out of all defined purposes for data use by all parties.

Field Scope Type Default Description Smaato Mapping
consent optional string It contains the data structure developed by the GDPR Consent Working Group under the auspices of IAB Europe. N/A

3.2.16 Object: Data

The data and segment objects together allow additional data about the user to be specified. This data may be from multiple sources whether from the exchange itself or third party providers 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 An array of segment objects. N/A
ext optional object Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.17 Object: Segment

Segment objects are essentially key-value pairs that convey specific units of data about the user. 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

3.2.18 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 Placeholder for exchange-specific extensions to OpenRTB. N/A

3.2.19 Object Regs.ext

Field Scope Type Default Description Smaato Mapping
gdpr optional integer Signaled when the request is or is not subject to GDPR via the extension attribute GDPR which is an optional integer that indicates: 0 = No, 1 = Yes.

Supports 2 different scenarios:

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

3.2.20 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 in the IAB OpenRTB 2.4 Specifications for more details.

Field Scope Type Default Description Smaato Mapping
private_auction optional integer 0 Indicator of auction eligibility to seats named in the object of the direct deal, where 0 = all bids are accepted, 1 = bids are restricted to the deals specified and the terms thereof.

1 – private auction

0 – open 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 to by the parties in an OpenRTB transaction to support flexibility beyond the standard defined in this specification. N/A

3.2.21 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 in the IAB OpenRTB 2.4 Specifications 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 the bid floor is specified and multiple currencies supported per bid request, then the currency should be specified here using ISO-­-4217 alphabetic codes. Note, this may be different from bid currency returned by the 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 bid floor indicates the apriori 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 An 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. N/A
wadomain optional string array An 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

 

Extension Objects

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 the banner size

For standard ads, this value will be 1 or 0.Defaultis 0.

For native ads, this value is 0.

 

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.

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 ID of the bid request.
seatbid optional objects array An 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, which allows a bidder to set data in the exchange’s cookie. The string may be in base85 cookie safe characters 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 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 ID 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 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 ID 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.
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.
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.
attr optional integer array An array of creative attributes. See Table 5.3 Creative Attributes.
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 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 ad chosen.
ext optional object Placeholder for exchange-specific extensions to OpenRTB.

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 (auto play)
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-­banner 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 Ad can be skipped (e.g., skip button on preroll 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 Video Protocols

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 Playback Methods

Value Description
1 Auto-­play sound on
2 Auto-­play sound  off
3 Click-­to-­play
4 Mouse-­over

5.10 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.11 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.12 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.13 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.16 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.17 IQG Media Ratings

The following table lists the media ratings used in describing content based on the IQG 2.1 categorization. Refer to www.iab.com/guidelines/digital-video-suite for more information

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

5.18 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.19 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.20 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.21 IP Location Service

Value Description
1 Ip2Location
2 Neustar
3 MaxMind

5.22 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

6. Bid Request/Response Samples

To find the Example Bid Request/Responses, please visit the individual example pages under the specific OpenRTB specifications.

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.

 

 

Native API Version 1.1 Documentation

Native Ads Bid Request Changes: Depending on our publisher’s request, we can send multiple main images asset requests in the same bid request. The maximum main images which we will request for the same ad placement will be limited to 3 in total.

Assets

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.

Not Applicable anymore (because of the latest Native Ads release in July)
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 detail. 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

Request

Field Scope Type Default Description Smaato Mapping
id required integer   Unique asset ID, assigned by
the exchange. Typically a counter for the array.
Rather than sending a fixed Asset ID for each asset type, Smaato will generate IDs based on existing assets of current Native Bid Request. With this change, we will be able to request multiple Main Image assets in bid request.
required optional integer  

title object = 1 (required)

img object = 1 (required)

video object = not supported yet

data object = 1 (required)

Always 0 (Changed from always 1 during the Native Ads Release in July 2018)
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

We include two asset instances into the Request with this field – one asset for descriptions, the other for CTA Texts.

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, img, data or video.

Title Object

 Field Scope Type Default Description Smaato Mapping
len 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: Icon

3: 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: 627
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: 627
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 Data Asset Types table for commonly used examples.
  • 2 for desc
  • 12 for ctatext

Example of a Native 1.1 Ad Request

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

Modified: November 13, 2019 at 4:39 pm