attribution-reporting-api icon indicating copy to clipboard operation
attribution-reporting-api copied to clipboard

Published 20 hours ago • verified publisher icon WICG

event_attribution_reporting_clicks.md is very hard to follow.

Open MattMenke2 opened this issue 3 years ago • 6 comments

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.

MattMenke2 avatar Jul 19 '21 15:07 MattMenke2

@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.

csharrison avatar Jul 19 '21 22:07 csharrison

I'll take a look.

apasel422 avatar Jul 20 '21 12:07 apasel422

CC @maudnals.

apasel422 avatar Aug 05 '21 15:08 apasel422

@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.

maudnals avatar Aug 06 '21 07:08 maudnals

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"?

Aleksei-Gorbushin-at-Walmart avatar Aug 25 '22 05:08 Aleksei-Gorbushin-at-Walmart

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

maudnals avatar Aug 25 '22 07:08 maudnals