Merge remote-tracking branch 'upstream/main' into KAnonFixes

FLEDGE_browser_bidding_and_auction_API.md

@@ -1,16 +1,16 @@
 > FLEDGE has been renamed to Protected Audience API. To learn more about the name change, see the [blog post](https://privacysandbox.com/intl/en_us/news/protected-audience-api-our-new-name-for-fledge)
 
-# FLEDGE Browser Bidding & Auction API
+# Protected Audience Browser Bidding & Auction API
 
 ## Background
 
-This document seeks to propose an API for web pages to perform FLEDGE auctions using Bidding and Auction (B&A) servers running in Trusted Execution Environments (TEE), as was announced [here](https://developer.chrome.com/blog/bidding-and-auction-services-availability/). This document seeks to document the web-exposed JavaScript API. The browser is responsible for formatting the data sent to the B&A servers using the B&A server API documented in [this explainer](https://github.com/privacysandbox/fledge-docs/blob/main/bidding_auction_services_api.md).
+This document seeks to propose an API for web pages to perform Protected Audience auctions using Bidding and Auction (B&A) servers running in Trusted Execution Environments (TEE), as was announced [here](https://developer.chrome.com/blog/bidding-and-auction-services-availability/). This document seeks to document the web-exposed JavaScript API. The browser is responsible for formatting the data sent to the B&A servers using the B&A server API documented in [this explainer](https://github.com/privacysandbox/fledge-docs/blob/main/bidding_auction_services_api.md).
 
-## Steps to perform a FLEDGE auction using B&A
+## Steps to perform a Protected Audience auction using B&A
 
 ### Step 1: Get auction blob from browser
 
-To execute an on-server FLEDGE auction, sellers begin by calling `navigator.getInterestGroupAdAuctionData()` with returns a `Promise<AdAuctionData>`:
+To execute an on-server Protected Audience auction, sellers begin by calling `navigator.getInterestGroupAdAuctionData()` with returns a `Promise<AdAuctionData>`:
 
 ```javascript
 const auctionBlob = navigator.getInterestGroupAdAuctionData({
@@ -145,7 +145,7 @@ Another way to prevent the encrypted blob’s size from being a leak is to have
 
 1.  This would hugely complicate the B&A server’s interactions and API, making adoption likely infeasible. The B&A API would no longer be a RESTful API as it would have to coordinate communication from both the browser and other servers (e.g. contextual auction server).
 
-1.  This would also require the on-device JavaScript to determine whether to send the FLEDGE request to the B&A server, perhaps at a time before it has the results of the contextual auction which might influence the decision. Without this information the device would have to send the encrypted blob for every ad request, even in cases where the contextual call indicated it was wasteful to do so.
+1.  This would also require the on-device JavaScript to determine whether to send the Protected Audience request to the B&A server, perhaps at a time before it has the results of the contextual auction which might influence the decision. Without this information the device would have to send the encrypted blob for every ad request, even in cases where the contextual call indicated it was wasteful to do so.
 
 Exposing size of the blob is a temporary leak that we hope to mitigate in the future:
 

FLEDGE_extended_PA_reporting.md

@@ -181,8 +181,11 @@ The parameters consist of:
 * an `eventType` which is a string identifying the event type that triggers this report to
 be sent (see [Triggering reports](#triggering-reports) below), and
 * a `contribution` object which contains:
-  * a `bucket` which is a 128bit ID or a `signalBucket`  which tells the browser how to calculate the bucket (represented as BigInt) and
-  * a `value` which is a non-negative integer or a `signalValue` which tells the browser how to calculate the value.
+  * a `bucket` which is a 128bit ID or a `signalBucket`  which tells the browser how to calculate the bucket (represented as BigInt),
+  * a `value` which is a non-negative integer or a `signalValue` which tells the browser how to calculate the value, and
+  * a `filteringId` which is an optional integer in the range [0, 255] used to allow for separating aggregation service queries. For
+     more detail, please see the [flexible filtering
+     explainer](https://github.com/patcg-individual-drafts/private-aggregation-api/blob/main/flexible_filtering.md#proposal-filtering-id-in-the-encrypted-payload).
 
 
 Where `signalBucket` and `signalValue` is a dictionary which consists of:

Fenced_Frames_Ads_Reporting.md

@@ -52,7 +52,7 @@ There are two variants of the `reportEvent` API for event-level reporting that a
 
 This API is available from all documents in a fenced frame tree (i.e., the ad creative URL that won the Protected Audience auction). Child iframe or redirected documents that are same-origin to the mapped URL of the fenced frame config can call this API without any restrictions. Cross-origin child iframe documents can only call this API if there is opt-in from both the fenced frame root and the cross-origin document. The fenced frame root opts in by being served with a new `Allow-Cross-Origin-Event-Reporting` response header set to `true`. The cross-origin document opts in by calling `reportEvent` with `crossOriginExposed=true`. [See TURTLEDOVE issue #1077](https://github.com/WICG/turtledove/issues/1077) for the motivation behind cross-origin support.
 
-The browser processes the beacon by sending an HTTP POST request, like the existing [navigator.sendBeacon](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon).
+The browser processes the beacon by sending an HTTP POST request, like the existing [navigator.sendBeacon](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon). The POST request is sent immediately or as soon as the corresponding registerAdBeacon is invoked, and is done asynchronously to avoid blocking other actions.
 
 Note `window.fence` here is a new namespace for APIs that are only available from within a fenced frame. In the interim period when FLEDGE supports rendering the winning ad in an iframe, `window.fence` will also be available in such an iframe.
 
@@ -330,7 +330,7 @@ For fenced frames rendering the ad components under the top-level ad fenced fram
 
 ```
 window.fence.setReportEventDataForAutomaticBeacons({
-  'eventType': 'reserved.top_navigation',
+  'eventType': 'reserved.top_navigation_commit',
   'destination':['seller', 'buyer']
 });
 ```

PA_Feature_Detecting.md

@@ -70,7 +70,7 @@ beacon, and then the ad frame can set the same automatic beacon data for both ev
 `top_navigation_commit` and `top_navigation` beacons, and filter out duplicate beacons that have the same exact data.
 
 ## Increase in limit to number of component ads
-[Intent to Ship](TBD)
+[Intent to Ship](https://groups.google.com/a/chromium.org/g/blink-dev/c/3RUQk0GCC9Q/m/wmbXOOB8AAAJ)
 
 Inside `generateBid` one can determine the currently active limit on number of components ads as follows:
 ```
@@ -85,7 +85,7 @@ const maxAdComponents = navigator.protectedAudience ?
 ```
 
 ## Reporting timeout
-[Intent to Ship](TBD)
+[Intent to Ship](https://groups.google.com/a/chromium.org/g/blink-dev/c/ZdZXN1D-MtI/)
 
 Inside `reportWin` one can determine its reporting timeout as follows:
 ```
@@ -101,19 +101,69 @@ const reportingTimeout = auctionConfig.reportingTimeout ?
 
 From the context of a web page, whether custom reporting timeout is enabled can be queried as follows:
 ```
-const reportingTimeoutEnabled = navigator.protectedAudience ?
-    navigator.protectedAudience.queryFeatureSupport("reportingTimeout") : false;
+const reportingTimeoutEnabled = navigator.protectedAudience &&
+    navigator.protectedAudience.queryFeatureSupport("reportingTimeout");
 ```
 
 ## Returning multiple bids from generateBid()
+[Intent to Ship](https://groups.google.com/a/chromium.org/g/blink-dev/c/ZdZXN1D-MtI/)
 
 Inside `generateBid()`, if `browserSignals.multiBidLimit` exists then returning
 an array of bids is supported. The value of `browserSignals.multiBidLimit`
 returns the maximum numbers of bids that can be returned, which may be as low as
 1.
 
 ## Component ad subsetting with targetNumAdComponents
+[Intent to Ship](https://groups.google.com/a/chromium.org/g/blink-dev/c/ZdZXN1D-MtI/)
 
 Inside `generateBid()`, if `browserSignals.multiBidLimit` exist then
 the `targetNumAdComponents` and `numMandatoryAdComponents` bid fields will be
 considered.
+
+## Cross-origin trusted signals
+[Intent to Ship](https://groups.google.com/a/chromium.org/g/blink-dev/c/5nvBAjmoO2g)
+
+From context of a web page:
+```
+navigator.protectedAudience && navigator.protectedAudience.queryFeatureSupport(
+    "permitCrossOriginTrustedSignals")
+```
+
+## Real time reporting
+[Intent to Ship](https://groups.google.com/a/chromium.org/g/blink-dev/c/9_dR-BdyeWE)
+
+From context of a web page:
+```
+navigator.protectedAudience && navigator.protectedAudience.queryFeatureSupport(
+    "realTimeReporting")
+```
+
+## Getting browser-side detectable features as an object
+Sometimes it's desirable to get status of all features detectable via `queryFeatureSupport` in a
+forward-compatible way. Sufficiently recent versions provide this functionality via
+`queryFeatureSupport('*')`, which returns a dictionary describing state of various features. Since
+that functionality isn't available in older versions, backwards-compatibility polyfilling is
+suggested:
+
+```
+let qfs = navigator.protectedAudience ?
+    navigator.protectedAudience.queryFeatureSupport.bind(navigator.protectedAudience) : null;
+
+let allFeatureStatus = qfs ?
+  (qfs("*") || {
+    adComponentsLimit: qfs("adComponentsLimit"),
+    deprecatedRenderURLReplacements: qfs("deprecatedRenderURLReplacements"),
+    reportingTimeout: qfs("reportingTimeout")
+   }) : {}
+```
+
+An example return value would be:
+```
+{
+  "adComponentsLimit":40,
+  "deprecatedRenderURLReplacements":false,
+  "permitCrossOriginTrustedSignals":true,
+  "realTimeReporting":true,
+  "reportingTimeout":true
+}
+```