event_attribution_reporting_clicks.md is very hard to follow.

MattMenke2 commented 3 years ago

I'm trying to read this doc, and find it very hard to understand.

It talks a lot about "triggering attributions" without first defining "triggering" There is a "triggering attribution" section...which doesn't define the term.. The doc also talks about "sources" - it's unclear what a source is. I think the doc needs a high level overview, so it's clearer how things plug in. As-is, I'd probably to read the doc 3 or 4 times to make sense of it.

This is up for security review this week, and I just don't have the time to repeatedly wade through the doc to understand it.

csharrison commented 3 years ago

@apasel422 do you think you could take a look at this? I know you were discussing simplifying this doc given a lot of information is in the spec now.

apasel422 commented 3 years ago

I'll take a look.

apasel422 commented 3 years ago

CC @maudnals.

maudnals commented 3 years ago

@apasel422 Below is an (unreviewed) paragraph taken from a developer doc I'm drafting now.

Maybe some of it could be reused here, with one caveat: the terms are defined in the context of advertising, and IIRC the explainers here in this repo aim at remaining generic / to some extent use-case-agnostic.

The fix for this may be to add "for example, in an advertising context" or so at relevant places in the text below.

Terminology

A conversion is a user action that is desirable for the advertiser or adtech company, such as a sign-up or purchase.
In this API, the term source is used to describe what happens on the ad display side—typically, a publisher site. The term trigger is used to describe what happens on the ad conversion side—typically, an advertiser site.
An attribution source event (or attribution source, or source for short) is when a user clicks or views an ad.
The attribution source type describes the attribution source event:
- event: the user viewed an ad
- navigation: the user clicked an ad
A source is said to be triggered for attribution when a user converts. An attribution trigger event describes a conversion.

Aleksei-Gorbushin-at-Walmart commented 2 years ago

It looks a little clumsy to me anyway.

An attribution source event of the event type would be registered by a browser when a user viewed an ad.
An attribution source event of the navigation type would be registered by a browser when a user clicked an ad.

Could we use "impression" and "click" instead of "event" and "navigation"?

maudnals commented 2 years ago

+1 to this, this was flagged in https://github.com/WICG/attribution-reporting-api/issues/374 in the past as well.

WICG / attribution-reporting-api

event_attribution_reporting_clicks.md is very hard to follow. #188

Terminology