Define structure of JSON used for conversion reports

[johnwilander]

We should agree on the structure of the attribution requests including the .well-known location. Maybe the data should be sent as an HTTP POST body instead of as URL path or query parameters?

[johnwilander]

Ping @michaelkleber @csharrison.

[csharrison]

HTTP POST body sounds reasonable to me, and encoding the data as JSON could lead to better integration with the Reporting API if we wanted to in the future.

I don't have a strong opinion on the .well-known, but it might be interesting to consider a directory structure like:
.well-known/conversions/report

To provide more flexibility if we wanted to add more endpoints, or split registration / reporting into two separate endpoints.

[johnwilander]

The word click in PCM's current well-known location was deliberate since we foresee attempts to also address view through attribution in the future. That piece of information could of course go into the JSON too, as some kind of attribution type field.

[johnwilander]

@csharrison Let's converge on something.

1. Have you settled on a JSON structure? Otherwise I'll propose one.
2. Are we settled on an HTTP POST with a JSON body? Any special considerations there? Headers that should be there or not be there?
3. I'm considering blocking redirects for the report request. OK with you?
4. Are you going with .well-known/conversions/report?
5. We should have versioning in the report so that we can move forward as the feature is enhanced or expanded. We will also need to be able to progress underlying crypto for fraud prevention. Do you think the term "version" is right? Some specs use "level" but that doesn't sit right with me here.

[csharrison]

Happy to!

1. We don't have a JSON structure right now but I was imagining something aligned with our URL structure defined here:
   https://github.com/WICG/conversion-measurement-api#conversion-reports. That is, it would look like

{
  impression-data: <int>,
  conversion-data: <int>,
  attribution-credit: <int>
}

However we are also exploring changing the names here (I tagged you here for thoughts), so the underlying report may look like:

{
  attribution-id: <int>,
  attribution-trigger-data: <int>,
  attribution-credit: <int>
}

I would appreciate your thoughts on the naming since I think that could be another point of alignment. I would also be fine removing the advertiser from the Referer header and adding a new field to the JSON representing where the conversion took place. With our new proposed naming scheme this could be called attribute-on.

2. I think HTTP POST with a JSON body sounds reasonable to me.

3. Can you elaborate on the reasoning for blocking redirects? I don't see a strong reason to disallow if the request does not come with any credentials.

4. See the naming issue I linked above. We have a number of possible ideas but I think my favorite is .well-known/report-attribution, a directory structure could also be used here like .well-known/attribution/report.

5. Version sounds fine, although I think we might want more descriptive metadata about the report too e.g. potentially separate metadata fields that describe the noise amounts or a crypto-specific version. I called out potentially adding a new field to the report that discusses noise level in our TAG issue.

{
  attribution-id: <int>,
  attribution-trigger-data: <int>,
  attribution-trigger-data-noise: .05
  attribution-credit: <int>
}

If you want to continue discussions related to names in general, maybe we could move that discussion to the open issue in our repo and we can discuss the other issues here.
@johnivdel for thoughts as well.

[darobin]

Is there a reason to expect that adding a version label would work here? If the endpoint halts and catches fire then deploying a new version will break the web; if the endpoint can on the contrary ignore the version then it won't achieve anything. Or am I missing something in the underlying expectations?

Tiny bikeshedding nitpick: if we could have names that can be read from without quoting that'd be great!

[johnwilander]

Happy to!

1. We don't have a JSON structure right now but I was imagining something aligned with our URL structure defined here:
   https://github.com/WICG/conversion-measurement-api#conversion-reports. That is, it would look like

{
  impression-data: <int>,
  conversion-data: <int>,
  attribution-credit: <int>
}

However we are also exploring changing the names here (I tagged you here for thoughts), so the underlying report may look like:

{
  attribution-id: <int>,
  attribution-trigger-data: <int>,
  attribution-credit: <int>
}

attribution-id == campaign ID?
attribution-trigger-data == conversion value?
attribution-credit == either of the websites involved? Which? It should be the registrable domain of the source or destination depending on where this report is sent, right? Or is this intended for third-parties since you will support three parties – click source, click destination, and third-party serving the ad.

We probably need to be more specific in these names if we are to use them in both features.

I would appreciate your thoughts on the naming since I think that could be another point of alignment. I would also be fine removing the advertiser from the Referer header and adding a new field to the JSON representing where the conversion took place. With our new proposed naming scheme this could be called attribute-on.

Right. I'd like to avoid a dependency on the referrer since that's such a fraught web technology anyway.

1. I think HTTP POST with a JSON body sounds reasonable to me.
2. Can you elaborate on the reasoning for blocking redirects? I don't see a strong reason to disallow if the request does not come with any credentials.

The request itself may be revealing with IP address, time of day etc and the user/vendor might want to put additional, paid-for privacy protections in place at the network layer. The browser is sending the report for the benefit of the receiving end. They should be able to get their server configuration right if they want the data.

3. See the naming issue I linked above. We have a number of possible ideas but I think my favorite is .well-known/report-attribution, a directory structure could also be used here like .well-known/attribution/report.

Do you envision further scoping, like .well-known/report-attribution/click and .well-known/report-attribution/view? Or would such details go in the JSON?

4. Version sounds fine,

One of the reasons why I want an open ended thing like version is that we might discover privacy problems down the road that will force us to make slight alterations that might not show at all in the reports. It'll be important for advertisers to know if a report was created with or without those alterations. The version field could likewise signal feature level. Imagine a vendor supporting cross-device attribution down the road. They may not want to add data to the report saying if it was the result of cross-device usage but a bump in version would at least allow advertisers to know that these reports are for users whose browser supports cross-device attribution.

although I think we might want more descriptive metadata about the report too e.g. potentially separate metadata fields that describe the noise amounts or a crypto-specific version. I called out potentially adding a new field to the report that discusses noise level in our TAG issue.

{
  attribution-id: <int>,
  attribution-trigger-data: <int>,
  attribution-trigger-data-noise: .05
  attribution-credit: <int>
}

If you want to continue discussions related to names in general, maybe we could move that discussion to the open issue in our repo and we can discuss the other issues here.
@johnivdel for thoughts as well.

[johnwilander]

Hi Robin, and thanks for joining the discussion!

Is there a reason to expect that adding a version label would work here? If the endpoint halts and catches fire then deploying a new version will break the web; if the endpoint can on the contrary ignore the version then it won't achieve anything. Or am I missing something in the underlying expectations?

See my comments on version above. Also, I don't think anything in PCM risks breaking the web. It's a very lazy, write-only feature with no signal back to websites on whether their data write operations were accepted or not, if there was a matching ad click, if a report was scheduled, or if a report was sent.

Tiny bikeshedding nitpick: if we could have names that can be read from without quoting that'd be great!

Examples? I don't understand "can be read from without quoting." 🙂

[darobin]

Hi @johnwilander! It's good to be here ;)

Regarding version: I might be missing something but you almost seem to be describing a features string? I know that the risk of breaking the (whole) web is low, but I also get worried whenever I see variants on versions, features, etc. Developers can have strong and unfounded assumptions about these, which has pretty much always gone wrong before (think doctypes, DOM supports, SVG queries, UA strings…).

Re quoting: if I understand the proposed format, the JSON would have keys matching the query string ones, so {"impression-data": 42}. Reading this from JS is unpleasant since you have to quote on access. As I said, it's a nitpick, but it feels unidiomatic from a webdev perspective.

[johnwilander]

Hi @johnwilander! It's good to be here ;)

Regarding version: I might be missing something but you almost seem to be describing a features string? I know that the risk of breaking the (whole) web is low, but I also get worried whenever I see variants on versions, features, etc. Developers can have strong and unfounded assumptions about these, which has pretty much always gone wrong before (think doctypes, DOM supports, SVG queries, UA strings…).

I would agree if developers had low or no incentive to stay up to date and browsers had a high incentive to support legacy functionality for the sake of users. But this is simple HTTP request going out to a report endpoint and the response is ignored. If the server doesn't want the report or cannot handle it, it's their choice. The browser doesn't even know if there is a server at the endpoint.

Imagine the browser sending this:

{
  attribution-report-version: 3,
  attribution-id: <int>,
  attribution-trigger-data: <int>,
  attribution-credit: <int>
}

… to https://publisher.example/.well-known/report-attribution/click and the server saying "Error: I don't understand version 3." That's a problem for publisher.example since they are no longer accepting attribution reports. Meanwhile, the browser carries on and the user sees no difference in their browsing.

Are you saying PCM should help publisher.example in some fashion? Would a feature string be better? Developers would have to parse it and we could not guarantee that changes to it would only be additive. We may be forced to remove things.

Also, changes might not be breaking in a technical sense but the interpretation of the data reported needs to change. Let's say version 3 adds noise to the conversion value. It will still be a valid conversion value and the server-side code ingesting version 2 will still work. But for the folks working with the data, something important has changed.

My thinking is that we want a simple signal telling developers that "Something has changed, go read the latest spec, and from now on, stay up to date so you don't have to get late surprises like this one."

Re quoting: if I understand the proposed format, the JSON would have keys matching the query string ones, so {"impression-data": 42}. Reading this from JS is unpleasant since you have to quote on access. As I said, it's a nitpick, but it feels unidiomatic from a webdev perspective.

Is that a specific JS concern? Note that this data is for servers so we don't know what language or platform it will be read on.

[csharrison]

attribution-id == campaign ID?

Actually that's the impression-data for us (the high entropy identifier). We would likely need another name for the low-entropy campaign ID. Maybe something like attribution-id-coarse and attribution-id-fine. Alternatively, we could use the aggregate/event-level terminology (something like what we proposed in AGGREGATE.md) and call it attribution-id-event and attribution-id-aggregate, since PCM is going for aggregate data in a sense via low-entropy IDs.

attribution-trigger-data == conversion value?
Yes. That is, the "conversion" is the event which triggers attribution.

attribution-credit == either of the websites involved? Which? It should be the registrable domain of the source or destination depending on where this report is sent, right? Or is this intended for third-parties since you will support three parties – click source, click destination, and third-party serving the ad.

Sorry no the attribution credit is another difference in our APIs (it can likely be omitted in PCM), because we send reports for the last clicked impression with credit 100 and the non-last-clicked impressions with credit 0.

The request itself may be revealing with IP address, time of day etc and the user/vendor might want to put additional, paid-for privacy protections in place at the network layer. The browser is sending the report for the benefit of the receiving end. They should be able to get their server configuration right if they want the data.

Just want to be clear here are you describing a case where the configured reporting origin does not have the capability to forward all of this sensitive data (ip, etc) anyways using server-to-server calls? I want to make sure that disallowing redirects is actually improving privacy over the base-line of s2s.

Do you envision further scoping, like .well-known/report-attribution/click and .well-known/report-attribution/view? Or would such details go in the JSON?

JSON most likely.

One of the reasons why I want an open ended thing like version is that we might discover privacy problems down the road that will force us to make slight alterations that might not show at all in the reports. It'll be important for advertisers to know if a report was created with or without those alterations. The version field could likewise signal feature level. Imagine a vendor supporting cross-device attribution down the road. They may not want to add data to the report saying if it was the result of cross-device usage but a bump in version would at least allow advertisers to know that these reports are for users whose browser supports cross-device attribution.

I see the benefit here but I also think a lot of this could be replaced with a simple default UA client hint with the UA vendor and major version. Would you be opposed to something like that accompanying the request (it does change the privacy properties for PCM)?

[johnwilander]

attribution-id == campaign ID?

Actually that's the impression-data for us (the high entropy identifier). We would likely need another name for the low-entropy campaign ID. Maybe something like attribution-id-coarse and attribution-id-fine. Alternatively, we could use the aggregate/event-level terminology (something like what we proposed in AGGREGATE.md) and call it attribution-id-event and attribution-id-aggregate, since PCM is going for aggregate data in a sense via low-entropy IDs.

I worry that introducing "aggregate" here will make it harder to add something dedicated to data aggregation later. You could have browsers support PCM and some aggregate reporting with a server involved.

Could attribution-id-campaign and attribution-id-event work and in the case of PCM the latter isn't a thing?

attribution-trigger-data == conversion value?
Yes. That is, the "conversion" is the event which triggers attribution.

attribution-credit == either of the websites involved? Which? It should be the registrable domain of the source or destination depending on where this report is sent, right? Or is this intended for third-parties since you will support three parties – click source, click destination, and third-party serving the ad.

Sorry no the attribution credit is another difference in our APIs (it can likely be omitted in PCM), because we send reports for the last clicked impression with credit 100 and the non-last-clicked impressions with credit 0.

Aha.

The request itself may be revealing with IP address, time of day etc and the user/vendor might want to put additional, paid-for privacy protections in place at the network layer. The browser is sending the report for the benefit of the receiving end. They should be able to get their server configuration right if they want the data.

Just want to be clear here are you describing a case where the configured reporting origin does not have the capability to forward all of this sensitive data (ip, etc) anyways using server-to-server calls? I want to make sure that disallowing redirects is actually improving privacy over the base-line of s2s.

Imagine a browser with a block list and using that list to enforce IP cloaking for PCM reports. Imagine further that there is a cost to that cloaking. The browser vendor would neither want a redirect to be a way to bust out of the IP cloaking nor be a cost driver. I'm thinking we can say this is a single request, no redirects, take it or leave it.

Do you envision further scoping, like .well-known/report-attribution/click and .well-known/report-attribution/view? Or would such details go in the JSON?

JSON most likely.

OK.

One of the reasons why I want an open ended thing like version is that we might discover privacy problems down the road that will force us to make slight alterations that might not show at all in the reports. It'll be important for advertisers to know if a report was created with or without those alterations. The version field could likewise signal feature level. Imagine a vendor supporting cross-device attribution down the road. They may not want to add data to the report saying if it was the result of cross-device usage but a bump in version would at least allow advertisers to know that these reports are for users whose browser supports cross-device attribution.

I see the benefit here but I also think a lot of this could be replaced with a simple default UA client hint with the UA vendor and major version. Would you be opposed to something like that accompanying the request (it does change the privacy properties for PCM)?

Even if browsers agreed on client hints, how easy would it be to squeeze all kinds of changes into there? Like, "version 3 applies 0.05 noise," "version 4 drops 20% of reports," "version 5 adds trust tokens for the click source," "version 6 adds trust tokens for the click destination," "version 6 allows third-parties to get reports," and "version 7 expands the campaign ID range with one more bit for websites with such and such privacy policy."

All of these examples are made up but something like that is what I expect this to be.

[csharrison]

attribution-id == campaign ID?

Actually that's the impression-data for us (the high entropy identifier). We would likely need another name for the low-entropy campaign ID. Maybe something like attribution-id-coarse and attribution-id-fine. Alternatively, we could use the aggregate/event-level terminology (something like what we proposed in AGGREGATE.md) and call it attribution-id-event and attribution-id-aggregate, since PCM is going for aggregate data in a sense via low-entropy IDs.

I worry that introducing "aggregate" here will make it harder to add something dedicated to data aggregation later. You could have browsers support PCM and some aggregate reporting with a server involved.

Could attribution-id-campaign and attribution-id-event work and in the case of PCM the latter isn't a thing?

That's reasonable, though maybe swapping the ordering like attribution-event-id / attribution-campaign-id is a bit more clear. Including "campaign" goes against some of our goals in trying to remove ads-specific language so my preference would be to use a more generic name though.
@maudnals for input as well

The request itself may be revealing with IP address, time of day etc and the user/vendor might want to put additional, paid-for privacy protections in place at the network layer. The browser is sending the report for the benefit of the receiving end. They should be able to get their server configuration right if they want the data.

Just want to be clear here are you describing a case where the configured reporting origin does not have the capability to forward all of this sensitive data (ip, etc) anyways using server-to-server calls? I want to make sure that disallowing redirects is actually improving privacy over the base-line of s2s.

Imagine a browser with a block list and using that list to enforce IP cloaking for PCM reports. Imagine further that there is a cost to that cloaking. The browser vendor would neither want a redirect to be a way to bust out of the IP cloaking nor be a cost driver. I'm thinking we can say this is a single request, no redirects, take it or leave it.

I see. I will need to think a bit on this one since I don't know if I fully understand the repercussions. My fear in removing the ability to redirect we could lead to situations where we can't gracefully swap out reporting endpoints if there are pending reports that browsers are waiting to send (via the artificial delays). In our API we delay reports sometimes for up to 3 weeks so this could cause issues.

One of the reasons why I want an open ended thing like version is that we might discover privacy problems down the road that will force us to make slight alterations that might not show at all in the reports. It'll be important for advertisers to know if a report was created with or without those alterations. The version field could likewise signal feature level. Imagine a vendor supporting cross-device attribution down the road. They may not want to add data to the report saying if it was the result of cross-device usage but a bump in version would at least allow advertisers to know that these reports are for users whose browser supports cross-device attribution.

I see the benefit here but I also think a lot of this could be replaced with a simple default UA client hint with the UA vendor and major version. Would you be opposed to something like that accompanying the request (it does change the privacy properties for PCM)?

Even if browsers agreed on client hints, how easy would it be to squeeze all kinds of changes into there? Like, "version 3 applies 0.05 noise," "version 4 drops 20% of reports," "version 5 adds trust tokens for the click source," "version 6 adds trust tokens for the click destination," "version 6 allows third-parties to get reports," and "version 7 expands the campaign ID range with one more bit for websites with such and such privacy policy."

All of these examples are made up but something like that is what I expect this to be.

So I imagine most of those features would be direct function of UA + major version, although I am supportive of an end state where we encode parameters like noise level in the report where we expect different UAs to have different policies.

At least for some of those features it seems like we would need a method of advertising support outside of the report too. Any support for adding extra bids to the campaign ID would need to be surfaced to code configuring an impression.

[johnwilander]

those features would be direct function of UA + major version, although I am supportive of an end state where we encode parameters like noise level in the report where we expect different UAs to have different policies.

attribution-id == campaign ID?

Actually that's the impression-data for us (the high entropy identifier). We would likely need another name for the low-entropy campaign ID. Maybe something like attribution-id-coarse and attribution-id-fine. Alternatively, we could use the aggregate/event-level terminology (something like what we proposed in AGGREGATE.md) and call it attribution-id-event and attribution-id-aggregate, since PCM is going for aggregate data in a sense via low-entropy IDs.

I worry that introducing "aggregate" here will make it harder to add something dedicated to data aggregation later. You could have browsers support PCM and some aggregate reporting with a server involved.
Could attribution-id-campaign and attribution-id-event work and in the case of PCM the latter isn't a thing?

That's reasonable, though maybe swapping the ordering like attribution-event-id / attribution-campaign-id is a bit more clear.

I was considering that but stuck with your ordering. I'm all for them being readable.

Including "campaign" goes against some of our goals in trying to remove ads-specific language so my preference would be to use a more generic name though.
@maudnals for input as well

Did not know. Can you share the rationale? We kind of went that way in the naming "Private Click Measurement" since there's no enforcement on the clicks happening on ads.

Do you want to avoid all references to ads or could it simply be attribution-ad-id?

The request itself may be revealing with IP address, time of day etc and the user/vendor might want to put additional, paid-for privacy protections in place at the network layer. The browser is sending the report for the benefit of the receiving end. They should be able to get their server configuration right if they want the data.

Just want to be clear here are you describing a case where the configured reporting origin does not have the capability to forward all of this sensitive data (ip, etc) anyways using server-to-server calls? I want to make sure that disallowing redirects is actually improving privacy over the base-line of s2s.

Imagine a browser with a block list and using that list to enforce IP cloaking for PCM reports. Imagine further that there is a cost to that cloaking. The browser vendor would neither want a redirect to be a way to bust out of the IP cloaking nor be a cost driver. I'm thinking we can say this is a single request, no redirects, take it or leave it.

I see. I will need to think a bit on this one since I don't know if I fully understand the repercussions. My fear in removing the ability to redirect we could lead to situations where we can't gracefully swap out reporting endpoints if there are pending reports that browsers are waiting to send (via the artificial delays). In our API we delay reports sometimes for up to 3 weeks so this could cause issues.

One of the reasons why I want an open ended thing like version is that we might discover privacy problems down the road that will force us to make slight alterations that might not show at all in the reports. It'll be important for advertisers to know if a report was created with or without those alterations. The version field could likewise signal feature level. Imagine a vendor supporting cross-device attribution down the road. They may not want to add data to the report saying if it was the result of cross-device usage but a bump in version would at least allow advertisers to know that these reports are for users whose browser supports cross-device attribution.

I see the benefit here but I also think a lot of this could be replaced with a simple default UA client hint with the UA vendor and major version. Would you be opposed to something like that accompanying the request (it does change the privacy properties for PCM)?

Even if browsers agreed on client hints, how easy would it be to squeeze all kinds of changes into there? Like, "version 3 applies 0.05 noise," "version 4 drops 20% of reports," "version 5 adds trust tokens for the click source," "version 6 adds trust tokens for the click destination," "version 6 allows third-parties to get reports," and "version 7 expands the campaign ID range with one more bit for websites with such and such privacy policy."
All of these examples are made up but something like that is what I expect this to be.

So I imagine most of those features would be direct function of UA + major version, although I am supportive of an end state where we encode parameters like noise level in the report where we expect different UAs to have different policies.

At least for some of those features it seems like we would need a method of advertising support outside of the report too. Any support for adding extra bids to the campaign ID would need to be surfaced to code configuring an impression.

[csharrison]

Did not know. Can you share the rationale? We kind of went that way in the naming "Private Click Measurement" since there's no enforcement on the clicks happening on ads.

Do you want to avoid all references to ads or could it simply be attribution-ad-id?

I think the idea was to separate out use-case and functionality, and future proofing the API to be usable in other contexts other than ad measurement (somewhat aligned with TAG guidelines https://w3ctag.github.io/design-principles/#naming-future-proofing).

We were indeed thinking of removing all references to ads. Happy to hear your thoughts though.

[johnwilander]

Did not know. Can you share the rationale? We kind of went that way in the naming "Private Click Measurement" since there's no enforcement on the clicks happening on ads.
Do you want to avoid all references to ads or could it simply be attribution-ad-id?

I think the idea was to separate out use-case and functionality, and future proofing the API to be usable in other contexts other than ad measurement (somewhat aligned with TAG guidelines https://w3ctag.github.io/design-principles/#naming-future-proofing).

We were indeed thinking of removing all references to ads. Happy to hear your thoughts though.

Going with the intent of the feature, maybe attribution-click-content-id? For readability I'd prefer to drop the prefix and just say click-content-id. We could even reduce it to content-id but that makes it vague as to whether it's content on the click source or destination side.

[johnwilander]

OK, here's a proposal where I state the content type in the JSON:

{
  "content-type" : <string>,
  "content-site" : <string>,
  "content-id" : <int>,
  "conversion-site" : <string>,
  "conversion-data" : <int>,
  "report-version" : <int>
}

For example:

{
  "content-type" : "click",
  "content-site" : "news.example",
  "content-id" : 22,
  "conversion-site" : "store.example",
  "conversion-data" : 30,
  "report-version" : 1
}

Down the road we'd have:

{
  "content-type" : <string>,
  "content-site" : <string>,
  "content-id" : <int>,
  "content-unlinkable-token" : <string>,
  "conversion-site" : <string>,
  "conversion-data" : <int>,
  "conversion-unlinkable-token" : <string>,
  "report-version" : <int>
}

I use the term "site" because PCM restricts these fields to the registrable domain. I'm not sure if you too restrict to the registrable domain, Charlie? If not, we may consider using hostname as the term. Also, I know some don't like the term "site" so can consider registrable-domain too.

Thoughts, @csharrison?

[annevk]

Note that the Reporting API requires a CORS preflight if I remember correctly (and this would too if we don't want to enshrine further same-origin policy exceptions). See also https://fetch.spec.whatwg.org/#cors-protocol-exceptions.

[csharrison]

Sorry I missed this John. A few thoughts:

• "content" seems overly broad but I am interested in @maudnals 's thoughts. Maybe this is OK if we keep the attribute names containing "attribution" in them.

• For the conversion site we liked "attribute-on" / "attributed-on", and our current code calls this the "destination" rather than specify the type in the name.

• We wanted to move away from "conversion" to further make this a more generic API without using ads terms. Rather than conversion-data we suggested "attribution-trigger-data" in our renaming issue.

• I am not confident the conversion-unlinkable-token param is the right move (although I'll need to think a little bit more on it). It might be useful to align with the trust token work which has all the crypto operation in separate headers.

[johnwilander]

Note that the Reporting API requires a CORS preflight if I remember correctly (and this would too if we don't want to enshrine further same-origin policy exceptions). See also https://fetch.spec.whatwg.org/#cors-protocol-exceptions.

I'm not sure how this would be a same-origin policy exception. There is only one origin involved in the report, an HTTP POST sent outside of any webpage context, so there is no cross-origin situation really. You could argue that sending the report to the click destination site is outside their control but they've chosen who can fire a tracking pixel from their site, no?

[johnwilander]

Sorry I missed this John. A few thoughts:

• "content" seems overly broad but I am interested in @maudnals 's thoughts. Maybe this is OK if we keep the attribute names containing "attribution" in them.

Is there really any less broad term which is a match? We can say link, I suppose, but that would encode that this is a click-through report which we agreed should be stated in its own field (content-type here).

• For the conversion site we liked "attribute-on" / "attributed-on", and our current code calls this the "destination" rather than specify the type in the name.

Could you spell out what the fields would be with these terms? I'm not sure I follow.

• We wanted to move away from "conversion" to further make this a more generic API without using ads terms. Rather than conversion-data we suggested "attribution-trigger-data" in our renaming issue.

Got it.

• I am not confident the conversion-unlinkable-token param is the right move (although I'll need to think a little bit more on it). It might be useful to align with the trust token work which has all the crypto operation in separate headers.

We don't need to decide that right now. Better to focus on the non-token fields first.

This is my interpretation of what you're saying:

{
  "attribution-content-type" : <string>,
  "attribution-content-site" : <string>,
  "attribution-content-id" : <int>,
  "attribution-trigger-site" : <string>,
  "attribution-trigger-data" : <int>,
  "attribution-report-version" : <int>
}

Feels redundant to me to add attribution to all the fields. Maybe that's not what you're saying?

[csharrison]

Is there really any less broad term which is a match? We can say link, I suppose, but that would encode that this is a click-through report which we agreed should be stated in its own field (content-type here).

I think "attribution-source" is clearer. I think we can elide "attribution" if it is clear this report is related to attribution (in the URL), but we should keep it in the HTML since we ideally want to make it clear that the new attributes are coming from the attribution API.

Here's a suggestion:

{
  "source-engagement-type" : <string>, // click or view
  "source-site" : <string>,
  "source-id" : <int>, // for PCM
  "source-event-id" : <int>, // for CM-API
  "attributed-on" : <string>,
  "trigger-data" : <int>,
  "version": <int>
}

Then the HTML could expand this:

<a
  attributionsourceid="12"
  attributionsourceeventid="1235"
  attributeon="https://foo.com">

Note that I also think we could try to go with "data" for coarse data and "id" for fine data like CM-API ids. Then we could say something like "source-data" and "source-id". @maudnals I am interested in your thoughts. I think I like "source" better than "anchor" to describe the source of the attribution mostly because it seems like it might be confusing since it seems very desirable to add support for window.open.

[johnwilander]

OK, so for PCM (note the added "-site" in "attributed-on-site" to match "source-site"):

{
  "source-engagement-type" : <string>, // click or view
  "source-site" : <string>, // registrable domain
  "source-id" : <int>,
  "attributed-on-site" : <string>, // registrable domain
  "trigger-data" : <int>,
  "version": <int>
}

Looks good?

When you say "trigger-data" is data because it's coarse, what does that mean? This is the 3 bit value for CM-API and the 6 or 4 bit value for PCM, right?

[csharrison]

Looks good?

That seems reasonable. One thing reason I was wary of using "site" was because in the future we may want an even broader scope like a first-party-set, but that kind of change could come along with an updated name so I think it's no big deal.

The other thing I want to be clear about is when I say site I mean it in terms of this spec object i.e. the (scheme, eTLD+1) tuple.

When you say "trigger-data" is data because it's coarse, what does that mean? This is the 3 bit value for CM-API and the 6 or 4 bit value for PCM, right?

Yeah, the intuition here is that "data" is generic but "ID" implies something that might be uniquely identifier or finer grained to me. I think we probably want a standard term for the "coarse data". In PCM "source-id" and "trigger-data" are very similar but one uses "id" and the other "data". Might be good to agree on a term to use for both.

[maudnals]

Sorry, just seeing this!

1. Data and ID

Note that I also think we could try to go with "data" for coarse data and "id" for fine data like CM-API ids. Then we could say something like "source-data" and "source-id". @maudnals I am interested in your thoughts.
The intuition here is that "data" is generic but "ID" implies something that might be uniquely identifier or finer grained to me. I think we probably want a standard term for the "coarse data". In PCM "source-id" and "trigger-data" are very similar but one uses "id" and the other "data". Might be good to agree on a term to use for both.

@csharrison data for coarse data and id for fine data sound clear to me.
One small nit: attribution- in all the fields would be redundant as already noted. I do think though that trigger- could be more descriptive. trigger is a bit harder to situate in time. In comparison, source- inherently makes it clear that source--prefixed attributes relate to the initial engagement. Maybe attribution-trigger-data would be a bit clearer than trigger-data.

2. Attribution credit

This would still be present in the JSON object for the CM-API, as credit then?

3. (minor: Hyphens in JSON, as noted by @darobin)

Hyphens stood out for me too, and feel less idiomatic coming from a web/JS perspective.
But unsure whether this is the case other languages, I did a quick poll on this with devs familiar with non-JS server-side languages and couldn't see a clear cut.
Also, it looks like CSP reports use hyphenated keys as well.

[michael-oneill]

I vote for camelCasing rather than hyphens. For anyone using JS/C/C# hyphens are really annoying in names.

[annevk]

Per https://w3ctag.github.io/design-principles/#casing-rules it's supposed to use underscores and it seems that https://w3c.github.io/reporting/ also follows that (e.g., user_agent). Let's not deviate from established naming conventions.

[michael-oneill]

Underscores are fine too, but there is precedent for camel casing, e.g. you can access style attributes like
<div id='elem' style='background-color:red' >/div>
via
elem.style.backgroundColor='red';

Just as long as its not hyphens.

[johnwilander]

It looks like we're settling on:

{
  "source_engagement_type" : <string>, // click or view
  "source_site" : <string>, // registrable domain
  "source_id" : <int>,
  "attributed_on_site" : <string>, // registrable domain
  "attribution_trigger_data" : <int>,
  "version": <int>
}

For example

{
  "source_engagement_type" : "click",
  "source_site" : "social.example",
  "source_id" : 40,
  "attributed_on_site" : "shop.example",
  "attribution_trigger_data" : 3,
  "version": 1
}

[annevk]

On naming, I'd rather not conflate site with registrable domain. If the registrable domain is social.example, the site is either (http, social.example) or (https, social.example), as per https://html.spec.whatwg.org/#site. I guess it might be reasonable to simplify if it's always HTTPS, hmm, is that the case?

[csharrison]

On naming, I'd rather not conflate site with registrable domain. If the registrable domain is social.example, the site is either (http, social.example) or (https, social.example), as per https://html.spec.whatwg.org/#site. I guess it might be reasonable to simplify if it's always HTTPS, hmm, is that the case?

+1 although I think we should just spell out the whole site e.g. the scheme + registrable domain tuple. I think simplifying to HTTPS is not great because it introduces complexity where we might want to consider localhost potentially trutworthy to receive reports (for example).

[johnwilander]

On naming, I'd rather not conflate site with registrable domain. If the registrable domain is social.example, the site is either (http, social.example) or (https, social.example), as per https://html.spec.whatwg.org/#site. I guess it might be reasonable to simplify if it's always HTTPS, hmm, is that the case?

+1 although I think we should just spell out the whole site e.g. the scheme + registrable domain tuple. I think simplifying to HTTPS is not great because it introduces complexity where we might want to consider localhost potentially trutworthy to receive reports (for example).

The values of source_site and attributed_on_site could of course include the scheme but that would just waste bytes on the wire. In our case, we don't even keep track of what the scheme was so we'd probably just still "https://" at the front. Would you prefer source_domain and attributed_on_domain even though it would be capped to the eTLD+1?

[csharrison]

The values of source_site and attributed_on_site could of course include the scheme but that would just waste bytes on the wire. In our case, we don't even keep track of what the scheme was so we'd probably just still "https://" at the front. Would you prefer source_domain and attributed_on_domain even though it would be capped to the eTLD+1?

In our API, the source is the origin (scheme+host+port), and the destination is schemeful site (scheme + eTLD+1). I could see removing the scheme for reporting but it does feel a bit weird because we do intentionally support localhost. Those reports would look empty.

[annevk]

Why would you not keep track of the scheme?

[johnwilander]

Why would you not keep track of the scheme?

Why should you? The report request is sent over HTTPS regardless. Also, why (mildly) disincentivize sites to move to HTTPS? If PCM required a schemeful match, the advertiser would lose all pending click data at the upgrade to HTTPS. The only thing that would make sense to me is to require the whole thing to me HTTPS-only but I recall bringing that up early and people didn’t like it.

[johannhof]

We should make an issue for the HTTPS-only question to have a definitive reference on that. At least on Firefox we will not expose new features like this to insecure contexts by policy (doesn't mean it has to be in the spec but that would be nice). That probably extends to a case like this where we would want all involved parties to be secure context.

[johnwilander]

The report format has now been updated in the spec: f7e51be