OpenRTB Extensions Protocol Buffer v.58

View raw content Back to Reference page

// Protocol version: v.58
import "openrtb.proto";
option java_outer_classname = "AdxExt";
package com.google.doubleclick;

// 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.
    UNKNOWN_AMP_AD_REQUIREMENT_TYPE = 1;
    // AMP ads are not allowed.
    AMP_AD_NOT_ALLOWED = 2;
    // Either AMP ads or non-AMP ads are allowed;
    // AMP ads are not early rendered.
    AMP_AD_ALLOWED_AND_NOT_EARLY_RENDERED = 3;
    // Either AMP ads or non-AMP ads are allowed;
    // AMP ads are early rendered.
    AMP_AD_ALLOWED_AND_EARLY_RENDERED = 4;
    // AMP ads are required.
    // Ads that are non-AMP may be rejected by the publisher.
    AMP_AD_REQUIRED = 5;
    // Exchange-specific values above 500.
  }
  optional AmpAdRequirementType ampad = 8
      [default = UNKNOWN_AMP_AD_REQUIREMENT_TYPE];

  // 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 AppExt.InstalledSdk.id.
      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
    // https://support.google.com/admanager/answer/7128453 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
  // https://storage.googleapis.com/adx-rtb-dictionaries/ad-restricted-categories.txt
  // 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;

  // Publisher's SKAdNetwork information to support app installation
  // attribution for iOS 14 and later. Apple's SKAdNetwork API helps
  // advertisers measure ad-driven app installation by sending a postback
  // to the ad network after a successful install. Publishers will need
  // to configure supported ad networks in their app's property list
  // (Info.plist) to allow an install to be attributed to the ad impression.
  // For more info visit:
  // https://developer.apple.com/documentation/storekit/skadnetwork
  message SKAdNetworkRequest {
    // Version of SKAdNetwork supported. Dependent on both the OS version
    // and the SDK version.
    optional string version = 1;

    // ID of publisher app in Apple’s App Store.
    optional string sourceapp = 2;

    // SKAdNetworkIdentifier entries in the publisher app's Info.plist.
    repeated string skadnetids = 3;
  }

  // [AdX: BidRequest.Mobile.skadn]
  optional SKAdNetworkRequest skadn = 14;
}

extend com.google.openrtb.BidRequest.Imp {
  // 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 com.google.openrtb.BidRequest.App {
  // 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 com.google.openrtb.BidResponse {
  // 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;

  // This field is deprecated due to being unused.
  // [AdX: BidResponse.Ad.bidder_name]
  optional string DEPRECATED_bidder_name = 3 [deprecated = true];

  // [AdX: BidResponse.Ad.AdSlot.exchange_deal_type]
  enum ExchangeDealType {
    OPEN_AUCTION = 0;
    PRIVATE_AUCTION = 1;
    PREFERRED_DEAL = 2;
    EXCHANGE_AUCTION_PACKAGE = 3;
  }
  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
    // AppExt.InstalledSdk.id 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;

  // 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;

  // Advertiser's SKAdNetwork information to support app installation
  // attribution for iOS 14 and later.  Apple's SKAdNetwork API helps
  // advertisers measure ad-driven app installation by sending a postback
  // to the ad network after a successful install. Ad networks will need
  // to send their network ID and signed advertiser information to allow
  // an install to be attributed to the ad impression.
  // For more info visit:
  // https://developer.apple.com/documentation/storekit/skadnetwork
  message SKAdNetworkResponse {
    // Version of SKAdNetwork supported by the advertiser. Also used to
    // specify how the signature was generated by the advertiser. This
    // should match the version from BidRequest.imp.ext.skad.version.
    optional string version = 1;

    // Ad network identifier used in signature. This should match one of the
    // items in BidRequest.imp.ext.skad.skadnetids.
    optional string network = 2;

    // Campaign ID compatible with Apple's spec.
    optional string campaign = 3;

    // ID of advertiser's app in Apple's app store.
    optional string itunesitem = 4;

    // A unique all-lowercase UUID generated by the advertiser to use for
    // generating the signature.
    optional string nonce = 5;

    // ID of publisher's app in Apple's app store. This should match the ID
    // from BidRequest.imp.ext.skad.sourceapp.
    optional string sourceapp = 6;

    // Unix time in millis used at the time of signature generation.
    optional string timestamp = 7;

    // SKAdNetwork signature as specified by Apple.
    optional string signature = 8;
  }

  // [AdX: BidResponse.Ad.skadn]
  optional SKAdNetworkResponse skadn = 19;

}

extend com.google.openrtb.BidResponse.SeatBid.Bid {
  // 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 com.google.openrtb.NativeRequest {
  // 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 com.google.openrtb.NativeResponse.EventTracker {
  // 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
  // https://developers.google.com/adwords/api/docs/appendix/codes-formats#country-codes
  optional string country = 1;
}

extend com.google.openrtb.BidRequest.Publisher {
  // Extension key for the AdX Publisher.ext
  optional PublisherExt publisher = 1002;
}

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

  enum VisibilityState {
    VISIBILITY_STATE_UNKNOWN = 0;
    // The page is at least partially visible. For example, in the foreground
    // tab of a non-minimized window.
    VISIBILITY_STATE_VISIBLE = 1;
    // The page is not visible at all to users. For example, when the page is
    // on a background browser tab, or in a minimized window.
    VISIBILITY_STATE_HIDDEN = 2;
  }
  // The visibility state of the web page containing the ad slot.
  // See https://www.w3.org/TR/page-visibility/.
  // [AdX: BidRequest.page_visibility]
  optional VisibilityState page_visibility = 2
      [default = VISIBILITY_STATE_UNKNOWN];

  // Indicates that the request is using semi-transparent branding,
  // which means only a truncated version of the request URL will
  // be provided.  This decision is made by the publisher, see
  // https://support.google.com/admanager/answer/4584891#urls for context.
  optional bool is_semi_transparent_request = 3;
}

extend com.google.openrtb.BidRequest.Site {
  // 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 BidRequest.id.
    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 com.google.openrtb.BidRequest {
  // 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
    // https://support.google.com/admanager/answer/9681920 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
  // https://support.google.com/authorizedbuyers/answer/9789378 for additional
  // information about the Google TCF v2 integration.
  //
  // See the IAB Global Vendor List at
  // https://vendorlist.consensu.org/v2/vendor-list.json for details about the
  // vendors listed in the consent string.
  optional string consent = 2;
}

extend com.google.openrtb.BidRequest.User {
  // 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 com.google.openrtb.BidRequest.Device {
  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;

  // This field will be set to true when, based on information available to
  // Google, this impression will serve to a user in Brazil. See
  // https://storage.googleapis.com/adx-rtb-dictionaries/lgpd-providers.csv for
  // the list of ad tech providers that are allowed to serve on LGPD-enforced
  // requests.
  //
  // See https://support.google.com/authorizedbuyers/answer/9928204 for more
  // information on LGPD.
  optional bool lgpd = 2;
}

extend com.google.openrtb.BidRequest.Regs {
  // 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 {
    UNKNOWN_DEAL_TYPE = 0;

    // 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 https://support.google.com/authorizedbuyers/answer/2604595
    // for more information.
    PREFERRED_DEAL = 1;

    // Bids participate in a Private Auction against a select list of buyers
    // with specific floors. See
    // https://support.google.com/authorizedbuyers/answer/2839853 for more
    // information.
    PRIVATE_AUCTION = 2;

    // 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 https://support.google.com/authorizedbuyers/answer/7174589
    // for more information.
    PROGRAMMATIC_GUARANTEED = 3;

    // The deal ID is an identifier for a collection of Open Auction inventory
    // matching a given set of targeting criteria. See
    // https://support.google.com/authorizedbuyers/answer/7516884 for more
    // information.
    AUCTION_PACKAGE = 4;
  }
  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
  // https://support.google.com/authorizedbuyers/answer/6114194 for more
  // information.
  optional bool publisher_blocks_overridden = 3;

  // Experimental field; subject to change.
  // An enum declaring the host of the creative, which will only be
  // populated for Programmatic Guaranteed deals.
  // Currently, this field should only ever be set to
  // CREATIVE_SOURCE_ADVERTISER.
  enum CreativeSourceType {
    CREATIVE_SOURCE_UNKNOWN = 0;
    // The creative is hosted by the advertiser, which means the bidder is
    // required to provide a creative in the bid response.
    CREATIVE_SOURCE_ADVERTISER = 1;
    // The creative is hosted by the publisher, which means the bidder
    // does not need to include a creative in the bid response.
    // For more information on publisher-hosted creatives, see
    // https://support.google.com/admanager/answer/9243220.
    // This feature isn't currently supported for RTB bidders.
    CREATIVE_SOURCE_PUBLISHER = 2;
  }
  optional CreativeSourceType creative_source = 4
      [default = CREATIVE_SOURCE_ADVERTISER];
}

extend com.google.openrtb.BidRequest.Imp.Pmp.Deal {
  // Extension key for AdX Deal.ext.
  optional DealExt deal = 1010;
}

message SourceExt {
  // Identifier of the OM SDK integration. Equivalent to
  // BidRequest.AdSlot.omidpn in the Google protocol. For more info,
  // see the OpenRTB Advisory for Open Measurement SDK:
  // https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/OpenRTB%20support%20for%20OMSDK.md#openrtb-and-adcom.
  optional string omidpn = 1;
  // Version of the OM SDK integration. Equivalent to BidRequest.AdSlot.omidpv
  // in the Google protocol. For more info, see the OpenRTB Advisory for
  // Open Measurement SDK:
  // https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/OpenRTB%20support%20for%20OMSDK.md#openrtb-and-adcom.
  optional string omidpv = 2;
}

extend com.google.openrtb.BidRequest.Source {
  // Extension key for Source.ext
  optional SourceExt source = 1059;
}