mdn
Editorial review: Topics API docs
Description
https://github.com/mdn/content/pull/28196 contains the engineering technical review for my work on Topics API docs, which has been completed and approved. Thank you to @samdutton for your thorough and detailed review work.
This is a new PR based on the same branch, which is intended to contain the editorial review for the same work.
Background information
The Topics API is an integral part of Google's privacy sandbox technologies. Many parts of this set are being made available by default in Chrome 115 (depending on a gradual ramp up to 100% of userbase over the 115 release period).
This PR provides documentation for the Topics API and its related HTTP headers and HTTP features.
See my research document for more details of exactly what changes are expected in the PR.
Motivation
Additional details
Related issues and pull requests
Preview URLs (24 pages)
/en-US/docs/Web/API/Document/browsingTopics/en-US/docs/Web/API/Document/en-US/docs/Web/API/HTMLIFrameElement/browsingTopics/en-US/docs/Web/API/HTMLIFrameElement/en-US/docs/Web/API/Request/Request/en-US/docs/Web/API/Speculation_Rules_API/en-US/docs/Web/API/Topics_API/Using/en-US/docs/Web/API/Topics_API/en-US/docs/Web/API/fetch/en-US/docs/Web/HTML/Element/iframe/en-US/docs/Web/HTTP/Headers/Observe-Browsing-Topics/en-US/docs/Web/HTTP/Headers/Permissions-Policy/browsing-topics/en-US/docs/Web/HTTP/Headers/Permissions-Policy/en-US/docs/Web/HTTP/Headers/Sec-Browsing-Topics/en-US/docs/Web/HTTP/Headers/Sec-Fetch-Dest/en-US/docs/Web/Privacy/Firefox_tracking_protection/en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment/en-US/docs/Web/Privacy/Privacy_sandbox/Partitioned_cookies/en-US/docs/Web/Privacy/Privacy_sandbox/en-US/docs/Web/Privacy/Redirect_tracking_protection/en-US/docs/Web/Privacy/State_Partitioning/en-US/docs/Web/Privacy/Storage_Access_Policy/Errors/en-US/docs/Web/Privacy/Storage_Access_Policy/en-US/docs/Web/Privacy
Flaws (14)
Note! 22 documents with no flaws that don't need to be listed. 🎉
URL: /en-US/docs/Web/API/Document
Title: Document
Flaw count: 6
- macros:
/en-US/docs/Web/API/Document/xmlStandalone does not exist/en-US/docs/Web/API/Document/captureEvents does not exist/en-US/docs/Web/API/Document/getBoxQuads does not exist/en-US/docs/Web/API/Document/releaseEvents does not exist/en-US/docs/Web/API/Document/queryCommandIndeterm does not exist- and 1 more flaws omitted
URL: /en-US/docs/Web/API/HTMLIFrameElement
Title: HTMLIFrameElement
Flaw count: 8
- macros:
/en-US/docs/Web/API/HTMLIFrameElement/align does not exist/en-US/docs/Web/API/HTMLIFrameElement/allow does not exist/en-US/docs/Web/API/HTMLIFrameElement/frameBorder does not exist/en-US/docs/Web/API/HTMLIFrameElement/longDesc does not exist/en-US/docs/Web/API/HTMLIFrameElement/marginHeight does not exist- and 3 more flaws omitted
External URLs (27)
URL: /en-US/docs/Web/Privacy/Privacy_sandbox
Title: Privacy sandbox
- https://developer.chrome.com/en/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment
Title: Privacy sandbox enrollment
- https://developer.chrome.com/en/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
- https://github.com/privacysandbox/attestation/blob/main/how-to-enroll.md (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/API/fetch
Title: fetch() global function
- https://bugzil.la/1508661 (1 time) (Note! This may be a new URL 👀)
- https://www.rfc-editor.org/rfc/rfc9110 (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/API/Document/browsingTopics
Title: Document: browsingTopics() method
- https://github.com/patcg-individual-drafts/topics/blob/main/taxonomy_v1.md (1 time) (Note! This may be a new URL 👀)
- https://patcg-individual-drafts.github.io/topics/ (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/API/Topics_API
Title: Topics API
- https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
- https://developer.chrome.com/docs/privacy-sandbox/topics/overview/ (1 time) (Note! This may be a new URL 👀)
- https://github.com/patcg-individual-drafts/topics/blob/main/taxonomy_v2.md (1 time) (Note! This may be a new URL 👀)
- https://glitch.com/edit/ (2 times) (Note! This may be a new URL 👀)
- https://mozilla.github.io/standards-positions/ (1 time) (Note! This may be a new URL 👀)
- https://patcg-individual-drafts.github.io/topics/ (1 time) (Note! This may be a new URL 👀)
- https://topics-demo.glitch.me/ (1 time) (Note! This may be a new URL 👀)
- https://topics-fetch-demo.glitch.me/ (1 time) (Note! This may be a new URL 👀)
- https://webkit.org/standards-positions/ (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/API/Topics_API/Using
Title: Using the Topics API
- https://developer.chrome.com/docs/privacy-sandbox/topics/overview/ (1 time) (Note! This may be a new URL 👀)
- https://developers.google.com/privacy-sandbox/blog/topics-enhancements (1 time) (Note! This may be a new URL 👀)
- https://glitch.com/edit/ (2 times) (Note! This may be a new URL 👀)
- https://topics-demo.glitch.me/ (1 time) (Note! This may be a new URL 👀)
- https://topics-fetch-demo.glitch.me/ (1 time) (Note! This may be a new URL 👀)
- https://www.chromium.org/developers/how-tos/run-chromium-with-flags/ (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/API/HTMLIFrameElement/browsingTopics
Title: HTMLIFrameElement: browsingTopics property
- https://patcg-individual-drafts.github.io/topics/ (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/HTTP/Headers/Permissions-Policy/browsing-topics
Title: Permissions-Policy: browsing-topics
- https://patcg-individual-drafts.github.io/topics/ (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/HTTP/Headers/Observe-Browsing-Topics
Title: Observe-Browsing-Topics
- https://patcg-individual-drafts.github.io/topics/ (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/HTTP/Headers/Sec-Browsing-Topics
Title: Sec-Browsing-Topics
- https://github.com/patcg-individual-drafts/topics/blob/main/taxonomy_v1.md (1 time) (Note! This may be a new URL 👀)
- https://patcg-individual-drafts.github.io/topics/ (1 time) (Note! This may be a new URL 👀)
(comment last updated: 2024-02-22 16:31:41)
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
This pull request has merge conflicts that must be resolved before it can be merged.
@wbamberg see https://github.com/mdn/content/discussions/30428 for relevant discussion about representing standards positions in this PR.
edit: the discussion is now at https://github.com/orgs/mdn/discussions/463
OK, I have reworked this content quite significantly after considering all the comments made. I'm a bit concerned that, previously I felt like I understood this API, and now I don't feel so sure, and have outstanding questions once more.
I think it might be a good approach for @samdutton to first read the new state of the main landing page and "Using..." guide, have a look at the following questions, and see if he can provide clarification and tell me where I'm now going wrong. I'll then try another rewrite to hopefully clear things up before @wbamberg reviews it again.
I am a bit concerned that this might turn into a huge megathread, in which case maybe we could set up a call to discuss this rather than going back and forth in comments?
-
In the new "Using..." guide, I've tried to explain what is going on in a high-level fashion before then talking about what technically happens separately, afterwards. In the "High-level overview" section, points 2-4, I've talked in a very hand-wavy fashion about the browser calculating topics per epoch, then choosing top topics per epoch, then choosing one top topic which is then sent to the caller when the
Looking at this again, I think it would make more sense for me to put point 4 as a subbullet under point 1, as surely this happens when the site is loaded...then explain the ongoing process of calculating user topics and top topics separately below...but again, I'm not sure if that is correct.
-
In the "How are topics returned to the caller?" section, I've tried to explain what happens when an
I'm particularly confused by how Observe-Browsing-Topics is used. I thought "observing a topic" was done on the client-side, when the
-
I've started to change the text that describes technically how this works to talk about the one chosen top topic being sent to the caller via the Sec-Browsing-Topics, rather than multiple top topics, as this is implied earlier comments on this thread ("That topic is returned to the caller"). Is this correct? If so, I'll need to change the descriptions of all the other API features to suit.
I'm also concerned about where
Document.browsingTopicsfits into this, as that is specifically defined as returning multiple topics that can then be sent to the caller in a manner of your choosing (i.e. fetch()) rather than a single topic. So why is this different? -
I've described the different features that cause the browser to observe topics and send the top topic back to the caller as features that "enable the Topics API" (see the "What API features enable the Topics API?" section). does that make sense?
I also wanted to check - you only need to use any one of these features, depending on what makes most sense for your particular codebase, right? You don't need to use a combination?
This pull request has merge conflicts that must be resolved before it can be merged.
This pull request has merge conflicts that must be resolved before it can be merged.
This pull request has merge conflicts that must be resolved before it can be merged.
Thanks all, for being so patient and thorough!
One thing we'll need to update: developer.mozilla.org/en-US/docs/Web/API/Topics_API/Using#selecting_topics_of_interest_to_influence_ad_choice
The algorithm for top topics selection used by Chrome has been updated: developers.google.com/privacy-sandbox/blog/topics-enhancements. With a little tweaking, we could pretty much use that explanation as it is.
On Fri, 23 Feb 2024 at 09:28, Chris Mills @.***> wrote:
Yay, thanks @wbamberg https://github.com/wbamberg!
— Reply to this email directly, view it on GitHub https://github.com/mdn/content/pull/30107#issuecomment-1960989382, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABSDKRK32WQK6YEPIUGHU3YVBOLNAVCNFSM6AAAAAA7CXGMRCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRQHE4DSMZYGI . You are receiving this because you were mentioned.Message ID: @.***>