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 all commits
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
69 changes: 67 additions & 2 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 @@ -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,52 @@ 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: conversion-site=advertiser.example, histogram-index=2, \
filter-data=12, lifetime-days=7
</pre>

The following keys are defined, corresponding to the members of
the {{PrivateAttributionImpressionOptions}} dictionary passed to
<a method for=PrivateAttribution>saveImpression()</a>.

<dl dfn-for=save-impression>
<dt><code>conversion-site</code></dt>
<dd>
Value of <a dict-member for=PrivateAttributionImpressionOptions>conversionSite</a>,
a [=structured header/string=]. This key is required,
and must be a valid domain name.
</dd>
<dt><code>histogram-index</code></dt>
<dd>
Value of <a dict-member for=PrivateAttributionImpressionOptions>histogramIndex</a>,
an [=structured header/integer=]. This key is required.
</dd>
<dt><code>filter-data</code></dt>
<dd>
Value of <a dict-member for=PrivateAttributionImpressionOptions>filterData</a>.
Implementations parsing the header must accept any valid
[=structured header/item=] or [=structured header/inner list=].
If the filter data is not understood, no impression is saved.
Comment on lines +898 to +900
Copy link

Choose a reason for hiding this comment

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

Are these sentences in conflict?

And what are the implications of the first sentence for how filter-data matching works?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Yeah, it doesn't make a lot of sense as written. I was trying to allow for extensibility of the filter data in the future, but not saving an impression sounds a lot like rejecting the filter data.

This key is optional.
</dd>
<dt><code>lifetime-days</code></dt>
<dd>
Value of <a dict-member for=PrivateAttributionImpressionOptions>lifetimeDays</a>,
an [=structured header/integer=]. This key is optional.
</dd>
</dl>

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 +1530,16 @@ 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
text: string; url: #string
text: integer; url: #integer
text: item; url: #item
text: inner list; url: #inner-list
</pre>
<pre class=biblio>
{
"coppacalypse": {
Expand Down
Loading