Initial detail of HTTP API #56
Conversation
api.bs
Outdated
| <a method for=PrivateAttribution>saveImpression()</a> API. | ||
|
|
||
| <pre class=example id=ex-save-impression-header> | ||
| Save-Impression: conversionSite=advertiser.example;histogramIndex=2;\ |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
api.bs
Outdated
| 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. |
There was a problem hiding this comment.
Are these sentences in conflict?
And what are the implications of the first sentence for how filter-data matching works?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I think that we can probably constrain the filter data in both the API and here to avoid the need to allow for problems. There's a future-proofing argument to be had, but perhaps the way to deal with that is that we add a new dictionary memory (API) or key (HTTP) if we want to change what can be stored with an impression. Right now, filterData is an unsigned long, so maybe the answer is to define this as an integer, which is set to zero if the key is absent or the key contains a value that does not fit into the value space of unsigned long.
There was a problem hiding this comment.
+1 to making this an integer for now (we can always accept other types backwards-compatibly in the future), but it's unclear to me if the absence of the field should mean "match any filter data value" or if, as you say, it should be set to 0, which would make it match only 0.
CC #57.
api.bs
Outdated
| <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. |
There was a problem hiding this comment.
I'm not sure that domain name is precise enough here, based on https://w3c.github.io/ppa/#conversion-site. We might want to say site instead.
| set on a response requesting that the user agent invoke the | ||
| <a method for=PrivateAttribution>saveImpression()</a> API. |
There was a problem hiding this comment.
Somewhat related to #106 (comment), do we need to check that the site in Step 2.1 of https://w3c.github.io/ppa/#save-impression-api-operation is using https:// as its scheme? The JS methods are already marked [SecureContext], but if we need to enforce the use of HTTPS then we should probably check that in the core save impression and measure conversion algorithms for consistency.
| <dt><code>conversion-site</code></dt> | ||
| <dd> | ||
| Value of <a dict-member for=PrivateAttributionImpressionOptions>conversionSite</a>, | ||
| a [=structured header/string=]. This key is required. |
There was a problem hiding this comment.
This is listed as a string, but the example above is encoded as a token. (Note the lack of surrounding ".)
@martinthomson Do you think we should bother with string here, or even support both?
There was a problem hiding this comment.
Yeah, I think that we can probably support tokens, but the question is whether we would want to. We're going to have to deal with IDNA. Punycode-encoded IDNA will work as a token. The only reason to stick with just string is to avoid the unnecessary flexibility.
We should be very careful when specifying this, so I would say that we're not done either way. We need to be very clear that this is punycode-encoded only and that it is not valid to include Unicode, even using the percent-encoded display string type.
Co-authored-by: Andrew Paseltiner <[email protected]>
Preview | Diff