From 0643fe47a2bf5ba8e72830843973b053ce6d3f58 Mon Sep 17 00:00:00 2001 From: Simon Trasler Date: Mon, 10 Jul 2023 17:37:57 -0700 Subject: [PATCH 01/38] Initial commit --- .../com/iabtechlab/openrtb/v2/openrtb.proto | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 src/main/com/iabtechlab/openrtb/v2/openrtb.proto diff --git a/src/main/com/iabtechlab/openrtb/v2/openrtb.proto b/src/main/com/iabtechlab/openrtb/v2/openrtb.proto new file mode 100644 index 0000000..bd4beb8 --- /dev/null +++ b/src/main/com/iabtechlab/openrtb/v2/openrtb.proto @@ -0,0 +1,37 @@ +syntax = "proto2"; + +option java_outer_classname = "OpenRtb"; +package com.iabtechlab.openrtb.v2; + +// Copyright 2020 IAB Tech Lab +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// OpenRTB extensions ("ext" fields in the spec & JSON representation) +// are represented here by Protocol Buffer extensions. This proto only +// reserves the range of IDs 100-9999 at every extensible object. Beware +// that upstream authors of a message may reserve extension IDs for their +// own use, so an author is not free to propagate a message adding their +// own extensions. + +// OpenRTB 2.0: 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). 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. From 92ecdc19ec03a8714a9e68b928e3f64c6c8b6be5 Mon Sep 17 00:00:00 2001 From: Simon Trasler Date: Fri, 14 Jul 2023 15:58:54 -0700 Subject: [PATCH 02/38] Draft definition --- .../com/iabtechlab/openrtb/v2/openrtb.proto | 2530 +++++++++++++++++ 1 file changed, 2530 insertions(+) diff --git a/src/main/com/iabtechlab/openrtb/v2/openrtb.proto b/src/main/com/iabtechlab/openrtb/v2/openrtb.proto index bd4beb8..55c6018 100644 --- a/src/main/com/iabtechlab/openrtb/v2/openrtb.proto +++ b/src/main/com/iabtechlab/openrtb/v2/openrtb.proto @@ -35,3 +35,2533 @@ package com.iabtechlab.openrtb.v2; // 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. +message BidRequest { + // Unique ID of the bid request, provided by the exchange. + // REQUIRED by the OpenRTB specification. + required string id = 1; + + // Array of Imp objects (Section 3.2.2) representing the impressions offered. + // At least 1 Imp object is required. + repeated Imp imp = 2; + + oneof distributionchannel_oneof { + // Details via a Site object (Section 3.2.6) about the publisher's website. + // Only applicable and recommended for websites. + Site site = 3; + + // Details via an App object (Section 3.2.7) about the publisher's app + // (non-browser applications). Only applicable and recommended for apps. + App app = 4; + + // This object should be included if the ad supported content is a Digital + // Out-Of-Home screen. A bid request with a DOOH object must not contain a + // site or app object. + Dooh dooh = 0; + } + + // Details via a Device object (Section 3.2.11) about the user's + // device to which the impression will be delivered. + optional Device device = 5; + + // Details via a User object (Section 3.2.13) about the human + // user of the device; the advertising audience. + optional User user = 6; + + // Indicator of test mode in which auctions are not billable, + // where 0 = live mode, 1 = test mode. + optional bool test = 15 [default = false]; + + // Auction type, where 1 = First Price, 2 = Second Price Plus. + // Refer to enum com.iabtechlab.openrtb.v3.AuctionType for generic values. + // Exchange-specific auction types can be defined using values > 500. + optional int32 at = 7 [default = 2]; + + // Maximum time in milliseconds to submit a bid to avoid timeout. + // This value is commonly communicated offline. + optional int32 tmax = 8; + + // 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. + repeated string wseat = 9; + + // Block list of buyer seats (e.g., advertisers, agencies) restricted + // from bidding on this impression. IDs of seats and knowledge + // of the buyer's customers to which they refer must be + // coordinated between bidders and the exchange a priori. + // At most, only one of wseat and bseat should be used in the + // same request. Omission of both implies no seat restrictions. + repeated string bseat = 17; + + // Flag to indicate if Exchange can verify that the impressions offered + // 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 + // represent all that are available. + optional bool allimps = 10 [default = false]; + + // Array of allowed currencies for bids on this bid request using ISO-4217 + // alpha codes. Recommended only if the exchange accepts multiple currencies. + repeated string cur = 11; + + // White list of languages for creatives using ISO-639-1-alpha-2. + // Omission implies no specific restrictions, but buyers would be + // advised to consider language attribute in the Device and/or + // Content objects if available. + repeated string wlang = 18; + + // Allowed list of languages for creatives using IETF BCP 47I. Omission + // implies no specific restrictions, but buyers would be advised to consider + // language attribute in the Device and/or Content objects if available. Only + // one of wlang or wlangb should be present. + repeated string wlangb = 20; + + // Blocked advertiser categories using the IAB content categories. + repeated string bcat = 12; + + // The taxonomy in use for bcat. + // Refer to the enum com.iabtechlab.adcom.v1.enums.CategoryTaxonomy for values. + optional int32 cattax = 21 [default = 1]; + + // Block list of advertisers by their domains (e.g., "ford.com"). + repeated string badv = 13; + + // Block list 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. + repeated string bapp = 16; + + // A Source object (Section 3.2.2) that provides data about the + // inventory source and which entity makes the final decision. + optional Source source = 19; + + // A Regs object (Section 3.2.16) that specifies any industry, legal, + // or governmental regulations in force for this request. + optional Regs regs = 14; + + // Extensions. + extensions 100 to 9999; + + // OpenRTB 2.5: 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. + message Source { + // Entity responsible for the final impression sale decision, + // where 0 = exchange, 1 = upstream source + // RECOMMENDED by the OpenRTB specification. + optional bool fd = 1; + + // Transaction ID that must be common across all participants in + // this bid request (e.g., potentially multiple exchanges). + // RECOMMENDED by the OpenRTB specification. + optional string tid = 2; + + // Payment ID chain string containing embedded syntax + // described in the TAG Payment ID Protocol v1.0. + // RECOMMENDED by the OpenRTB specification. + optional string pchain = 3; + + // This object represents both the links in the supply chain as well as an + // indicator whether or not the supply chain is complete. + optional SupplyChain schain = 4; + + // Extensions. + extensions 100 to 9999; + + // This object represents both the links in the supply chain as well as an + // indicator whether or not the supply chain is complete. + message SupplyChain { + // Flag indicating whether the chain contains all nodes involved in the + // transaction leading back to the owner of the site, app or other medium + // of the inventory, where 0 = no, 1 = yes. + optional bool complete = 1; + + // Version of the supply chain specification in use, in the format of + // "major.minor". For example, for version 1.0 of the spec, use the string + // "1.0". + optional string ver = 2; + + // Array of SupplyChainNode objects in the order of the chain. In a + // complete supply chain, the first node represents the initial + // advertising system and seller ID involved in the transaction, i.e. the + // owner of the site, app, or other medium. In an incomplete supply chain, + // it represents the first known node. The last node represents the entity + // sending this bid request. + repeated SupplyChainNode nodes = 3; + + // 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. + message SupplyChainNode { + // The canonical domain name of the SSP, Exchange, Header Wrapper, etc + // system that bidders connect to. This may be the operational domain + // of the system, if that is different than the parent corporate + // domain, to facilitate WHOIS and reverse IP lookups to establish + // clear ownership of the delegate system. This should be the same + // value as used to identify sellers in an ads.txt file if one exists. + optional string asi = 1; + + // The identifier associated with the seller or reseller account within + // the advertising system. This must contain the same value used in + // transactions (i.e. OpenRTB bid requests) in the field specified by + // the SSP/exchange. Typically, in OpenRTB, this is publisher.id. For + // OpenDirect it is typically the publisher’s organization ID. Should + // be limited to 64 characters in length. + optional string sid = 2; + + // The OpenRTB RequestId of the request as issued by this seller. + optional string rid = 3; + + // The name of the company (the legal entity) that is paid for + // inventory transacted under the given seller_id. This value is + // optional and should NOT be included if it exists in the advertising + // system’s sellers.json file. + optional string name = 4; + + // The business domain name of the entity represented by this node. + // This value is optional and should NOT be included if it exists in + // the advertising system’s sellers.json file. + optional string domain = 5; + + // Indicates whether this node will be involved in the flow of payment + // for the inventory. When set to 1, the advertising system in the asi + // field pays the seller in the sid field, who is responsible for + // paying the previous node in the chain. When set to 0, this node is + // not involved in the flow of payment for the inventory. For version + // 1.0 of SupplyChain, this property should always be 1. It is + // explicitly required to be included as it is expected that future + // versions of the specification will introduce non-payment handling + // nodes. Implementers should ensure that they support this field and + // propagate it onwards when constructing SupplyChain objects in bid + // requests sent to a downstream advertising system. + optional bool hp = 6; + + // Extensions. + extensions 100 to 9999; + } + } + } + + // OpenRTB 2.2: 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"). Refer to Section 7.1 for more information. + message Regs { + // Flag indicating if this request is subject to the COPPA regulations + // established by the USA FTC, where 0 = no, 1 = yes. + optional bool coppa = 1; + + // Flag that indicates whether or not the request is subject to GDPR regulations. + optional bool gdpr = 5; + + // Communicates signals regarding consumer privacy under US privacy regulation. + optional string us_privacy = 6; + + // Global Privacy Platform string containing encoded consumer privacy choices. + optional string gpp = 3; + + // Array of GPP string section ID(s) in force for the current transaction. + // In most cases, this field should have a single section ID. In rare + // occasions where such a single section ID can not be determined, the + // field may contain up to 2 values, separated by a comma. + repeated int32 gpp_sid = 4 [packed = true]; + + // Retired fields. + reserved 2; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.0: 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.5) 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. + // Any given bid for the impression must conform to one of the offered types. + message Imp { + // A unique identifier for this impression within the context of the bid + // request (typically, value starts with 1, and increments up to n + // for n impressions). + required string id = 1; + + // An array of Metric object (Section 3.2.5). + repeated Metric metric = 17; + + // A Banner object (Section 3.2.3); required if this impression is + // offered as a banner ad opportunity. + optional Banner banner = 2; + + // A Video object (Section 3.2.4); required if this impression is + // offered as a video ad opportunity. + optional Video video = 3; + + // An Audio object; required if this impression is offered + // as an audio ad opportunity. + optional Audio audio = 15; + + // A Native object (Section 3.2.5); required if this impression is + // offered as a native ad opportunity. + optional Native native = 13; + + // A Pmp object (Section 3.2.17) containing any private marketplace deals + // in effect for this impression. + optional Pmp pmp = 11; + + // Name of 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 partner. Recommended for video and/or apps. + optional string displaymanager = 4; + + // Version of 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 partner. Recommended for video and/or apps. + optional string displaymanagerver = 5; + + // 1 = the ad is interstitial or full screen, 0 = not interstitial. + optional bool instl = 6 [default = false]; + + // 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. + optional string tagid = 7; + + // Minimum bid for this impression expressed in CPM. + optional double bidfloor = 8 [default = 0]; + + // Currency specified using ISO-4217 alpha codes. This may be different + // from bid currency returned by bidder if this is allowed by the exchange. + optional string bidfloorcur = 9 [default = "USD"]; + + // 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. + optional bool clickbrowser = 16; + + // 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. + optional bool secure = 12; + + // Array of exchange-specific names of supported iframe busters. + repeated string iframebuster = 10; + + // Indicates whether the user receives a reward for viewing the ad, where 0 + // = no, 1 = yes. Typically video ad implementations allow users to read an + // additional news article for free, receive an extra life in a game, or get + // a sponsored ad-free music session. The reward is typically distributed + // after the video ad is completed. + optional bool rwdd = 18 [default = false]; + + // Indicates if server-side ad insertion (e.g., stitching an ad into an + // audio or video stream) is in use and the impact of this on asset and + // tracker retrieval, where 0 = status unknown, 1 = all client-side (i.e., + // not server-side), 2 = assets stitched server-side but tracking pixels + // fired client-side, 3 = all server-side. + optional int32 ssai = 19 [default = 0]; + + // Advisory as to the number of seconds that may elapse + // between the auction and the actual impression. + optional int32 exp = 14; + + // A means of passing a multiplier in the bid request, representing the + // total quantity of impressions for adverts that display to more than one + // person. + optional Qty qty = 0; + + // Timestamp when the item is estimated to be fulfilled (e.g. when a DOOH + // impression will be displayed) in Unix format (i.e., milliseconds since + // the epoch). + optional double dt = 0; + + // Details about ad slots being refreshed automatically. + optional Refresh refresh = 0; + + // Extensions. + extensions 100 to 9999; + + // OpenRTB 2.5: 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. + message Metric { + // Type of metric being presented using exchange curated string + // names which should be published to bidders a priori. + // REQUIRED by the OpenRTB specification. + optional string type = 1; + + // Number representing the value of the metric. + // Probabilities must be in the range 0.0 - 1.0. + // REQUIRED by the OpenRTB specification. + optional double value = 2; + + // Source of the value using exchange curated string names + // which should be published to bidders a priori. + // If the exchange itself is the source versus a third party, + // "EXCHANGE" is recommended. + // RECOMMENDED by the OpenRTB specification. + optional string vendor = 3; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.0: 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.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 and/or native by also including as Imp subordinates the Video + // and/or Native objects, respectively. However, any given bid for the + // impression must conform to one of the offered types. + message Banner { + // Array of format objects representing the banner sizes permitted. + // If none are specified, then use of the h and w attributes + // is highly recommended. + repeated Format format = 15; + + // Width in device independent pixels (DIPS). + // If no format objects are specified, this is an exact width + // requirement. Otherwise it is a preferred width. + optional int32 w = 1; + + // Height in device independent pixels (DIPS). + // If no format objects are specified, this is an exact height + // requirement. Otherwise it is a preferred height. + optional int32 h = 2; + + // Blocked banner ad types. + // Refer to enum BannerAdType for generic values. + repeated int32 btype = 5 [packed = true]; + + // Blocked creative attributes. + // Refer to enum com.iabtechlab.adcom.v1.enums.Creative.Attribute for generic values. + repeated int32 battr = 6 [packed = true]; + + // Ad position on screen. + // Refer to enum Position for generic values. + optional int32 pos = 4; + + // Whitelist of content MIME types supported. Popular MIME types include, + // but are not limited to "image/jpg", "image/gif" and + // "application/x-shockwave-flash". + repeated string mimes = 7; + + // Specify if the banner is delivered in the top frame (true) + // or in an iframe (false). + optional bool topframe = 8; + + // Directions in which the banner may expand. + // Refer to enum com.iabtechlab.adcom.v1.enums.ExpandableDirection for generic values. + repeated int32 expdir = 9 [packed = true]; + + // List of supported API frameworks for this impression. + // If an API is not explicitly listed, it is assumed not to be supported. + // Refer to enum com.iabtechlab.adcom.v1.enums.APIFramework for generic values. + repeated int32 api = 10 [packed = true]; + + // Unique identifier for this banner object. Recommended when Banner + // objects are used with a Video object to represent an array of + // companion ads. Values usually start at 1 and increase with each + // object; should be unique within an impression. + optional string id = 3; + + // Relevant only for Banner objects used with a Video object in an array + // of companion ads. Indicates the companion banner rendering mode + // relative to the associated video, where 0 = concurrent, 1 = end-card. + optional bool vcm = 16; + + // Retired fields. + reserved 11 to 14; + + // Extensions. + extensions 100 to 9999; + + // OpenRTB 2.4: 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. + message Format { + // Width in device independent pixels (DIPS). + optional int32 w = 1; + + // Height in device independent pixels (DIPS). + optional int32 h = 2; + + // Relative width when expressing size as a ratio. + optional int32 wratio = 3; + + // Relative height when expressing size as a ratio. + optional int32 hratio = 4; + + // The minimum width in device independent pixels (DIPS) at which the + // ad will be displayed when the size is expressed as a ratio. + optional int32 wmin = 5; + + // Extensions. + extensions 100 to 9999; + } + } + + // OpenRTB 2.0: 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 and/or native by also including as Imp subordinates the Banner + // and/or Native objects, respectively. However, any given bid for the + // impression must conform to one of the offered types. + message Video { + // Content MIME types supported (e.g., "video/mp4"). + // REQUIRED by the OpenRTB specification: at least 1 element. + repeated string mimes = 1; + + // Minimum video ad duration in seconds. + // RECOMMENDED by the OpenRTB specification. + optional int32 minduration = 3 [default = 0]; + + // Maximum video ad duration in seconds. + // RECOMMENDED by the OpenRTB specification. + optional int32 maxduration = 4; + + // Indicates the start delay in seconds for pre-roll, mid-roll, or + // post-roll ad placements. + // Refer to enum com.iabtechlab.adcom.v1.StartDelayMode for generic values. + // RECOMMENDED by the OpenRTB specification. + optional int32 startdelay = 8; + + // Indicates the maximum number of ads that may be served into a + // "dynamic" video ad pod (where the precise number of ads is not + // predetermined by the seller). + optional int32 maxseq = 28; + + // Indicates the total amount of time in seconds that advertisers may + // fill for a "dynamic" video ad pod (See Section 7.6 for more details), + // or the dynamic portion of a "hybrid" ad pod. This field is required + // only for the dynamic portion(s) of video ad pods. This field refers to + // the length of the entire ad break, whereas + // minduration/maxduration/rqddurs are constraints relating to the slots + // that make up the pod. + optional int32 poddur = 29; + + // Array of supported video bid response protocols. + // At least one supported protocol must be specified. + // Refer to enum com.iabtechlab.adcom.v1.Creative.AudioVideoType for generic values. + repeated int32 protocols = 21 [packed = true]; + + // Width of the video player in device independent pixels (DIPS). + // RECOMMENDED by the OpenRTB specification. + optional int32 w = 6; + + // Height of the video player in device independent pixels (DIPS). + // RECOMMENDED by the OpenRTB specification. + optional int32 h = 7; + + // Unique identifier indicating that an impression opportunity belongs to + // a video ad pod. If multiple impression opportunities within a bid + // request share the same podid, this indicates that those impression + // opportunities belong to the same video ad pod. + optional string podid = 30; + + // The sequence (position) of the video ad pod within a content stream. + optional int32 podseq = 31 [default = 0]; + + // Precise acceptable durations for video creatives in seconds. This + // field specifically targets the Live TV use case where non-exact ad + // durations would result in undesirable ‘dead air’. This field is + // mutually exclusive with minduration and maxduration; if rqddurs is + // specified, minduration and maxduration must not be specified and vice + // versa. + repeated int32 rqddurs = 32 [packed = true]; + + // Placement type for the impression. + // Refer to enum com.iabtechlab.adcom.v1.VideoPlacementSubtype for generic values. + optional int32 placement = 26 [deprecated = true]; + + // Video placement type for the impression. + // Refer to enum com.iabtechlab.adcom.v1.VideoPlcmtSubtype for generic values. + optional int32 plcmt = 35; + + // Indicates if the impression must be linear, nonlinear, etc. + // If none specified, assume all are allowed. + // Refer to enum com.iabtechlab.adcom.v1.enums.LinearityMode for generic values. + optional int32 linearity = 2; + + // 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. + optional bool skip = 23; + + // Videos of total duration greater than this number of seconds + // can be skippable; only applicable if the ad is skippable. + optional int32 skipmin = 24 [default = 0]; + + // Number of seconds a video must play before skipping is + // enabled; only applicable if the ad is skippable. + optional int32 skipafter = 25 [default = 0]; + + // If multiple ad impressions are offered in the same bid request, + // the sequence number will allow for the coordinated delivery of + // multiple creatives. + optional int32 sequence = 9 [default = 0, deprecated = true]; + + // For video ad pods, this value indicates that the seller can guarantee + // delivery against the indicated slot position in the pod. + optional int32 slotinpod = 33 [default = 0]; + + // Minimum CPM per second. This is a price floor for the "dynamic" + // portion of a video ad pod, relative to the duration of bids an + // advertiser may submit. + optional double mincpmpersec = 34; + + // Blocked creative attributes. + // Refer to enum com.iabtechlab.adcom.v1.enums.Creative.Attribute for generic values. + repeated int32 battr = 10 [packed = true]; + + // Maximum extended video ad duration, if extension is allowed. + // If blank or 0, extension is not allowed. If -1, extension is allowed, + // and there is no time limit imposed. If greater than 0, then the value + // represents the number of seconds of extended play supported beyond + // the maxduration value. + optional int32 maxextended = 11; + + // Minimum bit rate in Kbps. + optional int32 minbitrate = 12; + + // Maximum bit rate in Kbps. + optional int32 maxbitrate = 13; + + // Indicates if letter-boxing of 4:3 content into a 16:9 window is + // allowed, where 0 = no, 1 = yes. + optional bool boxingallowed = 14 [default = true]; + + // Playback methods that may be in use. If none are specified, any + // method may be used. 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. It is strongly advised to use only + // the first element of this array in preparation for this change. + // Refer to enum com.iabtechlab.adcom.v1.PlaybackMethod for generic values. + repeated int32 playbackmethod = 15 [packed = true]; + + // The event that causes playback to end. + // Refer to enum com.iabtechlab.adcom.v1.PlaybackCessationMode for generic values. + optional int32 playbackend = 27; + + // Supported delivery methods (e.g., streaming, progressive). + // If none specified, assume all are supported. + // Refer to enum com.iabtechlab.adcom.v1.enums.DeliveryMethod for generic values. + repeated int32 delivery = 16 [packed = true]; + + // Ad position on screen. + // Refer to enum com.iabtechlab.adcom.v1.PlacementPosition for generic values. + optional int32 pos = 17; + + // Array of Banner objects (Section 3.2.3) if companion ads are available. + repeated Banner companionad = 18; + + // List of supported API frameworks for this impression. + // If an API is not explicitly listed, it is assumed not to be supported. + // Refer to enum com.iabtechlab.adcom.v1.enums.APIFramework for generic values. + repeated int32 api = 19 [packed = true]; + + // Supported VAST companion ad types. Recommended if companion Banner + // objects are included via the companionad array. + // Refer to enum com.iabtechlab.adcom.v1.CompanionType for generic values. + repeated int32 companiontype = 20 [packed = true]; + + // Retired fields. + reserved 5, 22; + + // Extensions. + extensions 100 to 9999; + } + + // 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 + // that define these companion ads. + // + // The presence of a Audio as a subordinate of the Imp object indicates + // that this impression is offered as an audio type impression. + // At the publisher's discretion, that same impression may also be offered + // as banner, video, and/or native by also including as Imp subordinates + // objects of those types. However, any given bid for the impression must + // conform to one of the offered types. + message Audio { + // Content MIME types supported (e.g., "audio/mp4"). + // REQUIRED by the OpenRTB specification: at least 1 element. + repeated string mimes = 1; + + // Minimum audio ad duration in seconds. + // RECOMMENDED by the OpenRTB specification. + optional int32 minduration = 2 [default = 0]; + + // Maximum audio ad duration in seconds. + // RECOMMENDED by the OpenRTB specification. + optional int32 maxduration = 3; + + // Indicates the total amount of time in seconds that advertisers may + // fill for a "dynamic" video ad pod (See Section 7.6 for more details), + // or the dynamic portion of a "hybrid" ad pod. This field is required + // only for the dynamic portion(s) of video ad pods. This field refers to + // the length of the entire ad break, whereas + // minduration/maxduration/rqddurs are constraints relating to the slots + // that make up the pod. + optional int32 poddur = 25; + + // Array of supported audio protocols. + // Refer to enum com.iabtechlab.adcom.v1.Creative.AudioVideoType for generic values. + // RECOMMENDED by the OpenRTB specification. + repeated int32 protocols = 4 [packed = true]; + + // Indicates the start delay in seconds for pre-roll, mid-roll, or + // post-roll ad placements. + // Refer to enum com.iabtechlab.adcom.v1.StartDelayMode for generic values. + // RECOMMENDED by the OpenRTB specification. + optional int32 startdelay = 5; + + // Precise acceptable durations for audio creatives in seconds. This + // field specifically targets the live audio/radio use case where + // non-exact ad durations would result in undesirable 'dead air'. This + // field is mutually exclusive with minduraiton and maxduration; if + // rqddurs is specified, minduraiton and maxduration must not be + // specified and vice versa. + repeated int32 rqddurs = 26 [packed = true]; + + // Unique identifier indicating that an impression opportunity belongs to + // an audio ad pod. If multiple impression opportunities within a bid + // request share the same podid, this indicates that those impression + // opportunities belong to the same audio ad pod. + optional string podid = 27; + + // The sequence (position) of the audio ad pod within a content stream. + optional int32 podseq = 28 [default = 0]; + + // If multiple ad impressions are offered in the same bid request, + // the sequence number will allow for the coordinated delivery of + // multiple creatives. + optional int32 sequence = 6 [default = 0, deprecated = true]; + + // For audio ad pods, this value indicates that the seller can guarantee + // delivery against the indicated slot position in the pod. + optional int32 slotinpod = 29 [default = 0]; + + // Minimum CPM per second. This is a price floor for the "dynamic" + // portion of an audio ad pod, relative to the duration of bids an + // advertiser may submit. + optional double mincpmpersec = 30; + + // Blocked creative attributes. + // Refer to enum com.iabtechlab.adcom.v1.enums.Creative.Attribute for generic values. + repeated int32 battr = 7 [packed = true]; + + // Maximum extended video ad duration, if extension is allowed. + // If blank or 0, extension is not allowed. If -1, extension is allowed, + // and there is no time limit imposed. If greater than 0, then the value + // represents the number of seconds of extended play supported beyond + // the maxduration value. + optional int32 maxextended = 8; + + // Minimum bit rate in Kbps. + optional int32 minbitrate = 9; + + // Maximum bit rate in Kbps. + optional int32 maxbitrate = 10; + + // Supported delivery methods (e.g., streaming, progressive). + // If none specified, assume all are supported. + // Refer to enum com.iabtechlab.adcom.v1.enums.DeliveryMethod for generic values. + repeated int32 delivery = 11 [packed = true]; + + // Array of Banner objects if companion ads are available. + repeated Banner companionad = 12; + + // List of supported API frameworks for this impression. + // If an API is not explicitly listed, it is assumed not to be supported. + // Refer to enum com.iabtechlab.adcom.v1.enums.APIFramework for generic values. + repeated int32 api = 13 [packed = true]; + + // Supported DAAST companion ad types. Recommended if companion Banner + // objects are included via the companionad array. + // Refer to enum com.iabtechlab.adcom.v1.CompanionType for generic values. + repeated int32 companiontype = 20 [packed = true]; + + // The maximum number of ads that can be played in an ad pod. + optional int32 maxseq = 21; + + // Type of audio feed. + // Refer to enum com.iabtechlab.adcom.v1.enums.FeedType for generic values. + optional int32 feed = 22; + + // Indicates if the ad is stitched with audio content or delivered + // independently, where 0 = no, 1 = yes. + optional bool stitched = 23; + + // Volume normalization mode. + // Refer to enum com.iabtechlab.adcom.v1.VolumeNormalizationMode for generic values. + optional int32 nvol = 24; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.3: 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 Native Ad Specification. 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 Native Ad Specification. 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 and/or video by also including as Imp subordinates the Banner + // and/or Video objects, respectively. However, any given bid for the + // impression must conform to one of the offered types. + message Native { + oneof request_oneof { + // Request payload complying with the Native Ad Specification. + // Exactly one of {request, request_native} should be used; + // this is the OpenRTB-compliant field for JSON serialization. + string request = 1; + + // Request payload complying with the Native Ad Specification. + // Exactly one of {request, request_native} should be used; + // this is an alternate field preferred for Protobuf serialization. + NativeRequest request_native = 50; + } + + // Version of the Native Ad Specification to which request complies. + // RECOMMENDED by the OpenRTB specification. + optional string ver = 2; + + // List of supported API frameworks for this impression. + // If an API is not explicitly listed, it is assumed not to be supported. + // Refer to enum com.iabtechlab.adcom.v1.enums.APIFramework for generic values. + repeated int32 api = 3 [packed = true]; + + // Blocked creative attributes. + // Refer to enum com.iabtechlab.adcom.v1.enums.Creative.Attribute for generic values. + repeated int32 battr = 4 [packed = true]; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.2: 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.2 for more details. + message Pmp { + // Indicator of auction eligibility to seats named in the Direct Deals + // object, where 0 = all bids are accepted, 1 = bids are restricted to + // the deals specified and the terms thereof. + optional bool private_auction = 1 [default = false]; + + // Array of Deal (Section 3.2.18) objects that convey the specific deals + // applicable to this impression. + repeated Deal deals = 2; + + // Extensions. + extensions 100 to 9999; + + // OpenRTB 2.2: 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.2 for more details. + message Deal { + // A unique identifier for the direct deal. + // REQUIRED by the OpenRTB specification. + required string id = 1; + + // Minimum bid for this impression expressed in CPM. + optional double bidfloor = 2 [default = 0]; + + // Currency specified using ISO-4217 alpha codes. This may be different + // from bid currency returned by bidder if this is allowed + // by the exchange. + optional string bidfloorcur = 3 [default = "USD"]; + + // Optional override of the overall auction type of the bid request, + // where 1 = First Price, 2 = Second Price Plus, 3 = the value passed + // in bidfloor is the agreed upon deal price. Additional auction types + // can be defined by the exchange. + // Refer to enum com.iabtechlab.openrtb.v3.AuctionType for generic values. + optional int32 at = 6; + + // Whitelist of buyer seats (e.g., advertisers, agencies) allowed to + // bid on this deal. 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. + repeated string wseat = 4; + + // Array of advertiser domains (e.g., advertiser.com) allowed to + // bid on this deal. Omission implies no advertiser restrictions. + repeated string wadomain = 5; + + // Extensions. + extensions 100 to 9999; + } + } + } + + // OpenRTB 2.0: 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. + message Site { + // Site ID on the exchange. + // RECOMMENDED by the OpenRTB specification. + optional string id = 1; + + // Site name (may be masked at publisher's request). + optional string name = 2; + + // Domain of the site, used for advertiser side blocking. + // For example, "foo.com". + optional string domain = 3; + + // The taxonomy in use. + // Refer to the enum com.iabtechlab.adcom.v1.enums.CategoryTaxonomy for values. + optional int32 cattax = 16 [default = 1]; + + // Array of IAB content categories of the site. + repeated string cat = 4; + + // Array of IAB content categories that describe the current section + // of the site. + repeated string sectioncat = 5; + + // Array of IAB content categories that describe the current page or view + // of the site. + repeated string pagecat = 6; + + // URL of the page where the impression will be shown. + optional string page = 7; + + // Referrer URL that caused navigation to the current page. + optional string ref = 9; + + // Search string that caused navigation to the current page. + optional string search = 10; + + // Indicates if the site has been programmed to optimize layout + // when viewed on mobile devices, where 0 = no, 1 = yes. + optional bool mobile = 15; + + // Indicates if the site has a privacy policy, where 0 = no, 1 = yes. + optional bool privacypolicy = 8; + + // Details about the Publisher (Section 3.2.8) of the site. + optional Publisher publisher = 11; + + // Details about the Content (Section 3.2.9) within the site. + optional Content content = 12; + + oneof keywords_oneof { + // Comma separated list of keywords about the site. Only one of keywords or + // kwarray may be present. + optional string keywords = 13; + + // Array of keywords about the site. Only one of keywords or kwarray may be + // present. + repeated string kwarray = 0; + } + + // A domain to be used for inventory authorization in the case of inventory + // sharing arrangements between a site owner and content owner. This field + // is typically used by authorization crawlers to establish the domain of + // the content owner, who has the right to monetize some portion of ad + // inventory within the site. The content owner's domain should be listed + // in the site owner's ads.txt file as an inventorypartnerdomain. + // Authorization for supply from the inventorypartnerdomain will be + // published in the ads.txt file on the root of that domain. Refer to the + // ads.txt 1.1 spec for more details. + optional string inventorypartnerdomain = 0; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.0: 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. + message App { + // Application ID on the exchange. + // RECOMMENDED by the OpenRTB specification. + optional string id = 1; + + // Application name (may be aliased at publisher's request). App names for + // SDK-less requests (mostly from connected TVs) can be provided by the + // publisher directly in the request. + optional string name = 2; + + // 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. For SDK-less requests (mostly from connected + // TVs), it can be provided by the publisher directly in the request. + optional string bundle = 8; + + // Domain of the application. For example, "mygame.foo.com". + optional string domain = 3; + + // App store URL for an installed app; for QAG 1.5 compliance. + optional string storeurl = 16; + + // The taxonomy in use. + // Refer to the enum com.iabtechlab.adcom.v1.enums.CategoryTaxonomy for values. + optional int32 cattax = 17 [default = 1]; + + // Array of IAB content categories of the app. + repeated string cat = 4; + + // Array of IAB content categories that describe the current section + // of the app. + repeated string sectioncat = 5; + + // Array of IAB content categories that describe the current page or view + // of the app. + repeated string pagecat = 6; + + // Application version. + optional string ver = 7; + + // Indicates if the app has a privacy policy, where 0 = no, 1 = yes. + optional bool privacypolicy = 9; + + // 0 = app is free, 1 = the app is a paid version. + optional bool paid = 10; + + // Details about the Publisher (Section 3.2.8) of the app. + optional Publisher publisher = 11; + + // Details about the Content (Section 3.2.9) within the app. + optional Content content = 12; + + oneof keywords_oneof { + // Comma separated list of keywords about the app. Only one of keywords or + // kwarray may be present. + optional string keywords = 13; + + // Array of keywords about the app. Only one of keywords or kwarray may be + // present. + repeated string kwarray = 0; + } + + // A domain to be used for inventory authorization in the case of inventory + // sharing arrangements between an app owner and content owner. This field + // is typically used by authorization crawlers to establish the domain of + // the content owner, who has the right to monetize some portion of ad + // inventory within the app. The content owner's domain should be listed in + // the app owner's app-ads.txt file as an inventorypartnerdomain. + // Authorization for supply from the inventorypartnerdomain will be + // published in the ads.txt file on the root of that domain. Refer to the + // ads.txt 1.1 spec for more details. + optional string inventorypartnerdomain = 0; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.0: 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. + message Publisher { + // Exchange-specific publisher ID. + optional string id = 1; + + // Publisher name (may be aliased at publisher's request). + optional string name = 2; + + // The taxonomy in use. + // Refer to the enum com.iabtechlab.adcom.v1.enums.CategoryTaxonomy for values. + optional int32 cattax = 5 [default = 1]; + + // Array of IAB content categories that describe the publisher. + repeated string cat = 3; + + // Highest level domain of the publisher (e.g., "publisher.com"). + optional string domain = 4; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.0: 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 might be a video impression embedded in an iframe on an + // unknown web property or device. + message Content { + // ID uniquely identifying the content. + optional string id = 1; + + // Content episode number (typically applies to video content). + optional int32 episode = 2; + + // Content title. + // Video Examples: "Search Committee" (television), "A New Hope" (movie), + // or "Endgame" (made for web). + // Non-Video Example: "Why an Antarctic Glacier Is Melting So Quickly" + // (Time magazine article). + optional string title = 3; + + // Content series. + // Video Examples: "The Office" (television), "Star Wars" (movie), + // or "Arby 'N' The Chief" (made for web). + // Non-Video Example: "Ecocentric" (Time Magazine blog). + optional string series = 4; + + // Content season; typically for video content (e.g., "Season 3"). + optional string season = 5; + + // Artist credited with the content. + optional string artist = 21; + + // Genre that best describes the content (e.g., rock, pop, etc). + optional string genre = 22; + + // Album to which the content belongs; typically for audio. + optional string album = 23; + + // International Standard Recording Code conforming to ISO-3901. + optional string isrc = 24; + + // Details about the content Producer (Section 3.2.10). + optional Producer producer = 15; + + // URL of the content, for buy-side contextualization or review. + optional string url = 6; + + // The taxonomy in use. + // Refer to the enum com.iabtechlab.adcom.v1.enums.CategoryTaxonomy for values. + optional int32 cattax = 27 [default = 1]; + + // Array of IAB content categories that describe the content. + repeated string cat = 7; + + // Production quality. + // Refer to enum com.iabtechlab.adcom.v1.ProductionQuality for generic values. + optional int32 prodq = 25; + + // Type of content (game, video, text, etc.). + optional int32 context = 20; + + // Content rating (e.g., MPAA). + optional string contentrating = 10; + + // User rating of the content (e.g., number of stars, likes, etc.). + // Refer to enum com.iabtechlab.adcom.v1.enums.ContentContext for generic values. + optional string userrating = 11; + + // Media rating per QAG guidelines. + // Refer to enum com.iabtechlab.adcom.v1.MediaRating for generic values. + optional int32 qagmediarating = 17; + + // Comma separated list of keywords describing the content. Only one of + // keywords or kwarray may be present. + optional string keywords = 9; + + // Array of keywords about the site. Only one of keywords or kwarray may be + // present. + repeated string kwarray = 0; + + // 0 = not live, 1 = content is live (e.g., stream, live blog). + optional bool livestream = 13; + + // 0 = indirect, 1 = direct. + optional bool sourcerelationship = 14; + + // Length of content in seconds; appropriate for video or audio. + optional int32 len = 16; + + // Content language using ISO-639-1-alpha-2. + optional string language = 19; + + // Content language using IETF BCP 47. + // Only one of language or langb should be present. + optional string langb = 29; + + // Indicator of whether or not the content is embeddable (e.g., an + // embeddable video player), where 0 = no, 1 = yes. + optional bool embeddable = 18; + + // Additional content data. Each Data object represents a different + // data source. + repeated Data data = 26; + + // Details about the network the content is on. + optional Network network = 30; + + // Details about the channel the content is on. + optional Channel channel = 31; + + // Retired fields. + reserved 8; + + // Extensions. + extensions 100 to 9999; + + // OpenRTB 2.0: 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. + message Producer { + // Content producer or originator ID. Useful if content is syndicated, + // and may be posted on a site using embed tags. + optional string id = 1; + + // Content producer or originator name (e.g., "Warner Bros"). + optional string name = 2; + + // The taxonomy in use. + // Refer to the enum com.iabtechlab.adcom.v1.enums.CategoryTaxonomy for values. + optional int32 cattax = 5 [default = 1]; + + // Array of IAB content categories that describe the content producer. + repeated string cat = 3; + + // Highest level domain of the content producer (e.g., "producer.com"). + optional string domain = 4; + + // Extensions. + extensions 100 to 9999; + } + } + + // OpenRTB 2.0: 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. + message Device { + // Location of the device assumed to be the user's current location defined + // by a Geo object (Section 3.2.12). + // RECOMMENDED by the OpenRTB specification. + optional Geo geo = 4; + + // Standard "Do Not Track" flag as set in the header by the browser, + // where 0 = tracking is unrestricted, 1 = do not track. + // RECOMMENDED by the OpenRTB specification. + optional bool dnt = 1; + + // "Limit Ad Tracking" signal commercially endorsed (e.g., iOS, Android), + // where 0 = tracking is unrestricted, 1 = tracking must be limited per + // commercial guidelines. + // RECOMMENDED by the OpenRTB specification. + optional bool lmt = 23; + + // Browser user agent string. Certain data may be redacted or replaced. + // RECOMMENDED by the OpenRTB specification. + optional string ua = 2; + + // Structured user agent information defined by a UserAgent object (Section 3.2.29) + optional UserAgent sua = 31; + + // IPv4 address closest to device. + optional string ip = 3; + + // IPv6 address closest to device. + optional string ipv6 = 9; + + // The general type of device. + // Refer to enum com.iabtechlab.adcom.v1.enums.DeviceType for generic values. + optional int32 devicetype = 18; + + // Device make (e.g., "Apple"). + optional string make = 12; + + // Device model (e.g., "iPhone"). + optional string model = 13; + + // Device operating system (e.g., "iOS"). + optional string os = 14; + + // Device operating system version (e.g., "3.1.2"). + optional string osv = 15; + + // Hardware version of the device (e.g., "5S" for iPhone 5S). + optional string hwv = 24; + + // Physical height of the screen in pixels. + optional int32 h = 26; + + // Physical width of the screen in pixels. + optional int32 w = 25; + + // Screen size as pixels per linear inch. + optional int32 ppi = 27; + + // The ratio of physical pixels to device independent pixels. + optional double pxratio = 28; + + // Support for JavaScript, where 0 = no, 1 = yes. + optional bool js = 16; + + // Indicates if the geolocation API will be available to JavaScript + // code running in the banner, where 0 = no, 1 = yes. + optional bool geofetch = 29; + + // Version of Flash supported by the browser. + optional string flashver = 19; + + // Browser language using ISO-639-1-alpha-2. + optional string language = 11; + + // Browser language using IETF BCP 47. Only one of language or langb should + // be present. + optional string langb = 32; + + // Carrier or ISP (e.g., "VERIZON") using exchange curated string names + // which should be published to bidders a priori. + optional string carrier = 10; + + // Mobile carrier as the concatenated MCC-MNC code (e.g., + // "310-005" identifies Verizon Wireless CDMA in the USA). + // Refer to https://en.wikipedia.org/wiki/Mobile_country_code + // for further examples. Note that the dash between the MCC + // and MNC parts is required to remove parsing ambiguity. + optional string mccmnc = 30; + + // Network connection type. + // Refer to enum com.iabtechlab.adcom.v1.enums.ConnectionType for generic values. + optional int32 connectiontype = 17; + + // ID sanctioned for advertiser use in the clear (i.e., not hashed). + optional string ifa = 20; + + // Hardware device ID (e.g., IMEI); hashed via SHA1. + optional string didsha1 = 5 [deprecated = true]; + + // Hardware device ID (e.g., IMEI); hashed via MD5. + optional string didmd5 = 6 [deprecated = true]; + + // Platform device ID (e.g., Android ID); hashed via SHA1. + optional string dpidsha1 = 7 [deprecated = true]; + + // Platform device ID (e.g., Android ID); hashed via MD5. + optional string dpidmd5 = 8 [deprecated = true]; + + // MAC address of the device; hashed via SHA1. + optional string macsha1 = 21 [deprecated = true]; + + // MAC address of the device; hashed via MD5. + optional string macmd5 = 22 [deprecated = true]; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.0: 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. + message Geo { + // Latitude from -90.0 to +90.0, where negative is south. + optional double lat = 1; + + // Longitude from -180.0 to +180.0, where negative is west. + optional double lon = 2; + + // Source of location data; recommended when passing lat/lon. + // Refer to enum com.iabtechlab.adcom.v1.enums.LocationType for generic values. + optional int32 type = 9; + + // Estimated location accuracy in meters; recommended when lat/lon + // are specified and derived from a device's location services + // (i.e., type = 1). Note that this is the accuracy as reported + // from the device. Consult OS specific documentation + // (e.g., Android, iOS) for exact interpretation. + optional int32 accuracy = 11; + + // 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. + optional int32 lastfix = 12; + + // Service or provider used to determine geolocation from IP + // address if applicable (i.e., type = 2). + // Refer to enum com.iabtechlab.adcom.v1.enums.LocationService for generic values. + optional int32 ipservice = 13; + + // Country using ISO-3166-1 Alpha-3. + optional string country = 3; + + // Region code using ISO-3166-2; 2-letter state code if USA. + optional string region = 4; + + // Region of a country using FIPS 10-4 notation. While OpenRTB supports + // this attribute, it has been withdrawn by NIST in 2008. + optional string regionfips104 = 5; + + // Google metro code; similar to but not exactly Nielsen DMAs. + // See Appendix A for a link to the codes. + // (http://code.google.com/apis/adwords/docs/appendix/metrocodes.html). + optional string metro = 6; + + // City using United Nations Code for Trade & Transport Locations. + // See Appendix A for a link to the codes. + // (http://www.unece.org/cefact/locode/service/location.htm). + optional string city = 7; + + // Zip/postal code. + optional string zip = 8; + + // Local time as the number +/- of minutes from UTC. + optional int32 utcoffset = 10; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.0: 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. + message User { + // Exchange-specific ID for the user. At least one of id or buyeruid + // is recommended. + optional string id = 1; + + // Buyer-specific ID for the user as mapped by the exchange for the buyer. + // At least one of buyeruid or id is recommended. + optional string buyeruid = 2; + + // Year of birth as a 4-digit integer. + optional int32 yob = 3 [deprecated = true]; + + // Gender as "M" male, "F" female, "O" Other. (Null indicates unknown) + optional string gender = 4 [deprecated = true]; + + oneof keywords_oneof { + // Comma separated list of keywords, interests, or intent. Only one of keywords or kwarray may be present. + optional string keywords = 5; + + // Array of keywords about the user. Only one of keywords or kwarray may be present. + repeated string kwarray = 0; + } + + // Optional feature to pass bidder data set in the exchange's cookie. + // The string must be in base85 cookie safe characters and be in any format. + // Proper JSON encoding must be used to include "escaped" quotation marks. + optional string customdata = 6; + + // Location of the user's home base defined by a Geo object + // (Section 3.2.12). This is not necessarily their current location. + optional Geo geo = 7; + + // Additional user data. Each Data object (Section 3.2.14) represents a + // different data source. + repeated Data data = 8; + + // When GDPR regulations are in effect this attribute contains the + // Transparency and Consent Framework’s Consent String data structure. + optional string consent = 9; + + // Details for support of a standard protocol for multiple third party + // identity providers. + repeated EID eids = 11; + + // Extensions. + extensions 100 to 9999; + + // Extended identifiers support in the OpenRTB specification allows buyers + // to use audience data in real-time bidding. The exchange should ensure + // that business agreements allow for the sending of this data. Note, it + // is assumed that exchanges and DSPs will collaborate with the appropriate + // regulatory agencies and ID vendor(s) to ensure compliance. + message EID { + // Source or technology provider responsible for the set of included IDs. + // Expressed as a top-level domain. + optional string source = 1; + + // Array of extended ID UID objects from the given source. + repeated UID uids = 2; + + // Extensions. + extensions 100 to 9999; + + message UID { + // Cookie or platform-native identifier. + optional string id = 1; + + // Type of user agent the match is from. It is highly recommended to + // set this, as many DSPs separate app-native IDs from browser-based + // IDs and require a type value for ID resolution. + // Refer to enum com.iabtechlab.adcom.v1.enums.AgentType for generic values. + optional int32 atype = 2; + + // Extensions. + extensions 100 to 9999; + } + } + } + + // OpenRTB 2.0: 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 or + // can have multiple data objects. + // The specific data providers in use should be published by the exchange + // a priori to its bidders. + // This is used to send detected verticals to the buyer. + // For exchange bidding, this is also used to send key + // value pairs from the publisher to the buyer. + // https://support.google.com/admanager/answer/177381 + message Data { + // Exchange-specific ID for the data provider. + optional string id = 1; + + // Exchange-specific name for the data provider. + optional string name = 2; + + // Array of Segment (Section 3.2.15) objects that contain the actual + // data values. + repeated Segment segment = 3; + + // Extensions. + extensions 100 to 9999; + + // OpenRTB 2.0: 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. + message Segment { + // ID of the data segment specific to the data provider. + optional string id = 1; + + // Name of the data segment specific to the data provider. + optional string name = 2; + + // String representation of the data segment value. + optional string value = 3; + + // Extensions. + extensions 100 to 9999; + } + } + + // 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. + message Network { + // A unique identifier assigned by the publisher. This may not be a unique + // identifier across all supply sources. + optional string id = 1; + + // Network the content is on (e.g., a TV network like "ABC"). + optional string name = 2; + + // The primary domain of the network (e.g. "abc.com" in the case of the + // network ABC). It is recommended to include the top private domain (PSL+1) + // for DSP targeting normalization purposes. + optional string domain = 3; + + // Extensions. + extensions 100 to 9999; + } + + // 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 + // 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. + message Channel { + // A unique identifier assigned by the publisher. This may not be a unique + // identifier across all supply sources. + optional string id = 1; + + // Channel the content is on (e.g., a TV channel like "WABC-TV"). + optional string name = 2; + + // The primary domain of the channel (e.g. "abc7ny.com" in the case of the + // local channel WABC-TV). It is recommended to include the top private + // domain (PSL+1) for DSP targeting normalization purposes. + optional string domain = 3; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB 2.6: 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. + message UserAgent { + // Each BrandVersion object identifies a browser + // or similar software component. Implementers should send brands and + // versions derived from the Sec-CH-UA-Full-Version-List header + // or an equivalent JavaScript accessor from NavigatorUAData interface. + // This header or accessor are only available for browsers that support User-Agent Client Hints. + // RECOMMENDED by the OpenRTB specification. + repeated BrandVersion browsers = 1; + + // A BrandVersion object that identifies the + // user agent’s execution platform / OS. Implementers should send a brand + // derived from the Sec-CH-UA-Platform header, and version derived + // from the Sec-CH-UA-Platform-Version header + // or an equivalent JavaScript accessor from NavigatorUAData interface. + // This header or accessor are only available for browsers that support User-Agent Client Hints. + // RECOMMENDED by the OpenRTB specification. + optional BrandVersion platform = 2; + + // 1 if the agent prefers a "mobile" version of the content, if available, + // i.e. optimized for small screens or touch input. + // 0 if the agent prefers the "desktop" or "full" content. + // Implementers should derive this value from the Sec-CH-UA-Mobile header + // or an equivalent JavaScript accessor from NavigatorUAData interface. + // This header or accessor are only available for browsers that support User-Agent Client Hints. + optional bool mobile = 3; + + // Device’s major binary architecture, e.g. "x86" or "arm". + // Implementers should retrieve this value from the Sec-CH-UA-Arch header + // or an equivalent JavaScript accessor from NavigatorUAData interface. + // This header or accessor are only available for browsers that support User-Agent Client Hints. + optional string architecture = 4; + + // Device’s bitness, e.g. "64" for 64-bit architecture. + // Implementers should retrieve this value from the Sec-CH-UA-Bitness header + // or an equivalent JavaScript accessor from NavigatorUAData interface. + // This header or accessor are only available for browsers that support User-Agent Client Hints. + optional string bitness = 5; + + // Device model. Implementers should retrieve this value from the Sec-CH-UA-Model header + // or an equivalent JavaScript accessor from NavigatorUAData interface. + // This header or accessor are only available for browsers that support User-Agent Client Hints. + optional string model = 6; + + // The source of data used to create this object + // Refer to enum com.iabtechlab.adcom.v1.enums.UserAgentSource for generic values + optional int32 source = 7 [default = 0]; + + // Placeholder for vendor specific extensions to this object. + extensions 100 to 9999; + } + + // OpenRTB 2.6: 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. + message BrandVersion { + // A brand identifier, for example, "Chrome" or "Windows". The value may be + // sourced from the User-Agent Client Hints headers, representing either + // the user agent brand (from the Sec-CH-UA-Full-Version header) or the + // platform brand (from the Sec-CH-UA-Platform header). + optional string brand = 1; + + // A sequence of version components, in descending hierarchical order + // (major, minor, micro, ...). + repeated string version = 2; + + // Placeholder for vendor specific extensions to this object. + extensions 100 to 9999; + } + + // A programmatic impression is often referred to as a ‘spot’ in digital + // out-of-home and CTV, with an impression being a unique member of the + // audience viewing it. Therefore, a standard means of passing a multiplier + // in the bid request, representing the total quantity of impressions, is + // required. This object includes the impression multiplier, and describes + // the source of the multiplier value. + message Qty { + // The quantity of billable events which will be deemed to have occurred if + // this item is purchased. For example, a DOOH opportunity may be + // considered to be 14.2 impressions. Equivalent to qtyflt in OpenRTB 3.0. + optional double multiplier = 1; + + // The source type of the quantity measurement, ie. publisher. + // RECOMMENDED by the OpenRTB specification. + optional int32 sourcetype = 2; + + // The top level business domain name of the measurement vendor providing + // the quantity measurement. + // REQUIRED by the OpenRTB specification if sourcetype is equal to 1. + optional string vendor = 3; + + // Placeholder for vendor specific extensions to this object. + extensions 100 to 9999; + } + + // This object should be included if the ad supported content is a Digital + // Out-Of-Home screen. A bid request with a DOOH object must not contain a + // site or app object. At a minimum, it is useful to provide id and/or + // venuetypeid, but this is not strictly required. + message Dooh { + // Exchange provided id for a placement or logical grouping of placements. + optional string id = 1; + + // Name of the DOOH placement. + optional string name = 2; + + // The type of out-of-home venue. The taxonomy to be used is defined by the + // venuetax field. If no venuetax field is supplied, The OpenOOH Venue + // Taxonomy is assumed. + repeated string venuetype = 3; + + // The venue taxonomy in use. + optional int32 venuetypetax = 4 [default = 1]; + + // Details about the publisher of the placement. + optional Publisher publisher = 5; + + // Domain of the inventory owner (e.g., "mysite.foo.com"). + optional string domain = 6; + + // Comma separated list of keywords about the DOOH placement. + optional string keywords = 7; + + // Details about the Content within the DOOH placement. + optional Content content = 8; + + // Placeholder for vendor specific extensions to this object. + extensions 100 to 9999; + } + + message Refresh { + // A RefSettings object describing the mechanics of how an ad placement + // automatically refreshes. + repeated RefSettings refsettings = 1; + + // The number of times this ad slot had been refreshed since last page + // load. + optional int32 count = 2; + + // Placeholder for vendor specific extensions to this object. + extensions 100 to 9999; + + // Information on how often and what triggers an ad slot being refreshed. + message RefSettings { + // The type of the declared auto refresh. + optional int32 reftype = 1 [default = 0]; + + // The minimum refresh interval in seconds. This applies to all refresh + // types. This is the (uninterrupted) time the ad creative will be + // rendered before refreshing to the next creative. If the field is + // absent, the exposure time is unknown. This field does not account for + // viewability or external factors such as a user leaving a page. + optional int32 minint = 2; + + // Placeholder for vendor specific extensions to this object. + extensions 100 to 9999; + } + } +} + +// OpenRTB 2.0: 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. +message BidResponse { + // ID of the bid request to which this is a response. + // REQUIRED by the OpenRTB specification. + required string id = 1; + + // Array of seatbid objects; 1+ required if a bid is to be made. + repeated SeatBid seatbid = 2; + + // Bidder generated response ID to assist with logging/tracking. + optional string bidid = 3; + + // Bid currency using ISO-4217 alpha codes. + optional string cur = 4 [default = "USD"]; + + // Optional feature to allow a bidder to set data in the exchange's cookie. + // The string must be in base85 cookie safe characters and be in any format. + // Proper JSON encoding must be used to include "escaped" quotation marks. + optional string customdata = 5; + + // Reason for not bidding. + // Refer to enum com.iabtechlab.openrtb.v3.NoBidReason for generic values. + optional int32 nbr = 6; + + // Extensions. + extensions 100 to 9999; + + // OpenRTB 2.0: 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. + message SeatBid { + // Array of 1+ Bid objects (Section 4.2.3) each related to an impression. + // Multiple bids can relate to the same impression. + repeated Bid bid = 1; + + // ID of the buyer seat (e.g., advertiser, agency) on whose behalf this bid + // is made. + optional string seat = 2; + + // 0 = impressions can be won individually; 1 = impressions must be won or + // lost as a group. + optional bool group = 3 [default = false]; + + // Extensions. + extensions 100 to 9999; + + // OpenRTB 2.0: 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. + message Bid { + // Bidder generated bid ID to assist with logging/tracking. + // REQUIRED by the OpenRTB specification. + required string id = 1; + + // ID of the Imp object in the related bid request. + // REQUIRED by the OpenRTB specification. + required string impid = 2; + + // Bid price expressed as CPM although the actual transaction is for a + // unit impression only. Note that while the type indicates float, integer + // math is highly recommended when handling currencies + // (e.g., BigDecimal in Java). + // REQUIRED by the OpenRTB specification. + required double price = 3; + + // Win notice URL called by the exchange if the bid wins; optional means + // of serving ad markup. Substitution macros may be included in both the + // URL and optionally returned markup. + optional string nurl = 5; + + // Billing notice URL called by the exchange when a winning bid + // becomes billable based on exchange-specific business policy + // (e.g., typically delivered, viewed, etc.). Substitution macros + // may be included. + optional string burl = 22; + + // Loss notice URL called by the exchange when a bid is known to have + // been lost. Substitution macros may be included. Exchange-specific + // policy may preclude support for loss notices or the disclosure of + // winning clearing prices resulting in ${AUCTION_PRICE} macros being + // removed (i.e., replaced with a zero-length string). + optional string lurl = 23; + + oneof adm_oneof { + // Optional means of conveying ad markup in case the bid wins; + // supersedes the win notice if markup is included in both. + // For native ad bids, exactly one of {adm, adm_native} should be used; + // this is the OpenRTB-compliant field for JSON serialization. + string adm = 6; + + // Native ad response. + // For native ad bids, exactly one of {adm, adm_native} should be used; + // this is the field used for Protobuf serialization. + NativeResponse adm_native = 50; + } + + // ID of a preloaded ad to be served if the bid wins. + optional string adid = 4; + + // Advertiser domain for block list checking (e.g., "ford.com"). This can + // be an array of for the case of rotating creatives. Exchanges can + // mandate that only one domain is allowed. + repeated string adomain = 7; + + // 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. + optional string bundle = 14; + + // URL without cache-busting to an image that is representative of the + // content of the campaign for ad quality/safety checking. + optional string iurl = 8; + + // Campaign ID to assist with ad quality checking; the collection of + // creatives for which iurl should be representative. + optional string cid = 9; + + // Creative ID to assist with ad quality checking. + optional string crid = 10; + + // Tactic ID to enable buyers to label bids for reporting to the + // exchange the tactic through which their bid was submitted. The + // specific usage and meaning of the tactic ID should be communicated + // between buyer and exchanges a priori. + optional string tactic = 24; + + // The taxonomy in use. + // Refer to the enum com.iabtechlab.adcom.v1.enums.CategoryTaxonomy for values. + optional int32 cattax = 30 [default = 1]; + + // IAB content categories of the creative. + repeated string cat = 15; + + // Set of attributes describing the creative. + // Refer to enum com.iabtechlab.adcom.v1.enums.Creative.Attribute for generic values. + repeated int32 attr = 11 [packed = true]; + + // List of supported APIs for the markup. If an API is not explicitly + // listed, it is assumed to be unsupported. + // Refer to enum com.iabtechlab.adcom.v1.enums.APIFramework for generic values. + repeated int32 apis = 31 [packed = true]; + + // API required by the markup if applicable. + // Refer to enum com.iabtechlab.adcom.v1.enums.APIFramework for generic values. + optional int32 api = 18 [deprecated = true]; + + // Video response protocol of the markup if applicable. + // Refer to enum com.iabtechlab.adcom.v1.Creative.AudioVideoType for generic values. + optional int32 protocol = 19; + + // Creative media rating per QAG guidelines. + // Refer to enum com.iabtechlab.adcom.v1.MediaRating for generic values. + optional int32 qagmediarating = 20; + + // Language of the creative using ISO-639-1-alpha-2. The nonstandard + // code "xx" may also be used if the creative has no + // linguistic content (e.g., a banner with just a company logo). + optional string language = 25; + + // Language of the creative using IETF BCP 47. Only one of language or + // langb should be present. + optional string langb = 29; + + // Reference to the deal.id from the bid request if this bid pertains to a + // private marketplace direct deal. + optional string dealid = 13; + + // Width of the creative in device independent pixels (DIPS). + optional int32 w = 16; + + // Height of the creative in device independent pixels (DIPS). + optional int32 h = 17; + + // Relative width of the creative when expressing size as a ratio. + // Required for Flex Ads. + optional int32 wratio = 26; + + // Relative height of the creative when expressing size as a ratio. + // Required for Flex Ads. + optional int32 hratio = 27; + + // Advisory as to the number of seconds the bidder is willing to + // wait between the auction and the actual impression. + optional int32 exp = 21; + + // Duration of the video or audio creative in seconds. + optional int32 dur = 32; + + // Type of the creative markup so that it can properly be associated with + // the right sub-object of the BidRequest.Imp. + optional int32 mtype = 33; + + // Indicates that the bid response is only eligible for a specific + // position within a video or audio ad pod (e.g. first position, last + // position, or any). + optional int32 slotinpod = 28 [default = 0]; + + // Extensions. + extensions 100 to 9999; + } + } +} + +// OpenRTB Native 1.0: The Native Object defines the native advertising +// opportunity available for bid via this bid request. It must be included +// directly in the impression object if the impression offered for auction +// is a native ad format. +// Note: Prior to VERSION 1.1, the specification could be interpreted as +// requiring the native request to have a root node with a single field "native" +// that would contain the NativeRequest as its value. +// In 1.2 The NativeRequest Object specified here is now the root object. +message NativeRequest { + // Version of the Native Markup version in use. + optional string ver = 1; + + // The Layout ID of the native ad unit. + // Refer to enum LayoutId for generic values. + // RECOMMENDED by OpenRTB Native 1.0; optional in 1.1. + optional int32 layout = 2 [deprecated = true]; + + // The Ad unit ID of the native ad unit. + // This corresponds to one of IAB Core-6 native ad units. + // Refer to enum AdUnitId for generic values. + // RECOMMENDED by OpenRTB Native 1.0; optional in 1.1. + optional int32 adunit = 3 [deprecated = true]; + + // The context in which the ad appears. + // Refer to enum ContextType for generic values. + // RECOMMENDED in 1.2. + optional int32 context = 7; + + // A more detailed context in which the ad appears. + // Refer to enum com.iabtechlab.adcom.v1.enums.DisplayContextType for generic values. + optional int32 contextsubtype = 8; + + // The design/format/layout of the ad unit being offered. + // Refer to enum com.iabtechlab.adcom.v1.enums.DisplayPlacementType for generic values. + // RECOMMENDED by the OpenRTB Native specification. + optional int32 plcmttype = 9; + + // The number of identical placements in this Layout. + optional int32 plcmtcnt = 4 [default = 1]; + + // 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). + optional int32 seq = 5 [default = 0]; + + // Any bid must comply with the array of elements expressed by the Exchange. + // REQUIRED by the OpenRTB Native specification: at least 1 element. + repeated Asset assets = 6; + + // Whether the supply source / impression supports returning an assetsurl + // instead of an asset object. 0 or the absence of the field indicates no such + // support. + optional bool aurlsupport = 11; + + // Whether the supply source / impression supports returning a DCO URL + // instead of an asset object. 0 or the absence of the field indicates no such + // support. Beta feature. + optional bool durlsupport = 12; + + // Specifies what type of event tracking is supported. + repeated EventTrackers eventtrackers = 13; + + // Set to 1 when the native ad supports buyer-specific privacy notice. + // Set to 0 (or field absent) when the native ad doesn't support custom + // privacy links or if support is unknown. + // RECOMMENDED in 1.2. + optional bool privacy = 14; + + // Extensions. + extensions 100 to 9999; + + // OpenRTB Native 1.0: 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 + // Asset array so that the response can be aligned. + // + // To be more explicit, it is the ID of each asset object that maps the + // response to the request. So if a request for a title object is sent with + // id 1, then the response containing the title should have an id of 1. + // + // Since version 1.1 of the spec, there are recommended sizes/lengths/etc + // with some of the asset types. The goal for asset requirements + // standardization is to facilitate adoption of native by DSPs by limiting + // the diverse types/sizes/requirements of assets they must have available to + // purchase a native ad impression. While great diversity may exist in + // publishers, advertisers/DSPs can not be expected to provide infinite + // headline lengths, thumbnail aspect ratios, etc. While we have not gone as + // far as creating a single standard, we've honed in on a few options that + // cover the most common cases. SSPs can deviate from these standards, but + // should understand they may limit applicable DSP demand by doing so. DSPs + // should feel confident that if they support these standards they'll be able + // to access most native inventory. + message Asset { + // Unique asset ID, assigned by exchange. Typically a counter for the array. + // REQUIRED by the OpenRTB Native specification. + required int32 id = 1; + + // Set to true if asset is required + // (exchange will not accept a bid without it). + optional bool required = 2 [default = false]; + + // RECOMMENDED by the OpenRTB Native specification. + oneof asset_oneof { + // Title object for title assets. + Title title = 3; + + // Image object for image assets. + Image img = 4; + + // Video object for video assets. + // Note that in-stream video ads are not part of Native. + // Native ads may contain a video as the ad creative itself. + BidRequest.Imp.Video video = 5; + + // Data object for brand name, description, ratings, prices etc. + Data data = 6; + } + + // Extensions. + extensions 100 to 9999; + + // OpenRTB Native 1.0: The Title object is to be used for title element + // of the Native ad. + message Title { + // Maximum length of the text in the title element. + // RECOMMENDED that the value be either of: 25, 90, 140. + // REQUIRED by the OpenRTB Native specification. + required int32 len = 1; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB Native 1.0: The Image object to be used for all image elements + // of the Native ad such as Icons, Main Image, etc. + // RECOMMENDED sizes and aspect ratios are included in com.iabtechlab.adcom.v1.NativeImageAssetType. + message Image { + // Type ID of the image element supported by the publisher. + // The publisher can display this information in an appropriate format. + // Refer to enum com.iabtechlab.adcom.v1.NativeImageAssetType for generic values. + optional int32 type = 1; + + // Width of the image in pixels. + optional int32 w = 2; + + // 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. + // RECOMMENDED by the OpenRTB Native specification. + optional int32 wmin = 4; + + // Height of the image in pixels. + optional int32 h = 3; + + // 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. + // RECOMMENDED by the OpenRTB Native specification. + optional int32 hmin = 5; + + // Whitelist of content MIME types supported. Popular MIME types include, + // but are not limited to "image/jpg" and "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. + repeated string mimes = 6; + + // Extensions. + extensions 100 to 9999; + } + + // OpenRTB Native 1.0: The Data Object is to be used for all non-core + // elements of the native unit such as Ratings, Review Count, Stars, + // Download count, descriptions etc. It is also generic for future of Native + // elements not contemplated at the time of the writing of this document. + message Data { + // Type ID of the element supported by the publisher. The publisher can + // display this information in an appropriate format. + // Refer to enum com.iabtechlab.adcom.v1.NativeDataAssetType for generic values. + // REQUIRED by the OpenRTB Native specification. + required int32 type = 1; + + // Maximum length of the text in the element's response. Longer strings + // may be truncated and ellipsized by Ad Exchange or the publisher during + // rendering. + optional int32 len = 2; + + // Extensions. + extensions 100 to 9999; + } + } + + // OpenRTB Native 1.2: The EventTrackers object specifies the type 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. + message EventTrackers { + // Type of event available for tracking. + // Refer to enum com.iabtechlab.adcom.v1.EventType for generic values. + // REQUIRED by the OpenRTB Native specification. + required int32 event = 1; + + // Array of types of tracking available for the given event. + // Refer to enum com.iabtechlab.adcom.v1.enums.EventTrackingMethod for generic values. + // REQUIRED by the OpenRTB Native specification. + repeated int32 methods = 2; + + // Extensions. + extensions 100 to 9999; + } +} + +// OpenRTB Native 1.0: The native response object is the top level JSON object +// which identifies an native response. +// Note: Prior to VERSION 1.1, the native response's root node was an object +// with a single field "native" that would contain the object above as its +// value. In 1.2 The NativeResponse Object specified here is now the root +// object. +message NativeResponse { + // Version of the Native Markup version in use. + // RECOMMENDED in 1.2 + optional string ver = 1; + + // List of native ad's assets. + // RECOMMENDED in 1.0, 1.1, or in 1.2 as a fallback if assetsurl is provided. + // REQUIRED in 1.2, if not assetsurl is provided. + repeated Asset assets = 2; + + // URL of alternate source for the assets object. The expected response is a + // JSON object mirroring the asset object in the bid response, subject to + // certain requirements as specified in the individual objects. + // Where present, overrides the assets object in the response. + optional string assetsurl = 6; + + // URL where a dynamic creative specification may be found for populating this + // ad, per the Dynamic Content Ads Specification. + // Note this is a beta option as the interpretation of the Dynamic Content Ads + // Specification and how to assign those elementes into a native ad is outside + // the scope of this spec and must be agreed offline between parties or as may + // be specified in a future revision of the Dynamic Content Ads spec. + // Where present, overrides the assets object in the response. + optional string dcourl = 7; + + // Destination Link. This is default link object for the ad. + // Individual assets can also have a link object which applies if the asset is + // activated (clicked). If the asset doesn't have a link object, the parent + // link object applies. + // See ResponseLink definition. + // REQUIRED by the OpenRTB Native specification. + required Link link = 3; + + // Array of impression tracking URLs, expected to return a 1x1 image or + // 204 response - typically only passed when using 3rd party trackers. + // To be deprecated - replaced with eventtrackers. + repeated string imptrackers = 4; + + // Optional JavaScript impression tracker. This is a valid HTML, Javascript + // is already wrapped in