Technical Review: Add documentation for Fenced Frames #27781

chrisdavidmills · 2023-07-05T18:23:48Z

Note: This technical review is now completed and approved. For the follow-on editorial review, see #30874

Description

Fenced frames are 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 <fencedframe> element and the APIs that underpin it.

See my research document for more details of exactly what changes are expected in the PR.

Motivation

Additional details

Related issues and pull requests

github-actions · 2023-07-05T18:26:11Z

Preview URLs (29 pages)

Flaws (28)

Note! 12 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/HTTP/Headers/Content-Security-Policy/fenced-frame-src
Title: CSP: fenced-frame-src
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: http.headers.Content-Security-Policy.fenced-frame-src

URL: /en-US/docs/Web/HTML/Element/fencedframe
Title: <fencedframe>: The Fenced Frame element
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: html.elements.fencedframe

URL: /en-US/docs/Web/API/FencedFrameConfig
Title: FencedFrameConfig
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.FencedFrameConfig

URL: /en-US/docs/Web/API/FencedFrameConfig/setSharedStorageContext
Title: FencedFrameConfig: setSharedStorageContext() method
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.FencedFrameConfig.setSharedStorageContext

URL: /en-US/docs/Web/API/HTMLFencedFrameElement
Title: HTMLFencedFrameElement
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.HTMLFencedFrameElement

URL: /en-US/docs/Web/API/HTMLFencedFrameElement/width
Title: HTMLFencedFrameElement: width property
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.HTMLFencedFrameElement.width

URL: /en-US/docs/Web/API/HTMLFencedFrameElement/config
Title: HTMLFencedFrameElement: config property
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.HTMLFencedFrameElement.config

URL: /en-US/docs/Web/API/HTMLFencedFrameElement/allow
Title: HTMLFencedFrameElement: allow property
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.HTMLFencedFrameElement.allow

URL: /en-US/docs/Web/API/HTMLFencedFrameElement/height
Title: HTMLFencedFrameElement: height property
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.HTMLFencedFrameElement.height

URL: /en-US/docs/Web/API/Window/fence
Title: Window: fence property
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.Window.fence

URL: /en-US/docs/Web/API/Navigator
Title: Navigator
Flaw count: 1

macros:
- /en-US/docs/Web/API/Navigator/standalone does not exist

URL: /en-US/docs/Web/API/Navigator/deprecatedReplaceInURN
Title: Navigator: deprecatedReplaceInURN() method
Flaw count: 1

bad_bcd_queries:
- No BCD data for query: api.Navigator.deprecatedReplaceInURN

URL: /en-US/docs/Web/API/Fenced_frame_API
Title: Fenced Frame API
Flaw count: 3

macros:
- /en-US/docs/Web/API/Navigator/runAdAuction does not exist
broken_links:
- Can't resolve /en-US/docs/Web/Privacy/Privacy_sandbox/Enrollment
bad_bcd_queries:
- No BCD data for query: html.elements.fencedframe

URL: /en-US/docs/Web/API/Fence
Title: Fence
Flaw count: 3

macros:
- /en-US/docs/Web/API/InterestGroupReportingScriptRunnerGlobalScope/registerAdBeacon does not exist
- /en-US/docs/Web/API/InterestGroupReportingScriptRunnerGlobalScope/registerAdBeacon does not exist
bad_bcd_queries:
- No BCD data for query: api.Fence

URL: /en-US/docs/Web/API/Fence/setReportEventDataForAutomaticBeacons
Title: Fence: setReportEventDataForAutomaticBeacons() method
Flaw count: 3

macros:
- /en-US/docs/Web/API/InterestGroupReportingScriptRunnerGlobalScope/registerAdBeacon does not exist
- /en-US/docs/Web/API/InterestGroupReportingScriptRunnerGlobalScope/registerAdBeacon does not exist
bad_bcd_queries:
- No BCD data for query: api.Fence.setReportEventDataForAutomaticBeacons

URL: /en-US/docs/Web/API/Fence/getNestedConfigs
Title: Fence: getNestedConfigs() method
Flaw count: 2

broken_links:
- Can't resolve /docs/Web/API/Shared_Storage_API
bad_bcd_queries:
- No BCD data for query: api.Fence.getNestedConfigs

URL: /en-US/docs/Web/API/Fence/reportEvent
Title: Fence: reportEvent() method
Flaw count: 5

macros:
- /en-US/docs/Web/API/InterestGroupReportingScriptRunnerGlobalScope/registerAdBeacon does not exist
- /en-US/docs/Web/API/InterestGroupReportingScriptRunnerGlobalScope/registerAdBeacon does not exist
- /en-US/docs/Web/API/InterestGroupReportingScriptRunnerGlobalScope/registerAdBeacon does not exist
- /en-US/docs/Web/API/PrivateAggregation/contributeToHistogramOnEvent does not exist
bad_bcd_queries:
- No BCD data for query: api.Fence.reportEvent

External URLs (55)

URL: /en-US/docs/Web/HTML/Element/fencedframe
Title: <fencedframe>: The Fenced Frame element

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (2 times) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/shared-storage/ (1 time) (Note! This may be a new URL 👀)
https://www.w3.org/TR/html-aria/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/FencedFrameConfig
Title: FencedFrameConfig

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (3 times) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/private-aggregation/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/shared-storage/ (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/FencedFrameConfig/setSharedStorageContext
Title: FencedFrameConfig: setSharedStorageContext() method

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/private-aggregation/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/shared-storage/ (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/HTMLFencedFrameElement
Title: HTMLFencedFrameElement

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (2 times) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/shared-storage/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/HTMLFencedFrameElement/width
Title: HTMLFencedFrameElement: width property

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/HTMLFencedFrameElement/config
Title: HTMLFencedFrameElement: config property

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (2 times) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/shared-storage/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/HTMLFencedFrameElement/allow
Title: HTMLFencedFrameElement: allow property

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/HTMLFencedFrameElement/height
Title: HTMLFencedFrameElement: height property

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Window/fence
Title: Window: fence property

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Navigator/deprecatedReplaceInURN
Title: Navigator: deprecatedReplaceInURN() method

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Fenced_frame_API
Title: Fenced Frame API

https://developer.chrome.com/docs/privacy-sandbox/ (2 times) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (4 times) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/private-aggregation/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/shared-storage/ (3 times) (Note! This may be a new URL 👀)
https://protected-audience-demo-advertiser.web.app/ (1 time) (Note! This may be a new URL 👀)
https://shared-storage-demo.web.app/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Fenced_frame_API/Communication_with_embedded_frames
Title: Communication with embeded frames

https://developer.chrome.com/en/docs/privacy-sandbox/fledge/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Fence
Title: Fence

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Fence/setReportEventDataForAutomaticBeacons
Title: Fence: setReportEventDataForAutomaticBeacons() method

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/shared-storage/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Fence/getNestedConfigs
Title: Fence: getNestedConfigs() method

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/protected-audience/ (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Fence/reportEvent
Title: Fence: reportEvent() method

https://developer.chrome.com/docs/privacy-sandbox/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fenced-frame/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/fledge/ (1 time) (Note! This may be a new URL 👀)
https://developer.chrome.com/docs/privacy-sandbox/shared-storage/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2023-12-08 15:33:21)

bsmth · 2023-07-12T12:01:58Z

Thanks @chrisdavidmills - do you want me to have a look already or should I wait until it's out of draft status?

chrisdavidmills · 2023-07-12T12:04:53Z

Thanks @chrisdavidmills - do you want me to have a look already or should I wait until it's out of draft status?

It'd be better to wait until it is a) out of draft status, and b) I've got the Google eng folk to have a look at it, as there are still a fait few details here that I'm not sure about. I'll let you know. Cheers!

domfarolino · 2023-09-11T10:12:41Z

I was pinged to take a look at this from Google's perspective, and I'm wondering if you could update the compiled documentation links above (in #27781 (comment)), since they seem outdated now?

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

files/en-us/web/api/htmlfencedframeelement/allow/index.md

files/en-us/web/api/htmlfencedframeelement/height/index.md

files/en-us/web/api/htmlfencedframeelement/width/index.md

files/en-us/web/api/window/fence/index.md

files/en-us/web/html/element/a/index.md

files/en-us/web/http/permissions_policy/index.md

files/en-us/web/html/element/form/index.md

files/en-us/web/html/element/fencedframe/index.md

gtanzer

Sorry for the delay. Left a new round of comments. Home stretch!

chrisdavidmills · 2023-12-06T09:39:05Z

Thanks for the super-helpful comments @gtanzer; updated, and back to you.

gtanzer · 2023-12-08T03:53:03Z

files/en-us/web/api/fence/getnestedconfigs/index.md

+
+```js
+const configs = window.fence.getNestedConfigs();
+console.log(configs.length);


it might make more sense as an example here to have a different fenced frame, and then do fencedframe.config = configs[0] or something.

Done. I've replaced it with something slightly more substantial.

gtanzer · 2023-12-08T04:46:17Z

@chrisdavidmills Changes lgtm. I don't see an option to resolve each, maybe because I'm not technically a reviewer.

chrisdavidmills · 2023-12-08T08:54:18Z

Thanks a lot @gtanzer. I have gone through and resolved all the comments that sound like a done deal. There are four left that I think still need input from you:

Technical Review: Add documentation for Fenced Frames #27781 (comment) - is this OK?
Technical Review: Add documentation for Fenced Frames #27781 (comment) - I could still really do with a final clarification on this; it affects both the docs and the compat data
Technical Review: Add documentation for Fenced Frames #27781 (comment) and Technical Review: Add documentation for Fenced Frames #27781 (comment) - I feel like these deserve extra scrutiny

gtanzer · 2023-12-08T14:55:25Z

@chrisdavidmills Responded, thanks for surfacing them

chrisdavidmills · 2023-12-08T15:33:42Z

OK @gtanzer, just to let you know, next stage is to get this PR editorial reviewed. I'll close this PR and open up a new one based on the same branch to contain the editorial review.

Add documentation for Fenced Frames

9d4878e

chrisdavidmills requested review from a team as code owners July 5, 2023 18:23

chrisdavidmills requested review from wbamberg and bsmth and removed request for a team July 5, 2023 18:23

chrisdavidmills marked this pull request as draft July 5, 2023 18:23

github-actions bot added the Content:WebAPI Web API docs label Jul 5, 2023

More progress made on fenced frames

5ddb21b

github-actions bot added Content:HTML Hypertext Markup Language docs Content:HTTP HTTP docs labels Jul 10, 2023

chrisdavidmills added 3 commits July 10, 2023 21:56

remove editorial notes

dc959ce

Add first draft for FencedFrameConfig

66c02f9

Merge branch 'main' into fenced-frames

13d4f16

chrisdavidmills added 2 commits July 12, 2023 17:34

finalize first draft of fenced frame

7da4ab6

Merge branch 'main' into fenced-frames

ffb765b

chrisdavidmills marked this pull request as ready for review July 24, 2023 08:15

chrisdavidmills requested review from a team as code owners July 24, 2023 08:15

chrisdavidmills requested review from teoli2003 and estelle and removed request for a team July 24, 2023 08:15

chrisdavidmills added 2 commits July 25, 2023 08:56

add communication with frames guide

31570cc

Merge branch 'main' into fenced-frames

efac47f