Attributes naming and terms

[wicg]

Attributes naming and terms

[johnivdel]

To follow up on the above regarding the web exposed names specifically. Integrating some of the discussion on [privacycg/private-click-measurement#56](privacycg/private-click-measurement#56, here is a finalized set of proposed name change:

HTML

• impressiondata -> attributionsourceid
• conversiondestination -> attributeon
• impressionexpiry -> attributionexpiry
• reportingorigin -> attributionreportto

URLS

• /.well-known/register-conversion (conversion GET redirect url) -> /.well-known/trigger-attribution
• /.well-known/register-conversion (conversion report post url) -> /.well-known/report-attribution

Query params

• conversion-data (query param) -> data

The report param names would follow the results of the discussions on privacycg/private-click-measurement#30, which I have copied here for brevity:

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

[csharrison]

Accidentally closed by the PR. Re-opening

[maudnals]

@johnivdel @csharrison @samdutton

[csharrison]

Chatted about this in person, and one way I think one way to think about this is:

1. Using this API, all ad impressions (even in the view sense) would be annotated with data about itself
2. All subsequent uses of that data for attribution / reporting is scoped at something more like "eligible impressions" i.e. ones that are clicked in the current API.

In this framing "impression data" might be OK to keep around, as long as we don't call things downstream (like the click, or the data stored in the browser) as the impression data, since it's dealing with a subset of impressions. As a first idea, maybe we could have:

• "impression-data" --> data on each impression
• "attributable-impression-data" --> the subset of impression data that may be used later for attribution

[csharrison]

Sorry, to respond to more points:

1. "Impression" (term) refers to both the tag and the event.

Yes I think we should be using this to refer to the tag only and not the event (which could be a view, click, etc). That event should be called something else (e.g. the event which marks the impression eligible for attributability)

3. Both the terms "data" and "metadata" are used; similarly, we have impression-data and conversion-metadata attributes. This may be hard to remember and confusing for API users; it's not necessarily clear why one qualifies as data while the other as metadata. Note: I think the API already reflects this, and this is just about updating the explainer.

Yes let's just stick with "data".

[maudnals]

Great! Thanks.
3. is solved then, we can then open a dedicated PR for this.
This leaves us with "'impression' designates several entities" (1) and "'impression' means "view" in the ads space" (2)
With your feedback + our chat + a few extra insights, here's the completed picture:

---

(1) Several entities are designated by the same term

As of now, "impression" in the explainer and the API is used:

• To designate the HTML <a> tag, be it before or after a click or view has happened.
• To designate the event of the user clicking or viewing the ad.
• To designate a piece of data stored in the browser once a click or view has happened (= "attributable impression" concept @csharrison proposed); this piece of data includes, but is not limited to, impression-data.
• In the HTML attributes impression-data and impression-expiry.

Note: This list is a base to clarify; a distinct term for each of these may not be needed.

[Opinion: I think there's value in making theses entity types clear, by adding it as a "suffix" to whatever term ends up being used: "[...] tag", "[...] event". Because "tag" and "event" are concepts web developers are already familiar with - "tag" especially so, in the ads space.]

(2) "Impression" means "ad view" in the ads space

In theory, definition:
"An online advertisement impression is a single appearance of an advertisement on a web page" (source: IAB).

In theory, uses of this term in the wild:
Note: not all of these would map to the event-level API, but this illustrate how the term is used in the ads space.

• Google Ads: "An impression is counted each time your ad is shown" (source: Google Ads Help). "Cost-per-thousand impressions (CPM): A way to bid where you pay per one thousand views (impressions)" (source: Google Ads Help)
• Microsoft Ads: "Impressions are the number of times an ad has been displayed on search results pages" (source: Microsoft Ads Help)
• iOS: "A viewable impression is logged on Workbench when Apple has received confirmation from iOS that
  100 percent of the banner was fully displayed on-screen" (source: Apple's Ad Guide for Publishers, May 2020)

Note: this could be partly mitigated by the solutions we come up for (1) - for example, if a renaming is decided on and reduces occurrences of the term "impression" in contexts where it may be misunderstood.

[maudnals]

After gathering ideas and feedback, together with @csharrison, @johnivdel - with input from @michaelkleber, @domenic
and very helpful Ads folks I couldn't find a GitHub handle for - here is a shortlist of new names ideas.

Note that some of these new name ideas address the original concern mentioned in this issue ("impression may be confusing"). Others were suggested during the renaming brainstorming to address other points, that were raised organically on the way - for example, having an API name that is less tied to a use case and reflects more closely what the API does.

-	Current name	New name idea
[API Name]	Conversion Measurement Event-level API	Attribution reporting API
[Term] HTML tag, before or after a click/view has happened	impression	Attribution anchor
[Term] Event of the user clicking or viewing the ad	impression	click or view
[HTML attribute] Data/id tied to the tag	impressiondata	attributionid
[HTML attribute] Origin	conversiondestination	attributeon
[HTML attribute] Expiry	impressionexpiry	attributionexpiry
[HTML attribute] Where to send the report to	reportingorigin	attributionreportto
[Term] Piece of data stored in the browser once a click or view has happened; this piece of data includes, but is not limited to, impression-data.	impression	attributable click or view
[Term] Event of the user converting / that triggers an attribution request	conversion	attribution trigger
[Term] Data attached to a conversion	conversion data	attribution trigger data
[Term] Piece of data stored in the browser once a click or view has converted; this piece of data includes, but is not limited to, conversion data.= "linked data" conversion+impression	conversion	attributed click or view
[Term] Report	conversion report	attribution report
[Paths and query parameters] Path to trigger a conversion eventQuery parameter for the data attached to a conversion	.well-known/register-conversion?conversion-data=	** (1):.well-known/await-attribution or (2):.well-known/trigger-attribution. Query parameter: data (trigger-attribution?data=...) or attribution-trigger-data
[Path] Path where report is sent	.well-known/register-conversion?impression-data=x&conversion-data=y&attribution-credit=z	** (1):.well-known/await-attribution or (2):.well-known/trigger-attribution or (3):.well-known/register-attribution or (4):.well-known/report-attribution or (5):.well-known/schedule-attribution-report or (6):.well-known/attribute. Query parameters: attributionid, attribution-trigger-data or data — depending on what will be picked on the previous row , attribution-credit

**Open question:
Should these paths be the same? (i.e. option (1) or (2))
Pros of having these paths the same:
• Less cognitive load for developers
• "It's the same request", only more convoluted/delayed
Cons/Questions:
If the paths are the same, will it be clear in developer tooling that they're different? I.e. will same-naming get in the way of debugging an issue?

[csharrison]

Thanks so much Maud! I love the table view 👍

@johnwilander I mentioned in the last f2f that we were brainstorming some new names and terms for the API. Would you mind taking a look and sharing your thoughts?

I think the new names avoid some pitfalls of ambiguous technical ads terms on our side (impression & conversion) and also avoids embedding a use case (ads measurement) into the API name in favor of making the API more generic to the underlying primitive (attributing two events on different sites).

[abebis]

conversiondestination -> attributeto

attributeon :)

[maudnals]

Thank you John!

Remaining open questions at this point:
• Whether or not the sites in the JSON are schemeful or not
• Whether or not .well-known paths are grouped under a common path

For reference and cross-repo linking: All naming-related issues:
Structure of JSON used for conversion reports
Link attributes naming
Well-known url endpoint naming

[maudnals]

Renaming is complete, closing this issue.