// Copyright 2015, Beeswax.IO Inc.
// Author: ramr@beeswax.com
//
// OpenRTB Protocol Buffer Spec.
// Note: This file is derived from google/openrtb project.
syntax = "proto2";
package openrtb;
option java_package = "com.beeswax.openrtb";
import "beeswax/openrtb/extension.proto";
import "beeswax/openrtb/openrtb_common.proto";
// OpenRTB extensions ("ext" fields in the spec & JSON representation)
// are represented here by Protocol Buffer extensions.
// Next available tag: 16 - Tag 19 is taken in order to match Google openrtb proto
/*
* OpenRTB 3.3.1: The top-level bid request object.
*/
message BidRequest {
/*
* Unique ID of the bid request, provided by the exchange.
*/
required string id = 1;
/*
* Multiple impression auctions may be specified in a single bid request.
* At least one impression is required for a valid bid request.
*/
repeated Impression imp = 2;
/*
* Information pertaining to a website.
*/
optional Site site = 3;
/*
* Information pertaining to a mobile application.
*/
optional App app = 4;
/*
* Information pertaining to the device.
*/
optional Device device = 5;
/*
* Information known or derived about the human user of the device.
*/
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. If “1”, then first price auction. If “2”, then second price
* auction.
* Additional auction types can be defined as per the exchange’s business
* rules.
* Exchange specific rules should be numbered over 500.
*/
optional int32 at = 7 [default = 2];
/*
* Maximum amount of time in milliseconds to submit a bid (e.g., 120 means the
* bidder has 120ms to submit a bid before the auction is complete). If this
* value never changes across an exchange, then the exchange can supply this
* information offline.
*/
optional int32 tmax = 8;
/*
* Array of buyer seats allowed to bid on this auction. Seats are an optional
* feature of exchange. For example, [“4”,”34”,”82”,”A45”] indicates that only
* advertisers using these exchange seats are allowed to bid on the
* impressions in this auction.
*/
repeated string wseat = 9;
/*
* Flag to indicate whether Exchange can verify that all impressions offered
* represent all of the impressions available in context (e.g., all
* impressions available on the web page; all impressions available for a
* video [pre, mid and postroll spots], etc.) to support road-blocking. A true
* value should only be passed if the exchange is aware of all impressions in
* context for the publisher. NO means the exchange cannot verify, and YES
* means that all impressions represent all impressions available.
*/
optional Flag allimps = 10 [default = NO];
/*
* Array of allowed currencies for bids on this bid request using ISO-4217 alphabetic codes.
* If only one currency is used by the exchange, this parameter is not required.
*/
repeated string cur = 11;
/*
* Blocked Advertiser Categories. Note that there is no existing categorization / taxonomy of
* advertiser industries. However, as a substitute exchanges may decide to use IAB categories
* as an approximation.
*/
repeated string bcat = 12;
/*
* Array of strings of blocked top-level domains of advertisers.
* For example, {“company1.com”, “company2.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;
/*
* Container for any legal, governmental or industry regulations in force for the request.
*/
optional Regulations regs = 14;
/*
* 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;
optional BidRequestExtensions ext = 1000;
// Next available tag: 4
/*
* 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;
/*
* Extensions.
*/
extensions 100 to 9999;
}
// Next available tag: 15
/*
* OpenRTB 3.3.2: describes the ad position 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 as a bundle.
* Each “imp” object has a required ID so that bids can reference them individually.
* An exchange can also conduct private auctions by restricting involvement to specific
* subsets of seats within bidders.
*/
message Impression {
/*
* 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;
/*
* Banner object. Either a banner or video object (or both if the impression could be either)
* must be included in an impression object.
*/
optional Banner banner = 2;
/*
* Video object. Either a banner or video object (or both if the impression could be either)
* must be included in an impression object.
*/
optional Video video = 3;
/**
* A Native object (Section 3.2.5); required if this impression is
* offered as a native ad opportunity.
*/
optional Native native = 13;
/*
* Name of ad mediation partner, SDK technology, or native player responsible for rendering
* ad (typically video or mobile). Used by some ad servers to customize ad code by partner.
*/
optional string displaymanager = 4;
/*
* Version of ad mediation partner, SDK technology, or native player responsible for rendering
* ad (typically video or mobile). Used by some ad servers to customize ad code by partner.
*/
optional string displaymanagerver = 5;
/*
* YES if the ad is interstitial or full screen; else NO.
*/
optional Flag instl = 6 [default = NO];
/*
* 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;
/*
* Bid floor for this impression (in CPM of bidfloorcur).
*/
optional double bidfloor = 8 [default = 0];
/*
* If bid floor is specified and multiple currencies supported per bid request,
* then currency should be specified here using ISO-4217 alphabetic codes.
* Note, this may be different from bid currency returned by bidder,
* if this is allowed on an 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;
/*
* Array of names for supported iframe busters. Exchange specific.
*/
repeated string iframebuster = 10;
/*
* Contains any Deals eligible for this Impression.
*/
optional PMP pmp = 11;
/*
* A flag to indicate if the impression requires secure HTTPS creative
* assets and markup.
* Value of 1 indicates that the impression requires secure creatives.
* If the value is 0 or not set, then the impression allows non-secure
* HTTP creatives.
*/
optional int32 secure = 12;
/*
* Advisory as to the number of seconds that may elapse
* between the auction and the actual impression.
*/
optional int32 exp = 14;
optional ImpressionExtensions ext = 1000;
/*
* OpenRTB 3.3.3: A banner object typically describes an ad impressions opportunity for banner,
* rich media or in-banner video inventory.
*/
message Banner {
/*
* Width of the impression in pixels. Since some ad types are not restricted by size
* this field is not required, but it’s highly recommended.
*/
optional int32 w = 1;
/*
* Height of the impression in pixels. Since some ad types are not restricted by size
* this field is not required, but it’s highly recommended.
*/
optional int32 h = 2;
/**
* Maximum width of the impression in pixels. If included, it indicates that a range
* of sizes is allowed with this maximum width and "w" is taken as recommended.
* If not included, then "w" should be considered an exact requirement.
*/
optional int32 wmax = 11;
/**
* Maximum height of the impression in pixels. If included, it indicates that a range
* of sizes is allowed with this maximum height and "h" is taken as recommended.
* If not included, then "h" should be considered an exact requirement.
*/
optional int32 hmax = 12;
/**
* Minimum width of the impression in pixels. If included, it indicates that a range
* of sizes is allowed with this minimum width and "w" is taken as recommended.
* If not included, then "w" should be considered an exact requirement.
*/
optional int32 wmin = 13;
/**
* Minumum height of the impression in pixels. If included, it indicates
* that a range of sizes is allowed with this minimum height and "h" is
* taken as recommended.
* If not included, then "h" should be considered an exact requirement.
*/
optional int32 hmin = 14;
/*
* Unique identifier for this banner object. Useful for tracking multiple banner objects
* (e.g., in companion banner array). Usually starts with 1, increasing with each object.
* Combination of impression id X banner id should be unique.
*/
optional string id = 3;
/*
* The position of the ad as a relative measure of visibility or
* prominence.
*/
optional Enums.BidRequest.Impression.AdPosition pos = 4 [default = POSITION_UNKNOWN];
/*
* Blocked creative types. If blank, assume all types are allowed.
*/
repeated Enums.BidRequest.Impression.Banner.AdType btype = 5;
/*
* Blocked creative attributes. If blank assume all types are allowed.
*/
repeated CreativeAttribute battr = 6;
/*
* 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 (YES) or in an iframe (NO).
*/
optional Flag topframe = 8 [default = NO];
/*
* Specify properties for an expandable ad.
*/
repeated Enums.BidRequest.Impression.Banner.ExpandableDirection expdir = 9;
/*
* List of supported API frameworks for this banner. If an API is not explicitly listed
* it is assumed not to be supported.
*/
repeated Enums.BidRequest.Impression.ApiFramework api = 10;
optional BannerExtensions ext = 1000;
}
// Next available tag: 21 - Tags 26, 27 taken in order to match Google openrtb proto
/*
* OpenRTB 3.3.4: A video object typically describes an ad opportunity for in-stream video
* inventory (including linear pre-roll, mid-roll and post-roll, and non-linear overlays).
* Please note, in-banner video is typically represented by the banner object.
*/
message Video {
/*
* 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 = 1;
/*
* Indicates whether the ad impression is linear or non-linear.
*/
optional Enums.BidRequest.Impression.Video.Linearity linearity = 2 [default = LINEAR];
/*
* Minimum video ad duration in seconds.
*/
optional int32 minduration = 3;
/*
* Maximum video ad duration in seconds.
*/
optional int32 maxduration = 4;
/*
* Video bid response protocols.
*/
repeated Enums.BidRequest.Impression.Video.Protocol protocols = 5;
/*
* Width of the player in pixels. This field is not required, but it’s highly recommended.
*/
optional int32 w = 6;
/*
* Height of the player in pixels. This field is not required, but it’s highly recommended.
*/
optional int32 h = 7;
/*
* Indicates the start delay in seconds for preroll, midroll, or postroll ad placement.
* Check the enum VideoStartDelay for special values.
*/
optional int32 startdelay = 8 [default = -3];
/*
* 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 = 1];
/*
* Blocked creative attributes. If blank assume all types are allowed.
*/
repeated CreativeAttribute battr = 10;
/*
* 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 [default = 0];
/*
* Minimum bit rate in Kbps. Exchange may set this dynamically,
* or universally across their set of publishers.
*/
optional int32 minbitrate = 12;
/*
* Maximum bit rate in Kbps. Exchange may set this dynamically,
* or universally across their set of publishers.
*/
optional int32 maxbitrate = 13;
/*
* If exchange publisher has rules preventing letter boxing of 4x3 content to play in a
* 16x9 window, then this should be set to false. Default setting is true, which assumes
* that boxing of content to fit into a window is allowed.
*/
optional Flag boxingallowed = 14 [default = YES];
/*
* List of allowed playback methods. If blank, assume that all are allowed.
*/
repeated Enums.BidRequest.Impression.Video.PlaybackMethod playbackmethod = 15;
/*
* List of supported delivery methods. If blank, assume all are supported.
*/
repeated Enums.BidRequest.Impression.Video.ContentDelivery delivery = 16;
/*
* The position of the ad as a relative measure of visibility or prominence.
*/
optional Enums.BidRequest.Impression.AdPosition pos = 17 [default = POSITION_UNKNOWN];
/*
* If companion ads are available, they can be listed as an array of banner objects.
*/
repeated Banner companionad = 18;
/*
* List of supported API frameworks for this banner. If an API is not explicitly listed
* it is assumed not to be supported.
*/
repeated Enums.BidRequest.Impression.ApiFramework api = 19;
/*
* Recommended if companion objects are included.
*/
repeated Enums.BidRequest.Impression.Video.CompanionType companiontype = 20;
/*
* Placement type for the impression.
*/
optional Enums.BidRequest.Impression.Video.VideoPlacementType placement = 26;
/*
* The event that causes playback to end.
*/
optional Enums.BidRequest.Impression.Video.PlaybackCessationMode playbackend = 27;
optional VideoExtensions ext = 1000;
}
/**
* OpenRTB 3.2.5: 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 {
/**
* Request payload complying with the Native Ad Specification.
*/
required NativeRequest request = 1;
/**
* Version of the Native Ad Specification to which request complies;
* highly recommended for efficient parsing.
*/
optional string ver = 2;
/**
* List of supported API frameworks for this impression. Refer to List 5.6.
* If an API is not explicitly listed, it is assumed not to be supported.
*/
repeated Enums.BidRequest.Impression.ApiFramework api = 3 [packed = true];
/**
* Blocked creative attributes. Refer to List 5.3.
*/
repeated CreativeAttribute battr = 4 [packed = true];
optional NativeExtensions ext = 1000;
}
/*
* OpenRTB 3.3.16: contains a parent object for usage within the context of private
* marketplaces and the use of the RTB protocol to execute Direct Deals.
*/
message PMP {
/*
* Flag indicating that this impression is a private auction eligible only to seats named
* in the DirectDeals object.
*/
optional Flag private_auction = 1;
/*
* A collection of deal objects encapsulating a list of direct deals eligible for
* this impression.
*/
repeated DirectDeal deals = 2;
optional PMPExtensions ext = 1000;
/*
* OpenRTB 3.3.17: constitutes a deal struck a priori between a buyer and a seller and
* indicates that this impression is available under the terms of that deal.
*/
message DirectDeal {
/*
* A unique identifier for the direct deal.
*/
required string id = 1;
/*
* Bid floor for this impression (in CPM of bidfloorcur).
*/
optional double bidfloor = 2 [default = 0];
/*
* If bid floor is specified and multiple currencies supported per bid request,
* then currency should be specified here using ISO-4217 alphabetic codes. Notes.
* this may be different from bid currency returned by bidder, if this is allowed
* on an exchange.
*/
optional string bidfloorcur = 3 [default = "USD"];
/*
* Array of buyer seats allowed to bid on this auction. Seats are an optional feature
* of exchange. For example, [“4”,”34”,”82”,”A45”] indicates that only advertisers
* using these exchange seats are allowed to bid on the impressions in this auction.
*/
repeated string wseat = 4;
/*
* Array of advertiser domains allowed to bid on this Direct Deal. For example,
* [ "advertiser1.com", "advertiser2.com" ] indicates that only the listed
* advertisers are allowed to bid on this direct deal.
*/
repeated string wadomain = 5;
/*
* Auction Type. If “1”, then first price auction. If “2”, then second price auction.
* Additional auction types can be defined as per the exchange’s business rules.
*/
optional int32 at = 6;
optional DirectDealExtensions ext = 1000;
}
}
}
// Next available tag: 16
/*
* OpenRTB 3.3.5: should be included if the ad supported content is part of a website
* (as opposed to an application).
*/
message Site {
/*
* Site ID on the exchange.
*/
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;
/*
* Array of IAB content categories for the overall site.
*/
repeated string cat = 4;
/*
* Array of IAB content categories for the current subsection of the site.
*/
repeated string sectioncat = 5;
/*
* Array of IAB content categories for the current page.
*/
repeated string pagecat = 6;
/*
* URL of the page where the impression will be shown.
*/
optional string page = 7;
/*
* Specifies whether the site has a privacy policy.
*/
optional Flag privacypolicy = 8;
/*
* Referrer URL that caused navigation to the current page.
*/
optional string ref = 10;
/*
* Search string that caused navigation to the current page.
*/
optional string search = 11;
/*
* Mobile-optimized signal, where 0 = no, 1 = yes.
*/
optional bool mobile = 15;
/*
* Site's Publisher.
*/
optional Publisher publisher = 12;
/*
* Site's Content.
*/
optional Content content = 13;
/*
* List of keywords describing this site in a comma separated string.
*/
optional string keywords = 14;
optional SiteExtensions ext = 1000;
}
// Next available tag: 15
/*
* OpenRTB 3.3.6: should be included if the ad supported content is part of a mobile application
* (as opposed to a mobile website).
*/
message App {
/*
* Application ID on the exchange.
*/
optional string id = 1 [default = "-1"];
/*
* Application name (may be masked at publisher’s request).
*/
optional string name = 2 [default = "-1"];
/*
* Domain of the application. For example, “mygame.foo.com”.
*/
optional string domain = 3;
/*
* Array of IAB content categories for the overall application.
*/
repeated string cat = 4;
/*
* Array of IAB content categories for the current subsection of the application.
*/
repeated string sectioncat = 5;
/*
* Array of IAB content categories for the current page/view of the app.
*/
repeated string pagecat = 6;
/*
* Application version.
*/
optional string ver = 7;
/*
* Application bundle or package name (e.g., com.foo.mygame). This is intended to be a
* unique ID across multiple exchanges.
*/
optional string bundle = 8 [default = "-1"];
/*
* Specifies whether the application has a privacy policy.
*/
optional Flag privacypolicy = 9;
/*
* Application is a paid version or free.
*/
optional Flag paid = 10;
/*
* Application's Publisher.
*/
optional Publisher publisher = 11;
/*
* Application's Content.
*/
optional Content content = 12;
/*
* List of keywords describing this site in a comma separated string.
*/
optional string keywords = 13;
/*
* For QAG 1.5 compliance, an app store URL for an installed app
* should be passed in the bid request.
*/
optional string storeurl = 14;
optional AppExtensions ext = 1000;
}
// Next available tag: 20
/*
* OpenRTB 3.3.7: describes the content of a site or app.
* This object may be useful in the situation where 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, video impressions 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.
*/
optional string title = 3;
/*
* Content series.
*/
optional string series = 4;
/*
* Content season.
*/
optional string season = 5;
/*
* Original URL of the content, for buy-side contextualization or review.
*/
optional string url = 6;
/*
* Array of IAB content categories for the content.
*/
repeated string cat = 7;
/*
* Video quality per the IAB’s classification.
*/
optional Enums.BidRequest.Content.VideoQuality videoquality = 8;
/*
* Comma separated list of keywords describing the content.
*/
optional string keywords = 9;
/*
* Content rating (e.g., MPAA).
*/
optional string contentrating = 10;
/*
* User rating of the content (e.g., number of stars, likes, etc.).
*/
optional string userrating = 11;
/*
* Specifies the type of content (game, video, text, etc.).
*/
optional Enums.BidRequest.Content.Context context = 12;
/*
* Is content live?
*/
optional Flag livestream = 13;
/*
* Direct or indirect.
*/
optional Enums.BidRequest.Content.SourceRelationship sourcerelationship = 14;
/*
* Content's Producer.
*/
optional Producer producer = 15;
/*
* Length of content (appropriate for video or audio) in seconds.
*/
optional int32 len = 16;
/*
* Media rating of the content, per QAG guidelines.
*/
optional Enums.BidRequest.Content.QAGMediaRating qagmediarating = 17 [default = UNKNOWN];
/*
* From QAG Video Addendum. If content can be embedded (such as an embeddable video player)
* this value should be set to YES. If content cannot be embedded, this should be set to NO.
*/
optional Flag embeddable = 18;
/*
* Language of the content. Use alpha-2/ISO 639-1 codes.
*/
optional string language = 19;
optional ContentExtensions ext = 1000;
}
// Next available tag: 29 - Tag 30 taken in order to match Google openrtb proto
/*
* OpenRTB 3.3.10: Provides information pertaining to the device including its hardware,
* platform, location, and carrier. This device can refer to a mobile handset, a desktop
* computer, set top box or other digital device. In general, the most essential fields are
* either the IP address (to enable geo-lookup for the bidder), or providing geo information
* directly in the geo object.
*/
message Device {
/*
* Do Not Track.
*/
optional Flag dnt = 1;
/*
* Browser user agent string.
*/
optional string ua = 2;
/*
* IPv4 address closest to device.
*/
optional string ip = 3 [default="0.0.0.0"];
/*
* Geography as derived from the device’s location services (e.g., cell tower triangulation,
* GPS) or IP address.
*/
optional Geo geo = 4;
/*
* SHA1 hashed device ID; IMEI when available, else MEID or ESN.
* OpenRTB’s preferred method for device ID hashing is SHA1.
*/
optional string didsha1 = 5;
/*
* MD5 hashed device ID; IMEI when available, else MEID or ESN.
* Should be interpreted as case insensitive.
*/
optional string didmd5 = 6;
/*
* SHA1 hashed platform-specific ID (e.g., Android ID or UDID for iOS).
* OpenRTB’s preferred method for device ID hash is SHA1.
*/
optional string dpidsha1 = 7;
/*
* MD5 hashed platform-specific ID (e.g., Android ID or UDID for iOS).
* Should be interpreted as case insensitive.
*/
optional string dpidmd5 = 8;
/*
* IP address in IPv6.
*/
optional string ipv6 = 9;
/*
* Carrier or ISP derived from the IP address.
* Should be specified using Mobile Network Code (MNC).
*/
optional string carrier = 10 [default = "-1"];
/*
* Browser language; use alpha-2/ISO 639-1 codes.
*/
optional string language = 11;
/*
* Device make (e.g., “Apple”).
*/
optional string make = 12 [default = "-1"];
/*
* Device model (e.g., “iPhone”).
*/
optional string model = 13 [default = "-1"];
/*
* Device operating system (e.g., “iOS”).
*/
optional string os = 14 [default = "-1"];
/*
* Device operating system version (e.g., “3.1.2”).
*/
optional string osv = 15 [default = "-1"];
/*
* Device supports Javascript?
*/
optional Flag js = 16 [default = YES];
/*
* Return the detected data connection type for the device.
*/
optional Enums.BidRequest.Device.ConnectionType connectiontype = 17 [default = CONNECTION_UNKNOWN];
/*
* Return the device type being used.
*/
optional Enums.BidRequest.Device.DeviceType devicetype = 18 [default = UNKNOWN];
/*
* Return the Flash version detected.
*/
optional string flashver = 19;
/*
* "Limit Ad Tracking" signal commercially endorsed (e.g., iOS, Android),
* where false = tracking is unrestricted,
* true = tracking must be limited per commercial guidelines.
*/
optional bool lmt = 20;
/*
* Hardware version of the device (e.g., "5S" for iPhone 5S).
*/
optional string hwv = 21;
/*
* Physical width of the screen in pixels.
*/
optional int32 w = 22;
/*
* Physical height of the screen in pixels.
*/
optional int32 h = 23;
/*
* Screen size as pixels per linear inch.
*/
optional int32 ppi = 24;
/*
* The ratio of physical pixels to device independent pixels.
*/
optional double pxratio = 25;
/*
* ID sanctioned for advertiser use in the clear (i.e., not hashed).
*/
optional string ifa = 26;
/*
* MAC address of the device; hashed via SHA1.
*/
optional string macsha1 = 27;
/**
* MAC address of the device; hashed via MD5.
*/
optional string macmd5 = 28;
/*
* 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;
optional DeviceExtensions ext = 1000;
}
// Next available tag: 9
/*
* OpenRTB 3.3.12: contains information known or derived about the human user of the device.
* Note that the user ID is an exchange artifact (refer to the “device” object for hardware or
* platform derived IDs) and may be subject to rotation policies. However, this user ID must be
* stable long enough to serve reasonably as the basis for frequency capping.
* If device ID is used as a proxy for unique user ID, use the device object.
*/
message User {
/*
* Unique consumer ID of this user on the exchange.
*/
optional string id = 1;
/*
* Buyer’s user ID for this user as mapped by exchange for the buyer.
*/
optional string buyeruid = 2;
/*
* Year of birth as a 4-digit integer.
*/
optional int32 yob = 3;
/*
* Gender as “M” male, “F” female, “O” Other. (Null indicates unknown)
*/
optional string gender = 4;
/*
* Comma separated list of keywords of consumer interests or intent.
*/
optional string keywords = 5;
/*
* If supported by the exchange, this is custom data that the bidder had stored in the
* exchange’s cookie. The string may be in base85 cookie safe characters, and be in any
* format. This may useful for storing user features. Note: Proper JSON encoding must
* be used to include “escaped” quotation marks.
*/
optional string customdata = 6;
/*
* Home geo for the user (e.g., based off of registration data); this is different from the
* current location of the access device (that is defined by the geo object embedded in the
* Device Object).
*/
optional Geo geo = 7;
/*
* User's custom Data.
*/
repeated Data data = 8;
optional UserExtensions ext = 1000;
}
// Next available tag: 5
/*
* OpenRTB 3.3.8: describes the publisher of a site or app.
*/
message Publisher {
/*
* Publisher ID on the exchange.
*/
optional string id = 1 ;
/*
* Publisher name (may be masked at publisher’s request).
*/
optional string name = 2;
/*
* Array of IAB content categories for the publisher.
*/
repeated string cat = 3;
/*
* Publisher’s highest level domain name, for example “foopub.com”.
*/
optional string domain = 4;
optional PublisherExtensions ext = 1000;
}
// Next available tag: 5
/*
* OpenRTB 3.3.9: describes the producer of content object, which might be different from the
* publisher of the content of the page. This object is useful in the case of syndicated content,
* such as embedded videos, for example.
*/
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;
/*
* Array of IAB content categories for the content producer.
*/
repeated string cat = 3;
/*
* URL of the content producer.
*/
optional string domain = 4;
optional ProducerExtensions ext = 1000;
}
// Next available tag: 11
/*
* OpenRTB 3.3.11: describes the current geographic location of the Device (e.g., based on IP
* address or GPS), or the home geo of the User (e.g., based on registration data).
* If both the Device and User objects contain Geo objects with different information,
* it’s up to the bidder to determine which Geo information to use.
*/
message Geo {
/*
* Latitude from -90 to 90. South is negative. This should only be passed if known
* to be accurate (For example, not the centroid of a postal code).
*/
optional double lat = 1;
/*
* Longitude from -180 to 180. West is negative. This should only be passed if known
* to be accurate (For example, not the centroid of a postal code).
*/
optional double lon = 2;
/*
* Country using ISO-3166-1 Alpha-3.
*/
optional string country = 3;
/*
* Region using ISO 3166-2
*/
optional string region = 4;
/*
* Region of a country using fips 10-4 notation (alternative to ISO 3166-2).
*/
optional string regionfips104 = 5;
/*
* Pass the metro code (see http://code.google.com/apis/adwords/docs/appendix/metrocodes.html).
* Metro codes are similar to but not exactly the same as Nielsen DMAs.
*/
optional string metro = 6;
/*
* Beeswax does normalization in the following way:
* (1) user.geo.city field is populated with city IDs of MaxMind database (see notes) if available.
* Mapping from city IDs to city names can be found in the Buzz's `cities` view.
* (2) device.geo.city field is populated with the city name defined by google in geo table (see notes)
* for GOOGLE_ADX requests. Beeswax always clear this field for non-GOOGLE_ADX requests.
*
* Notes:
* (1) Beeswax uses Maxmind's database to augment geo information. The database
* is also used in defining targetable cities.
* Link to Maxmind: https://www.maxmind.com
* Link to Beeswax targeting keys: https://docs.beeswax.com/docs/list-of-targeting-modules-and-keys
* (2) Link to google's geo table: https://storage.googleapis.com/adx-rtb-dictionaries/geo-table.csv
*/
optional string city = 7;
/*
* Zip/postal code.
*/
optional string zip = 8;
/*
* Indicate the source of the geo data (GPS, IP address, user provided).
* Type should be provided when lat/lon is provided.
*/
optional Enums.BidRequest.Geo.LocationType type = 9;
/*
* Local time as the number +/- of minutes from UTC.
*/
optional int32 utcoffset = 10;
optional GeoExtensions ext = 1000;
}
// Next available tag: 4
/*
* OpenRTB 3.3.13: The data and segment objects together allow data about the user to be passed
* to bidders in the bid request. This data may be from multiple sources (e.g., the exchange
* itself, third party providers) as specified by the data object ID field.
* A bid request can mix data objects from multiple providers.
*/
message Data {
/*
* Exchange specific ID for the data provider.
*/
optional string id = 1;
/*
* Data provider name.
*/
optional string name = 2;
/*
* Array of segment objects.
*/
repeated Segment segment = 3;
optional DataExtensions ext = 1000;
/*
* OpenRTB 3.3.14: convey specific units of information from the provider identified
* in the parent data object.
*/
message Segment {
/*
* ID of a data provider’s segment applicable to the user.
*/
optional string id = 1;
/*
* Name of a data provider’s segment applicable to the user.
*/
optional string name = 2;
/*
* String representing the value of the segment. The method for transmitting this data
* should be negotiated offline with the data provider.
* For example for gender, “male”, or “female”, for age, “30-40”).
*/
optional string value = 3;
optional SegmentExtensions ext = 1000;
}
}
// Next available tag: 2
/*
* OpenRTB 3.3.15: Legal, governmental, or industry regulations that apply to the request.
*/
message Regulations {
/*
* Indicated wether or not this request falls under the COPPA regulations
* established by the USA FTC.
*/
optional Flag coppa = 1;
optional RegulationsExtensions ext = 1000;
}
}
// Next available tag: 7
/*
* OpenRTB 4.3.1: top-level bid response object.
*/
message BidResponse {
/*
* ID of the bid request.
*/
optional string id = 1;
/*
* Array of seatbid objects.
*/
repeated SeatBid seatbid = 2;
/*
* Bid response ID to assist tracking for bidders.
* This value is chosen by the bidder for cross-reference.
*/
optional string bidid = 3;
/*
* Bid currency using ISO-4217 alphabetic codes.
*/
optional string cur = 4 [default = "USD"];
/*
* This is an optional feature, which allows a bidder to set data in the exchange’s cookie.
* The string may be in base85 cookie safe characters, and be in any format.
* This may be useful for storing user features.
* Note: Proper JSON encoding must be used to include “escaped” quotation marks.
*/
optional string customdata = 5;
/*
* Reason for not bidding.
*/
optional Enums.BidResponse.NoBidReason nbr = 6;
optional BidResponseExtensions ext = 1000;
// Next available tag: 4
/*
* OpenRTB 4.3.2: A bid response can contain multiple “seatbid” objects, each on behalf of a
* different bidder seat. Since a bid request can include multiple impressions, each “seatbid”
* object can contain multiple bids each pertaining to a different impression on behalf of a seat.
* Thus, each “bid” object must include the impression ID to which it pertains as well as
* the bid price. 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 (i.e., all or nothing).
*/
message SeatBid {
/*
* Array of bid objects; each bid object relates to an imp object in the bid request.
* Note that, if supported by an exchange, one imp object can have many bid objects.
*/
repeated Bid bid = 1;
/*
* ID of the bidder seat on whose behalf this bid is made.
*/
optional string seat = 2;
/*
* Should impressions be won or lost as a group?
*/
optional Flag group = 3;
optional SeatBidExtensions ext = 1000;
/*
* OpenRTB 4.3.3: For each bid, the “nurl” attribute contains the win notice URL.
* If the bidder wins the impression, the exchange calls this notice URL a) to inform the bidder
* of the win and b) to convey certain information using substitution macros
* (see Section 4.6 Substitution Macros). The “adomain” attribute can be used to check
* advertiser block list compliance. The “iurl” attribute can provide a link to an image that
* is representative of the campaign’s content (irrespective of whether the campaign may have
* multiple creatives). This enables human review for spotting inappropriate content.
* The “cid” attribute can be used to block ads that were previously identified as
* inappropriate; essentially a safety net beyond the block lists. The “crid” attribute
* can be helpful in reporting creative issues back to bidders. Finally, the “attr” array
* indicates the creative attributes that describe the ad to be served.
*/
message Bid {
/*
* ID for the bid object chosen by the bidder for tracking and debugging purposes.
* Useful when multiple bids are submitted for a single impression for a given seat.
*/
required string id = 1;
/*
* ID of the impression object to which this bid applies.
*/
required string impid = 2;
/*
* Bid price in CPM. WARNING/Best Practice Note: Although this value is a float,
* OpenRTB strongly suggests using integer math for accounting to avoid rounding errors.
*/
required double price = 3;
/*
* ID that references the ad to be served if the bid wins.
*/
optional string adid = 4;
/*
* Win notice URL. Note that ad markup is also typically, but not necessarily,
* returned via this URL.
*/
optional string nurl = 5;
/*
* Actual ad markup. XHTML if a response to a banner object,
* or VAST XML if a response to a video object.
*
* Open Bidder macros are supported for this field.
*/
optional string adm = 6;
/*
* Native ad response.
* You can only set one of adm and adm_native; either will generate the "adm" field in JSON.
*/
optional NativeResponse adm_native = 50;
/*
* Advertiser’s primary or top-level domain for advertiser checking.
* This can be a list of domains if there is a rotating creative.
* However, exchanges may mandate that only one landing domain is allowed.
*/
repeated string adomain = 7;
/**
* Bundle or package name (e.g., com.foo.mygame) of the app being advertised, if applicable;
* intended to be a unique ID across exchanges.
*/
optional string bundle = 15;
/*
* Sample image URL (without cache busting) for content checking.
*/
optional string iurl = 8;
/*
* Campaign ID or similar that appears within the ad markup.
*/
optional string cid = 9;
/*
* Creative ID for reporting content issues or defects.
* This could also be used as a reference to a creative ID that is posted with an exchange.
*
* Open Bidder macros are supported for this field.
*/
optional string crid = 10;
/**
* IAB content category of the creative.
*/
repeated string cat = 16;
/*
* Array of creative attributes.
*/
repeated CreativeAttribute attr = 11;
/*
* A unique identifier for the direct deal associated with the bid.
*/
optional string dealid = 12;
/**
* Width of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin
* optional fields it is recommended that the response bid contains this field to signal
* the size of ad chosen.
*/
optional int32 w = 13;
/**
* Height of the ad in pixels. If the bid request contained the wmax/hmax and wmin/hmin
* optional fields it is recommended that the response bid contains this field to signal
* the size of ad chosen.
*/
optional int32 h = 14;
optional BidExtensions ext = 1000;
}
}
}
/**
* OpenRTB Native 4.1: 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.
*/
message NativeRequest {
/**
* Version of the Native Markup version in use.
*/
optional string ver = 1;
/**
* The Layout ID of the native ad unit.
* This field is not required, but it's highly recommended.
*/
optional Enums.BidRequest.Impression.NativeRequest.LayoutId layout = 2;
/**
* The Ad unit ID of the native ad unit. This corresponds to one of IAB Core-6 native ad units.
* This field is not required, but it's highly recommended.
*/
optional Enums.BidRequest.Impression.NativeRequest.AdUnitId adunit = 3;
/**
* 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.
* This is not the sequence number of the content in the stream.
*/
optional int32 seq = 5 [default = 0];
/**
* Any bid must comply with the array of elements expressed by the Exchange.
*/
repeated Asset assets = 6;
/**
* The context in which the ad appears.
*/
optional Enums.BidRequest.Impression.NativeRequest.Context context = 7;
/**
* A more detailed context in which the ad appears.
*/
optional Enums.BidRequest.Impression.NativeRequest.ContextSubtype contextsubtype = 8;
/**
* The design/format/layout of the ad unit being offered.
*/
optional Enums.BidRequest.Impression.NativeRequest.PlacementType plcmttype = 9;
/**
* Extensions.
*/
extensions 100 to 9999;
/**
* OpenRTB Native 4.2: 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.
*/
message Asset {
/**
* Unique asset ID, assigned by exchange. Typically a counter for the array.
*/
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];
/**
* Title object for title assets.
*/
optional Title title = 3;
/**
* Image object for image assets.
*/
optional 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.
*/
optional BidRequest.Impression.Video video = 5;
/**
* Data object for ratings, prices etc.
*/
optional Data data = 6;
/**
* Extensions.
*/
extensions 100 to 9999;
/**
* OpenRTB Native 4.3: 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.
*/
required int32 len = 1;
/**
* Extensions.
*/
extensions 100 to 9999;
}
/**
* OpenRTB Native 4.4: The Image object to be used for all image elements of the
* Native ad such as Icons, Main Image, etc.
*/
message Image {
/**
* Type ID of the image element supported by the publisher.
* The publisher can display this information in an appropriate format.
*/
optional ImageAssetType type = 1;
/**
* Width of the image in pixels.
*/
optional int32 w = 2;
/**
* Height of the image in pixels.
*/
optional int32 h = 3;
/**
* 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.
*/
optional int32 wmin = 4;
/**
* 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.
*/
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 7.4: Common image asset element types of native advertising at
* the time of writing this spec. This list is non-exhaustive and intended to be
* extended by the buyers and sellers as the format evolves.
*/
enum ImageAssetType {
/** Icon image. */
ICON = 1;
/** Logo image for the brand/app. */
LOGO = 2;
/** Large image preview for the ad. */
MAIN = 3;
// Exchange-specific values above 500.
}
}
/**
* OpenRT Native 4.6: 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.
*/
optional DataAssetType type = 1;
/**
* Maximum length of the text in the element's response.
*/
optional int32 len = 2;
/**
* Extensions.
*/
extensions 100 to 9999;
/**
* OpenRTB Native 7.3: Common asset element types of native advertising.
* This list is non-exhaustive and intended to be extended by the buyers and sellers
* as the format evolves. An implementing exchange may not support all asset variants
* or introduce new ones unique to that system.
*/
enum DataAssetType {
/** Sponsored By message where response should contain the brand name of the sponsor. */
SPONSORED = 1;
/** Descriptive text associated with the product or service being advertised. */
DESC = 2;
/**
* Rating of the product being offered to the user.
* For example an app's rating in an app store from 0-5.
*/
RATING = 3;
/** Number of social ratings or "likes" of the product being offered to the user. */
LIKES = 4;
/** Number downloads/installs of this product. */
DOWNLOADS = 5;
/**
* Price for product / app / in-app purchase.
* Value should include currency symbol in localised format.
*/
PRICE = 6;
/**
* Sale price that can be used together with price to indicate a discounted price
* compared to a regular price. Value should include currency symbol in localised format.
*/
SALEPRICE = 7;
/** Phone number. */
PHONE = 8;
/** Address. */
ADDRESS = 9;
/** Additional descriptive text associated with the product or service being advertised. */
DESC2 = 10;
/** Display URL for the text ad. */
DISPLAYURL = 11;
/** Text describing a "call to action" button for the destination URL. */
CTATEXT = 12;
// Exchange-specific values above 500.
// STORE bit for ADX NativeAdTemplate
STORE = 500;
}
}
}
}
/**
* OpenRTB Native 5.2: The native response object is the top level JSON object which identifies
* an native response.
*/
message NativeResponse {
/**
* Version of the Native Markup version in use.
*/
optional string ver = 1;
/**
* List of native ad's assets.
*/
repeated Asset assets = 2;
/**
* Destination Link.
*/
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.
*/
repeated string imptrackers = 4;
/**
* Optional javascript impression tracker. Contains