As part of the Privacy Sandbox, Chrome proposed the Protected Audience API—an in-browser API that lets advertisers and ad tech companies show interest-group targeted ads without relying on third-party cookies, while protecting users from cross-site tracking.
Chrome is running an origin trial for the Protected Audience API. Authorized Buyers are eligible to participate in the testing of the Protected Audience API on Ad Manager publisher inventory. Bidders can achieve the following by testing the Protected Audience API:
- Iterate on and learn about the efficacy of Protected Audience API flows.
- Generate feedback on potential API improvements in public forums—for example, GitHub.
- Prepare for supporting personalized advertising through the API without relying on third-party cookies.
Authorized Buyers interested in testing should check out the Onboarding section for details.
Serving flow summary
Here's a summary of the Protected Audience ad serving flow for Authorized Buyers partners:
- A bidder works with its advertisers to maintain interest groups for each advertiser. Oftentimes, advertisers would add a bidder's tag to the advertiser's page to add a browser to interest groups.
- An end-user visits an advertiser's page. The page might contain the bidder's tag.
- The bidder's tag invokes the Protected Audience API
joinAdInterestGroup()
. This call requests the browser to add the user to an interest group. - The end-user visits a publisher webpage. The user's browser requests Google's publisher ad tag.
- Google's publisher ad tag makes a contextual ad request to a Google server.
- Google sends contextual bid requests to the participating bidders. See the Bid request changes section for more information.
- The bidder returns a bid response including the
InterestGroupBidding
message, which is needed to participate in the interest group auction. In OpenRTB this is specified with theBidResponse.ext.igbid
field, and in the deprecated Google RTB protocol this is specified with theBidResponse.interest_group_bidding
field. If the bidder doesn't specify this information, Google doesn't include the bidder's origin ininterestGroupBuyers
in the auction configuration.InterestGroupBidding
can also contain optional buyer-specific signals that will be passed to the bidder's bidding function during the in-browser auction. In OpenRTB this is specified with theBidResponse.ext.igbid.igbuyer.buyerdata
field, and in the deprecated Google RTB protocol this is specified with theBidResponse.interest_group_bidding.interest_group_buyers.per_buyer_signals
field. See the Bid response changes section for more information. - Google runs the server-side auction and returns a bid response to the browser. The server-side auction considers traditional, server-side bids. The bid response can contain information about a contextual winning bid (if any).
- The bid response contains an auction configuration for the in-browser
auction. This can include contextual signals from each participating buyer
(that were sent through OpenRTB's
buyerdata
or the deprecated Google RTB protocol'sper_buyer_signals
earlier), contextual winner information, and settings for bid eligibility. - Google's publisher tag invokes the Protected Audience API
runAdAuction()
to initiate the on-device interest group auction. Google only includes buyers that were included as anInterestGroupBuyer
inInterestGroupBidding
during auction configuration. - Google passes each eligible bidder's optional buyer-specific signals to the Protected Audience auction configuration.
- If a given bidder's interest groups specified the
trustedBiddingSignalsUrl
, the browser makes a request to each group'strustedBiddingSignalsUrl
to fetch real-time signals for each group. See details in the Protected Audience API spec. - The browser invokes the bidder's
generateBid()
for each interest group that opted in and is eligible to participate in the in-browser auction. This step computes the bid and selects a creative.generateBid()
has access to the optional buyer signals provided by the bidder and the trusted bidding signals for the given interest group. - The browser invokes the seller's (in this case, Google's)
scoreAd()
to assign a rank to each bid in the interest group ad auction. Bids are ranked and filtered based on publisher protections, ad policies, and other constraints. - The browser runs an auction with the eligible interest group bids. The top-ranked contextual bid participates in the in-browser auction.
- After the auction, if there is an interest group winner, the browser invokes
the seller's
reportResult()
and bidder'sreportWin()
to notify each party about the winner of the in-browser auction. - If an interest group ad wins, Google's publisher tag renders the ad in an iframe.
Serving flow details
Before ad serving
Creative review
Creatives must be reviewed and approved by Google before they can be served from
Protected Audience in-browser auctions. You can submit creatives for review
through the Real-time Bidding API or through
automatic creative scanning. Creatives for
Protected Audience in-browser interest group ad auctions must include
renderUrls
for review.
Requirements for renderUrls
:
- The
renderUrl
submitted through the API should match therenderUrl
used in the interest group ad auction. - Each
renderUrl
may only represent a single advertiser or advertising campaign. A givenrenderUrl
cannot be used to render ads on behalf of multiple advertisers. EachrenderUrl
must map to a single creative. - The
renderUrl
needs to be accessible and fetchable by Google's offline creative review systems for up to 7 days after the ad was last bid with.
Real-time Bidding API
Bidders can use the Real-time Bidding API to upload creatives for interest group bidding.
Automatic creative scanning
Bidders can set up automatic creative scanning for creatives that aren't uploaded through the Real-time Bidding API.
If you set up automatic creative scanning, Google finds creatives in the in-browser auction and automatically scans them, so that they're eligible for future auctions.
Here's how to turn on automatic creative scanning:
Add all of the interest group creative's
renderUrl
origins to the Authorized Buyer account.Add the following custom HTTP headers to the creative's HTTP response:
Authorized-Buyers-Creative-ID
string
Buyer-specific creative ID. The maximum length of the creative ID is 128 bytes.
Authorized-Buyers-Click-Through-URLs
string
The set of declared destination URLs for the creative encoded according to RFC2396.
Example:
HTTP/1.1 200 OK
Date: Mon, 8 Jan 2022 12:28:53 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Mon, 8 Jan 2022 12:01:53 GMT
Content-Length: 88
Content-Type: text/html
Connection: Closed
Authorized-Buyers-Creative-ID:123456
Authorized-Buyers-Click-Through-URLs:https://www.advertiser.com/clickUrl1,https://www.advertiser.com/clickUrl12
<html>
<body>
<h1>Hello, World!</h1>
</body>
</html>
Creative expiration
Creatives are approved for 15 days. If you submit creatives with the Real-time Bidding API, you'll need to re-submit the creative after 15 days. If you rely on automatic creative scanning, the scanning process automatically re-scans them.
Buyer Reporting ID
You can break down reporting metrics (such as impressions) using dimensions
provided by the buyer (for example, campaign ID or advertiser ID). To add a
dimension for interest group spend, specify a buyerAndSellerReportingId
for
your ad when you add the user's device to the interest group. See additional
details in Protected Audience
documentation.
The following is an example of how to add buyerAndSellerReportingId
into
the interest group configuration:
const myGroup = {
...
'ads': [
{
...
'buyerAndSellerReportingId':
'{"google_signals": {"buyer_reporting_id": "12345"}}',
...
}
]
}
joinAdInterestGroup(myGroup);
The buyer_reporting_id
will appear as a new dimension in the Authorized
Buyer's Reporting Tool, as Buyer Reporting ID dimension.
Server-side auction
Bid request changes
The following are early versions of supported protocols for use in the experiment:
- OpenRTB early link
- Google RTB protocol (deprecated) early link
Indicate interest group auction support
Bid requests have a new fields to indicate support for interest group auctions:
- OpenRTB:
BidRequest.imp.ext.ae
BidRequest.imp.ext.igbid
- Google RTB Protocol (deprecated):
BidRequest.adslot.supported_auction_environment
BidRequest.adslot.interest_group_bidding_allowed
You can use this field to differentiate between impression opportunities that
support the Protected Audience in-browser interest group auction and those that
support only the traditional server-side exchange auction. The
AuctionEnvironment
enum can have the following values:
SERVER_SIDE_AUCTION
(OpenRTB JSON:0
): The auction determining the winning ad runs on the exchange's servers.ON_DEVICE_INTEREST_GROUP_AUCTION
(OpenRTB JSON:1
): Requests with Protected Audience support, in which a contextual auction runs on the exchange's servers and the interest group bidding and the final auction runs in the browser.SERVER_SIDE_INTEREST_GROUP_AUCTION
(OpenRTB JSON:3
): The contextual auction runs on the exchange's servers, and bidding logic for interest group bids and scoring logic for determining the final winning ad are run in Bidding and Auction servers.
Indicate Protected Audience ad slot size
The bid request includes the following fields to provide you with the Protected Audience ad slot size:
- OpenRTB:
BidRequest.imp.ext.interest_group_auction
.width
BidRequest.imp.ext.interest_group_auction
.height
- Google RTB Protocol (deprecated):
BidRequest.adslot.interest_group_auction.width
BidRequest.adslot.interest_group_auction.height
These fields indicate the size of the ad slot for the Protected Audience auction in pixels.
This size may differ from those in the contextual request, such as those seen
in OpenRTB's BidRequest.imp.banner.format.w
and
BidRequest.imp.banner.format.h
fields or the deprecated Google RTB protocol's
BidRequest.adslot.width
and BidRequest.adslot.height
fields.
The contextual request might have multiple sizes. The on-device auction winning ad is expected to fill only a single fixed slot size.
Indicate Protected Audience ad renderability
Protected Audience ads may or may not render depending on the current
integration stage (see non-rendering
experiment). The render_interest_group_ads
field on the bid request indicates whether the winning Protected Audience ad
will be rendered.
- OpenRTB:
BidRequest.imp.ext.interest_group_auction.render_interest_group_ads
- Google RTB Protocol (deprecated):
BidRequest.adslot.interest_group_auction.render_interest_group_ads
Minimize relying on user identifiers
Contextual bid requests in scope for the Protected Audience API testing can
continue to carry traditional cookie-based identifiers when available from the
browser, such as BidRequest.user.id
and BidRequest.user.buyerid
fields, or
BidRequest.google_user_id
and BidRequest.hosted_match_data
in
the deprecated Google RTB protocol. The presence of such identifiers in bid
requests are subject to existing privacy policies. We recommend that you
not rely on cookie-based identifiers for targeting and bidding purposes during
testing to better prepare for efficient buying when third-party cookies are no
longer available.
Google might also run small-scale experiments where cookie-based identifiers are redacted from bid requests in scope for the Protected Audience API testing. This is to assess the potential impact of third party cookie deprecation.
Chrome-facilitated third-party cookie deprecation testing
To prepare for the third-party cookie deprecation (3PCD) in 2024, Chrome now offers Chrome-facilitated testing.
Sites and vendors can use Chrome-facilitated testing to test their systems under 3PCD. In the test, Chrome browsers are assigned to a 3PCD experiment group, either Mode A or Mode B. Each browser is assigned a consistent label corresponding to a specific 3PCD experiment group that you can access through the in-browser Chrome API.
Google passes the unmodified label from the Chrome API on the RTB bid request. Due to the small traffic slices of an individual label, Google doesn't always include the label in privacy-limited contexts.
Here are the fields where you can view the label:
- OpenRTB:
BidRequest.device.ext.cdep
- Google RTB Protocol (deprecated):
BidRequest.device.cookie_deprecation_label
Bid response changes
Indicate interest group auction participation
You are responsible for explicitly indicating your intent to participate in the
in-browser auction by returning the InterestGroupBidding
object in the
contextual bid response:
- OpenRTB:
BidResponse.ext.igbid
- Google RTB Protocol (deprecated):
BidResponse.interest_group_bidding
You must provide a contextual bid response. The response is not required to
include a contextual bid. The InterestGroupBidding
object should contain the
origin
for each InterestGroupBuyer
, which should match one of the origins
configured by the bidder for their account. The origin
is added to the auction
configuration's interestGroupBuyers
when the Google Publisher Tag calls
runAdAuction()
.
Propagate buyer contextual signals
You can include a buyer's signals in the contextual bid response, which Google
propagates as a JSON object to their on-device bidding function through the
perBuyerSignals
argument. This can be included in the bid response with the
following fields depending on the protocol:
- OpenRTB:
BidResponse.ext.igbid.igbuyer.buyerdata
- Google RTB (deprecated):
BidResponse.interest_group_bidding.per_buyer_signals
Propagate buyer contextual rendering signals
Interest group creatives may use limited contextual signals during rendering by sending those signals through the contextual bid response and receiving them them on the render URL request using macro expansion. For example, rendering signals could be used to customize a creative's look and feel to improve performance in the context of a given ad slot or publisher page.
You can include a buyer's rendering signals serialized as a URL-safe string in
the contextual bid response, which Google will replace in the winning interest
group render URL by constructing the
${RENDER_DATA_buyer.origin.example[_OPTIONAL_SUFFIX]}
macro.
Rendering signals can be specified in the bid response with the following fields, depending on the protocol:
- OpenRTB:
BidResponse.ext.igbid.igbuyer.rsig
- Google RTB (deprecated):
BidResponse.interest_group_bidding.interest_group_buyer.rendering_signals
Up to 3 sets of rendering signals with different macro suffixes may be included in the bid response to distinguish different signals. For example, a suffix could be used to match a specific set of signals applicable only to creatives with the corresponding macro in their render URL, thus reducing data transfer size.
The interest group buyer will be rejected from participating in the Protected Audience auction if the signals are not URL-safe, macro suffixes are not unique, or more than 3 sets of signals are provided.
Specify maximum in-browser bid price
In the Protected Audience proposal, the bid computation and the final auction are expected to run locally on-device. This may create potential abuse vectors that can affect the integrity of the final auction outcomes, such as the winning bid price.
As a mitigation supported during the Protected Audience API testing by Google for its RTB partners, you can specify an expected maximum bid value in each contextual bid response. Expected maximum bid is the maximum bid price that your bidding function is expected to return. If the winning bid reported from the in-browser auction exceeds this amount, then the winning bid isn't counted as a billable event. This approach is subject to change.
In the bid response, you can specify the expected maximum bid value in the following fields:
- OpenRTB:
BidResponse.igbid.igbuyer.maxbid
(expressed in CPM currency units) - Google RTB protocol (deprecated):
BidResponse.interest_group_bidding.interest_group_buyers.max_bid_cpm_micros
(expressed in microCPM)
Attribute impressions to multiple accounts
A bidder must select a billing ID to attribute their interest group bid's impressions using the following fields:
- OpenRTB:
BidResponse.igbid.igbuyer.billing_id
- Google RTB protocol (deprecated):
BidResponse.interest_group_bidding.interest_group_buyers.billing_id
The billing ID selected must be an eligible billing ID from the bid request:
- OpenRTB:
BidRequest.imp.ext.billing_id
- Google RTB protocol (deprecated):
BidRequest.adslot.matching_ad_data.billing_id
If the billing ID to attribute interest group bidding impressions to is not provided, the bidder won't participate in the Protected Audience auction.
Child accounts can have up to two billing IDs. The buyer could use one billing ID for contextual spend and the other one for interest group spend. Reach out to your account manager if you would like to configure two billing IDs for a child account.
It is possible to set a daily budget for each billing ID. Reach out to your account manager to set the daily budget for the child accounts's billing IDs.
Billing IDs for all child accounts with available budget eligible to bid on the impression appear on the bid request for spend attribution selection. Reach out to your account manager to modify the budget for an interest group billing ID.
During in-browser auction
Generate in-browser bids
Use generateBid()
to generate in-browser bids.
Google provides the following parameters:
auctionSignals
: EmptyperBuyerSignals
: A JavaScript object of the same signals provided by the bidder in the contextual response
The following parameters are returned:
ad
: Google ignores this field.bid
: A numerical bid that enters the auction. Must be in CPM units (not micros).render
: The URL rendered to display the creative if the bid wins the auction. Google must review and approve this URL, or it will be filtered from the auction.allowComponentAuction
: Must betrue
. Google currently supports testing of multi-seller auctions.
Here's an example:
function generateBid(...) {
...
return {'ad': 'example',
'bid': ad.metadata.bid,
'render': ad.renderUrl,
'allowComponentAuction': true};
}
See the Protected Audience spec On-Device
Bidding
section for an explanation of the generateBid()
function.
Bid currency
In-browser auction bids are placed in units of CPM of the chosen bid currency.
The bid currency must be indicated in both the contextual bid response and in
the return value of generateBid
and must be a valid ISO 4217 alpha code, such
as "USD", "EUR", or "JPY".
In OpenRTB, use the new cur
field in the InterestGroupBuyer
object in
Google's bid response extension.
Here's an example:
ext {
igbid {
impid: "1"
igbuyer {
origin: "https://examplebuyerorigin.com"
cur: "EUR"
}
}
}
In the Google RTB protocol, use the new currency
field in the
InterestGroupBuyer
message in the bid response.
Here's an example:
interest_group_bidding {
adslot_id: 1
interest_group_buyer {
origin: "https://examplebuyerorigin.com"
currency: "EUR"
}
}
Bidders' generateBid
functions must return bids in the same currency as
indicated in the contextual bid response. Fill the new bidCurrency
property in
generateBid
's return value:
function generateBid(...) {
...
return {'ad': ad,
'bid': bid,
'bidCurrency': 'EUR',
...};
}
If the currency from the contextual bid response is different from the currency
returned by generateBid
, or if either of them returns an invalid currency, the
bid will be filtered before the auction.
Ad quality checks
Creative policy and publisher controls enforcement might be more restrictive for in-browser interest group bids during the Protected Audience API testing for RTB partners.
Digital Services Act support
Due to Digital Services Act Article 26, publishers may require buyers to render
in-ad transparency disclosures. When the "Ask buyers to only show ads with DSA
transparency information on my site or app in EEA" control is enabled by a
publisher, interest group buyers can determine which opportunities they will be
required to render buyer transparency for by noting the values of
BidRequest.regs.dsa.required
and BidRequest.dsa.pubrender
in the bid
request (BidRequest.dsa.dsa_support
and
BidRequest.dsa.publisher_rendering_support
respectively in the deprecated
Google RTB protocol).
When a bidder who wishes to participate in Protected Audience API auctions
receives the signal in bid request that DSA transparency must be displayed for
ads delivered through the Protected Audience API, they should assess whether
they can appropriately display the required information and specify by setting
BidResponse.ext.igbid.igbuyer.dsaadrender
(BidResponse.interest_group_bidding.interest_group_buyers.dsa_buyer_render
in
the deprecated Google RTB protocol). Otherwise, the buyer won't be included
in the Protected Audience API auction.
For more information on Digital Services Act Ad Transparency, see the Help Center Article: Supporting the Digital Services Act.
Bid filtering
Google enforces publisher controls and ad policies during the on-device auction.
After in-browser auction
Report auction result to buyer: reportWin()
Google doesn't populate the following arguments:
auctionSignals
sellerSignals
Use reportWin()
to report the auction result to the buyer.
See the Buyer Reporting on Render and Ad Events section of the Protected Audience API explainer for more information.
Macros
The renderUrl
that references the Protected Audience API creative can include
one or more placeholders, called macros. After the interest group auction
concludes, but before rendering, macros are replaced by the corresponding
values. renderUrl
used in the on-device auction can include the following
macros:
${GDPR}
|
Expands to 0 if GDPR does not apply or 1 if GDPR applies. See documentation. |
${GDPR_CONSENT_XXXX}
|
Expands to the Transparency
& Consent (TC) string associated with the request. If the Transparency &
Consent (TC) string is blank or invalid, this macro does not expand.
Use this macro to pass the TC string to a IAB GVL-registered vendor in a URL.
Replace Creatives with the ${GDPR_CONSENT_XXXX} macro should occur only one time within
the renderUrl .
|
${ADDL_CONSENT}
|
Expands to the Additional Consent (AC) string associated with the request. |
${AD_WIDTH}, ${AD_HEIGHT)
|
These macros insert the ad slot width and height. |
${RENDER_DATA_buyer.origin.example[_OPTIONAL_SUFFIX]}
|
Macro containing render-time buyer signals specified on the bid response.
Replace the |
Impression counting
During the Protected Audience API testing with RTB partners, Google will count
impressions when the browser calls its reportResult()
function and
subsequently fetches Google's reporting URL in a call to sendReportTo()
.
Since the event used by Google for counting impressions in Protected Audience in-browser auctions might be different from the event used for counting impressions by its RTB buyer partners, impression counts might differ.
One of Google's goals for testing the Protected Audience API is to identify and reduce these discrepancies.
Attribution of billable impressions
All of a bidder's spend from Protected Audience in-browser auctions is attributed to a single bidder account based on the mapping from the interest group owner origins configured for the bidder. Attributing spend to different child seat accounts of a bidder isn't supported.
Daily budget cap
During the Protected Audience API testing, each account has an account-level Protected Audience spend daily budget cap. The daily budget cap limits the risk in the in-browser auction environment. Once the daily budget cap is reached, the account no longer receives Protected Audience-eligible bid requests.
The account can continue to participate in server-side contextual auctions after
reaching the Protected Audience cap. For example, a bidder account that reaches
the Protected Audience cap might receive a bid request with auction_environment
= SERVER_SIDE_AUCTION
(OpenRTB JSON: 0
), even if the bid request is eligible
for a Protected Audience auction.
Real-time feedback and minimum bid to win
Bidders who are opted in to receive real-time feedback will receive feedback for interest group buyers requested to be included in an on-device Protected Audience auction. Each interest group buyer that a bidder specifies on a bid response will receive one feedback object, regardless of how many bids the interest group buyer places in the Protected Audience auction. The following information will be available on the interest group buyer feedback object:
- The feedback type of the feedback object will be
INTEREST_GROUP_BUYER_FEEDBACK
. - The origin of the interest group buyer.
- The minimum bid to win for the interest group buyer in order to win the overall auction.
- The minimum bid to win for the interest group buyer in order to beat the highest-ranked bid from the server side component of the overall auction.
- The status code of the interest group buyer. Possible status codes are defined in interest-group-buyer-status-codes.txt.
Refer to the protocol documentation for Authorized Buyers RTB and OpenRTB Extensions for the specific field names.
Bid feedback notification
Chrome provides a temporary debugging API for the Protected Audience API that allows Ad Manager to send real-time server-to-server debug notifications that contain feedback on a Protected Audience bid. This notification will include reasons why bids might have been filtered in the Protected Audience in-browser auction in addition to other information about a bid described below.
Bidders can contact their account manager to configure a static URL that will be used to deliver Protected Audience debugging bid feedback notifications. This static URL will be fetched from Google servers with selected macros replaced after the Protected Audience auction completes. The following macros are supported:
%%GOOGLE_QUERY_ID%%
: This macro is replaced by the Google Query ID that was sent on the Protected Audience-enabled contextual bid request. In the OpenRTB protocol this is specified withBidRequest.ext.google_query_id
, whereas the deprecated Google RTB protocol usesBidRequest.google_query_id
.%%INTEREST_GROUP_OWNER%%
: The origin of the owner of the interest group.%%BID_CPM%%
: The bid price in CPM that was specified by the buyer in thegenerateBid()
function.%%RENDER_URL%%
: The render URL of the creative.%%STATUS%%
: A status code if the bid was rejected withinscoreAd()
. Values are creative status codes.
Here is a sample static URL that a bidder might provide their account manager:
https://dsp.example/debug?google_query_id=%%GOOGLE_QUERY_ID%%&ig_owner=%%INTEREST_GROUP_OWNER%%&render_url=%%RENDER_URL%%&bid=%%BID_CPM%%&status=%%STATUS%%
Bid feedback notification is a temporary feature dependent upon Chrome's
temporary ForDebuggingOnly
API.
Product-level TURTLEDOVE
Ads Composed of Multiple Pieces or Product-level TURTLEDOVE (PLTD) is supported for Google RTB partners during the Protected Audience API testing. Let your account manager know during integration if you plan to test PLTD, as extra resources and configuration are required.
Onboarding
Here's how you can test the Protected Audience API:
Steps
- Fill out the request form to join the Protected Audience API experiment.
- After you submit the request form, reach out to your account manager or file a ticket using the Authorized Buyer Help Center.
- Once the account is configured, both Google and the partner can verify the integration through the steps in Test stages.
Creative Review
In order to bid with product-level ads (ads composed of multiple pieces) in Protected Audience API auctions, follow these requirements:
- Include the
&pltd=True
query parameter in therenderUrl
for the component ad's container (also called the top-levelrenderUrl
) to distinguish top-levelrenderUrls
during creative review. - Render a representative creative when the component ad's container is
fetched for a creative review by Google. In order to understand when a
representative ad rendering should be returned, you can refer to the
validation=True
query parameter set by the Google creative review system.
Integration checklist
- Set up a bid request endpoint that will populate Protected Audience API
related fields on the contextual bid response—for example,
interest_group_bidding
. - Implement tagging on the advertiser's pages to join the user's browser to the interest group.
- Implement
generateBid()
andreportWin()
. - Select interest group owner origins and add them to the Authorized Buyer
account.
- Interest group owner origins should match the origins where the
generateBid()
functions are hosted. - Reach out to the account manager or file a ticket using the Authorized Buyer Help Center to complete this step.
- Interest group owner origins should match the origins where the
- Set up Pretargeting for inventory relevant to Protected Audience API testing.
- Submit creatives for review and approval through the Creatives API.
- (Optional) Set up the trusted bidding signals endpoints.
- (Optional) Set up a test advertiser page that lets Google engineers add their browser to the interest groups owned by your interest group buyer's origin. This lets us manually trigger Protected Audience auctions.
- (Optional) Enable real-time feedback on your account to receive feedback for interest group buyers requested to be included in a Protected Audience auction.
- (Optional) Reach out to your account manager to configure a static URL to receive a server-to-server notification that provides Protected Audience bid feedback for the status of a bid from an on-device Protected Audience auction to help with debugging unexpected issues. See bid feedback notification for details.
Test stages
Stage 1: Manual test
Here's how to manually trigger a Protected Audience auction, ensure the ad can be rendered, and record the impression:
- Use Chrome 101 or later.
- Enable the Privacy Sandbox API and Fenced Frame using
chrome://flags/#privacy-sandbox-ads-apis
andchrome://flags/#enable-fenced-frames
. See more at the Test the privacy sandbox. - Submit a creative for approval using the Real-time Bidding API.
- Use the bidder-provided advertiser page to add a browser to the bidder-owned interest group.
Use the following Google-provided test publisher page to trigger a Protected Audience auction:
https://fledge-testing.uc.r.appspot.com/?nid=allow_all
The in-browser interest group must bid high enough to win the auction, as it might compete against conventional server-side bids. Google also provides a dedicated test publisher page for each partner, where only the given partner can participate in the auction. It might be easier to reliably win in-browser auctions on a partner specific page.
Verify the following:
- The expected winning ad is rendered.
- Auction result is sent server-side—meaning a winning bidder
receives a ping back from
reportWin()
. - The test publisher page console logs a debug message for each bid with
the following information:
renderUrl
: The render URL of the bid.interestGroupOwner
: The interest group owner of the bid.accepted
: This field istrue
if the bid was accepted andfalse
if the bid was rejected byscoreAd()
.externalBidStatus
: A status code if the bid was rejected withinscoreAd()
. Values are creative status codes.
Stage 2: (Optional) Non-rendering experiment
After Google and the partner have manually verified that the partner can participate in the Protected Audience auction, Google enables the partner for the next stage of testing.
Google allocates a small amount of live traffic to run Protected Audience auctions. Then, Google and the partner no longer need to manually trigger a Protected Audience auction. The result of the Protected Audience auction isn't rendered. This allows us to test the integration at scale.
Reach out to your account manager or file a ticket through the Authorized Buyer Help Center when you're ready. Google will enable the account for this stage.
Stage 3: Rendering Experiment
Once Google and the partner have verified Protected Audience auctions at scale without rendering, Google can enable the partner to render the Protected Audience winning ad. Google has a small amount of traffic where Protected Audience auctions are eligible to run, and winning interest group ads are rendered. Participating bidders' in-browser bids compete with the traditional bids.
Reach out to your account manager or file a ticket through the Authorized Buyer Help Center when you're ready. Google will enable the account for this stage.
Additional Features
The following features are extensions of the core protocol.
Parallelization
Parallelization is an optimization that decreases end-to-end auction latency by
initiating the contextual ad request in parallel with the requests to the
buyer trusted servers
specified in trustedBiddingSignalsUrl
.
Parallelization reduces latency but affects interest group buyer eligibility and support for coordinated experiments. Parallelization applies to all bidders who participate in the on-device interest group auction. Bidders don't need to take action to participate in parallel auctions but should familiarize themselves with how parallelization may affect their eligibility in on-device auctions. Experiment group IDs for coordinated experiments are not yet supported within parallel auctions.
Serving flow summary
Here's a summary of the parallel auction flow:
On-device interest group buyer eligibility
For parallel auctions, navigator.runAdAuction
's call happens before
the contextual ad response is returned. In order to initiate buyer trusted
server calls, navigator.runAdAuction
requires that the
interestGroupBuyers
parameter must be
passed as a value, while the remaining auction parameters accept Javascript
Promises that can be resolved after the contextual ad response. Since
interestGroupBuyers
is passed before the contextual ad response,
the contextual ad response (including bid responses)
cannot be used to choose which buyers participate in the parallelized auction
for the given request. Instead Google's publisher tag caches,
in the user's browser, the interestGroupBuyers
parameter from previous
navigator.runAdAuction
executions on the same domain.
Parallelization has several important considerations:
Auction signals that aren't needed for buyer trusted server requests, such as
perBuyerSignals
, can continue to be specified in RTB bid responses in the same way as for non-parallelized auctions. Once the Promises for these signals are resolved, the remaining steps of the on-device auction will complete in the same manner as for the non-parallel auction flow.Since parallelization relies on caching the list of interest group buyers, Google does not always run a parallel auction, as the parallelization cache may be empty or expired. If the cache is empty or expired, Google runs a standard non-parallel Protected Audience API auction and uses buyer intent to participate in the non-parallel auction to build the interest group buyer cache.
If at least one buyer for any bidder is cached for the current publisher domain, then Google will run a parallel auction, which will be indicated on the bid request:
- Google RTB Protocol:
BidRequest.adslot.interest_group_auction.parallelized
- OpenRTB:
BidRequest.imp.ext.interest_group_auction.parallelized
- Google RTB Protocol:
Each registered interest group buyer origin for a given bidder that was included in the parallel auction will have a corresponding
ParallelAuctionBuyer
entry:- Google RTB Protocol:
BidRequest.adslot.interest_group_auction.parallel_auction_buyer
- OpenRTB:
BidRequest.imp.ext.interest_group_auction.pbuyer
- Google RTB Protocol:
If a parallel auction is run, but a specific buyer origin is not present in the cache, then that given buyer cannot be added to the current on-device auction. This is indicated by a request with
parallelized=True
that lacks aParallelAuctionBuyer
entry for a given interest group buyer origin. However, bidders that indicate interest by including valid and eligibleInterestGroupBuyer
(s) on their bid response will have the corresponding interest group buyer origins added to the cache, and those origins will be eligible for future parallelized requests from the same browser and domain. Intent to participate in interest group auctions can be indicated in the following fields:- Google RTB Protocol:
BidResponse.adslot.interest_group_bidding.interest_group_buyers
- OpenRTB:
BidResponse.ext.igbid.igbuyer
- Google RTB Protocol:
Cached buyer origins (which are included in the parallel auction's
interestGroupBuyers
parameter) for which a bidder doesn't indicate intent to participate on their bid response may receive a buyer trusted server call but won't participate in the parallel auction.