Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Spec reserved.top_navigation_start and reserved.top_navigation_commit #130

Merged
merged 13 commits into from Nov 7, 2023
Merged

Spec reserved.top_navigation_start and reserved.top_navigation_commit #130

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
23e4266
start work
blu25 Oct 23, 2023
3548de2
Merge branch 'master' into liam-reserved-top-start-commit
blu25 Oct 23, 2023
1b3ee75
convert other instances to using automatic beacon data map
blu25 Oct 23, 2023
b1eb3b0
fix incorrectly called function
blu25 Oct 25, 2023
1b4fa5d
use enumerated type
blu25 Oct 26, 2023
f1a8d86
reformat automatic beacon event type
blu25 Oct 26, 2023
930670c
reword sentence
blu25 Oct 26, 2023
8a1c809
remove step
blu25 Oct 26, 2023
08d991d
unexport automatic beacon dfns
blu25 Oct 27, 2023
e9842fc
Merge branch 'master' into liam-reserved-top-start-commit
blu25 Oct 31, 2023
9005860
address comments and re-add top_navigation
blu25 Nov 1, 2023
a19087b
add WPT
blu25 Nov 3, 2023
e922439
reword
blu25 Nov 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
138 changes: 96 additions & 42 deletions spec.bs
View file
Open in desktop
Expand Up @@ -761,25 +761,40 @@ following [=struct/items=]:
:: a [=boolean=], initially false
</dl>

An <dfn for=fencedframetype>automatic beacon event type</dfn> is either "<dfn
for="automatic beacon event type">`reserved.top_navigation_start`</dfn>", "<dfn
for="automatic beacon event type">`reserved.top_navigation_commit`</dfn>", or "<dfn
for="automatic beacon event type">`reserved.top_navigation`</dfn>".

Advisement: <code>[=automatic beacon event type/reserved.top_navigation=]</code> is an earlier
naming of <code>[=automatic beacon event type/reserved.top_navigation_commit=]</code>. While they
both do the same thing, <code>[=automatic beacon event type/reserved.top_navigation=]</code> will be
removed in the future and should not be used for new code.

An <dfn for=fencedframetype>automatic beacon data</dfn> is a [=struct=] with the following
[=struct/items=]:

<dl dfn-for="automatic beacon data">
: <dfn>eventData</dfn>
:: a [=string=]

: <dfn>destination</dfn>
:: a [=list=] of {{FenceReportingDestination}}s

: <dfn>once</dfn>
:: a [=boolean=]
</dl>

A <dfn export for=fencedframetype>fenced frame reporter</dfn> is a [=struct=] with the following
[=struct/items=]:
<dl export dfn-for="fenced frame reporter">
: <dfn>fenced frame reporting metadata reference</dfn>
:: a mutable reference to a [=fencedframetype/fenced frame reporting metadata=]
<span class=XXX>TODO: Handle pointers/references in a more spec-y way</span>

: <dfn>automatic beacon data</dfn>
:: null, or a [=struct=] with the following [=struct/items=]:
<dl dfn-for="automatic beacon data">
: <dfn>eventData</dfn>
:: a [=string=]

: <dfn>destination</dfn>
:: a [=list=] of {{FenceReportingDestination}}s

: <dfn>once</dfn>
:: a [=boolean=]
</dl>
: <dfn>automatic beacon data map</dfn>
:: a [=map=] whose [=map/keys=] are [=fencedframetype/automatic beacon event type=]s and whose
[=map/values=] are null or an [=fencedframetype/automatic beacon data=]
</dl>

A <dfn for=fencedframetype>destination enum event</dfn> is a [=struct=] with the following
Expand All @@ -800,8 +815,25 @@ A <dfn for=fencedframetype>destination enum event</dfn> is a [=struct=] with the

A <dfn for=fencedframetype>destination URL event</dfn> is a [=URL=].

An <dfn for=fencedframetype>automatic beacon event</dfn> is a [=struct=] with the following
[=struct/items=]:
<dl dfn-for="automatic beacon event">
: <dfn>type</dfn>
:: an [=fencedframetype/automatic beacon event type=]

: <dfn>data</dfn>
:: a [=string=]

: <dfn>attributionReportingEnabled</dfn>
:: a [=boolean=]

: <dfn>attributionReportingContextOrigin</dfn>
:: an [=origin=]
</dl>

A <dfn for=fencedframetype>destination event</dfn> is either a
[=fencedframetype/destination enum event=] or a [=fencedframetype/destination URL event=].
[=fencedframetype/destination enum event=], a [=fencedframetype/destination URL event=], or a
[=fencedframetype/automatic beacon event=].

<div algorithm>
In order to <dfn>send a beacon</dfn> with a [=fencedframetype/reporting destination info=]
Expand All @@ -815,12 +847,14 @@ A <dfn for=fencedframetype>destination event</dfn> is either a

1. Let |useParallelQueue| be false.

1. If |event| is a [=fencedframetype/destination enum event=], then:
1. If |event| is either a [=fencedframetype/destination enum event=] or an
[=fencedframetype/automatic beacon event=], then:

1. Let |destination map| be |destination info|'s
[=reporting destination info/reporting url map=].

1. Let |eventType| be |event|'s [=destination enum event/type=].
1. Let |eventType| be either |event|'s [=destination enum event/type|destination type=], or
[=automatic beacon event/type|automatic type=], depending on which variant |event| is.

1. If |destination map|[|eventType|] does not [=map/exist=], return.

Expand All @@ -830,8 +864,9 @@ A <dfn for=fencedframetype>destination event</dfn> is either a
of [=getting supported registrars=] is not [=list/is empty|empty=] and |event|'s
[=destination enum event/attributionReportingContextOrigin=] [=check if an origin is suitable|is suitable=]:

1. If |event|'s [=destination enum event/type=] is `"reserved.top_navigation"`,
set |attributionReportingEligibility| to "<code>[=eligibility/navigation-source=]</code>".
1. If |event|'s {{FenceEvent/eventType}} matches one of the [=fencedframetype/automatic
beacon event type=] values, set |attributionReportingEligibility| to
"<code>[=eligibility/navigation-source=]</code>".

1. Otherwise, set |attributionReportingEligibility| to "<code>[=eligibility/event-source=]</code>".

Expand Down Expand Up @@ -1176,8 +1211,8 @@ A <dfn export>fenced frame config instance</dfn> is a [=struct=] with the follow
:: a reference to |config|'s [=fenced frame config/fenced frame reporting metadata=]'s
[=fenced frame reporting metadata/value=]

: [=fenced frame reporter/automatic beacon data=]
:: null
: [=fenced frame reporter/automatic beacon data map=]
:: an empty [=map=]

: [=fenced frame config instance/exfiltration budget metadata reference=]
::
Expand Down Expand Up @@ -1530,7 +1565,8 @@ Several APIs specific to fenced frames are defined on the {{Fence}} interface.
{{FenceEvent/eventType}}:
1. [=exception/Throw=] a {{TypeError}}.

1. If |event|'s {{FenceEvent/eventType}} is not `"reserved.top_navigation"`, return.
1. If |event|'s {{FenceEvent/eventType}} does not match one of the [=fencedframetype/automatic
beacon event type=] values, return.

1. Let |instance| be [=this=]'s [=relevant global object=]'s [=Window/browsing context=]'s
[=browsing context/fenced frame config instance=].
Expand All @@ -1544,7 +1580,8 @@ Several APIs specific to fenced frames are defined on the {{Fence}} interface.
1. If |instance|'s [=fenced frame config instance/fenced frame reporter=] is null, then return.

1. Set |instance|'s [=fenced frame config instance/fenced frame reporter=]'s [=fenced frame
reporter/automatic beacon data=] to a [=struct=] with the following [=struct/items=]:
reporter/automatic beacon data map=][|event|'s {{FenceEvent/eventType}}] to an
[=fencedframetype/automatic beacon data=] with the following [=struct/items=]:

: [=automatic beacon data/eventData=]
:: |event|'s {{FenceEvent/eventData}} if defined, otherwise empty string
Expand Down Expand Up @@ -1658,17 +1695,17 @@ table](https://fetch.spec.whatwg.org/#destination-table) to illustrate that <{fe
A side effect of the fenced boundary model is that ads will lose the ability to know if a click
resulted in a successful navigation. This is because the page loaded from a top-level [=navigate|
navigation=] originating from a fenced frame will not be allowed to report to the fenced frame that
it loaded (through something like <code>window.[=Window/opener=]</code>). Instead, we introduce a
special event-level [=destination enum event/type|reporting type=], `reserved.top_navigation`, which
automatically sends an [=report an event|event-level beacon=] when a fenced frame initiates a
successful [=navigate|navigation=] to a [=top-level traversable=].
it loaded (through something like <code>window.[=Window/opener=]</code>). Instead, we introduce
special event-level [=automatic beacon event/type|reporting type=]s, <code>[=automatic beacon event
type/reserved.top_navigation_start=]</code> and <code>[=automatic beacon event
type/reserved.top_navigation_commit=]</code>, which automatically sends an [=report an
event|event-level beacon=] when a fenced frame initiates a successful [=navigate|navigation=] to a
[=top-level traversable=].

<div algorithm>
To <dfn>attempt to send an automatic beacon</dfn> given a [=source snapshot params=]
|sourceSnapshotParams|, an [=origin=] |sourceOrigin|, a {{Document}} |targetDocument|, and a
[=string=] |eventType|, run these steps:

1. [=Assert=]: |eventType| is "`reserved.top_navigation`".
|sourceSnapshotParams|, an [=origin=] |sourceOrigin|, a {{Document}} |targetDocument|, and an
[=fencedframetype/automatic beacon event type=] |eventType|, run these steps:

1. If |targetDocument|'s [=node navigable=]'s [=traversable navigable=] is not a [=top-level
traversable=], abort these steps.
Expand All @@ -1686,7 +1723,7 @@ successful [=navigate|navigation=] to a [=top-level traversable=].
<{fencedframe}>.

1. Let |beacon data| be |config|'s [=fenced frame config instance/fenced frame reporter=]'s
[=fenced frame reporter/automatic beacon data=].
[=fenced frame reporter/automatic beacon data map=][|eventType|].

1. If |beacon data| is null, abort these steps.

Expand All @@ -1698,27 +1735,28 @@ successful [=navigate|navigation=] to a [=top-level traversable=].
[=fencedframetype/fenced frame reporting map=]'s [=map/keys=]:

1. Run [=report an event=] using |config|'s [=fenced frame config instance/fenced frame
reporter=] with |destination| and a [=fencedframetype/destination enum event=] with the
reporter=] with |destination| and an [=fencedframetype/automatic beacon event=] with the
following [=struct/items=]:

: [=destination enum event/type=]
: [=automatic beacon event/type=]
:: |eventType|

: [=destination enum event/data=]
: [=automatic beacon event/data=]
:: |beacon data|'s [=automatic beacon data/eventData=] if |beacon data|'s [=automatic beacon
data/destinations=] [=list/contains=] |destination|, the empty string otherwise.

: [=destination enum event/attributionReportingEnabled=]
: [=automatic beacon event/attributionReportingEnabled=]
:: |sourceSnapshotParams|'s [=source snapshot params/attribution reporting enabled=]

: [=destination enum event/attributionReportingContextOrigin=]
: [=automatic beacon event/attributionReportingContextOrigin=]
:: |sourceSnapshotParams|'s [=source snapshot params/attribution reporting context origin=]

1. If |beacon data|'s [=automatic beacon data/once=] is true, set |config|'s [=fenced frame
config instance/fenced frame reporter=]'s [=fenced frame reporter/automatic beacon data=] to
null.
config instance/fenced frame reporter=]'s [=fenced frame reporter/automatic beacon data
map=][|eventType|] to null.

<wpt>
/fenced-frame/automatic-beacon-anchor-click-handler.https.html
/fenced-frame/automatic-beacon-click-handler.https.html
/fenced-frame/automatic-beacon-two-events-clear.https.html
/fenced-frame/automatic-beacon-two-events-persist.https.html
Expand All @@ -1728,13 +1766,29 @@ successful [=navigate|navigation=] to a [=top-level traversable=].
</wpt>
</div>

<div algorithm="automatic beacon patch">
<div algorithm="top_navigation_start beacon patch">
Modify [[HTML]]'s [=navigate=] algorithm. Add a new step after step 4 that reads:

5. [=Attempt to send an automatic beacon=] given <var ignore>sourceSnapshotParams</var>, <var
ignore>initiatorOriginSnapshot</var>, <var ignore>navigable</var>’s associated {{Document}},
and <code>[=automatic beacon event type/reserved.top_navigation_start=]</code>.
</div>

<div algorithm="top_navigation_commit beacon patch">
Modify [[HTML]]'s [=attempt to populate the history entry's document=] algorithm. In step 6,
substep 11, add a new step after step 5 that reads:

6. if <var ignore>failure</var> is false, then [=attempt to send an automatic beacon=] given <var
ignore>sourceSnapshotParams</var>, <var ignore>entry</var>'s [=document state=]'s [=document
state/initiator origin=], <var ignore>document</var>, and "`reserved.top_navigation`".
6. If <var ignore>failure</var> is false, then:

1. [=Attempt to send an automatic beacon=] given <var
ignore>sourceSnapshotParams</var>, <var ignore>entry</var>'s [=document state=]'s [=document
state/initiator origin=], <var ignore>document</var>, and <code>[=automatic beacon event
type/reserved.top_navigation_commit=]</code>.

1. [=Attempt to send an automatic beacon=] given <var
ignore>sourceSnapshotParams</var>, <var ignore>entry</var>'s [=document state=]'s [=document
state/initiator origin=], <var ignore>document</var>, and <code>[=automatic beacon event
type/reserved.top_navigation=]</code>.
</div>

<h2 id=html-integration>HTML Integration</h2>
Expand Down Expand Up @@ -2394,7 +2448,7 @@ CORP violation report=] algorithm, as leaving it unfenced may cause a privacy le
Note: The [=source snapshot params/initiator fenced frame config instance=] is the [=fenced frame
config instance=] that's loaded into a navigation initiator's [=browsing context=], if any exists.
It is used by the [=attempt to send an automatic beacon=] algorithm to retrieve the [=fenced frame
reporter/automatic beacon data=] to be sent out if the <{fencedframe}>-initiated navigation
reporter/automatic beacon data map=] to be sent out if the <{fencedframe}>-initiated navigation
succeeds. The [=source snapshot params/target fenced frame config=] on the other hand, is the
non-[=instantiate a config|instantiated=] [=fenced frame config=] that will be loaded into a a
<{fencedframe}> element for navigations targeting fenced frames. These fields do not interact
Expand Down