Protected Audience API (formerly FLEDGE)

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:

Flow diagram

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 BidResponse with the interest_group_bidding field. If the bidder doesn't specify interest_group_bidding, Google doesn't include the bidder's origin in interestGroupBuyers in the auction configuration. The bid response can also containinterest_group_bidding.per_buyer_signals. per_buyer_signals will be passed to the bidder's bidding function during in-browser auction. 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 interest_group_bidding.per_buyer_signals), 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 who have previously returned interest_group_bidding as interestGroupBuyers in the auction configuration.
Google passes each eligible bidder's per_buyer_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's trustedBiddingSignalsUrl 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 per_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's reportWin() 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 a Fenced Frame.

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. The uploaded renderUrl should match the renderUrl used in the interest group ad auction. There can be only one render URL per creative, per bidder.

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%3A%2F%2Fwww.advertiser.com%2FclickUrl1,https%3A%2F%2Fwww.advertiser.com%2FclickUrl12

<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.

Server-side auction

Bid request changes

The following are early versions of supported protocols for use in the experiment:

Google RTB protocol early link
OpenRTB early link

Indicate interest group auction support

Bid requests have a new field, auction_environment.

Google RTB Protocol: BidRequest.adslot.auction_environment
OpenRTB: BidRequest.imp.ext.auction_environment

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 auction_environment enum can have the following values:

SERVER_SIDE_AUCTION (OpenRTB JSON: 0): Traditional server-side auctions
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

Indicate Protected Audience ad slot size

The bid request includes the following fields to provide you with the Protected Audience ad slot size:

Google RTB Protocol:
- BidRequest.adslot.interest_group_auction.width
- BidRequest.adslot.interest_group_auction.height
OpenRTB:
- BidRequest.imp.ext.interest_group_auction.width
- BidRequest.imp.ext.interest_group_auction.height

These fields indicate the size of the ad slot for the Protected Audience auction in pixels.

This size might be different from the sizes for the contextual request (Adslot.widthandAdslot.height, or in OpenRTB: BidRequest.imp.banner.format).

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.

Google RTB Protocol: BidRequest.adslot.interest_group_auction.render_interest_group_ads
OpenRTB: BidRequest.imp.ext.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 the google_user_id (BidRequest.user.id in OpenRTB) and hosted_match_data (BidRequest.user.buyerid in OpenRTB) fields. The presence of such identifiers in bid requests will continue to be subject to any 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.

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:

Google RTB Protocol: BidResponse.interest_group_bidding
OpenRTB: BidResponse.ext.igbid

You must provide a contextual bid response. The response is not required to include a contextual bid. The InterestGroupBidding object should contain the interest group owner's origin, 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 Google Publisher Tag calls runAdAuction().

Propagate buyer contextual signals (perBuyerSignals)

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:

Google RTB: BidResponse.interest_group_bidding.per_buyer_signals
OpenRTB: BidResponse.ext.igbid.igbuyer.buyerdata

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:

Google RTB protocol: BidResponse.interest_group_bidding.interest_group_buyers.max_bid_cpm_micros (expressed in microCPM)
OpenRTB: BidResponse.igbid.igbuyer.maxbid(expressed in CPM currency units)

Attribute impressions to multiple accounts

Optionally, a bidder can select which billing ID to attribute their interest group bid's impressions using the following fields:

Google RTB protocol: BidResponse.interest_group_bidding.interest_group_buyers.billing_id
OpenRTB: BidResponse.igbid.igbuyer.billing_id

The billing ID selected must be an eligible billing ID from the bid request:

Google RTB protocol: BidRequest.adslot.matching_ad_data.billing_id
OpenRTB: BidRequest.imp.ext.billing_id

If the billing ID to attribute interest group bidding impressions to is not provided, interest group spend is attributed to the default bidder account's interest group billing ID.

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: Empty
perBuyerSignals: 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 USD 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 be true. 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. Currently, only "USD" is supported, so you should indicate "USD" in all contextual bid responses and generateBid functions.

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: "USD"
    }
  }
}

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: "USD"
  }
}

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': 'USD',
          ...};
}

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.

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 `XXXX` with the IAB GVL ID of the IAB GVL-registered vendor. If the TC string is blank or invalid, this macro does not expand. Creatives with the `${GDPR_CONSENT_XXXX}` macro could become blocked if the IAB GVL-registered vendor associated with the IAB GVL ID you inserted does not have user consent. 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.

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: 0), even if the bid request is eligible for a Protected Audience auction.

Minimum bid to win notification

As a temporary mechanism, Google provides a dedicated server-to-server notification to communicate minimum bid to win values from on-device Protected Audience auctions. This delivery mechanism is subject to change.

Bidders can contact their account manager to set a static URL that will be used to deliver minimum bid to win notifications. If a bidder responds to a contextual bid request with the interest_group_bidding field specified, the static URL is called after the on-device Protected Audience auction completes. The static URL supports the following macros:

%%GOOGLE_QUERY_ID%%: This macro is replaced by the Google Query ID (BidRequest.google_query_id in Authorized Buyer protocol, and BidRequest.ext.google_query_id in OpenRTB protocol) that was sent on the contextual bid request for a Protected Audience-enabled opportunity.
%%TD_AUCTION_MIN_TO_WIN%%: This macro is replaced by the minimum bid to win value of the on-device Protected Audience auction. The units are in CPM of the bidder's account currency.

For bids submitted with a contextual bid response, the minimum bid to win of the server-side auction will continue to be provided using the real-time feedback mechanism; this value currently does not take into account any Protected Audience bids.

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 (BidRequest.google_query_id in Authorized Buyer protocol, and BidRequest.ext.google_query_id in OpenRTB protocol) that was sent on the Protected Audience-enabled contextual bid request.
%%INTEREST_GROUP_OWNER%%: The origin of the owner of the interest group.
%%BID_CPM%%: The bid price in USD CPM that was specified by the buyer in the generateBid() function.
%%RENDER_URL%%: The render URL of the creative.
%%STATUS%%: A status code if the bid was rejected within scoreAd(). 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.

Click events

Bidders can report click events on Protected Audience ads to Google using the Fenced Frame Reporting API. Bidders should use click event type to notify Google of clicks. Here's an example:

window.fence.reportEvent({
    'eventType': 'click',
    // Google does not require bidders to send data to Google in 'eventData'.
    // However, 'eventData' must be a non-null value, such as an empty string.
    'eventData': '',
    'destinations': ['direct-seller']
});

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.
Google will create a dedicated account for testing the Protected Audience API. This will simplify testing by isolating any potential issues to a separate account.
Once the account is configured, both Google and the partner can verify the integration through the steps in Test stages.

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() and reportWin().
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.
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) Reach out to your account manager to configure a static URL to receive a server-to-server notification that contains the minimum bid to win value from on-device Protected Audience auctions. See minimum bid to win notification for details.
(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 and chrome://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:
1. The expected winning ad is rendered.
2. Auction result is sent server-side—meaning a winning bidder receives a ping back from reportWin().
3. 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 is true if the bid was accepted and false if the bid was rejected by scoreAd().
  - externalBidStatus: A status code if the bid was rejected within scoreAd(). Values are creative status codes.

Stage 2: 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 test 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 test account for this stage.