Settings View Source API Reference OpenRtbEcto v0.6.5

Ecto schemas for OpenRTB 2.x & 3.0 according to the following specifications

In some cases, partners will send boolean values in the JSON payloads for fields that are defined as integers in the spec. This type can handle those cases and properly cast the values.

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). Other attributes in this top-level object establish rules and restrictions that apply to all impressions being offered.

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.

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.

This object represents the most general type of impression. Although the term “banner” may have 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.

Further identification based on User-Agent Client Hints, the BrandVersion object is used to identify a device’s browser or similar software component, and the user agent’s execution platform or operating system.

This object describes the channel an ad will be displayed on. A Channel is defined as the entity that curates a content library, or stream within a brand name for viewers. Examples are specific view selectable ‘channels’ within linear and streaming television (MTV, HGTV, CNN, BBC One, etc) or a specific stream of audio content commonly called ‘stations.’ Name is a human-readable field while domain and id can be used for reporting and targeting purposes. See 7.6 for further examples.

This object describes the content in which the impression will appear, which may be syndicated or nonsyndicated 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 might be a video impression embedded in an iframe on an unknown web property or device.

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.

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.

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.

Extended identifiers support in the OpenRTB specification allows buyers to use audience data in real-time bidding. This object can contain one or more UIDs from a single source or a technology provider. The exchange should ensure that business agreements allow for the sending of this data.

This object represents an allowed size (i.e., height and width combination) or Flex Ad parameters for a banner impression. These are typically used in an array where multiple sizes are permitted. It is recommended that either the w/h pair or the wratio/hratio/wmin set (i.e., for Flex Ads) be specified.

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

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.

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.

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.

This object describes the network an ad will be displayed on. A Network is defined as the parent entity of the Channel object’s entity for the purposes of organizing Channels. Examples are companies that own and/or license a collection of content channels (Viacom, Discovery, CBS, WarnerMedia, Turner and others), or studio that creates such content and self-distributes content. Name is a human-readable field while domain and id can be used for reporting and targeting purposes. See 7.6 for further examples.

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.

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.

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.

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

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.

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.

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 in decisioning.

This object is composed of a set of nodes where each node represents a specific entity that participates in the transacting of inventory. The entire chain of nodes from beginning to end represents all entities who are involved in the direct flow of payment for inventory. Detailed implementation examples can be found here: https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md

This object is associated with a SupplyChain object as an array of nodes. These nodes define the identity of an entity participating in the supply chain of a bid request. Detailed implementation examples can be found here: https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md. The SupplyChainNode object contains the following attributes

This object contains a single user identifier provided as part of extended identifiers. The exchange should ensure that business agreements allow for the sending of this data.

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.

Structured user agent information, which can be used when a client supports User-Agent Client Hints. If both device.ua and device.sua are present in the bid request, device.sua should be considered the more accurate representation of the device attributes. This is because the device.ua may contain a frozen or reduced user agent string due to deprecation of user agent strings by browsers.

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.

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.

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.

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.

Schemas for the OpenRTB Native specification version 1.2

The Native Object defines the native advertising opportunity available for bid via this bid request.

The main container object for each asset requested or supported by Exchange on behalf of the rendering client.

The Data Object is to be used for all non-core elements of the native unit such as Brand Name, Ratings, Review Count, Stars, Download count, descriptions etc. It is also generic for future native elements not contemplated at the time of the writing of this document. In some cases, additional recommendations are also included in the Data Asset Types table.

The event trackers object specifies the types of events the bidder can request to be tracked in the bid response, and which types of tracking are available for each event type, and is included as an array in the request.

The Image object to be used for all image elements of the Native ad such as Icons, Main Image, etc.

The Title object is to be used for title element of the Native ad.

The video object to be used for all video elements supported in the Native Ad. This corresponds to the Video object of OpenRTB.

The native object is the top level JSON object which identifies a native response.

Corresponds to the Asset Object in the request. The main container object for each asset requested or supported by Exchange on behalf of the rendering client. Any object that is required is to be flagged as such. Only one of the {title,img,video,data} objects should be present in each object. All others should be null/absent. The id is to be unique within the AssetObject array so that the response can be aligned.

Corresponds to the Data Object in the request, with the value filled in. The Data Object is to be used for all miscellaneous elements of the native unit such as Brand Name, Ratings, Review Count, Stars, Downloads, Price count etc. It is also generic for future native elements not contemplated at the time of the writing of this document.

The event trackers response is an array of objects and specifies the types of events the bidder wishes to track and the URLs/information to track them. Bidder must only respond with methods indicated as available in the request. Note that most javascript trackers expect to be loaded at impression time, so it’s not generally recommended for the buyer to respond with javascript trackers on other events, but the appropriateness of this is up to each buyer.

Corresponds to the Image Object in the request. The Image object to be used for all image elements of the Native ad such as Icons, Main Image, etc.

Used for ‘call to action’ assets, or other links from the Native ad. This Object should be associated to its peer object in the parent Asset Object or as the master link in the top level Native Ad response object. When that peer object is activated (clicked) the action should take the user to the location of the link.

Corresponds to the Title Object in the request, with the value filled in.

Corresponds to the Video Object in the request, yet containing a value of a conforming VAST tag as a value.

Bid Request Payload

The request object contains minimal high level attributes (e.g., its ID, test mode, auction type, maximum auction time, buyer restrictions, etc.) and subordinate objects that cover the source of the request and the actual offer of sale. The latter includes the item(s) being offered and any applicable deals.

This object constitutes a specific deal that was struck a priori between a seller and a buyer. Its presence indicates that this item is available under the terms of that deal.

This object represents a unit of goods being offered for sale either on the open market or in relation to a private marketplace deal. The id attribute is required since there may be multiple items being offered in the same bid request and bids must reference the specific item of interest. This object interfaces to Layer-4 domain objects for deeper specification of the item being offered (e.g., an impression).

This object is associated with an item as an array of metrics. These metrics can offer insight 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.

The Request object contains a globally unique bid request ID. This id attribute is required as is an Item array with at least one object (i.e., at least one item for sale). Other attributes establish rules and restrictions that apply to all items being offered. This object also interfaces to Layer-4 domain objects for context such as the user, device, site or app, etc.

This object carries data about the source of the transaction including the unique ID of the transaction itself, source authentication information, and the chain of custody.

The response object contains minimal high level attributes (e.g., reference to the request ID, bid currency, etc.) and an array of seat bids, each of which is a set of bids on behalf of a buyer seat.

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

This object constitutes a buyer defined key/value pair used to inject dynamic values into media markup. While they apply to any media markup irrespective of how it is conveyed, the principle use case is for media that was uploaded to the exchange prior to the transaction (e.g., pre-registered for creative quality review) and referenced in bid. The full form of the macro to be substituted at runtime is ${CUSTOM_KEY}, where “KEY” is the name supplied in the key attribute. This ensures no conflict with standard OpenRTB macros.

This object is the bid response object under the Openrtb root. Its id attribute is a reflection of the bid request ID. The bidid attribute is an optional response tracking ID for bidders. If specified, it will be available for use in substitution macros placed in markup and notification URLs. At least one Seatbid object is required, which contains at least one Bid for an item. Other attributes are optional.

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