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

  1. 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.
  2. An end-user visits an advertiser's page. The page might contain the bidder's tag.
  3. The bidder's tag invokes the Protected Audience API joinAdInterestGroup(). This call requests the browser to add the user to an interest group.
  4. The end-user visits a publisher webpage. The user's browser requests Google's publisher ad tag.
  5. Google's publisher ad tag makes a contextual ad request to a Google server.
  6. Google sends contextual bid requests to the participating bidders. See the Bid request changes section for more information.
  7. 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 the BidResponse.ext.igbid field, and in the deprecated Google RTB protocol this is specified with the BidResponse.interest_group_bidding field. If the bidder doesn't specify this information, Google doesn't include the bidder's origin in interestGroupBuyers 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 the BidResponse.ext.igbid.igbuyer.buyerdata field, and in the deprecated Google RTB protocol this is specified with the BidResponse.interest_group_bidding.interest_group_buyers.per_buyer_signals field. See the Bid response changes section for more information.
  8. 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).
  9. 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's per_buyer_signals earlier), contextual winner information, and settings for bid eligibility.
  10. 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 an InterestGroupBuyer in InterestGroupBidding during auction configuration.
  11. Google passes each eligible bidder's optional buyer-specific signals to the Protected Audience auction configuration.
  12. 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.
  13. 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.
  14. 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.
  15. The browser runs an auction with the eligible interest group bids. The top-ranked contextual bid participates in the in-browser auction.
  16. 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.
  17. 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 the renderUrl used in the interest group ad auction.
  • Each renderUrl may only represent a single advertiser or advertising campaign. A given renderUrl cannot be used to render ads on behalf of multiple advertisers. Each renderUrl 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:

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.

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: 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 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 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 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.
${RENDER_DATA_buyer.origin.example[_OPTIONAL_SUFFIX]}

Macro containing render-time buyer signals specified on the bid response.

Replace the buyer.origin.example placeholder with the origin of the interest group buyer, which should correspond to interest_group_buyers.origin in the bid response. You may include an _OPTIONAL_SUFFIX to provide up to three different rendering signal values.

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 with BidRequest.ext.google_query_id, whereas the deprecated Google RTB protocol uses BidRequest.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 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.

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

  1. Fill out the request form to join the Protected Audience API experiment.
  2. After you submit the request form, reach out to your account manager or file a ticket using the Authorized Buyer Help Center.
  3. 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 the renderUrl for the component ad's container (also called the top-level renderUrl) to distinguish top-level renderUrls 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() 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) 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:

  1. Use Chrome 101 or later.
  2. 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.
  3. Submit a creative for approval using the Real-time Bidding API.
  4. Use the bidder-provided advertiser page to add a browser to the bidder-owned interest group.
  5. 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.

  6. 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: (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: Flow diagram

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:

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

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

  3. 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
  4. 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
  5. 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 a ParallelAuctionBuyer entry for a given interest group buyer origin. However, bidders that indicate interest by including valid and eligible InterestGroupBuyer(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
  6. 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.