Update topic selection algorithm information based on recent Chrome changes

files/en-us/web/api/document/browsingtopics/index.md

@@ -15,7 +15,7 @@ browser-compat: api.Document.browsingTopics
 
 > **Note:** An [Enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment) is required to use this feature in your applications.
 
-The `browsingTopics()` method of the {{domxref("Document")}} interface returns a promise that fulfills with an array of objects representing the selected topics for the current user, which can then be returned to the ad tech platform in a subsequent fetch request. It also triggers the browser to observe the topics inferred from the calling site's URL (i.e. the site where the ad tech `<iframe>` is embedded).
+The `browsingTopics()` method of the {{domxref("Document")}} interface returns a promise that fulfills with an array of objects representing the top topics for the user, one from each of the last three epochs. These topics could then be returned to the ad tech platform in a subsequent fetch request. By default, the method also causes the browser to record the current page visit as observed by the caller, so the page's hostname can later be used in topics calculation.
 
 See [Using the Topics API](/en-US/docs/Web/API/Topics_API/Using) for more details.
 

files/en-us/web/api/document/index.md

@@ -175,7 +175,7 @@ _This interface also inherits from the {{DOMxRef("Node")}} and {{DOMxRef("EventT
 - {{DOMxRef("Document.append()")}}
   - : Inserts a set of {{domxref("Node")}} objects or string objects after the last child of the document.
 - {{DOMxRef("Document.browsingTopics()")}} {{Experimental_Inline}} {{non-standard_inline}}
-  - : Returns a promise that fulfills with an array of objects representing observed topics for the current user and site. It also triggers the browser to observe topics for the current user and site. See the [Topics API](/en-US/docs/Web/API/Topics_API) for more details.
+  - : Returns a promise that fulfills with an array of objects representing the top topics for the user, one from each of the last three epochs. By default, the method also causes the browser to record the current page visit as observed by the caller, so the page's hostname can later be used in topics calculation. See the [Topics API](/en-US/docs/Web/API/Topics_API) for more details.
 - {{DOMxRef("Document.captureEvents()")}} {{Deprecated_Inline}}
   - : See {{DOMxRef("Window.captureEvents")}}.
 - {{DOMxRef("Document.caretPositionFromPoint()")}}

files/en-us/web/api/topics_api/index.md

@@ -41,7 +41,7 @@ The Topics API has no distinct interfaces of its own.
 ### Extensions to other interfaces
 
 - {{domxref("Document.browsingTopics()")}}
-  - : Returns a promise that fulfills with an array of objects representing the selected topics for the current user, for the three most recent epochs. It also triggers the browser to observe the topics inferred from the calling site's URL (i.e. the site where the ad tech `<iframe>` is embedded).
+  - : Returns a promise that fulfills with an array of objects representing the top topics for the user, one from each of the last three epochs. By default, the method also causes the browser to record the current page visit as observed by the caller, so the page's hostname can later be used in topics calculation.
 - {{domxref("fetch()")}} / {{domxref("Request.Request", "Request()")}}, the `browsingTopics` option
   - : A boolean specifying that the selected topics for the current user should be sent in a {{httpheader("Sec-Browsing-Topics")}} header with the associated request.
 - {{domxref("HTMLIFrameElement.browsingTopics")}}

files/en-us/web/api/topics_api/using/index.md

@@ -33,27 +33,29 @@ If the `<iframe>` content from `ad-tech1.example` implements a [feature that ena
 
 ### Selecting topics of interest to influence ad choice
 
+> **Note:** Different browser implementations may select topics in different ways. The below text is based on how Chrome currently selects topics, for demonstration purposes.
+
 On an ongoing basis, the browser will:
 
 1. Keep track of how often the user observes each topic during each new **epoch**. An epoch is a week by default, but the length can be altered for testing purposes (see [Testing hints](#testing_hints)).
 
-2. Select a topic for each user, for each epoch, using the following algorithm:
+   Chrome places each of the 22 root topics (those without an ancestor) from the taxonomy into [one of two buckets](https://github.com/patcg-individual-drafts/topics/blob/main/topics-utility-buckets-v1.md) indicating higher or standard utility for the overall ad tech ecosystem. All descendants of the root topics inherit the same bucket assignment from their parent. The assignment of root topics to buckets is based on input about utility Google received from companies across the ecosystem.
 
-   1. It makes a list of the top five observed topics. If the number of topics observed was fewer than 5, it adds random topics from the taxonomy to make the number up to five.
-   2. It chooses one of the top five topics at random.
-   3. There is a 5% chance that the chosen topic will be replaced with a completely random topic. However, this random topic will only be used if the ad tech platform has previously observed that topic for the user.
+2. Select top topics for each user, at the end of each epoch:
 
-3. Return up to three **chosen topics** (the chosen topics for the last three epochs) to `ad-tech1.example`, only if `ad-tech1.example` appears in the list of caller domains for each topic, as stored in the topic's history entry.
+   1. Chrome converts caller domain hostnames from the user's browsing history into topics.
+   2. These topics are sorted first by bucket, and then by frequency (how many times they were matched in a hostname). That is, if two topics are in the same bucket but have different frequencies, the higher frequency topic is sorted higher.
+   3. Chrome selects the top five topics as the user's top topics for that epoch, which are eligible to be shared with callers.
 
-   > **Note:** Initially, no topics are returned, so the `<iframe>` will likely display a default non-targeted ad. However, once the end of the first epoch is reached, the API will start to return topics and `ad-tech1.example` can start to show more relevant ads based on the observed topics for the current user.
+3. The top topics are returned to `ad-tech1.example`, only if `ad-tech1.example` appears in the list of caller domains for each topic, as stored in the topic's history entry.
 
-   > **Note:** Exactly how the top topics are chosen is defined by the browser rather than the spec, and will vary across implementations. For example, [read about how Chromium does this](https://developers.google.com/privacy-sandbox/blog/topics-enhancements#top_topics_selection).
+   > **Note:** Initially, no topics are returned, so the `<iframe>` will likely display a default non-targeted ad. However, once the end of the first epoch is reached, the API will start to return topics and `ad-tech1.example` can start to show more relevant ads based on the observed topics for the current user.
 
-`ad-tech1.example` then uses the returned topics to select a relevant ad to serve to the user.
+`ad-tech1.example` then selects a relevant ad to serve to the user, based on the returned topics.
 
 ## What API features enable the Topics API?
 
-The following features all serve a dual purpose — they trigger the browser to observe topics, **and** return the topics to the caller. To do so, they need to be included in a calling ad tech's `<iframe>`; the `<iframe>` then has to be embedded on the pages where you want topics observed.
+The following features all serve a dual purpose — they return the user's top topics to the caller and they trigger the browser to record the current page visit as observed by the caller, so the page's hostname can later be used in topics calculation. To do so, they need to be included in a calling ad tech's `<iframe>`; the `<iframe>` then has to be embedded on the pages where you want topics observed.
 
 - You can specify a `browsingTopics: true` option in the options object of a {{domxref("fetch()")}} call to the ad tech platform.
 - You could also pass `browsingTopics: true` into the options object of a {{domxref("Request.Request", "Request()")}} constructor call, and pass the resulting {{domxref("Request")}} object into the {{domxref("fetch()")}} call.
@@ -74,15 +76,15 @@ The following features all serve a dual purpose — they trigger the browser to
 
 When the request associated with one of the above features is sent:
 
-1. A {{httpheader("Sec-Browsing-Topics")}} header is sent along with the request, which contains the topic(s) chosen for the current user.
+1. A {{httpheader("Sec-Browsing-Topics")}} header is sent along with the request, which contains the top topic(s) for the current user.
 2. The ad tech server selects a relevant ad to display in the `<iframe>`, based on these topics, and sends the required data to display it in the response.
 3. An {{httpheader("Observe-Browsing-Topics")}} header should be set on the response to the request — this has the effect of causing the browser to record the current page visit as observed by the calling ad tech provider, so the associated topic(s) will be recorded in a topics history entry, and subsequently be used in [topic selection](#selecting_topics_of_interest_to_influence_ad_choice).
 
-   > **Note:** It is important to clarify that this doesn't record the chosen topics sent in the `Sec-Browsing-Topics` header as observed. It records the topics inferred from the calling site's URL (i.e. the site where the ad tech `<iframe>` is embedded) as observed.
+   > **Note:** It is important to clarify that this doesn't record the top topics sent in the `Sec-Browsing-Topics` header as observed. It records the topics inferred from the calling site's URL (i.e. the site where the ad tech `<iframe>` is embedded) as observed.
 
 ### The `browsingTopics()` method
 
-Alternatively, the embedded `<iframe>` can call {{domxref("Document.browsingTopics()")}} to return a user's current chosen topic(s), which can then be returned to the ad tech platform in a subsequent fetch request. This does not rely on the HTTP headers, but is somewhat less performant. You are advised to use one of the HTTP header methods listed above, falling back to `browsingTopics()` only in situations where the headers cannot be modified.
+Alternatively, the embedded `<iframe>` can call {{domxref("Document.browsingTopics()")}} to return a user's current top topic(s), which can then be returned to the ad tech platform in a subsequent fetch request. This does not rely on the HTTP headers, but is somewhat less performant. You are advised to use one of the HTTP header methods listed above, falling back to `browsingTopics()` only in situations where the headers cannot be modified.
 
 > **Note:** Because the `browsingTopics()` method does not rely on the HTTP headers, the {{httpheader("Observe-Browsing-Topics")}} header is not used for setting the topics as observed and recording/updating topics history entries; the browser does this automatically when the method is called.