# OpenRtbEcto v1.4.6 - API Reference

## Modules

- [OpenRtbEcto](OpenRtbEcto.md): Ecto schemas for OpenRTB 2.x & 3.0 according to the following specifications
- [OpenRtbEcto.JSON.Encoder](OpenRtbEcto.JSON.Encoder.md)
- [OpenRtbEcto.Types.TinyInt](OpenRtbEcto.Types.TinyInt.md): 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.

- [OpenRtbEcto.V2.BidRequest](OpenRtbEcto.V2.BidRequest.md): 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.
- [OpenRtbEcto.V2.BidRequest.App](OpenRtbEcto.V2.BidRequest.App.md): 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.

- [OpenRtbEcto.V2.BidRequest.Audio](OpenRtbEcto.V2.BidRequest.Audio.md): 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.
- [OpenRtbEcto.V2.BidRequest.Banner](OpenRtbEcto.V2.BidRequest.Banner.md): 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.
- [OpenRtbEcto.V2.BidRequest.BrandVersion](OpenRtbEcto.V2.BidRequest.BrandVersion.md): 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.

- [OpenRtbEcto.V2.BidRequest.Channel](OpenRtbEcto.V2.BidRequest.Channel.md): 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.

- [OpenRtbEcto.V2.BidRequest.Content](OpenRtbEcto.V2.BidRequest.Content.md): 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.

- [OpenRtbEcto.V2.BidRequest.Data](OpenRtbEcto.V2.BidRequest.Data.md): 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.

- [OpenRtbEcto.V2.BidRequest.Deal](OpenRtbEcto.V2.BidRequest.Deal.md): 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.

- [OpenRtbEcto.V2.BidRequest.Device](OpenRtbEcto.V2.BidRequest.Device.md): 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.

- [OpenRtbEcto.V2.BidRequest.Eids](OpenRtbEcto.V2.BidRequest.Eids.md): 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. 

- [OpenRtbEcto.V2.BidRequest.Format](OpenRtbEcto.V2.BidRequest.Format.md): 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.

- [OpenRtbEcto.V2.BidRequest.Geo](OpenRtbEcto.V2.BidRequest.Geo.md): 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).
- [OpenRtbEcto.V2.BidRequest.Imp](OpenRtbEcto.V2.BidRequest.Imp.md): 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.
- [OpenRtbEcto.V2.BidRequest.Metric](OpenRtbEcto.V2.BidRequest.Metric.md): 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.

- [OpenRtbEcto.V2.BidRequest.Native](OpenRtbEcto.V2.BidRequest.Native.md): 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.
- [OpenRtbEcto.V2.BidRequest.Network](OpenRtbEcto.V2.BidRequest.Network.md): 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.

- [OpenRtbEcto.V2.BidRequest.Pmp](OpenRtbEcto.V2.BidRequest.Pmp.md): 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.

- [OpenRtbEcto.V2.BidRequest.Producer](OpenRtbEcto.V2.BidRequest.Producer.md): 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.

- [OpenRtbEcto.V2.BidRequest.Publisher](OpenRtbEcto.V2.BidRequest.Publisher.md): 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.

- [OpenRtbEcto.V2.BidRequest.Regs](OpenRtbEcto.V2.BidRequest.Regs.md): 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”).

- [OpenRtbEcto.V2.BidRequest.Segment](OpenRtbEcto.V2.BidRequest.Segment.md): 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.

- [OpenRtbEcto.V2.BidRequest.Site](OpenRtbEcto.V2.BidRequest.Site.md): 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.

- [OpenRtbEcto.V2.BidRequest.Source](OpenRtbEcto.V2.BidRequest.Source.md): 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.

- [OpenRtbEcto.V2.BidRequest.SupplyChain](OpenRtbEcto.V2.BidRequest.SupplyChain.md): 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

- [OpenRtbEcto.V2.BidRequest.SupplyChainNode](OpenRtbEcto.V2.BidRequest.SupplyChainNode.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:

- [OpenRtbEcto.V2.BidRequest.Uid](OpenRtbEcto.V2.BidRequest.Uid.md): 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.

- [OpenRtbEcto.V2.BidRequest.User](OpenRtbEcto.V2.BidRequest.User.md): 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.

- [OpenRtbEcto.V2.BidRequest.UserAgent](OpenRtbEcto.V2.BidRequest.UserAgent.md): 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.

- [OpenRtbEcto.V2.BidRequest.Video](OpenRtbEcto.V2.BidRequest.Video.md): 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.
- [OpenRtbEcto.V2.BidResponse](OpenRtbEcto.V2.BidResponse.md): 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.
- [OpenRtbEcto.V2.BidResponse.Bid](OpenRtbEcto.V2.BidResponse.Bid.md): 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.

- [OpenRtbEcto.V2.BidResponse.SeatBid](OpenRtbEcto.V2.BidResponse.SeatBid.md): 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.

- [OpenRtbEcto.V2.Native](OpenRtbEcto.V2.Native.md): Schemas for the [OpenRTB Native specification version 1.2](https://www.iab.com/wp-content/uploads/2018/03/OpenRTB-Native-Ads-Specification-Final-1.2.pdf)

- [OpenRtbEcto.V2.Native.Helper](OpenRtbEcto.V2.Native.Helper.md)
- [OpenRtbEcto.V2.Native.Request](OpenRtbEcto.V2.Native.Request.md): The Native Object defines the native advertising opportunity available for bid via this bid request.

- [OpenRtbEcto.V2.Native.Request.Asset](OpenRtbEcto.V2.Native.Request.Asset.md): The main container object for each asset requested or supported by Exchange on behalf of the rendering client.

- [OpenRtbEcto.V2.Native.Request.Data](OpenRtbEcto.V2.Native.Request.Data.md): 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.

- [OpenRtbEcto.V2.Native.Request.EventTracker](OpenRtbEcto.V2.Native.Request.EventTracker.md): 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.

- [OpenRtbEcto.V2.Native.Request.Img](OpenRtbEcto.V2.Native.Request.Img.md): The Image object to be used for all image elements of the Native ad such as Icons, Main Image, etc.

- [OpenRtbEcto.V2.Native.Request.Title](OpenRtbEcto.V2.Native.Request.Title.md): The Title object is to be used for title element of the Native ad.

- [OpenRtbEcto.V2.Native.Request.Video](OpenRtbEcto.V2.Native.Request.Video.md): The video object to be used for all video elements supported in the Native Ad.
This corresponds to the Video object of OpenRTB.

- [OpenRtbEcto.V2.Native.Response](OpenRtbEcto.V2.Native.Response.md): The native object is the top level JSON object which identifies a native response.

- [OpenRtbEcto.V2.Native.Response.Asset](OpenRtbEcto.V2.Native.Response.Asset.md): 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.

- [OpenRtbEcto.V2.Native.Response.Data](OpenRtbEcto.V2.Native.Response.Data.md): 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.

- [OpenRtbEcto.V2.Native.Response.EventTracker](OpenRtbEcto.V2.Native.Response.EventTracker.md): 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.

- [OpenRtbEcto.V2.Native.Response.Img](OpenRtbEcto.V2.Native.Response.Img.md): 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.

- [OpenRtbEcto.V2.Native.Response.Link](OpenRtbEcto.V2.Native.Response.Link.md): 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.

- [OpenRtbEcto.V2.Native.Response.Title](OpenRtbEcto.V2.Native.Response.Title.md): Corresponds to the Title Object in the request, with the value filled in.

- [OpenRtbEcto.V2.Native.Response.Video](OpenRtbEcto.V2.Native.Response.Video.md): Corresponds to the Video Object in the request, yet containing a value of a conforming VAST tag as a value.

- [OpenRtbEcto.V3.BidRequest](OpenRtbEcto.V3.BidRequest.md): ### 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.
- [OpenRtbEcto.V3.BidRequest.Deal](OpenRtbEcto.V3.BidRequest.Deal.md): 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.
- [OpenRtbEcto.V3.BidRequest.Item](OpenRtbEcto.V3.BidRequest.Item.md): 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).
- [OpenRtbEcto.V3.BidRequest.Metric](OpenRtbEcto.V3.BidRequest.Metric.md): 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.
- [OpenRtbEcto.V3.BidRequest.Request](OpenRtbEcto.V3.BidRequest.Request.md): 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.
- [OpenRtbEcto.V3.BidRequest.Source](OpenRtbEcto.V3.BidRequest.Source.md): 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.
- [OpenRtbEcto.V3.BidResponse](OpenRtbEcto.V3.BidResponse.md): 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.
- [OpenRtbEcto.V3.BidResponse.Bid](OpenRtbEcto.V3.BidResponse.Bid.md): 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.
- [OpenRtbEcto.V3.BidResponse.Macro](OpenRtbEcto.V3.BidResponse.Macro.md): 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.
- [OpenRtbEcto.V3.BidResponse.Response](OpenRtbEcto.V3.BidResponse.Response.md): 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.
- [OpenRtbEcto.V3.BidResponse.SeatBid](OpenRtbEcto.V3.BidResponse.SeatBid.md): 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.