Google が入札リクエストをアプリケーションに送信すると、リアルタイム ビッダーのインタラクションが開始されます。このガイドでは、入札リクエストを処理するアプリケーションをコーディングする方法について説明します。
リクエストの解析
Google は、HTTP POST リクエストのバイナリ ペイロードとしてアタッチされたシリアル化されたプロトコル バッファとして入札リクエストを送信します。Content-Type は application/octet-stream に設定されています。例については、入札リクエストの例をご覧ください。
このリクエストを解析して、BidRequest メッセージのインスタンスに変換する必要があります。BidRequest は、参照データページから入手できる realtime-bidding.proto で定義されます。BidRequest 用に生成されたクラスで ParseFromString() メソッドを使用して、メッセージを解析できます。たとえば、次の C++ コードは、文字列の POST ペイロードで指定されたリクエストを解析します。
string post_payload = /* the payload from the POST request */;
BidRequest bid_request;
if (bid_request.ParseFromString(post_payload)) {
// Process the request.
}
実際のリクエストの POST ペイロードから取得するのと同様に、入札リクエストをバイナリ形式に変換するには、C++ で次のようにします。ただし、OpenRTB JSON には該当しません。
string text_format_example = /* example from above */;
BidRequest bid_request;
if (TextFormat::ParseFromString(text_format_example, &bid_request)) {
string post_payload;
if (bid_request.SerializeToString(&post_payload)) {
// post_payload is a binary serialization of the protocol buffer
}
}
// Feedback on bids submitted in previous responses. This is only set if
// real-time feedback is enabled for your bidder. Contact your account
// manager if you want to enable real-time feedback.
message BidResponseFeedback {
// The unique id from BidRequest.id
optional bytes request_id = 1;
// The index of the BidResponse_Ad if there was more than one. The index
// starts at zero for the first creative.
optional int32 creative_index = 2;
// 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 = 3;
// 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 int64 cpm_micros = 4;
// The minimum bid value necessary to have won the auction, in micros of
// 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 int64 minimum_bid_to_win = 7;
// The minimum bid value necessary to have won the server-side component of
// the overall auction given that there was also an interest group bidding
// component to the overall auction which ran using the Protected Audience
// API. The value is expressed in CPM micros of the buyer account currency.
// The minimum bid to win for the overall auction, including bids from the
// server-side and the on-device interest group components, is populated in
// the minimum_bid_to_win field of the same BidResponseFeedback object.
optional int64 server_side_component_minimum_bid_to_win = 16;
// Billable event rate multiplier that was applied to this bid during
// ranking. The adjustment reflects the likelihood that your bid would
// generate a billable event (namely, the ad renders successfully) if it won
// the auction, relative to the probability that other bids generate a
// billable event if they won the auction. This adjustment can be larger or
// smaller than 1. This affects the final ranking in the auction only; in
// particular, this multiplier does not affect the payment or whether the
// bid clears any floor price.
optional float billable_event_rate_bid_adjustment = 15 [default = 1];
// 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 micros of your account currency.
optional int64 sampled_mediation_cpm_ahead_of_auction_winner = 10;
// Event notification token that was included in the bid response.
optional bytes event_notification_token = 5;
// Buyer creative ID that was included in the bid response.
optional string buyer_creative_id = 6;
// Possible types of bid response feedback objects.
enum FeedbackType {
FEEDBACK_TYPE_UNSPECIFIED = 0;
// Feedback for a bid that was submitted on a bid response.
BID_FEEDBACK = 1;
// Feedback for an interest group buyer submitted on a bid response to
// particpate in an interest group bidding component of the auction run
// using the Protected Audience API.
INTEREST_GROUP_BUYER_FEEDBACK = 2;
}
// The type of the BidResponseFeedback message. Google will send separate
// BidResponseFeedback objects for:
// a) Each bid submitted on a bid response
// b) Each buyer submitted on a bid response to particpate in an interest
// group bidding component of the auction run using the Protected Audience
// API.
optional FeedbackType feedback_type = 17;
// Origin of an interest group buyer that was included in the bid response.
// This field is populated only for feedback where a bidder opted in an
// interest group buyer to participate in the interest group bidding
// component of the overall auction run using the Protected Audience API.
// To learn more about origins, see https://www.rfc-editor.org/rfc/rfc6454.
// To learn more about interest group bidding and the Protected Audience
// API, see
// https://developers.google.com/authorized-buyers/rtb/fledge-origin-trial.
optional string buyer_origin = 18;
// The status code for the submitted interest group buyer. This field is
// only populated in the feedback for an interest group buyer that a bidder
// requested to enter into the interest group auction through the bid
// response. Individual creative status codes of bids submitted by the buyer
// in the on-device interest group auction are not available. See
// https://storage.googleapis.com/adx-rtb-dictionaries/interest-group-buyer-status-codes.txt
// for a list of interest group buyer status codes.
optional int32 interest_group_buyer_status_code = 19;
}
repeated BidResponseFeedback bid_response_feedback = 44;
// How many milliseconds Google will wait for a response before ignoring it.
optional int32 response_deadline_ms = 57;
// -----------------------------------------------------------
// Testing options.
//
// If true, then this is a test request. Results will not be displayed to
// users and you will not be billed for a response even if it wins the
// auction. You should still do regular processing since the request may be
// used to evaluate latencies or for other testing. During your initial
// testing with Google traffic any response that you make will be filtered
// out of the auction whether this option has a value of true or false.
optional bool is_test = 15 [default = false];
// If true, then this request is intended to measure network latency.
// Return an empty BidResponse with only processing_time_ms set as quickly as
// possible without executing any bidding logic.
optional bool is_ping = 17 [default = false];
// If true, then the callout model predicted that you will not bid
// on this request. We send a sampled percentage of such requests so that we
// can automatically update the model when bidding patterns change.
optional bool is_predicted_to_be_ignored = 45 [default = false];
// SupplyChain object. For more information, see
// https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/supplychainobject.md.
message SupplyChain {
// Indicates whether the chain contains all nodes involved in the
// transaction leading back to the owner of the site, app or other medium of
// the inventory.
optional bool complete = 1;
message SupplyChainNode {
// The canonical domain name of the SSP, Exchange, Header Wrapper, etc
// system that bidders connect to. This may be the operational domain of
// the system, if that is different than the parent corporate domain, to
// facilitate WHOIS and reverse IP lookups to establish clear ownership of
// the delegate system. This should be the same value as used to identify
// sellers in an ads.txt file if one exists.
optional string advertising_system_identifier = 1;
// The identifier associated with the seller or reseller account within
// the advertising system. This must contain the same value used in
// transactions, specifically the publisher_id field in the Google
// protocol. Should be limited to 64 characters in length.
optional string seller_identifier = 2;
// Indicates whether this node will be involved in the flow of payment for
// the inventory. When set to true, the advertising system in the
// advertising_system_identifier field pays the seller in the
// seller_identifier field, who is responsible for paying the previous
// node in the chain. When set to false, this node is not involved in the
// flow of payment for the inventory.
optional bool handles_payment = 6;
}
// Array of SupplyChainNode objects in the order of the chain. In a complete
// supply chain, the first node represents the initial advertising system
// and seller ID involved in the transaction, for example, the owner of the
// site, app, or other medium. In an incomplete supply chain, it represents
// the first known node. The last node represents the entity sending this
// bid request.
repeated SupplyChainNode nodes = 2;
// Version of the supply chain specification in use, in the format of
// "major.minor". For example, for version 1.0 of the spec, use the string
// "1.0".
optional string version = 3;
}
optional SupplyChain supply_chain = 69;
// Experimental feature; may be subject to change. See
// https://support.google.com/authorizedbuyers/answer/10890762 for more
// information.
//
// Describes the scope of frequency cap enforcement available for this
// request. Frequency caps to be enforced for a bid can be specified in the
// BidResponse.ad.adslot.frequency_cap field.
enum FrequencyCappingScope {
// Default value which should not be used, or which can indicate that
// frequency cap scope could not be reliably determined.
FREQUENCY_CAPPING_SCOPE_UNKNOWN = 0;
// Frequency capping based on bid response specifications is not available
// for this request. A frequency-capped bid for a bid request with no
// frequency cap availability will be filtered prior to the auction.
FREQUENCY_CAPPING_SCOPE_NONE = 1;
// Frequency capping enforcement is available across multiple sites within
// the same browser.
FREQUENCY_CAPPING_SCOPE_BROWSER = 2;
// Frequency capping enforcement is available across multiple apps on the
// device, excluding browsers.
FREQUENCY_CAPPING_SCOPE_DEVICE = 3;
// Frequency capping enforcement is available within a single app.
FREQUENCY_CAPPING_SCOPE_APP = 4;
// Frequency capping enforcement is available within a single site.
FREQUENCY_CAPPING_SCOPE_SITE = 5;
}
optional FrequencyCappingScope frequency_capping_scope = 70;
// The Digital Services Act (DSA) transparency requirements. See
// https://support.google.com/admanager/answer/14335032.
message Dsa {
// Values indicating whether DSA declarations should be included in the bid
// response and, if so, whether or not the publisher is an Online Platform
// (OP) or Very Large Online Platform (VLOP), as defined by the DSA.
enum DsaSupport {
DSA_SUPPORT_UNKNOWN = 0;
// DSA declarations are not required in the bid response.
NOT_REQUIRED = 1;
// DSA declarations are supported, but not required in the bid response.
SUPPORTED = 2;
// DSA declarations are required in the bid response.
REQUIRED = 3;
// DSA declarations are required in the bid response and the publisher is
// an OP or VLOP.
REQUIRED_BY_ONLINE_PLATFORM = 4;
}
// Indicates if DSA declarations should be included in the bid response.
// Bids where DSA declarations are required but not included will not be
// accepted.
optional DsaSupport dsa_support = 1;
// Options describing a publisher's ability to render DSA transparency
// declarations.
enum PublisherRenderingSupport {
PUBLISHER_RENDERING_SUPPORT_UNKNOWN = 0;
// Publisher can't render.
PUBLISHER_UNABLE_TO_RENDER = 1;
// Publisher could render depending on the buyer's rendering capability as
// described in the BidResponse.ad.dsa_transparency.buyer_render field.
PUBLISHER_CAN_RENDER = 2;
// Publisher will render regardless of the buyer's rendering capability as
// described in the BidResponse.ad.dsa_transparency.buyer_render field.
PUBLISHER_WILL_RENDER = 3;
}
// Indicates if the publisher will render the DSA Transparency info. This
// will signal if the publisher is able to and intends to render the icon
// or other appropriate user-facing symbol and display the DSA transparency
// info to the end user.
optional PublisherRenderingSupport publisher_rendering_support = 2;
// Options describing if a publisher requires DSA transparency declarations.
enum DataToPublisher {
DATA_TO_PUBLISHER_UNKNOWN = 0;
// Do not send transparency data.
DO_NOT_SEND = 1;
// Optional to send transparency data.
OPTIONAL = 2;
// Send transparency data.
SEND = 3;
}
// Indicates whether the bidder should provide DSA transparency declarations
// in the bid response. A publisher may need this information for audit or
// other purposes, even if they will not render the transparency
// declarations themselves.
optional DataToPublisher data_to_publisher = 3;
}
// The Digital Services Act (DSA) transparency information requirements.
optional Dsa dsa = 86;
}
// This is the message that you return in response to a BidRequest. You may
// specify zero or more ads. For each ad, you should provide an ad slot on
// which the ad can run. An ad slot is identified by the AdSlot.id from the
// BidRequest. If you do not want to bid, submit a response with no ads and
// with only the processing_time_ms set.
message BidResponse {
message Ad {
// The event notification token is sent to AdX by bidders for
// troubleshooting. AdX will include the token in real-time feedback for the
// bid. The content of the token will not be logged by AdX. AdX will ignore
// any token longer than 128 bytes.
optional bytes event_notification_token = 25;
// A unique identifier chosen by you for the creative in this response.
// This must always be set, must be limited to at most 64 bytes, and must be
// a valid UTF8 string. Every buyer_creative_id you use must always be
// associated with the same creative. This field is used to communicate
// approval statuses when issues are found. Do not specify the same id for
// different creatives, or all creatives will be disapproved if a problem
// with a single creative is found. Do not specify different ids for the
// same creative in different responses or no creatives will be served since
// approval status is assigned on a per-id basis.
optional string buyer_creative_id = 10;
// Only one of the following should be set:
// 1) html_snippet, 2) video_url, 3) native_ad, or 4) sdk_rendered_ad.
//
// The HTML snippet that will be placed on the web page to display the ad.
// Use BidResponse.Ad.AdSlot.billing_id to indicate which billing id
// this snippet is attributed to.
optional string html_snippet = 1;
// The URL to fetch a video ad. The URL should return an XML response that
// conforms to the VAST 2.0 or 3.0 standard. Use
// BidResponse.Ad.AdSlot.billing_id to indicate which billing id to
// attribute this ad to. Only one of the following should be set:
// html_snippet, video_url. Only set this field if the BidRequest is for an
// in-video ad (BidRequest.video is present).
optional string video_url = 9;
// The VAST document to be returned. This document should conform to the
// VAST 2.0 or 3.0 standard. Use BidResponse.Ad.AdSlot.billing_id to
// indicate which billing ID to attribute this ad to.
// Only set this field if the BidRequest is for an in-video ad and the
// response is VAST XML.
optional string video_vast_xml = 24;
// 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 = 23;
// The content of a native ad. Native ads consist of multiple building
// blocks, which are rendered by the publisher. Only one of the following
// should be set: html_snippet, video_url, or native_ad.
// Only set this field if the BidRequest is for a native ad
// (BidRequest.adslot.native is present).
message NativeAd {
// A video in the form of either a URL for a VAST tag, or an in-line VAST
// tag. Only set this field if VIDEO is required or recommended in the
// BidRequest's NativeAdTemplate.
oneof video {
// The URL to fetch a video ad. The URL should return an XML response
// that conforms to VAST standards.
string video_url = 13;
// The VAST document to be returned. Max size is 100kB.
string video_vast_xml = 16;
}
// A short title for the ad.
optional string headline = 1;
// A long description of the ad.
optional string body = 2;
// A label for the button that the user is supposed to click
optional string call_to_action = 3;
// The name of the advertiser or sponsor, to be displayed in the ad
// creative.
optional string advertiser = 4;
message Image {
optional string url = 1;
// Image width and height are specified in pixels. You may provide a
// larger image than was requested, so long as the aspect ratio is
// preserved.
optional int32 width = 2;
optional int32 height = 3;
}
// A large image.
optional Image image = 5;
// A smaller image, for the advertiser's logo.
optional Image logo = 6;
// The app icon, for app download ads.
optional Image app_icon = 7;
// The app rating in the app store. Must be in the range [0-5].
optional double star_rating = 8;
// The URL that the browser/SDK will load when the user clicks the ad.
// This can be the landing page directly, or the first step of a redirect
// chain that eventually leads to it. For backward compatibility, if this
// is not set, the first Ad.click_through_url is used.
optional string click_link_url = 14;
// This field is deprecated in favor of the repeated click_tracking_urls
// field at the BidResponse.Ad level. It will be removed at the end of
// Q2 2022.
// The URL to use for click tracking. The SDK pings click tracking url on
// a background thread. When resolving the url, HTTP 30x redirects are
// followed. The SDK ignores the contents of the response; this URL
// has no effect on the landing page for the user.
optional string DEPRECATED_click_tracking_url = 11 [deprecated = true];
// This field is deprecated in favor of the click_tracking_urls
// field at the BidResponse.Ad level. It will be removed at the end of
// Q2 2022.
// The URLs to use for click tracking. This will be used throughout the
// serving stack and will incorporate any URL in click_tracking_url.
repeated string DEPRECATED_click_tracking_urls = 15 [deprecated = true];
// The price of the promoted app including the currency info.
optional string price = 10;
}
optional NativeAd native_ad = 18;
// The set of destination URLs for the snippet. This includes the URLs that
// the user will go to if they click on the displayed ad, and any URLs that
// are visible in the rendered ad. Do not include intermediate calls to the
// adserver that are unrelated to the inal landing page. A BidResponse that
// returns a snippet or video ad but declares no click_through_url will be
// discarded. Only set this field if html_snippet or video_url or native_ad
// are set. This data is used as a destination URL declaration, for example
// for post-filtering of publisher-blocked URLs or ad categorization.
//
// For non-native ads, it is not used for click tracking or any
// other ad functionality; it is only used as a destination URL
// declaration.
//
// For native ads, if NativeAd.click_link_url is not set, the first
// value of click_through_url is used to direct the user to the landing
// page. In addition, all values are used as destination
// URL declarations (similar to the non-native case).
repeated string click_through_url = 4;
// All vendor types for the ads that may be shown from this snippet. You
// should only declare vendor ids listed in the vendors.txt file in the
// technical documentation. We will check to ensure that the vendors you
// declare are in the allowed_vendor_type list sent in the BidRequest for
// AdX publishers.
repeated int32 vendor_type = 5;
// All attributes for the ads that may be shown from this snippet. See
// buyer-declarable-creative-attributes.txt in the technical documentation
// for a list of ids. We will check to ensure none of these attributes are
// in the excluded_attribute list in the BidRequest.
repeated int32 attribute = 6;
// All sensitive categories for the ads that may be shown from this snippet.
// See ad-sensitive-categories.txt in the technical documentation for a list
// of ids. We will check to ensure none of these categories were in the
// excluded_sensitive_category list in the BidRequest.
repeated int32 category = 7;
// 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. We will check to ensure these categories were listed
// in the allowed_restricted_category list in the BidRequest. If you are
// bidding with ads in restricted categories you MUST ALWAYS declare them
// here.
repeated int32 restricted_category = 17;
// All names of the ad's advertisers.
repeated string advertiser_name = 11;
// The width and the height in pixels of the ad. Setting these is optional.
// However, these must be set if the bid BidRequest.AdSlot has more than one
// width and height or if BidRequest.Mobile.is_interstitial_request is true.
optional int32 width = 14;
optional int32 height = 15;
message AdSlot {
// The slot id from the BidRequest that the ad may appear in.
required int32 id = 1;
// The maximum CPM you want to be charged if you win the auction for this
// ad slot, expressed in micros of the specified currency or default
// bidding currency. For example, to bid a CPM of 1.29 USD, set
// max_cpm_micros = 1290000. Winning bids are rounded up to billable
// units. For example, in USD, bids are rounded up to the next multiple
// of 10,000 micros (one cent).
required int64 max_cpm_micros = 2;
// The minimum CPM you want to be charged if you win the auction for this
// ad slot, expressed in micros of the specified currency or default
// bidding currency. This may represent a second price if you choose
// max_cpm_micros as the highest of several bids, or some form of reserve
// price if you want to override the reserve price set by the publisher.
// The bid must be less than or equal to max_cpm_micros or it will be
// ignored. This field is optional and does not need to be set. This
// field is not applicable when responding to bid requests with
// auction_type set to FIRST_PRICE.
optional int64 min_cpm_micros = 3;
// The currency used by max_cpm_micros and min_cpm_micros, using ISO-4217
// alpha codes. If this field is populated, the specified currency will
// be used to interpret the bid. Otherwise, the default bidding currency
// will be used, which is determined in the following priority:
// 1. The bidder-level currency, if configured in RTB account settings.
// 2. The buyer-level currency. The buyer will be determined by the
// billing ID specified in the billing_id field of the bid response if it
// is populated, otherwise it will be based on the sole billing ID sent
// in the bid request.
//
// The currency of a buyer account is set on account creation and can be
// checked by contacting a Technical Account Manager.
optional string currency = 15;
// Billing id to attribute this impression to. The value must be in the
// set of billing ids for this slot that were sent in the
// BidRequest.AdSlot.matching_ad_data.billing_id. This must always be set
// if the BidRequest has more than one
// BidRequest.AdSlot.matching_ad_data.billing_id or if the bidder has
// active child seats.
optional int64 billing_id = 4;
// The deal id that you want this bid to participate in. Leave unset
// or set it to "1" if a deal is available but you want to
// ignore the deal and participate in the open auction.
optional int64 deal_id = 5 [default = 0];
// For exchange bidders (third party exchanges doing real-time bidding on
// DFP), the deal id from the exchange's namespace that is associated with
// this bid and reported to publishers. Leave unset if there is no
// associated deal. This is arbitrary UTF8 text and must be at most 64
// bytes.
optional string exchange_deal_id = 6;
// When exchange_deal_id is set, the type of deal. This is reported to
// publishers and affects how the deal is treated in the auction.
enum ExchangeDealType {
OPEN_AUCTION = 0;
PRIVATE_AUCTION = 1;
PREFERRED_DEAL = 2;
EXCHANGE_AUCTION_PACKAGE = 3;
}
optional ExchangeDealType exchange_deal_type = 7 [default = OPEN_AUCTION];
// The seat ID in the bidder's namespace representing the seat on whose
// behalf this bid was made.
optional string seat_id = 25;
// 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 = 8;
// 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 = 12;
// Experimental feature; may be subject to change. See
// https://support.google.com/authorizedbuyers/answer/10890762 for more
// information.
//
// Specifies frequency capping to be applied to the bid. Impressions for
// each user are capped at the level specified by frequency_cap_id. A bid
// will not participate in the auction if an additional impression for the
// user would violate any of the specified caps. Multiple frequency caps
// can be specified for the same frequency_cap_id.
//
// A bid is filtered before the auction if the frequency cap is malformed.
// Instances where the cap is malformed include:
// - frequency_cap_id is empty or is very long
// - max_mpressions or time_range are non-positive
// - there are a large number of frequency caps for a single bid
// - time_unit is not specified
//
// Note that if a subsequent bid with the same frequency_cap_id uses a
// different duration (represented by time_unit and time_range) then
// impressions counted against the old frequency cap will not count
// against the new one, and the impressions counted against the new
// frequency cap with a different time_unit and time_range will not count
// against the old frequency cap..
message FrequencyCap {
// An ID that can represent a bidder's use-case for frequency capping.
// For example, it could represent their campaign, ad, line item, or
// some other entity. It should not contain any user-specific
// information or identifiers and should not be longer than 64
// characters.
optional string frequency_cap_id = 1;
// The time units for which frequency caps can be enforced.
enum TimeUnit {
UNKNOWN_TIME_UNIT = 0;
MINUTE = 1;
DAY = 2;
WEEK = 3;
MONTH = 4;
// When INDEFINITE is used, time_range will be ignored. INDEFINITE
// means the frequency cap will be applied for a long period of time,
// (longer than a month) but not necessarily forever.
INDEFINITE = 5;
}
// The unit of time used to specify the time window for which a
// frequency cap applies.
optional TimeUnit time_unit = 2;
// The length of the time window, in units specified by time_unit, for
// which the frequency cap applies. For instance, if time_unit=WEEK and
// time_range=3, then capping is applied for a three week period. If the
// time_unit=INDEFINITE, this will be ignored.
optional int32 time_range = 3 [default = 1];
// The maximum number of impressions allowed to be shown to a user for
// the provided frequency_cap_id within the time window described by
// time_unit and time_range.
optional int32 max_impressions = 4;
}
repeated FrequencyCap frequency_cap = 16;
// Position within the pod.
enum PodPosition {
// Any position in the pod.
POD_POSITION_ANY = 0;
// Last position in the pod.
POD_POSITION_LAST = 1;
// First position in the pod.
POD_POSITION_FIRST = 2;
// First or last position in the pod.
POD_POSITION_FIRST_OR_LAST = 3;
}
// Indicates that the bid is only eligible
// for a specific position within the pod.
optional PodPosition position_in_pod = 22;
// All bids with the same bid_group_id will be won or lost as a group.
// Bids must have a non-empty bid_group_id to allow an ad to be played
// as part of a pod.
// This field is currently only supported for rewarded video pods
// requests. If an ad is submitted on multiple positional bids
// represented by AdSlot messages, each bid (AdSlot message)
// must have a different bid_group_id.
// For example, if a bidder wants to bid ad_1 for first position
// and last position in the pod and ad_2 for any position and
// want to ensure either both win at the same time or neither of those
// wins, bidder needs to submit:
// ad {
// buyer_creative_id: "ad_1",
// adslot {
// position_in_pod: POD_POSITION_FIRST,
// bid_group_id: "group1"
// },
// adslot {
// position_in_pod: POD_POSITION_LAST,
// bid_group_id: "group2"
// }
// },
// ad {
// buyer_creative_id: "ad_2",
// adslot {
// position_in_pod: POD_POSITION_ANY,
// bid_group_id: "group1"
// },
// adslot {
// position_in_pod: POD_POSITION_ANY,
// bid_group_id: "group2"
// }
// }
optional string bid_group_id = 23;
}
repeated AdSlot adslot = 3;
// The URLs to call when the impression is rendered. This is supported for
// all inventory types and all formats.
repeated string impression_tracking_url = 19;
// The URLs to call when the user clicks on the ad. Currently supported only
// for native ads and Programmatic Guaranteed deals with publisher-
// managed creatives. In the publisher managed case, these click trackers
// will be sent to the bidder server to server. In all other cases, these
// will be sent from the user's device. For more information on
// publisher-managed creatives, see
// https://support.google.com/admanager/answer/9243220.
repeated string click_tracking_urls = 30;
// Link to ad preferences page. This is only supported for native ads.
// If present, a standard AdChoices icon is added to the native creative and
// linked to this URL.
optional string ad_choices_destination_url = 21;
message ImpressionTrackingResource {
// The URL of a Javascript resource. The URLs should not contain script
// tags. For example: "https://mycdn.com/tracker.js".
optional string script_url = 1;
// Additional context provided for rendering.
enum Context {
UNKNOWN_CONTEXT = 0;
// Currently not supported.
OMID = 1;
}
repeated Context context = 2;
// 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 = 3;
// Used to uniquely identify the verification script provider.
optional string vendor_key = 4;
}
// Resources to invoke when the impression is rendered. This is supported
// for native and banner formats only and explicitly allowed scripts
// only.
repeated ImpressionTrackingResource impression_tracking_resource = 26;
// An ad that will be rendered by an SDK known to the buyer. This can only
// be used when the BidRequest included a mobile.installed_sdk submessage.
message SdkRenderedAd {
// The identifier for the SDK that will render the ad. Must match a
// mobile.installed_sdk.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;
// Declared ad assets to support creative scanning, classification, and
// enforcement of ad policy and publisher blocks for ads rendered with a
// custom SDK.
message DeclaredAd {
// Ad content used by SDK to render an ad.
oneof content {
// The HTML snippet representative of the SDK-rendered ad.
string html_snippet = 1;
// The URL to the VAST asset used in the SDK-rendered ad.
string video_url = 2;
// The VAST document used to render custom SDK-rendered ad. This
// document should conform to the VAST 2.0 or 3.0 standard.
string video_vast_xml = 5;
// The content of a native ad. Native ads consist of multiple building
// blocks (such as image and text), which are rendered by the buyer
// SDK.
NativeAd native_ad = 6;
}
// The final landing pages of the SDK-rendered ad.
repeated string click_through_url = 4;
}
optional DeclaredAd declared_ad = 6;
}
optional SdkRenderedAd sdk_rendered_ad = 27;
// 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.mobile.skad.version.
optional string version = 1;
// Ad network identifier used in signature. This should match one of the
// items in BidRequest.mobile.skad.skadnetids.
optional string network = 2;
// Campaign ID compatible with Apple's spec. Used in SKAdNetwork 3.0 and
// below. Replaced by Source Identifier (`source_identifier` field) in
// SKAdNetwork 4.0 and above.
optional int64 campaign = 3;
// A four-digit integer that ad networks define to represent the ad
// campaign. Used in SKAdNetwork 4.0+ and replaces the `campaign` field.
optional int64 source_identifier = 11;
// ID of advertiser's app in Apple's app store.
optional string itunesitem = 4;
// ID of custom product page to display (for iOS 15 or later).
// If not specified, default product page will be displayed.
// See https://developer.apple.com/app-store/custom-product-pages/
// for more details about custom product pages.
optional string product_page_id = 12;
// SKAdNetwork API starting from version 2.2 supports multiple ad
// presentation options specified by the `fidelity-type` parameter of the
// SKAdNetwork signature. This holds parameters used to generate the
// signature that would be different for each fidelity type supported.
// For more info visit:
// https://developer.apple.com/documentation/storekit/skadnetwork/signing_and_providing_ads
message Fidelity {
// The fidelity type of the attribution to track.
optional SKAdNetworkFidelityType fidelity_type = 1 [default =
STOREKIT_RENDERED_ADS];
// A unique all-lowercase UUID generated by the advertiser to use for
// generating the signature.
optional string nonce = 2;
// Unix time in millis used at the time of signature generation.
optional int64 timestamp = 3;
// SKAdNetwork signature as specified by Apple.
optional string signature = 4;
}
repeated Fidelity fidelities = 9;
// A unique all-lowercase UUID generated by the advertiser to use for
// generating the signature.
// Note: This field will be deprecated in favor of the
// BidResponse.ad.skadn.fidelities.nonce field to support multiple
// fidelity types.
optional string nonce = 5;
// ID of publisher's app in Apple's app store. This should match the ID
// from BidRequest.mobile.skad.sourceapp.
optional string sourceapp = 6;
// Unix time in millis used at the time of signature generation.
// Note: This field will be deprecated in favor of the
// BidResponse.ad.skadn.fidelities.timestamp field to support multiple
// fidelity types.
optional int64 timestamp = 7;
// SKAdNetwork signature as specified by Apple.
// Note: This field will be deprecated in favor of the
// BidResponse.ad.skadn.fidelities.signature field to support multiple
// fidelity types.
optional string signature = 8;
// These options indicate how to present SKOverlay recommending the
// advertised app.
// Supported by iOS 14 and later.
//
// For more info visit:
// https://developer.apple.com/documentation/storekit/skoverlay
message SKOverlay {
// Delay in seconds after the ad begins before presenting the overlay.
// If this field is set to 0, the overlay will be shown immediately
// after the ad begins. If this field is unset, the overlay will not
// be shown for the ad.
optional int32 delay_seconds = 1;
// Delay in seconds after the endcard shows before presenting the
// overlay. (This field only applies to rewarded or interstitial video
// creatives.) If this field is set to 0, the overlay will be shown
// immediately after the endcard shows. If this field is unset,
// the overlay will not be shown for the endcard.
// If both `delay_seconds` and `endcard_delay_seconds` are set,
// the overlay will be automatically dismissed when the ad ends,
// and shown again after the endcard shows.
optional int32 endcard_delay_seconds = 2;
// Whether this overlay can be dismissed by the user.
optional bool dismissible = 3 [default = true];
}
optional SKOverlay skoverlay = 13;
// Google Mobile Ads SDK options for SKAdNetwork handling.
message SKAdNetworkOptions {
// By default, SKAdNetwork attribution will only be initiated if the
// click-through URL lands on the app store, either as a direct link to
// the app store or as the final destination of a server-side redirect
// chain. Enables GMA SDK to always initiate SKAdNetwork
// attribution on-click regardless of the detected click's final
// destination URL. Note that enabling this will launch the app store
// even for clicks that are not meant to open the app store, for example
// clicks on Ad Choices icon. For more info, see:
// https://developers.google.com/authorized-buyers/rtb/skadnetwork
optional bool always_open_appstore = 1 [default = false];
}
optional SKAdNetworkOptions skadn_options = 10;
}
optional SKAdNetworkResponse skadn = 29;
// ID of the advertised app (only for app promotion).
// On Android, this should be a bundle or package name such as
// com.foo.mygame. On iOS, it is a numeric ID.
//
// In addition to this field, set the app_promotion_type field below to take
// advantage of features specific to app promotion types.
optional string advertised_app_id = 32;
// Possible types of app promotion.
enum AppPromotionType {
UNKNOWN_APP_PROMOTION_TYPE = 0;
// For encouraging new users to download and install the advertised app.
// Clicking this ad will show the app store listing as an overlay (for
// supported formats), without leaving the publisher app.
// Click through URL for this ad points to the app store listing.
INSTALLS = 1;
// Other types of app promotion that do not fall into the categories
// above. No features specific to app promotion types will apply.
OTHER = 3;
}
// Type of the app promotion corresponding to the advertised app specified
// in the advertised_app_id field above.
// If the advertised app is not specified, this field will be ignored.
//
// Setting advertised_app_id field without this field will be treated as if
// this field were set to OTHER.
optional AppPromotionType app_promotion_type = 33;
// DSA Ad Transparency declarations. See
// https://support.google.com/admanager/answer/14335032.
message DsaTransparency {
// Free text string describing the name of the advertiser on whose behalf
// the ad is shown. Bids will not be accepted if this value is longer
// than 100 characters.
optional string displayed_on_behalf = 1;
// Free text string describing the advertiser who paid for the ad. Must
// always be included even if it's the same as what is listed in the
// displayed_on_behalf attribute. Bids will not be accepted if this value
// is longer than 100 characters.
optional string paying_entity = 2;
// Indicates that the buyer will render their own DSA transparency
// information inside the creative.
optional bool buyer_render = 3;
}
// DSA Ad Transparency information provided by the buyer.
optional DsaTransparency dsa_transparency = 39;
}
repeated Ad ad = 2;
// If is_test was set in the BidRequest, then you may return debug information
// as plain text in this field. Don't set this field under normal
// conditions, or set it to values longer than 100 characters. You should only
// use this field when asked to do so as part of troubleshooting particular
// problems.
optional string debug_string = 5;
// Set this to the processing time in milliseconds from when you
// received the request to when you returned the response.
optional int32 processing_time_ms = 4;
// An optional, bidder-specified reason for not submitting a bid. This field
// is equivalent to BidResponse.nbr in the OpenRTB protocol and uses the same
// namespace of no-bid reason codes. See
// https://developers.google.com/authorized-buyers/rtb/downloads/no-bid-reasons.txt
// for the full set of no-bid reason codes.
optional int32 no_bid_reason = 6;
}
// SKAdNetwork API starting from version 2.2 supports multiple ad
// presentation options specified by the `fidelity-type` parameter of the
// SKAdNetwork signature. The following are the fidelity types supported by
// Apple. For more info visit:
// https://developer.apple.com/documentation/storekit/skadnetwork/signing_and_providing_ads
enum SKAdNetworkFidelityType {
// Attribution for app installs within 24 hours of viewing an ad for at least
// 3 seconds. Supported for SKAdnetwork version 2.2 and up. For more info see:
// https://developer.apple.com/documentation/storekit/skadnetwork/generating_the_signature_to_validate_view-through_ads
VIEW_THROUGH_ADS = 0;
// Attribution for app installs initiated from the StoreKit-rendered App Store
// product page driven by ad clicks. Supported for all SKAdNetwork versions.
// For more info see:
// https://developer.apple.com/documentation/storekit/skadnetwork/generating_the_signature_to_validate_storekit-rendered_ads
STOREKIT_RENDERED_ADS = 1;
}