OpenRTB Extensions Protocol Buffer v.50

View raw content Back to Reference page

// Protocol version: v.50
import "openrtb.proto";
option java_outer_classname = "AdxExt";

// Copyright 2020 Google Inc. All Rights Reserved.

// Protocol buffer for Ad Exchange OpenRTB specification.

// Ad Exchange extensions for the Imp object.
message ImpExt {
  // [AdX: BidRequest.AdSlot.MatchingAdData.billing_id]
  repeated int64 billing_id = 1;

  // [AdX: BidRequest.publisher_settings_list_id]
  // [AdX: BidRequest.AdSlot.publisher_settings_list_id]
  repeated fixed64 publisher_settings_list_id = 2;

  // [AdX: BidRequest.AdSlot.allowed_vendor_type]
  repeated int32 allowed_vendor_type = 3 [packed = true];

  // A creative that is disallowed to bid on this impression due to Ad
  // Exchange policies or creative disapproval, excluded creative attributes,
  // excluded product or sensitive categories, allowed vendor types,
  // restricted categories or languages applicable to the bid request.
  message ExcludedCreative {
    // Buyer creative ID of the disallowed creative.
    optional string buyer_creative_id = 1;

  // Creatives that are disallowed for the impression. Submitting a bid with
  // one of the creatives in this list will result in such bid being filtered
  // before the auction. Please contact your account manager if you would like
  // to enable this feature.
  repeated ExcludedCreative excluded_creatives = 10;

  // [AdX: BidRequest.AdSlot.ExchangeBidding.publisher_parameter]
  repeated string publisher_parameter = 4;

  // [AdX: BidRequest.AdSlot.dfp_ad_unit_code]
  optional string dfp_ad_unit_code = 6;

  // [AdX: BidRequest.AdSlot.is_rewarded]
  optional bool is_rewarded_inventory = 7;

  // Possible requirement types for AMP ads.
  enum AmpAdRequirementType {
    // AMP ad requirements unknown.
    // AMP ads are not allowed.
    // Either AMP ads or non-AMP ads are allowed;
    // AMP ads are not early rendered.
    // Either AMP ads or non-AMP ads are allowed;
    // AMP ads are early rendered.
    // AMP ads are required.
    // Ads that are non-AMP may be rejected by the publisher.
    // Exchange-specific values above 500.
  optional AmpAdRequirementType ampad = 8

  // Data, opaque to Google and to the publisher, generated by the buyer
  // within the publisher's mobile application.
  message BuyerGeneratedRequestData {
    // Identification for the source of the buyer generated request data when
    // that source is from within an application.
    message SourceApp {
      // Identifier for the SDK that generated this data. It will match the id
      // in
      optional string id = 1;
    // The source of the data.
    oneof source {
      SourceApp source_app = 1;

    // Data sent from the buyer's source within the publisher's domain to the
    // bidder. This data is opaque to the publisher and to Google.
    optional string data = 2;

  repeated BuyerGeneratedRequestData buyer_generated_request_data = 9;

  // Parameters related to Open Bidding.
  message OpenBidding {
    // This field is set to true if the publisher set up a yield group or a
    // mediation group that targets this adslot and this bidder. See
    // for information on
    // Open Bidding and its effects on the bidding process.
    optional bool is_open_bidding = 2;
  optional OpenBidding open_bidding = 12;

  // The allowed restricted ad categories. See
  // for a list of ids. If you bid with an ad in a restricted category, you MUST
  // ALWAYS declare the category in the bid response regardless of the values in
  // this field.
  repeated int32 allowed_restricted_category = 13;

extend {
  // Extension key for AdX Imp.ext.
  optional ImpExt imp = 1009;

message AppExt {
  // Identification of and information about an SDK installed in the
  // publisher's app that the bidder has access to, often because it's the
  // bidder's SDK.
  message InstalledSdk {
    // Identifier for the installed SDK.
    optional string id = 1;

    // Semantic version of the installed SDK and the adapter that communicates
    // between the installed SDK and Google's SDK.
    message Version {
      optional int32 major = 1 [default = -1];
      optional int32 minor = 2 [default = -1];
      optional int32 micro = 3 [default = -1];

    // The version of the installed SDK.
    optional Version sdk_version = 2;

    // The version of the adapter that communicates with the installed SDK.
    optional Version adapter_version = 3;
  repeated InstalledSdk installed_sdk = 1;

extend {
  // Extension key for AdX App.ext.
  optional AppExt app = 1011;

// Ad Exchange extensions for the BidResponse object.
message BidResponseExt {
  // [AdX: BidResponse.processing_time_ms]
  optional int32 processing_time_ms = 1;

extend {
  // Extension key for AdX BidResponse.ext.
  optional BidResponseExt bid_response = 1005;

// Ad Exchange extensions for the Bid object.
message BidExt {
  // [AdX: BidResponse.Ad.impression_tracking_url]
  repeated string impression_tracking_url = 1;

  // [AdX: BidResponse.Ad.ad_choices_destination_url]
  optional string ad_choices_destination_url = 2;

  // [AdX: BidResponse.Ad.bidder_name]
  optional string bidder_name = 3;

  // [AdX: BidResponse.Ad.AdSlot.exchange_deal_type]
  enum ExchangeDealType {
  optional ExchangeDealType exchange_deal_type = 4 [default = OPEN_AUCTION];

  // [AdX: BidResponse.Ad.attribute]
  // See buyer-declarable-creative-attributes.txt in the technical documentation
  // for a list of ids. Note that not all declarable attributes come through in
  // the BidRequest in the various `battr` fields.
  repeated int32 attribute = 5 [packed = true];

  // The URL to fetch an AMPHTML ad. Only one of the following should be set:
  // html_snippet, video_url, amp_ad_url, native_ad.
  optional string amp_ad_url = 6;

  // An ad that will be rendered by an SDK known to the buyer. This can only
  // be used when the BidRequest included an AppExt.InstalledSdk submessage.
  message SdkRenderedAd {
    // The identifier for the SDK that will render the ad. Must match an
    // sent in the corresponding bid request.
    optional string id = 1;

    // Data to pass to the SDK in order to render the ad. This data is opaque
    // to the publisher and to Google.
    optional string rendering_data = 2;
  optional SdkRenderedAd sdk_rendered_ad = 7;

  message EventNotificationToken {
    // The contents of the token, which will be ignored if longer than 64
    // bytes.
    optional string payload = 1;
  // A token set by bidders for troubleshooting which will be included in the
  // real-time feedback for the Bid it is sent in. The contents of the token
  // will not be logged.
  optional EventNotificationToken event_notification_token = 8;

  // All restricted categories for the ads that may be shown from this snippet.
  // See ad-restricted-categories.txt in the technical documentation for a list
  // of ids. If you are bidding with ads in restricted categories, you must
  // always declare them here.
  repeated int32 restricted_category = 9;

  // The billing ID to attribute this impression to. The value must be in the
  // repeated BidRequest.Imp.ImpExt.billing_id field sent for this impression.
  // If the length of BidRequest.Imp.ImpExt.billing_id is exactly 1
  // and the bidder does not have any active child seats, this field
  // is not required and its contents will be ignored.
  optional int64 billing_id = 10;

  // This field is deprecated as of July 8, 2020 and will be removed July 31,
  // 2020.
  // [AdX: BidResponse.Ad.AdSlot.use_bid_translation_service]
  // This field is applicable only for bid requests that are marked as first
  // price, and will otherwise be ignored. If the field is set to true on a
  // first price request, then the bid will go through a bid translation service
  // that converts the second price bid into a first price bid for
  // participation in the first price auction (i.e. may reduce but will
  // never increase the bid). If the field is not set, then for first price
  // eligible queries the bid will be treated as a first price bid. This
  // field is a temporary product for bidders that require assistance
  // migrating to 1st price bidding.
  optional bool DEPRECATED_use_bid_translation_service = 12;

  // Token used to identify end third party buyer information if an
  // exchange as an open bidder is an intermediary. This is obtained from the
  // third party buyer and must be passed to Google unaltered in the bid
  // response.
  optional string third_party_buyer_token = 14;

  // Buyer declared ID which will be used to break down spend and invalid
  // traffic metrics in IVT transparency reporting in Query Tool. Note that IDs
  // with fewer than 1000 impressions will not be used to break down metrics.
  // IDs longer than 64 bytes will be ignored.
  optional string buyer_reporting_id = 17;

extend {
  // Extension key for AdX Bid.ext.
  optional BidExt bid = 1014;

message NativeRequestExt {
  // [AdX: BidRequest.AdSlot.native_ad_template[0].style_id]
  optional int32 style_id = 1;

  // [AdX: BidRequest.AdSlot.native_ad_template[0].style_height]
  optional int32 style_height = 2;

  // [AdX: BidRequest.AdSlot.native_ad_template[0].style_width]
  optional int32 style_width = 3;

  // [AdX: BidRequest.AdSlot.native_ad_template[0].style_layout_type]
  enum LayoutType {
    PIXEL = 0;
    FLUID = 1;
  optional LayoutType style_layout_type = 4 [default = PIXEL];

extend {
  // Extension key for the AdX Native.ext.
  optional NativeRequestExt native_ext = 1001;

message EventTrackerExt {
  // Additional context provided for rendering.
  enum Context {
    UNKNOWN = 0;

    // Currently not supported.
    OMID = 1;
  repeated Context context = 1;

  // Parameters associated with the resource that will be passed to the
  // resource when it is loaded. The format of the parameters is dependent
  // on the script vendor.
  optional string verification_parameters = 2;

  // Used to uniquely identify the verification script provider.
  optional string vendor_key = 3;

extend {
  // Extension key for the AdX EventTracker.ext.
  optional EventTrackerExt eventtrackers = 1000;

message PublisherExt {
  // The billing address country code of the publisher. This may be different
  // from the hosting country of the website. For a complete list of country
  // codes, please refer to
  optional string country = 1;

extend {
  // Extension key for the AdX Publisher.ext
  optional PublisherExt publisher = 1002;

message SiteExt {
  enum AmpPage {
    // This is not an AMP page.
    // This is an Amp page.
  // Whether this is an AMP page or not. Omitted if unknown.
  optional AmpPage amp = 1;

extend {
  // Extension key for the Adx Site.ext
  optional SiteExt site = 1010;

message BidRequestExt {
  // Feedback on bids submitted in previous responses. This is only set if
  // real-time feedback is enabled for your bidder. Please contact your
  // account manager if you wish to enable real-time feedback.
  message BidFeedback {
    // The unique id from
    optional string request_id = 1;

    // The status code for the ad. See creative-status-codes.txt in the
    // technical documentation for a list of ids.
    optional int32 creative_status_code = 2;

    // If the bid won the auction, this is the price paid in your account
    // currency.  If the bid participated in the auction but was out-bid, this
    // is the CPM that should have been exceeded in order to win.  This is not
    // set if the bid was filtered prior to the auction, if the publisher or
    // winning bidder has opted out of price feedback or if your account has
    // opted out of sharing winning prices with other bidders. For first-price
    // auctions, minimum_bid_to_win is populated instead of this field.
    optional double price = 3;

    // The minimum bid value necessary to have the auction, in your account
    // currency. If your bid won the auction, this is the second highest bid
    // that was not filtered (including the floor price). If your bid did not
    // win the auction, this is the winning candidate's bid. This field will
    // only be populated if your bid participated in a first-price auction, and
    // will not be populated if your bid was filtered prior to the auction.
    optional double minimum_bid_to_win = 6;

    // When a publisher uses an RTB auction and waterfall-based SDK mediation on
    // the same query, the winner of the real-time auction must also compete in
    // a mediation waterfall (which is ordered by price) to win the impression.
    // If the bid participated in the auction and there was no waterfall, the
    // value of this field is 0. If the bid participated in the auction and
    // there was a waterfall, the value of this field is a price representing a
    // sample bid from the eligible mediation networks that were higher than the
    // auction winner, weighted by expected fill rate.  This field can be used
    // in conjunction with minimum_bid_to_win to train bidding models. The CPM
    // is in your account currency.
    optional double sampled_mediation_cpm_ahead_of_auction_winner = 8;

    message EventNotificationToken {
      // The contents of the token.
      optional string payload = 1;
    // The token included in the corresponding bid.
    optional EventNotificationToken event_notification_token = 4;

    // The creative ID included in the corresponding bid.
    optional string buyer_creative_id = 5;
  repeated BidFeedback bid_feedback = 1;

  // This represents a unique ID for the overall query.  In the event
  // that there are multiple callouts for a query, all callout requests for that
  // query will contain the same google_query_id.
  optional string google_query_id = 2;

extend {
  // Extension key for the Adx BidRequest.ext
  optional BidRequestExt bid_request = 1018;

message UserExt {
  message ConsentedProvidersSettings {
    // Set of IDs corresponding to ad tech providers (ATPs) for whom the
    // publisher has specified to Google that its EEA users have given legally
    // valid consent to: 1) the use of cookies or other local storage where
    // legally required; and 2) the collection, sharing, and use of personal
    // data for personalization of ads by an ATP in accordance with Google’s EU
    // User Consent Policy.
    // If a publisher is using the IAB Transparency and Consent Framework (TCF)
    // v2 to manage user consent, this is the set of ATPs consented via the
    // Additional Consent string (see
    // for details about
    // Google's Additional Consent mode). ATPs consented via the TCF v2 consent
    // string are represented in the UserExt.consent field.
    // A mapping of ATP ID to ATP name is posted at providers.csv.
    repeated int64 consented_providers = 2 [packed = true];
  // Information about the ad tech providers for whom the publisher has
  // specified to Google that its EEA user has consented to the use of their
  // personal data for ads personalization in accordance with Google's EU User
  // Consent Policy. This field will only be populated when RegsExt.gdpr is
  // true.
  optional ConsentedProvidersSettings consented_providers_settings = 1;

  // The web-safe base64-encoded IAB Transparency and Consent Framework (TCF) v2
  // consent string fetched from the publisher's IAB Consent Management Platform
  // (CMP). The structure of the string is defined by the IAB TCF v2. This field
  // will be populated if the publisher has integrated with a CMP for TCF v2 and
  // that CMP indicates that GDPR applies to this ad request and provides a
  // valid consent string.  See
  // for additional
  // information about the Google TCF v2 integration.
  // See the IAB Global Vendor List at
  // for details about the
  // vendors listed in the consent string.
  optional string consent = 2;

extend {
  // Extension key for the Adx User.ext
  optional UserExt user = 1007;

message DeviceExt {
  // Beta feature. Represents a short-lived user session on CTV/OTT devices,
  // with a maximum session duration of 6 hours.
  // The use of session_id is never allowed for ads personalization.
  // session_id may only be used for frequency capping, competitive exclusions
  // or related purposes. Please contact your account manager if you would like
  // to enable this feature.
  optional string session_id = 1;

extend {
  optional DeviceExt device = 1066;

message RegsExt {
  // This field will be set to true in either of the two following cases:
  //   1. Google receives a valid IAB Transparency and Consent Framework (TCF)
  //      v2 consent string and the Consent Management Platform indicates that
  //      GDPR applies to this ad request.
  //   2. Google does not receive an IAB TCF v2 consent string and, based on
  //      information available to Google, this impression will serve to an
  //      EEA user.
  // It does not constitute legal guidance on GDPR.
  optional bool gdpr = 1;

extend {
  // Extension key for the Adx Regs.ext
  optional RegsExt regs = 1001;

message DealExt {
  // The type of the deal. Note that Authorized Buyers policy overrides apply to
  // all Programmatic Guaranteed and Preferred Deal bids, and do not apply to
  // bids for other deal types.
  enum DealType {

    // Bids are fixed-price and evaluated before the Open Auction. Bidders are
    // not required to bid with Preferred Deals when they are present on the bid
    // request. See
    // for more information.

    // Bids participate in a Private Auction against a select list of buyers
    // with specific floors. See
    // for more
    // information.

    // Bids are fixed-price and evaluated before the Open Auction. Bidders are
    // expected to bid with Programmatic Guaranteed deals whenever they are
    // present on a bid request and the must_bid field is true in order to
    // ensure that the number of impressions agreed upon for a given deal are
    // served. See
    // for more information.

    // The deal ID is an identifier for a collection of Open Auction inventory
    // matching a given set of targeting criteria. See
    // for more
    // information.
  optional DealType deal_type = 1 [default = UNKNOWN_DEAL_TYPE];

  // This field is only applicable to Programmatic Guaranteed deals. The
  // buyer is allowed to skip bidding on the impression if this field is
  // false. When it is true, the buyer is required to bid on this deal for
  // this impression opportunity. This field will always be filled explicitly
  // for the JSON wire format.
  optional bool must_bid = 2 [default = true];

  // Whether the publisher has exempted this deal from configured blocks. This
  // setting does not override AdX policies or Ad Review Center decisions. See
  // for more
  // information.
  optional bool publisher_blocks_overridden = 3;

extend {
  // Extension key for AdX Deal.ext.
  optional DealExt deal = 1010;