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

Initial detail of HTTP API #56

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Initial detail of HTTP API #56

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
932a8fb
Initial detail of HTTP API
andyleiserson Dec 13, 2024
bab0f95
Revert optional filterData
andyleiserson Dec 16, 2024
5a342e1
Correct syntax of Save-Impression header; add detail
andyleiserson Dec 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 33 additions & 3 deletions api.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -385,6 +385,10 @@ it may be useful to examine the supported
<a attribute for=PrivateAttribution>aggregationServices</a> in deciding
whether to use the Private Attribution API.

It is also possible to register an impression by including the
[:Save-Impression:]
header in the HTTP response when serving a resource to the user agent.

To request a conversion report, a site calls
<a method for=PrivateAttribution>measureConversion()</a>.
Before calling this API, a site must
Expand Down Expand Up @@ -463,7 +467,7 @@ navigator.privateAttribution.saveImpression({
<xmp class=idl>
dictionary PrivateAttributionImpressionOptions {
required unsigned long histogramIndex;
required unsigned long filterData;
unsigned long filterData;
andyleiserson marked this conversation as resolved.
Show resolved Hide resolved
required DOMString conversionSite;
unsigned long lifetimeDays;
};
Expand Down Expand Up @@ -624,8 +628,13 @@ The arguments to <a method for=PrivateAttribution>measureConversion()</a> are as
<dt><dfn>intermediarySites</dfn></dt>
<dd>
A list of sites which called the <a method for=PrivateAttribution>saveImpression()</a> API.
Only [=impressions=] recorded by scripts originating from one of the intermediary sites
are eligible to match this [=conversion=].
[=Impressions=] are only eligible to match this [=conversion=] if either:
1. they were registered by a call to <a method for=PrivateAttribution>saveImpression()</a>
in a script originating from one of the intermediary sites, or
2. they were registered by a [:Save-Impression:] header associated with a resource
from one of the intermediary sites.
<!-- TODO: HTTP registration should also apply to impression sites.
-- Interaction between impression and intermediary sites needs to be clarified (#55). -->
</dd>
</dl>

Expand Down Expand Up @@ -855,6 +864,21 @@ if the user has opted out of collection of diagnostic data.
* User ability to view the impression store and past report submissions.


# HTTP API # {#http-api}

\`<dfn http-header><code>Save-Impression</code></dfn>\` is a
[=structured header/dictionary|Dictionary Structured Header=]
set on a response requesting that the user agent invoke the
<a method for=PrivateAttribution>saveImpression()</a> API.

<pre class=example id=ex-save-impression-header>
Save-Impression: conversionSite=advertiser.example;histogramIndex=2;\
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it intentional that this is a single-key dictionary (conversionSite) with parameters for histogramIndex, filterData, and lifetimeDays?

Not suggesting it's wrong, but just making sure the intention wasn't for each of those last three to themselves be a top-level key, in which case the ; separator should be replaced with a space. Making them top-level keys is arguably more flexible, as they can themselves gain parameters over time, but it depends on what future changes, if any, we want this header to support. It's unclear to me if there's a benefit to making this a dictionary (rather than a single item) if there will only ever be one top-level key.

Related, would it make sense to allow multiple impressions to be registered in a single HTTP response? If so, maybe this should be a top-level list instead.

Finally, per https://httpwg.org/specs/rfc9651#rfc.section.3.2:

Member keys cannot contain uppercase characters.

So these might be more conventionally spelled like conversion-site. This also applies to parameters.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @apasel422 for reviewing. I've tentatively changed it to commas (i.e. a top-level dictionary) so the definition is at least valid, but depending on the multiple impressions question and the necessary filterData expressiveness, we might want something else. I also added the multiple impressions question as a topic for the meeting.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A top-level dictionary means that we will only permit a single impression to be saved. It is possible to add some structure to parameters like list=(this is a list of seven items) but the syntax is a bit unnatural, but it might be that those limitations will encourage good design... or at least creative design.

filterData=12;lifetimeDays=7
</pre>

TODO need to specify in more detail when and how this header is interpreted


# Implementation Considerations # {#implementation-considerations}

* Management and distribution of values for the following:
Expand Down Expand Up @@ -1475,6 +1499,12 @@ The privacy architecture is courtesy of the authors of [[PPA-DP]].
spec:html; type:dfn; text:site
spec:infra; type:dfn; text:user agent
</pre>
<pre class=anchors>
spec:structured header; type:dfn; urlPrefix: https://httpwg.org/specs/rfc9651;
text: structured header; url: #name-introduction
for: structured header
text: dictionary; url: #dictionary
</pre>
<pre class=biblio>
{
"coppacalypse": {
Expand Down
Loading