A proposal to bypass some process for PA B&A parity features

[Mike Taylor]

Dear API Owners,

In our meeting on December 17th, 2024 (if it’s even possible to remember that far back) we were reviewing 2 Protected Audience I2Ses to bring feature parity from PA to PA Bidding & Auction services (PA/B&A).

• Intent to Ship: Protected Audience (B&A) - Private Aggregation & downsampling forDebuggingOnly reporting

• Intent to Ship: Protected Audience (B&A) - Selectable Reporting IDs

Some discussion came up questioning if we need to re-approve each feature that has already been approved for PA for PA/B&A, assuming the privacy properties are the same. I spoke with Paul Jensen (cc’d), and it sounds like there are something like a dozen more “parity features” they plan to ship to PA/B&A. I also clarified with Paul that the team will do the normal internal launch process, so there will be Security, Privacy, Testing, Enterprise, etc reviews.

A proposal: if we agree that we don’t need additional LGTMs for these parity features, the PA team can point to this thread to get the internal Web Platform bit approved (which normally requires pointing to a blink-dev thread with 3 LGTMs). 

The PA team should make it clear in future PA I2Ses if the feature will also ship in B&A, and what, if any, differences they foresee (at which point we might request a separate I2S for approval in the B&A context). If a feature has evolved significantly after that, to the point that it would benefit from wider review, an I2S should be sent. New B&A features that don’t also ship in PA will require the normal intent process. And the PA team should send PSAs where I2Ses are not required.

What do you think? If you agree, can you reply with an LGTM (or any questions you might have otherwise)?

Thanks, Mike

[Chris Harrelson]

I think this would be fine as long as:

* The spec PRs are all landed

* The API shape change is straightforward (e.g. just some more parameters)

* The privacy implications are unchanged relative to local PA (which you noted but just want to reiterate)

--
You received this message because you are subscribed to the Google Groups "blink-api-owners-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-api-owners-d...@chromium.org.
To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/b4bbc7b4-bf03-4e3e-9c63-ae476a24acd8%40chromium.org.

[Mike Taylor]

I agree that those seem like reasonable requirements.

[Yoav Weiss (@Shopify)]

LGTM given Chris' requirements.

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/71f130c9-8bf5-4d21-816f-f454086492f8%40chromium.org.

[Domenic Denicola]

I agree this is a good direction.

But, I'd like to learn a bit more about the API shape changes that this sort of thing involves. I looked through the spec PRs and didn't see any IDL updates. Could Paul or someone else provide example code that does not work before such changes, and does work afterward?

I ask because this might impact whether it's a good idea for these features to get ChromeStatus entries, MDN documentation updates, beta blog post visibility, etc.

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CAOmohSJMZ6oMbgO1_LT1zx6M07GD3YH5asY1ucPUqQjBxQ%2BB_w%40mail.gmail.com.

[Paul Jensen]

> Could Paul or someone else provide example code that does not work before such changes, and does work afterward?

In the two Intent-to-Ships that Mike linked, examples of code that didn't work before but now works, would be a bidding script that called Private Aggregation APIs or returned selectable reporting IDs when run on Bidding and Auction services.  For example:

generateBid(...) {
  ...

  privateAggregation.contributeToHistogram({ bucket: 1n, value: 2 });

  ...
  return {...
          'selectedBuyerAndSellerReportingId': 'deal2'};
}

Such a bidding script worked previously during on-device auctions where the scripts are executed by the browser, but not during auctions run on Bidding and Auctions services where the scripts are executed by servers.

[Mike Taylor]

Thanks Paul for the response, and Domenic for the question. It made me realize I didn't fully understand what B&A parity meant. Here is my updated understanding of the before and after case relevant to adding a parity feature to PA/B&A.

My own nomenclature reminder:
PA: on-device Protected Audience
PA/B&A: TEE-based Protected Audience Bidding & Auction Services

Let’s take the Selectable Reporting IDs example from
https://groups.google.com/a/chromium.org/g/blink-dev/c/saFkCnhdfAs/m/D3hcG2ZYBgAJ?e=48417069.

PA runs auctions by calling navigator.runAdAuction(auctionConfig), where the auctionConfig points to various buyers’ and seller worklet scripts.

PA/B&A instead works by first calling navigator.getInterestGroupAdAuctionData(), sending the encrypted blob it returns via Fetch to the B&A server, and when it eventually returns, and the developer sends the winning result to navigator.runAdAuction() (with the rest of the auctionConfig).

Borrowing from https://developers.google.com/privacy-sandbox/private-advertising/protected-audience-api/guide/reporting-id#interest_group, the relevant code to use this feature in PA is as follows:

An advertiser calls joinAdInterestGroup to add an IG to the client, and uses selectableBuyerAndSellerReportingIds to enable “deals”.

```
navigator.joinAdInterestGroup({
  owner: 'https://buyer.example',
  name: 'example-interest-group',
  ads: [{
    renderUrl: `https://buyer.example/ad.html`,
    buyerReportingId: 'brid123',
    buyerAndSellerReportingId: 'bsrid123',
    selectableBuyerAndSellerReportingIds: ['sbsrid1', 'sbsrid2', 'sbsrid3']
  }]
});
```

The relevant buyer- and seller-provided worklet scripts then have access to these selectable reporting IDs inside of generateBid(), scoreAd(), reportResult(), and reportWin(), and importantly, generateBid() can select a selectableBuyerAndSellerReportingId from the interest group by including it in their bid.

Before support for this particular feature was added to PA/B&A - selectableBuyerAndSellerReportingIds would not be recognized by the remote TEE B&A services (and should be ignored), so “deals” weren’t available via PA/B&A.

Tl;dr - the web-exposed JavaScript API surface shouldn’t be changing when adding a parity feature to PA/B&A. But now getInterestGroupAdAuctionData() knows about this feature, and the remote servers understand it and allow utilizing it similar to on-device auctions. Before, that wasn’t the case.

Given that, the proposal remains:

If the following are true, we don't require an I2S, but a PSA should be sent instead:

• The relevant spec PRs have landed
• The API shape change is straightforward, if any change at all (e.g. just some more parameters)
• The privacy properties are unchanged relative to local PA

Otherwise, we would require an I2S, especially if the following apply:

• This feature is only shipping in PA/B&A (i.e., there is no PA-parity)
• The PA/B&A version of a feature has evolved significantly from the version shipped in PA
  
• API OWNERs request an I2S in reply to a PSA

Thoughts? Feelings? Questions?

[Chris Harrelson]

LGTM!

[Domenic Denicola]

I'm not against this change, but I admit I'm still confused. Mike says

> the web-exposed JavaScript API surface shouldn’t be changing when adding a parity feature to PA/B&A

but Paul's example code shows JavaScript API changes, from what I can tell: a new contributeToHistogram() API. (Or maybe a new option to that API? I can't really connect Paul's example code to Mike's explanation.)

Also, Mike says

> The API shape change is straightforward, if any change at all (e.g. just some more parameters)

I don't think we would add a blanket exception for adding new parameters to Javascript APIs in general. But we think it's OK for this category of change? Is it worth being more precise about the limitations of such "straightforward" changes? Is it always to a certain API? (Maybe Paul's contributeToHistogram()? Or one of the nested dictionaries in Mike's joinAdInterestGroup()?)

[Mike Taylor]

On 1/23/25 1:57 AM, Domenic Denicola wrote:

I'm not against this change, but I admit I'm still confused. Mike says

> the web-exposed JavaScript API surface shouldn’t be changing when adding a parity feature to PA/B&A

but Paul's example code shows JavaScript API changes, from what I can tell: a new contributeToHistogram() API. (Or maybe a new option to that API? I can't really connect Paul's example code to Mike's explanation.)

It's possible (likely?) that I'm confused here. It would be useful for Paul to chime in and clarify, but I don't think there are any new APIs or options in either example.

My understanding is that contributeToHistogram() was added to PA in https://groups.google.com/a/chromium.org/g/blink-dev/c/9_dR-BdyeWE/m/7CQsaZcqAAAJ?e=48417069 (approved back in September 2024).

And this intent adds support for that method/"Private Aggregation" in general to PA/B&A in https://groups.google.com/a/chromium.org/g/blink-dev/c/5CZ9X8htGeg/m/2uU5ve7qBAAJ?e=48417069.

So there is no API change there, except now you're (eventually/indirectly) passing that API to navigator.getInterestGroupAdAuctionData() to be handled by the B&A servers.

Also, Mike says

> The API shape change is straightforward, if any change at all (e.g. just some more parameters)

I don't think we would add a blanket exception for adding new parameters to Javascript APIs in general. But we think it's OK for this category of change? Is it worth being more precise about the limitations of such "straightforward" changes? Is it always to a certain API? (Maybe Paul's contributeToHistogram()? Or one of the nested dictionaries in Mike's joinAdInterestGroup()?)

That's fair. I think in this case a more precise description would be: existing APIs/options/functionality is now understood by navigator.getInterestGroupAdAuctionData() and the values returned by fetches to the B&A servers can be used by buyer/seller script worklets.

So probably "no API shape changes"? My initial proposal mentioned parameter changes, largely because I didn't fully understand the flow, and my understanding of it is still kinda spotty. Paul, is that accurate?

[Paul Jensen]

On Thu, Jan 23, 2025 at 4:41 AM Mike Taylor <mike...@chromium.org> wrote:

On 1/23/25 1:57 AM, Domenic Denicola wrote:

I'm not against this change, but I admit I'm still confused. Mike says

> the web-exposed JavaScript API surface shouldn’t be changing when adding a parity feature to PA/B&A

but Paul's example code shows JavaScript API changes, from what I can tell: a new contributeToHistogram() API. (Or maybe a new option to that API? I can't really connect Paul's example code to Mike's explanation.)

It's possible (likely?) that I'm confused here. It would be useful for Paul to chime in and clarify, but I don't think there are any new APIs or options in either example.

Correct. 

My understanding is that contributeToHistogram() was added to PA in https://groups.google.com/a/chromium.org/g/blink-dev/c/9_dR-BdyeWE/m/7CQsaZcqAAAJ?e=48417069 (approved back in September 2024).

Mostly correct: contributeToHistogram() was added to PA, though it was in https://groups.google.com/a/chromium.org/g/blink-dev/c/8cKaLstq2QQ (approved back in June 2023). 

And this intent adds support for that method/"Private Aggregation" in general to PA/B&A in https://groups.google.com/a/chromium.org/g/blink-dev/c/5CZ9X8htGeg/m/2uU5ve7qBAAJ?e=48417069.

Correct. 

So there is no API change there, except now you're (eventually/indirectly) passing that API to navigator.getInterestGroupAdAuctionData() to be handled by the B&A servers.

Right, I'd phrase it as contributeToHistogram() has been available to PA bidding and scoring scripts when the ad selection auction was run on-device since 2023, but our latest I2S makes the same contributeToHistogram() API available to PA bidding and scoring scripts when the ad selection auction is run on Bidding and Auction Services.  Same API, no API changes, just available to PA bidding and scoring scripts when run either on-device or on-server.

Also, Mike says

> The API shape change is straightforward, if any change at all (e.g. just some more parameters)

I don't think we would add a blanket exception for adding new parameters to Javascript APIs in general. But we think it's OK for this category of change? Is it worth being more precise about the limitations of such "straightforward" changes? Is it always to a certain API? (Maybe Paul's contributeToHistogram()? Or one of the nested dictionaries in Mike's joinAdInterestGroup()?)

That's fair. I think in this case a more precise description would be: existing APIs/options/functionality is now understood by navigator.getInterestGroupAdAuctionData() and the values returned by fetches to the B&A servers can be used by buyer/seller script worklets.

So probably "no API shape changes"? My initial proposal mentioned parameter changes, largely because I didn't fully understand the flow, and my understanding of it is still kinda spotty. Paul, is that accurate?

We strive to keep the JavaScript API we're exposing to PA bidding and scoring scripts identical between auctions run on-server versus on-device, making it easier for developers to use either and transition between them while minimizing introduction of bugs.  We have to make changes to the Web and IETF spec'd protocol between the browser and the server, but that should be invisible to developers using the Protected Audience API.

[Domenic Denicola]

Thanks very much to both of you for patiently explaining. I'm happy to proceed with Mike's suggestion, either tightened up a bit to "no API changes", or left with some wiggle room if we think that's better.

[Mike Taylor]

Thanks Domenic. Let's amend the agreement to reflect "No API changes" to be conservative - we can revisit in the future if we learn there are some minimal changes we think meet the PSA bar vs I2S:

If the following are true, we don't require an I2S, but a PSA should be sent instead:

• The relevant spec PRs have landed

• No API changes
  

• The privacy properties are unchanged relative to local PA

Otherwise, we would require an I2S, especially if the following apply:

• This feature is only shipping in PA/B&A (i.e., there is no PA-parity)
• The PA/B&A version of a feature has evolved significantly from the version shipped in PA
  
• API OWNERs request an I2S in reply to a PSA

We have 3 LGTMs in this thread (from Chris, Yoav, and Domenic). I propose that if there are no objections or further questions here by Feb 10, the PA team can point to this email for leadership launchcal approvals in lieu of LGTMs (and recommend the team also link to the relevant PSA).