FLEDGE RTB origin trial

Stay organized with collections Save and categorize content based on your preferences.

As part of the Privacy Sandbox, Chrome proposed FLEDGE—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 FLEDGE. Authorized Buyers can participate in the origin trial testing of FLEDGE on Ad Manager publisher inventory. Bidders can use the origin trial to do the following:

  • Iterate on and learn about the efficacy of FLEDGE flows.
  • Generate feedback on potential API improvements in public forums—for example, GitHub.
  • Prepare for supporting personalized advertising through FLEDGE 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 FLEDGE ad serving flow for Authorized Buyers partners:

alt_text

  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 FLEDGE 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 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.
  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 interest_group_bidding.per_buyer_signals), contextual winner information, and settings for bid eligibility.
  10. Google’s publisher tag invokes the FLEDGE 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.
  11. Google passes each eligible bidder’s per_buyer_signals to the FLEDGE 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 FLEDGE 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 per_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 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 FLEDGE in-browser auctions. You can submit creatives for review through the Real Time Bidding API.

The creatives to be used in FLEDGE in-browser interest group ad auctions must be uploaded with their renderUrls specified. The specified render URLs must match the render URLs of the ads stored as part of the interest group in the browser that you intend to bid within the in-browser interest group auction. One render URL can be associated with only one creative for a given bidder.

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 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 FLEDGE 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 FLEDGE 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 FLEDGE ad slot size

The bid request includes the following fields to provide you with the FLEDGE 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 FLEDGE 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 FLEDGE ad renderability

FLEDGE 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 FLEDGE 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 FLEDGE origin trial 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 the origin trial 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 FLEDGE origin trial. 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 FLEDGE 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 FLEDGE origin trial 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 the 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 response to feedback from the origin trial.

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)

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 FLEDGE spec On-Device Bidding section for an explanation of the generateBid() function.

Currency support

Google supports only bids submitted in USD CPM units in FLEDGE in-browser auctions. Support for more bidding currencies might become available later.

Ad quality checks

Creative policy and publisher controls enforcement might be more restrictive for in-browser interest group bids during FLEDGE origin trial 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 FLEDGE explainer for more information.

Impression counting

During the FLEDGE origin trial 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 FLEDGE 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 FLEDGE in original trials is to identify and reduce these discrepancies.

Attribution of billable impressions

All of a bidder's spend from FLEDGE 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 FLEDGE origin trial testing, each account has an account-level FLEDGE 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 FLEDGE-eligible bid requests.

The account can continue to participate in server-side contextual auctions after reaching the FLEDGE cap. For example, a bidder account that reaches the FLEDGE cap might receive a bid request with auction_environment = SERVER_SIDE_AUCTION (OpenRTB: 0), even if the bid request is eligible for a FLEDGE 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 FLEDGE 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 FLEDGE 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 FLEDGE-enabled opportunity.
  • %%TD_AUCTION_MIN_TO_WIN%%: This macro is replaced by the minimum bid to win value of the on-device FLEDGE auction. The units are in CPM of the bidder's account currency.
    • Note that minimum bid to win values for the on-device FLEDGE auction currently do not take into account any losing FLEDGE bids. This means that if a bid wins the on-device auction, its minimum bid to win will be the maximum of the highest contextual bid and any applicable auction floors.

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

Bid Feedback Notification

Chrome provides a temporary debugging API for FLEDGE that allows Ad Manager to send real-time server-to-server debug notifications that contain feedback on a FLEDGE bid. This notification will include reasons why bids might have been filtered in the FLEDGE 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 FLEDGE debugging bid feedback notifications. This static URL will be fetched from Google servers with selected macros replaced after the FLEDGE 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 FLEDGE-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.

Product-level TURTLEDOVE

Ads Composed of Multiple Pieces or Product-level TURTLEDOVE (PLTD) is supported for Google RTB partners during the FLEDGE origin trial 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 join the FLEDGE RTB origin trial:

Steps

  1. Fill out the request form to join the FLEDGE 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. Google will create a dedicated account for testing the FLEDGE origin trial. This will simplify testing by isolating any potential issues to a separate account.
  4. 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 FLEDGE 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 FLEDGE 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 FLEDGE 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 FLEDGE 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 FLEDGE bid feedback for the status of a bid from an on-device FLEDGE 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 FLEDGE 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 FLEDGE 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: Non-rendering experiment

After Google and the partner have manually verified that the partner can participate in the FLEDGE auction, Google enables the partner for the next stage of testing.

Google allocates a small amount of live traffic where to run FLEDGE auctions. Then, Google and the partner no longer need to manually trigger a FLEDGE auction. The result of the FLEDGE 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 FLEDGE auctions at scale without rendering, Google can enable the partner to render the FLEDGE winning ad. Google has a small amount of traffic where FLEDGE 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.