OpenRTB 2.4 Specifications

Home » Marketer Documentation » 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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”).

3.2.19 Object Regs.ext

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.

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.

Extension Objects

Object: ImpressionExtension

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.

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.

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.

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.

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.

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

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.

5.6 API Frameworks

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

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.

5.8 Video Protocols

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

5.9 Video Playback Methods

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.

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.

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.

5.13 Content Delivery Methods

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

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.

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

5.18 Location Type

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

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.

5.20 Connection Type

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

5.21 IP Location Service

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.

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

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

context

plcmttype

plcmtcnt

seq

assets

Request

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

Title Object

Image Object

Data Object

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

Last Modified: August 31, 2023 at 11:54 am