[{
"type": "thumb-down",
"id": "missingTheInformationINeed",
"label":"Missing the information I need"
},{
"type": "thumb-down",
"id": "tooComplicatedTooManySteps",
"label":"Too complicated / too many steps"
},{
"type": "thumb-down",
"id": "outOfDate",
"label":"Out of date"
},{
"type": "thumb-down",
"id": "samplesCodeIssue",
"label":"Samples/Code issue"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"Other"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"Easy to understand"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"Solved my problem"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"Other"
}]
Process the Request
A real-time bidding interaction begins when Google sends a bid request to
your application. This guide explains how to code your application to
process the bid request.
Parse request
Google sends a bid request as a serialized protocol buffer attached as the
binary payload of an HTTP POST request. The Content-Type is set to
application/octet-stream. See Example bid request for an example.
You must parse this request into an instance of the BidRequest
message. BidRequest is defined in realtime-bidding.proto,
which can be obtained from the reference data page. You can parse the message
using the ParseFromString() method in the generated class for the
BidRequest. For example, the following C++ code parses a request
given a POST payload in a string:
string post_payload = /* the payload from the POST request */;
BidRequest bid_request;
if (bid_request.ParseFromString(post_payload)) {
// Process the request.
}
Once you have the BidRequest you can then work with it as an
object, extracting and interpreting the fields you need. For example, in
C++:
for (int i = 0; i < bid_request.adslot_size(); ++i) {
const BidRequest_AdSlot& adslot = bid_request.adslot(i);
// Decide what to bid on adslot.
}
Some information sent in a BidRequest, such as the Google User
ID, language, or geographic location, are not always available. If you have
pretargeting ad groups that use information that is unknown for a given
impression, then those ad groups will not match. In cases where the missing
information doesn't matter for the pretargeting conditions, bid requests are
sent with the information omitted.
Information about the pretargeting ad group is available in the
MatchingAdData group for each AdSlot. It contains the
first matching ad group ID of the pretargeting ad group that prompted Google to
send out the bid request, that is, the ad group and campaign that are charged
if your response wins the auction for the impression. Under certain
circumstances, you need to explicitly specify the billing_id for
attribution in the BidResponse.AdSlot, for example, when the
BidRequest.AdSlot has more than one matching_ad_data.
For more information on the constraints on the contents of the bid, refer to
therealtime-bidding.proto.
Dictionary files
The bid request uses identifiers defined in dictionary files, which are
available on the reference data
page.
Bid URL macros
Optionally, some fields of the BidRequest can be inserted into
the URL used in the HTTP POST request. This is useful, for example, if you use
a lightweight frontend that load balances over multiple backends using a value
from the request. Contact your technical account manager to request support for
new macros.
Macro
Description
%%GOOGLE_USER_ID%%
Replaced with the google_user_id
from the BidRequest. For example, the bidder URL
If the Google User ID is unknown, the empty string is substituted, with a
result similar to
http://google.bidder.com/path?gid=
%%HAS_MOBILE%%
Replaced with 1 or 0 when calling
BidRequest's has_mobile().
%%HAS_VIDEO%%
Replaced with 1 (true) or 0 (false)
when calling BidRequest's has_video().
%%HOSTED_MATCH_DATA%%
Replaced with the value of the hosted_match_data field
from the BidRequest.
%%MOBILE_IS_APP%%
Replaced with 1 (true) or 0 (false)
from BidRequest's mobile.is_app field.
Adapting to deprecated fields
At any time, some fields in the BidRequest may appear with the
prefix DEPRECATED_. This means that after a specified period of
time those fields will no longer appear in the BidRequest. The
exact period of time in each case—called a notification period—is
announced in Release Notes, blog posts,
and the email newsletter. During the notification period, update your bidder
code to remove any dependencies on deprecated fields. Otherwise, your bidder
may rely on information from the BidRequest that is no longer
being sent.
Deprecated fields (updated May 1, 2013)
The fields in the following table are no longer being sent:
Message
Field
BidRequest
protocol_version
excluded_click_through_url
company_name
country
region
city
metro
Mobile submessage of the
BidRequest (Formerly called the MobileApp
submessage)
app_name
company_name
carrier_name
carrier_country
MatchingAdData submessage of the
BidRequest
campaign_id
The following table describes fields in the BidRequest that
have been deprecated:
Message
Field
MatchingAdData submessage of the
BidRequest
buyer_minimum_cpm
fixed_cpm_micros
Ad submessage of BidRequest
allowed_attribute
publisher_settings
excluded_click_through_url
BidRequest
protocol_version
click_tracking_url
cookie
hashed_cookie
excluded_click_through_url
seller_network
publisher_settings
MatchingNetwork
network_id
google_user_id
Find mobile app ID from transaction URL
Mobile application transactions will report URLs that look like this:
mbappgewtimrzgyytanjyg4888888.com
Use a base-32 decoder to decode the portion of the string in bold
(gewtimrzgyytanjyg4888888).
You can use an online
decoder, but you'll have to capitalize the letters and replace trailing
8s with = values.
So decoding this value:
GEWTIMRZGYYTANJYG4======
results in:
1-429610587
The string 429610587 is the app ID for the iOS app
iFunny.
Here's another example. The reported URL is:
mbappgewtgmjug4ytmmrtgm888888.com
Decoding this value:
GEWTGMJUG4YTMMRTGM======
results in:
1-314716233
The result 314716233 is the app ID for the iOS app
TextNow.
Find mobile app name from transaction URL
Here's an example of getting the app name. The reported URL is as follows:
Bid requests sent to exchange and network bidders participating in Open
Bidding are similar to those of Authorized Buyers participating in standard
real-time bidding. Open Bidding customers will receive a small number of
additional fields, and a few existing fields may have alternative uses. These
include the following:
OpenRTB
Authorized Buyers
Details
BidRequest.imp[].ext.dfp_ad_unit_code
BidRequest.adslot[].dfp_ad_unit_code
Contains the publisher's Ad Manager network code followed by the ad
unit hierarchy, separated by forward slashes.
As an example, this would appear with formatting similar to:
/1234/cruises/mars.
BidRequest.user.data[].segment[]
BidRequest.adslot[].exchange_bidding.key_value[]
Repeated key-value pairs sent from publisher to exchange bidder.
You can determine that the values are key-value pairs sent by the
publisher when BidRequest.user.data[].name is set to
“Publisher Passed”.
BidRequest.imp[].ext.buyer_generated_request_data
BidRequest.adslot[].buyer_generated_request_data
Data, generated by the buyer's SDK within the publisher's mobile
app. This is sent to Open Bidding customers that use their own SDK, as
opposed to the Google Mobile Ads SDK.
BidRequest.app.ext.installed_sdk[]
BidRequest.mobile.installed_sdk[]
Identification and details about the SDK installed in the
publisher's app that the bidder has access to. This is sent to Open
Bidding customers that use their own SDK, as opposed to the Google Mobile
Ads SDK.
In order for your SDK to appear in this field, you must contact your
Technical Account Manager in order to link your SDK to your account.
Declare allowed vendors
Technology vendors which provide services such as research, remarketing, and
ad serving may play a role in the interaction between buyers and sellers. Only
vendors which Google has vetted for participation in Authorized Buyers
interactions are allowed.
To understand the BidRequest and create your
BidResponse, you need to be aware of the two different
possibilities for declaring technology vendors:
Other vendors can only participate if they are declared in both the
BidRequest and BidResponse:
In the BidRequest, the allowed_vendor_type
field specifies which vendors the seller allows. Vendors that will be sent in
the allowed_vendor_type field of the BidRequest are
listed in the Vendors.txt
dictionary file.
In the BidResponse, the vendor_type field
specifies which of those allowed vendors the buyer intends to use.
Example bid request
The following examples represent human-readable samples of the Protobuf and
JSON requests.
To convert the bid request into a binary form, like you would get from the
POST payload in a real request, you can do the following (in C++). Note,
however, that this is not applicable to 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
}
}
Remarketing
Authorized Buyers passes a mobile advertising ID in bid requests from a
mobile application. The mobile advertising ID can be an
iOS IDFA or
Android's advertising ID, which is sent via the
%%EXTRA_TAG_DATA%% macro in the JavaScript tag managed by
Authorized Buyers.
The %%ADVERTISING_IDENTIFIER%% macro allows buyers to receive
iOS IDFA or Android's Advertising ID on impression rendering. It returns an
encrypted proto buffer MobileAdvertisingId like
%%EXTRA_TAG_DATA%%:
You can create user lists from mobile advertising IDs using advertising IDs
you've collected during impression rendering. These user lists can be maintained
on your server or on ours. To create user lists on Google's servers you can use
our bulk upload facility.
When the mobile advertising ID matches a user list, you can use it to run
remarketing.
Real-time feedback
Real-time feedback is available to Authorized Buyers, as well
as exchanges and networks using Open Bidding.
Bid response feedback is supported on the subsequent bid request for both
AdX Protocol and OpenRTB. For OpenRTB, it is sent in
BidRequestExt.
In addition to the default fields sent in Bid Response Feedback, you can
also send custom data in the bid response (in either AdX Proto or OpenRTB)
using an event_notification_token that is returned in the
BidResponse. The event_notification_token is
arbitrary data known only to the bidder that might help with debugging, for
example: a new targeting ID or bidding ID representing a new tactic, or
metadata associated with the creative known only to the bidder. For details,
see OpenRTB
Extensions Protocol Buffer for RTB and AdX Proto
for AdX.
When Authorized Buyers sends a bid request to a bidder, the bidder replies
with a BidResponse. If the bidder has real-time feedback enabled,
then in a subsequent bid request, Authorized Buyers sends feedback on the
response in a BidResponseFeedback message, as shown below:
// 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 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;
// Experimental feature; may be subject to change. See
// https://github.com/google/ads-privacy/tree/master/experiments/turtledove-simulation
// and https://developers.google.com/authorized-buyers/rtb/turtledove
// for more information about the TURTLEDOVE simulation for RTB.
//
// This is the bid price CPM specified by the bidder in the bid response or
// computed by a bidding function in the TURTLEDOVE simulation expressed in
// micros of the bidding currency. The bidding currency is determined by:
// 1. The bidder-level currency, if configured.
// 2. Otherwise, the currency of the buyer account indicated by the
// billing ID in the billing_id field.
// 3. If billing_id is empty, the currency of the buyer account indicated
// by the sole billing ID in the bid request.
optional int64 bid_cpm_micros = 11;
// 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;
// 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;
}
repeated BidResponseFeedback bid_response_feedback = 44;
From this message, the first field you should check is
bid_response_feedback.creative_status_code; you can find the code
meaning in
creative-status-codes.txt. Note that if you win the bid, you can opt out
from the price feedback. For more information, see How to
opt-out.
The real-time feedback includes the bid request ID and one of the
following:
Auction outcome
Real-time feedback
The buyer didn't submit a bid.
Nothing.
The buyer submitted a bid that was filtered out before reaching
the auction.
For an app impression and a creative status code of 53, the
app publisher could have been using a mediation waterfall and therefore the
winning bid would have competed against other demand in the publisher's
passback waterfall chain. Learn how to use
sampled_mediation_cpm_ahead_of_auction_winner when
bidding.
Sample
The following is a sample of real-time feedback as seen in supported
protocols:
After placing a bid in a first-price auction, you will receive real-time
feedback including the minimum_bid_to_win and
sampled_mediation_cpm_ahead_of_auction_winner fields if the bid
was not filtered from the auction. These signals can be used to inform your
bidding logic on how much higher or lower your bid could have been in order to
win the impression.
minimum_bid_to_win: The minimum bid that could have been
placed to win the real-time bidding auction. If you won the auction, this will
be the lowest bid you could have placed while still winning. If you lost the
auction, this will be the winning bid.
sampled_mediation_cpm_ahead_of_auction_winner: If there are
other networks in the mediation chain, the
value of this field is a price representing a sample bid from one of the
eligible mediation networks that were higher than the auction winner, weighted
by expected fill rate. This will be set to 0 if none of the networks in the
mediation chain are expected to fill, or if the publisher does not use SDK
mediation.
How it works
In order to describe the calculations used to determine the possible values
for minimum_bid_to_win and
sampled_mediation_cpm_ahead_of_auction_winner, we first need to
define the following:
The following represents the CPMs in the mediation chain in descending order:
\[C_1, C_2, …, C_n\]
The following represents the corresponding fill rates for the CPMs in the
mediation chain:
\[f_1, f_2, …, f_n\]
The following is a function used to determine the expected CPM and its
probability from mediation chain element \(i\), based on the given fill
rate:
\(X_i = \{C_i\) with probability \(f_i\); \(0\) with probability \(1 - f_i\}\)
The final winning mediation chain will be:
\[\{C_1, C_2, …, C_K, W\}\]
where \(W\) is the winning bid, and \(C_K > W >= C_{K+1}\)
The reserve price, or floor, is denoted as \(F\).
The runner-up bid is denoted as \(R\).
Calculations for auction winner
Field
Calculation
minimum_bid_to_win
\(max\{F, R, X_{K+1}, …, X_n\}\)
sampled_mediation_cpm_ahead_of_auction_winner
\(\{C_i\) with probability \(\prod_{j=1}^{i-1}(1-f_j) \cdot f_i \div \prod_{j=1}^{K}(1-f_j)\}\)
For \(1 <= i <= K\).
Calculations for auction loser
Field
Calculation
minimum_bid_to_win
\(max\{F, W\}\)
sampled_mediation_cpm_ahead_of_auction_winner
\(max\{X_1, …, X_K\}\)
Example with a simple mediation chain
Assume a publisher uses both real-time bidding and an SDK mediation chain as
follows:
SDK Mediation Chain
Expected CPM
Fill Rate
Network 1
\(C_1 = $3.00\)
\(f_1 = 5\%\)
Network 2
\(C_2 = $2.00\)
\(f_2 = 45\%\)
Network 3
\(C_3 = $0.50\)
\(f_3 = 80\%\)
Network 4
\(C_4 = $0.10\)
\(f_4 = 85\%\)
Assume the following as the result of the RTB auction:
RTB Auction
CPM
Auction Winner (W)
$1.00
Auction Runner-UP (R)
$0.05
Reserve Price / Floor (F)
$0
Bid that won the auction
The following is an example of how values and probabilities for
minimum_bid_to_win and
sampled_mediation_cpm_ahead_of_auction_winner are calculated for a
bid that won.
The following is an example of how values and probabilities for
minimum_bid_to_win and
sampled_mediation_cpm_ahead_of_auction_winner are calculated for a
bids that lost.
minimum_bid_to_win
Probability
\(max(F, W) = $1.00\)
\(100\%\)
sampled_mediation_cpm_ahead_of_auction_winner
Probability
\(C_1 = $3.00\)
\(f_1 = 5\%\)
\(C_2 = $2.00\)
\((1-f_1) \cdot f_2 =~ 42.8\%\)
\(0\)
\((1-f_1) \cdot (1-f_2) =~ 52.2\%\)
Bid flattening
Bid flattening describes the processing of a single complex
BidRequest into multiple bid requests that are sent to your
application. Because they retain identical IDs
(BidRequest.google_query_id in the Authorized Buyers RTB Protocol
or BidRequestExt.google_query_id in the OpenRTB protocol) you can
determine which bid requests are correlated after flattening.
Video pods
Bid requests for a video pod with multiple ad opportunities are flattened,
such that each bid request is for an individual ad opportunity from that pod.
This enables you to bid on multiple ad opportunities for a given pod.
Deals
An ad opportunity for a given bidder can be applicable to various deal
types, in addition to the open auction. With bid flattening for deals, one bid
request will be sent for the open auction, and one for each type of fixed-price
deal. In practice, ad constraints can differ between auctions and fixed-price
deal types, for example, for a given video ad opportunity that is available to
both the open auction and a fixed-price deal, a bidder will receive distinct
bid requests for each where constraints such as maximum ad duration and whether
skippable ads are allowed can differ. As a result, flattening applied to the ad
opportunity allows you to more easily discern the ad constraints for the open
auction and the fixed-price deal.
Ad formats
Some ad opportunities can accept multiple formats. With bid flattening, each
format is sent in a distinct bid request where attributes such as eligible
billing IDs are relevant to the format specified in the request.
Bid requests containing the following formats will be flattened into
distinct bid requests:
Banner
Video
Audio
Native
Ad format flattening example
Below is an example showing a simplified OpenRTB JSON bid request without ad
format flattening in comparison to an equivalent set of flatenned requests:
Open Measurement allows you to specify third-party vendors that provide
independent measurement and verification services for ads served to mobile app
environments.
You can determine whether a publisher supports Open Measurement in the bid
request by checking whether the ad opportunity excludes the OmsdkType:
OMSDK 1.0 attribute found in Publisher-excludable
creative attributes. For the Authorized Buyers protocol, this would be
found under BidRequest.adslot[].excluded_attribute. For the
OpenRTB protocol, this would be found under the battr attribute
for Banner or
Video, depending on
the format.
For more information on how to interpret bid requests containing Open
Measurement signals, refer to the Open Measurement
SDK Help Center article.
Sample bid requests
The following sections show sample bid requests for different ad types.