Editorial review: Topics API docs (#30107)

* Add Topic API docs * Update files/en-us/web/api/fetch/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Making fixes for samdutton review comments * prettier fix * Making fixes for samdutton comments * fix ad tech example URL issue * Rewrite explanatory text for Topics API usage * improve Sec-Browsing-Topics header description and ref page * minor tweaks to browsingTopics() wording * Further update description of API usage, based on samdutton comments * Fixes for latest samdutton review * remove specification macros for features that have no spec_url in BCD * final few bits of cleanup * Update history entry description with feedback from Yao * Add privacy sandbox enrollment information, restructure privacy section to fit it * Restructure and clarify topics api content, answer review comments * missing paren * Other small tweaks * Update non-standard and spec opposition information * fix linting errors * Further updates to topics API description * Update standards positions information * more changes to increase accuracy of content * Update files/en-us/web/api/topics_api/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/topics_api/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/topics_api/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Update files/en-us/web/api/document/browsingtopics/index.md Co-authored-by: wbamberg <will@bootbonnet.ca> * Fixes for wbamberg review comments --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: wbamberg <will@bootbonnet.ca>
mdn · Feb 22, 2024 · b8282f9 · b8282f9
1 parent 7415a0b
commit b8282f9
Show file tree

Hide file tree

Showing 26 changed files with 797 additions and 93 deletions.
diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt
@@ -12780,6 +12780,7 @@
 /en-US/docs/Web/Performance/Time_to_interactive	/en-US/docs/Glossary/Time_to_interactive
 /en-US/docs/Web/Performance/business_case_for_performance	/en-US/docs/Learn/Performance/business_case_for_performance
 /en-US/docs/Web/Performance/learn	/en-US/docs/Web/Performance/How_browsers_work
+/en-US/docs/Web/Privacy/Partitioned_cookies	/en-US/docs/Web/Privacy/Privacy_sandbox/Partitioned_cookies
 /en-US/docs/Web/Privacy/Tracking_Protection	/en-US/docs/Web/Privacy/Firefox_tracking_protection
 /en-US/docs/Web/Progressive_web_apps/Add_to_home_screen	/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable
 /en-US/docs/Web/Progressive_web_apps/Advantages	/en-US/docs/Web/Progressive_web_apps

diff --git a/files/en-us/web/api/document/browsingtopics/index.md b/files/en-us/web/api/document/browsingtopics/index.md
@@ -0,0 +1,102 @@
+---
+title: "Document: browsingTopics() method"
+short-title: browsingTopics()
+slug: Web/API/Document/browsingTopics
+page-type: web-api-instance-method
+status:
+  - non-standard
+browser-compat: api.Document.browsingTopics
+---
+
+{{APIRef("Topics API")}}
+
+> **Warning:** This feature is currently opposed by two browser vendors. See the [Standards positions](/en-US/docs/Web/API/Topics_API#standards_positions) section below for details of opposition.
+
+> **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).
+
+See [Using the Topics API](/en-US/docs/Web/API/Topics_API/Using) for more details.
+
+> **Note:** `browsingTopics()` does not rely on HTTP headers to send topics and mark topics as observed like the other [Topics API enabling features](/en-US/docs/Web/API/Topics_API/Using#what_api_features_enable_the_topics_api), but it is somewhat less performant. You are advised to use one of the HTTP header-using features, falling back to `browsingTopics()` only in situations where the headers cannot be modified.
+
+## Syntax
+
+```js-nolint
+browsingTopics()
+browsingTopics(options)
+```
+
+### Parameters
+
+- `options` {{optional_inline}}
+  - : An options object, which can contain the following properties:
+    - `skipObservation`
+      - : A boolean value that, if set to `true`, causes the browser to _not_ observe topics when `browsingTopics()` is invoked. The default is `false`, which causes topics to be observed.
+
+### Return value
+
+A {{jsxref("Promise")}} that fulfills with an array of up to three objects representing the current user's selected topics for the last three epochs. Each object contains the following properties:
+
+- `configVersion`
+  - : A string identifying the algorithm (other than the model part) used to calculate the topic.
+- `modelVersion`
+  - : A string representing the model used to classify a string (such as a web page's hostname) into topic IDs.
+- `taxonomyVersion`
+  - : A string representing the taxonomy version used.
+- `topic`
+  - : A number representing the ID of the topic, which can be used by the browser to retrieve the topic from the taxonomy (see an example [taxonomy of interests](https://github.com/patcg-individual-drafts/topics/blob/main/taxonomy_v1.md)).
+- `version`
+  - : The `configVersion`, `modelVersion`, and `taxonomyVersion`, concatenated with colons (`:`) between each.
+
+The exact property values may vary by browser implementation. An example object from Chrome might look as follows:
+
+```js
+{
+  configVersion: "chrome.1",
+  modelVersion: "1",
+  taxonomyVersion: "1",
+  topic: 43,
+  version: "chrome.1:1:1"
+}
+```
+
+### Exceptions
+
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Thrown if:
+    - Usage of the [Topics API](/en-US/docs/Web/API/Topics_API) is disallowed by a {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
+    - The calling site does not have the Topics API included in a successful [privacy sandbox enrollment process](/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment).
+
+## Examples
+
+```js
+// Get an array of top topics for this user
+const topics = await document.browsingTopics();
+
+// Request an ad creative
+const response = await fetch("https://ads.example/get-creative", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify(topics),
+});
+
+// Get the JSON from the response
+const creative = await response.json();
+
+// Display ad
+```
+
+## Specifications
+
+This feature is not part of an official standard, although it is specified in the [Topics API Unofficial Proposal Draft](https://patcg-individual-drafts.github.io/topics/).
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Topics API](/en-US/docs/Web/API/Topics_API)
diff --git a/files/en-us/web/api/document/index.md b/files/en-us/web/api/document/index.md
@@ -174,6 +174,8 @@ _This interface also inherits from the {{DOMxRef("Node")}} and {{DOMxRef("EventT
   - : Adopt node from an external document.
 - {{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}}
+  - : 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.
 - {{DOMxRef("Document.captureEvents()")}} {{Deprecated_Inline}}
   - : See {{DOMxRef("Window.captureEvents")}}.
 - {{DOMxRef("Document.caretPositionFromPoint()")}}

diff --git a/files/en-us/web/api/fetch/index.md b/files/en-us/web/api/fetch/index.md
@@ -41,44 +41,67 @@ fetch(resource, options)
   - : An object containing any custom settings you want to apply to the request.
     The possible options are:
 
-    - `method`
-      - : The request method, e.g., `"GET"`, `"POST"`.
-        The default is `"GET"`.
-        Note that the {{httpheader("Origin")}} header is not set on Fetch requests with a method of {{HTTPMethod("HEAD")}} or {{HTTPMethod("GET")}}.
-        Any string that is a case-insensitive match for one of the methods in [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-overview) will be uppercased automatically.
-        If you want to use a custom method (like `PATCH`), you should uppercase it yourself.
-    - `headers`
-
-      - : Any headers you want to add to your request, contained within a {{domxref("Headers")}} object or an object literal with {{jsxref("String")}} values.
-        Note that [some names are forbidden](/en-US/docs/Glossary/Forbidden_header_name).
-
-        > **Note:** The [`Authorization`](/en-US/docs/Web/HTTP/Headers/Authorization) HTTP header may be added to a request, but will be removed if the request is redirected cross-origin.
-
     - `body`
+
       - : Any body that you want to add to your request:
         this can be a {{domxref("Blob")}}, an {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, a {{jsxref("DataView")}},
         a {{domxref("FormData")}}, a {{domxref("URLSearchParams")}}, string object or literal,
         or a {{domxref("ReadableStream")}} object. This latest possibility is still experimental; check the [compatibility information](/en-US/docs/Web/API/Request#browser_compatibility) to verify you can use it.
         Note that a request using the `GET` or `HEAD` method cannot have a body.
-    - `mode`
-      - : The [mode](/en-US/docs/Web/API/Request/mode) you want to use for the request, e.g., `cors`,
-        `no-cors`, or `same-origin`.
+
+    - `browsingTopics` {{experimental_inline}}
+
+      - : 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. See [Using the Topics API](/en-US/docs/Web/API/Topics_API/Using) for more details.
+
+    - `cache`
+
+      - : A string indicating how the request will interact with the browser's [HTTP cache](/en-US/docs/Web/HTTP/Caching). The possible values, `default`, `no-store`, `reload`, `no-cache`, `force-cache`, and `only-if-cached`, are documented in the article for the {{domxref("Request/cache", "cache")}} property of the {{domxref("Request")}} object.
+
     - `credentials`
 
       - : Controls what browsers do with credentials ([cookies](/en-US/docs/Web/HTTP/Cookies), [HTTP authentication](/en-US/docs/Web/HTTP/Authentication) entries, and TLS client certificates). Must be one of the following strings:
 
-        - `omit`
-          - : Tells browsers to exclude credentials from the request, and ignore any credentials sent back in the response (e.g., any {{HTTPHeader("Set-Cookie")}} header).
-        - `same-origin`
-          - : Tells browsers to include credentials with requests to same-origin URLs, and use any credentials sent back in responses from same-origin URLs. **This is the default value.**
-        - `include`
+        - `omit`: Tells browsers to exclude credentials from the request, and ignore any credentials sent back in the response (e.g., any {{HTTPHeader("Set-Cookie")}} header).
+        - `same-origin`: Tells browsers to include credentials with requests to same-origin URLs, and use any credentials sent back in responses from same-origin URLs. **This is the default value.**
+        - `include`: Tells browsers to include credentials in both same- and cross-origin requests, and always use any credentials sent back in responses.
 
-          - : Tells browsers to include credentials in both same- and cross-origin requests, and always use any credentials sent back in responses.
+          > **Note:** Credentials may be included in simple and "final" cross-origin requests, but should not be included in [CORS preflight requests](/en-US/docs/Web/HTTP/CORS#preflight_requests_and_credentials).
 
-            > **Note:** Credentials may be included in simple and "final" cross-origin requests, but should not be included in [CORS preflight requests](/en-US/docs/Web/HTTP/CORS#preflight_requests_and_credentials).
+    - `headers`
 
-    - `cache`
-      - : A string indicating how the request will interact with the browser's [HTTP cache](/en-US/docs/Web/HTTP/Caching). The possible values, `default`, `no-store`, `reload`, `no-cache`, `force-cache`, and `only-if-cached`, are documented in the article for the {{domxref("Request/cache", "cache")}} property of the {{domxref("Request")}} object.
+      - : Any headers you want to add to your request, contained within a {{domxref("Headers")}} object or an object literal with {{jsxref("String")}} values.
+        Note that [some names are forbidden](/en-US/docs/Glossary/Forbidden_header_name).
+
+        > **Note:** The [`Authorization`](/en-US/docs/Web/HTTP/Headers/Authorization) HTTP header may be added to a request, but will be removed if the request is redirected cross-origin.
+
+    - `integrity`
+
+      - : Contains the [subresource integrity](/en-US/docs/Web/Security/Subresource_Integrity)
+        value of the request (e.g., `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`).
+
+    - `keepalive`
+      - : The `keepalive` option can be used to allow the request to outlive the page.
+        Fetch with the `keepalive` flag is a replacement for the {{domxref("Navigator.sendBeacon()")}} API.
+    - `method`
+
+      - : The request method, e.g., `"GET"`, `"POST"`.
+        The default is `"GET"`.
+        Note that the {{httpheader("Origin")}} header is not set on Fetch requests with a method of {{HTTPMethod("HEAD")}} or {{HTTPMethod("GET")}}.
+        (This behavior was corrected in Firefox 65 — see [Firefox bug 1508661](https://bugzil.la/1508661).)
+        Any string which is a case-insensitive match for one of the methods in [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-overview) will be uppercased automatically.
+        If you want to use a custom method (like `PATCH`), you should uppercase it yourself.
+
+    - `mode`
+      - : The mode you want to use for the request, e.g., `cors`,
+        `no-cors`, or `same-origin`.
+    - `priority`
+      - : Specifies the priority of the fetch request relative to other requests of the same type. Must be one of the following strings:
+        - `high`
+          - : A high priority fetch request relative to other requests of the same type.
+        - `low`
+          - : A low priority fetch request relative to other requests of the same type.
+        - `auto`
+          - : Automatically determine the priority of the fetch request relative to other requests of the same type (default).
     - `redirect`
 
       - : How to handle a `redirect` response:
@@ -92,31 +115,19 @@ fetch(resource, options)
             See [WHATWG fetch standard](https://fetch.spec.whatwg.org/#concept-request-redirect-mode) for more information.
 
     - `referrer`
+
       - : A string specifying the referrer of the request. This can be a
         same-origin URL, `about:client`, or an empty string.
+
     - `referrerPolicy`
       - : Specifies the [referrer policy](https://w3c.github.io/webappsec-referrer-policy/#referrer-policies) to use for the request. May be one of `no-referrer`,
         `no-referrer-when-downgrade`, `same-origin`,
         `origin`, `strict-origin`,
         `origin-when-cross-origin`,
         `strict-origin-when-cross-origin`, or `unsafe-url`.
-    - `integrity`
-      - : Contains the [subresource integrity](/en-US/docs/Web/Security/Subresource_Integrity)
-        value of the request (e.g., `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`).
-    - `keepalive`
-      - : The `keepalive` option can be used to allow the request to outlive the page.
-        Fetch with the `keepalive` flag is a replacement for the {{domxref("Navigator.sendBeacon()")}} API.
     - `signal`
       - : An {{domxref("AbortSignal")}} object instance; allows you to communicate with a
         fetch request and abort it if desired via an {{domxref("AbortController")}}.
-    - `priority`
-      - : Specifies the priority of the fetch request relative to other requests of the same type. Must be one of the following strings:
-        - `high`
-          - : A high-priority fetch request relative to other requests of the same type.
-        - `low`
-          - : A low-priority fetch request relative to other requests of the same type.
-        - `auto`
-          - : Automatically determine the priority of the fetch request relative to other requests of the same type (default).
 
 ### Return value
 
@@ -127,6 +138,8 @@ A {{jsxref("Promise")}} that resolves to a {{domxref("Response")}} object.
 - `AbortError` {{domxref("DOMException")}}
   - : The request was aborted due to a call to the {{domxref("AbortController")}}
     {{domxref("AbortController.abort", "abort()")}} method.
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Usage of the [Topics API](/en-US/docs/Web/API/Topics_API) is specifically disallowed by a {{httpheader('Permissions-Policy/browsing-topics','browsing-topics')}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy), and a `fetch()` request was made with `browsingTopics: true`.
 - {{jsxref("TypeError")}}
   - : Can occur for the following reasons:
 

diff --git a/files/en-us/web/api/htmliframeelement/browsingtopics/index.md b/files/en-us/web/api/htmliframeelement/browsingtopics/index.md
@@ -0,0 +1,70 @@
+---
+title: "HTMLIFrameElement: browsingTopics property"
+short-title: browsingTopics
+slug: Web/API/HTMLIFrameElement/browsingTopics
+page-type: web-api-instance-property
+status:
+  - non-standard
+browser-compat: api.HTMLIFrameElement.browsingTopics
+---
+
+{{APIRef("HTML DOM")}}
+
+> **Warning:** This feature is currently opposed by two browser vendors. See the [Standards positions](#standards_positions) section below for details of opposition.
+
+The **`browsingTopics`** property of the {{domxref("HTMLIFrameElement")}} interface is a boolean specifying that that the selected topics for the current user should be sent with the request for the associated {{htmlelement("iframe")}}'s source in a {{httpheader("Sec-Browsing-Topics")}} header. This reflects the `browsingtopics` HTML attribute.
+
+See [Using the Topics API](/en-US/docs/Web/API/Topics_API/Using) for more details.
+
+## Value
+
+A boolean. The default value is `false`; set it to `true` to send the associated `<iframe>` source request with a {{httpheader("Sec-Browsing-Topics")}} header containing the selected topics for the current user.
+
+## Examples
+
+### Get
+
+Set `browsingtopics` to `true` then load the `<iframe>` contents declaratively:
+
+```html
+<iframe browsingtopics title="Advertising container" src="adtech1.example">
+  ...
+</iframe>
+```
+
+Log the `browsingTopics` value via script:
+
+```js
+const iframeElem = document.querySelector("iframe");
+console.log(iframeElem.browsingTopics); // will return true in supporting browsers
+```
+
+### Set
+
+Specify a minimum `<iframe>`:
+
+```html
+<iframe> ... </iframe>
+```
+
+Set `browsingtopics` to `true` then load the `<iframe>` contents via script:
+
+```js
+const iframeElem = document.querySelector("iframe");
+
+iframeElem.browsingTopics = true;
+iframeElem.title = "Advertising container";
+iframeElem.src = "adtech1.example";
+```
+
+## Specifications
+
+This feature is not part of an official standard, although it is specified in the [Topics API Unofficial Proposal Draft](https://patcg-individual-drafts.github.io/topics/).
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Topics API](/en-US/docs/Web/API/Topics_API)
diff --git a/files/en-us/web/api/htmliframeelement/index.md b/files/en-us/web/api/htmliframeelement/index.md
@@ -23,16 +23,14 @@ _Inherits properties from its parent, {{domxref("HTMLElement")}}_.
   - : A boolean value indicating whether the inline frame is willing to be placed into full screen mode. See [Using fullscreen mode](/en-US/docs/Web/API/Fullscreen_API) for details.
 - {{domxref("HTMLIFrameElement.allowPaymentRequest")}} {{Deprecated_Inline}} {{Non-standard_Inline}}
   - : A boolean value indicating whether the [Payment Request API](/en-US/docs/Web/API/Payment_Request_API) may be invoked inside a cross-origin iframe.
+- {{domxref("HTMLIFrameElement.browsingTopics")}} {{Experimental_Inline}}
+  - : A boolean property specifying that that the selected topics for the current user should be sent with the request for the associated {{htmlelement("iframe")}}'s source. This reflects the `browsingtopics` content attribute value.
 - {{domxref("HTMLIFrameElement.contentDocument")}} {{ReadOnlyInline}}
   - : Returns a {{domxref("Document")}}, the active document in the inline frame's nested browsing context.
 - {{domxref("HTMLIFrameElement.contentWindow")}} {{ReadOnlyInline}}
-
   - : Returns a {{glossary("WindowProxy")}}, the window proxy for the nested browsing context.
-
 - {{domxref("HTMLIFrameElement.credentialless")}} {{Experimental_Inline}}
-
   - : A boolean value indicating whether the `<iframe>` is credentialless, meaning that its content is loaded in a new, ephemeral context. This context does not have access to the parent context's shared storage and credentials. In return, the {{httpheader("Cross-Origin-Embedder-Policy")}} (COEP) embedding rules can be lifted, so documents with COEP set can embed third-party documents that do not. See [IFrame credentialless](/en-US/docs/Web/Security/IFrame_credentialless) for a deeper explanation.
-
 - {{domxref("HTMLIFrameElement.csp")}} {{Experimental_Inline}}
   - : Specifies the Content Security Policy that an embedded document must agree to enforce upon itself.
 - {{domxref("HTMLIFrameElement.featurePolicy")}} {{ReadOnlyInline}} {{Experimental_Inline}}