From e2ae1fb8580eb879dd52a7d76da67d8c93a853f3 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Fri, 11 Mar 2022 18:06:17 -0500 Subject: [PATCH 1/2] Editorial: use associated Document in place of responsible document --- index.bs | 12 +- index.html | 5154 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 5160 insertions(+), 6 deletions(-) create mode 100644 index.html diff --git a/index.bs b/index.bs index 1a076e07e3..eff8e4ee4e 100644 --- a/index.bs +++ b/index.bs @@ -539,7 +539,7 @@ and an [=environment settings object=] |settings|, run the following steps: 1. Let |currentTime| be the current time. 1. Assert: |params|["{{AttributionSourceParams/attributionDestination}}"] and |params|["{{AttributionSourceParams/attributionSourceEventId}}"] [=map/exist=]. -1. If |settings|'s [=environment settings object/responsible document=] is +1. If |settings|'s [=relevant global object=]'s [=associated Document=] is not [=allowed to use=] the [=attribution-reporting=] [=policy-controlled feature=], return null. 1. Let |attributionDestination| be the result of running [=parse an attribution destination=] with |params|["{{AttributionSourceParams/attributionDestination}}"]. @@ -699,7 +699,7 @@ Given a [=request=] |request|: return allowed. 1. Let |environment| be |request|'s [=request/window=]. 1. If |environment| is not an [=environment settings object=], return allowed. -1. If |environment|'s [=environment settings object/responsible document=] is not [=allowed to use=] the [=attribution-reporting=] [=policy-controlled feature=], +1. If |environment|'s [=relevant global object=]'s [=associated Document=] is not [=allowed to use=] the [=attribution-reporting=] [=policy-controlled feature=], return allowed. 1. If |environment|'s [=environment settings object/origin=] is not a [=potentially trustworthy origin=], return allowed. 1. If |environment|'s [=environment/top-level origin=] is an [=opaque origin=], return allowed. @@ -890,12 +890,12 @@ To queue a report for delivery given an [=attribution report=] |repor 1. If |report|'s [=attribution report/delivered=] value is true, return. 1. Set |report|'s [=attribution report/delivered=] value to true. 1. If |report|'s [=attribution report/report time=] is less than the current time, add an [=implementation-defined=] random amount to report time. - - Note: On startup, it is possible the user agent will need to send many reports whose report times passed while the browser was + + Note: On startup, it is possible the user agent will need to send many reports whose report times passed while the browser was closed. Adding random delay prevents temporal joining of reports from different [=attribution source/source origin=]s. 1. Wait until |report|'s [=attribution report/report time=] is the current time. 1. Optionally, wait a further [=implementation-defined=] length of time. - + Note: This is intended to allow user agents to optimize device resource usage. 1. Run [=attempt to deliver a report=] with |report|. @@ -986,7 +986,7 @@ To attempt to deliver a report given an [=attribution report=] |repor :: "`no-store`" 1. [=Queue a task=] to [=fetch=] |request| with [=fetch/processResponse=] being these steps: 1. [=Queue a task=] to remove |report| from the [=attribution report cache=]. - + Issue(220): This fetch should use a network partition key for an opaque origin. A user agent MAY retry this algorithm in the event that there was an error. diff --git a/index.html b/index.html new file mode 100644 index 0000000000..573fec920b --- /dev/null +++ b/index.html @@ -0,0 +1,5154 @@ + + + + Attribution Reporting + + + + + + + + + + + + + + + + + +
+

+

Attribution Reporting

+

Draft Community Group Report,

+
+
+
This version: +
https://wicg.github.io/conversion-measurement-api +
Issue Tracking: +
GitHub +
Inline In Spec +
Editors: +
(Google Inc.) +
(Google Inc.) +
(Google Inc.) +
+
+
+

Copyright © 2022 the Contributors to the Attribution Reporting Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). +A human-readable summary is available.

+
+
+
+

Abstract

+

An API to report that an event may have been caused by another cross-site event. These reports are designed to transfer little enough data between sites that the sites can’t use them to track individual users.

+
+
+

Status of this document

+
+

This specification was published by the Web Platform Incubator Community Group. + It is not a W3C Standard nor is it on the W3C Standards Track. + + Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. + + Learn more about W3C Community and Business Groups.

+

+
+
+ +
+

1. Introduction

+

This section is non-normative

+

This specification describes how web browsers can provide a mechanism to the +web that supports measuring and attributing conversions (e.g. purchases) to ads +a user interacted with on another site. This mechanism should remove one need +for cross-site identifiers like third-party cookies.

+

1.1. Overview

+

A page can register an attribution source on a site by providing attributionsourceeventid and attributiondestination attributes on an a element. +When such an a element is clicked, and the resulting navigation commits in a document within the same site as +the attributiondestination, the attribution source is stored in UA storage.

+

Alternatively, a page can register an attribution source on a site by providing a registerattributionsource attribute on an a element. When such an a element is added +to the page, the attribution source is stored in UA storage.

+

At a later point, the attributiondestination site may fire an HTTP request to +trigger attribution, which matches an attribution trigger with any previously +stored sources. If a matching source exists, it is scheduled to be +reported at a later time, possibly multiple days in the future.

+

Reports are sent to reporting endpoints that are configured in the attribution source +and attribution trigger.

+

2. HTML monkeypatches

+

2.1. long long reflection

+

Add the following rules for reflecting content attributes:

+

If a reflecting IDL attribute has a signed integer type (long long) then, on getting, the content attribute must be +parsed according to the rules for parsing integers, and if that is successful, and the value is in the +range of the IDL attribute’s type, the resulting value must be returned. If, on the other hand, it fails or returns +an out of range value, or if the attribute is absent, then the default value must be returned instead, or 0 if there +is no default value. On setting, the given value must be converted to the shortest possible string representing the +number as a valid integer and then that string must be used as the new content attribute value.

+

If a reflecting IDL attribute has a signed integer type (long long) that is limited to only non-negative numbers then, +on getting, the content attribute must be parsed according to the rules for parsing non-negative integers, and if +that is successful, and the value is in the range of the IDL attribute’s type, the resulting value must be returned. +If, on the other hand, it fails or returns an out of range value, or if the attribute is absent, the default value +must be returned instead, or −1 if there is no default value. On setting, if the value is negative, the user agent +must throw an "IndexSizeError" DOMException. Otherwise, the given value must be converted to the shortest possible +string representing the number as a valid non-negative integer and then that string must be used as the new content +attribute value.

+

2.2. <a> element

+

Add the following content attributes to the a element:

+
+
attributionsourceeventid +
+

Identifies the declared attribution source

+
attributiondestination +
+

Site which can attribute an event to the declared attribution source

+
attributionreportto +
+

origin to receive attribution reports

+
attributionexpiry +
+

Length of time the attribution souce is valid

+
attributionsourcepriority +
+

The priority of this source relative to other sources when triggering attribution

+
registerattributionsource +
+

Registers an attribution source with a source type "event"

+
+

Extend the a element’s DOM interface to include the following interface:

+
partial interface HTMLAnchorElement {
+    [CEReactions] attribute USVString attributionDestination;
+    [CEReactions] attribute DOMString attributionSourceEventId;
+    [CEReactions] attribute USVString attributionReportTo;
+    [CEReactions] attribute long long attributionExpiry;
+    [CEReactions] attribute long long attributionSourcePriority;
+    [CEReactions] attribute boolean registerAttributionSource;
+};
+
+

The IDL attributes attributionDestination, attributionSourceEventId, attributionReportTo, attributionSourcePriority, registerAttributionSource must reflect the respective +content attributes of the same name.

+

The IDL attribute attributionExpiry must reflect the attributionexpiry content attribute, limited to only non-negative numbers.

+

The attributiondestination attribute is a string +representing an origin that is intended to be same site with the origin +of the final navigation URL resulting from running follow the hyperlink with the a element.

+

The attributionsourceeventid attribute is a string +containing information about the attribution source and will be supplied in the attribution report.

+

The attributionreportto attribute optionally declares the origin to send the attribution report for this source.

+

The attributionexpiry attribute optionally defines the amount +of time in milliseconds the attribution source should be considered for reporting.

+

The attributionsourcepriority attribute optionally defines the +priority of a source relative to other sources when triggering attribution. If not specified, 0 is used as the +priority. An attribution trigger with a given reporting endpoint and attribution destination will always be attributed to the source with the highest priority value that has the same reporting endpoint and attribution destination.

+

The registerattributionsource attribute, if present, registers an +additional source whose source type is "event".

+

Note: One simple priority scheme would be to use the current millisecond timestamp as the priority value.

+

2.3. Navigation

+

This section ensures that an attribution source associated with a navigation +results in a top-level navigation whose final URL is same site with the attribution destination.

+

2.3.1. Navigation Params

+

A navigation params struct has an item:

+
+
attribution source +
+

null or an attribution source declared when initiating a navigation

+
+

2.3.2. Navigate algorithm

+

Modify the navigate algorithm to accept a new optional parameter attributionSource of type attribution source defaulting to null.

+

In navigate, within step

+
+
    +
  1. +

    This is the step that attempts to obtain resource, if necessary. Jump to the first appropriate substep: +...

    +
+
+

in the case where

+
+

If resource is a response

+
+

modify the substep

+
+
    +
  1. +

    Let navigationParams be a new navigation params whose request is null, response is resource +...

    +
+
+

to set the attribution source of navigationParams to attributionSource.

+

In the case where

+
+

If resource is a request whose URL’s scheme is "javascript"

+
+

modify the substep

+
+
    +
  1. +

    Let navigationParams be a new navigation params whose request is resource, +...

    +
+
+

to set the attribution source of navigationParams to attributionSource.

+

In the case where

+
+

If resource is a request whose URL’s scheme is a fetch scheme

+
+

modify the substep to pass attributionSource to the process a navigate fetch algorithm.

+

Note: The final case, where the request is not a javascript or fetch scheme, does not need to be handled + as it will not result in the navigation of a top-level browsing context.

+

2.3.3. Process a navigate fetch

+

Modify the process a navigate fetch algorithm to accept a new optional parameter attributionSource of type attribution source defaulting to null.

+

In process a navigate fetch, modify the step

+
+
    +
  1. +

    Otherwise, if locationURL is a URL whose scheme is a fetch scheme, then run process a navigate fetch with a new request +...

    +
+
+

to also pass attributionSource into the process a navigate fetch algorithm.

+

Modify the step

+
+
    +
  1. +

    Let navigationParams be a new navigation params whose request is request, response is response, +...

    +
+
+

to set the attribution source of navigationParams to attributionSource.

+

2.3.4. Document creation

+

At the time create and initialize a Document object is invoked, the user agent knows the final URL used for the +navigation and can validate the attribution destination.

+

In create and initialize a Document object, before

+
+
    +
  1. +

    Let permissionsPolicy be the result of creating a permissions policy from a response given browsingContext +...

    +
+
+

add the following step:

+
    +
  1. +

    Execute maybe process a navigation attribution source with navigationParams and browsingContext.

    +
+ +

Attribution source information declared on the a element needs to be passed to the navigate algorithm.

+

In follow the hyperlink after

+
+
    +
  1. +

    Let historyHandling be "replace" if windowType is not "existing or none"; otherwise, "default".

    +
+
+

add the following steps:

+
    +
  1. +

    Let attributionSource be null.

    +
  2. +

    If subject is an a element, set attributionSource to the result of running obtain an attribution source from an anchor with subject.

    +
+

Modify the step:

+
+
    +
  1. +

    Queue an element task on the DOM manipulation task source given subject to navigate target to request +...

    +
+
+

to call navigate with attributionSource set to attributionSource.

+

3. Fetch monkeypatches

+

In main fetch, within the step:

+
+
    +
  1. +

    If response is not a network error and any of the following returns blocked +...

    +
+
+

add the following check to the list:

+ +

4. Attribution Reporting API

+
dictionary AttributionSourceParams {
+  required USVString attributionDestination;
+  required DOMString attributionSourceEventId;
+  USVString attributionReportTo;
+  long long attributionExpiry;
+  long long attributionSourcePriority;
+};
+
+[Exposed=Window, SecureContext]
+interface AttributionReporting {
+  Promise<undefined> registerAttributionSource(AttributionSourceParams params);
+};
+
+[SecureContext]
+partial interface Window {
+  readonly attribute AttributionReporting attributionReporting;
+};
+
+

The registerAttributionSource(params) method steps are:

+
    +
  1. +

    Let source be the result of running obtain an attribution source from params with params and the relevant settings object of this.

    +
  2. +

    If source is null, return a promise rejected with the undefined value.

    +
  3. +

    Set source to the result of running obtain an event attribution source from a source with source.

    +
  4. +

    Queue a task to process an attribution source with source.

    +
  5. +

    Return a promise resolved with the undefined value.

    +
+

Note: This function returns a promise even though the promise is always resolved or rejected by the +time the function returns; in the future, the promise may be resolved with a value that provides +finer-grained detail about other errors that occurred during the process an attribution source step.

+

5. Permissions Policy integration

+ This specification defines a policy-controlled feature identified by the string "attribution-reporting". Its default allowlist is *. +

6. Structures

+

6.1. Attribution mode

+

An attribution mode is a tuple consisting of a mode and a random trigger data. The mode is +either "truthfully", "never", or "falsely". The random trigger data is a non-negative 64-bit +integer, if the mode is "falsely", or null otherwise.

+

6.2. Attribution source

+

An attribution source is a struct with the following items:

+
+
source identifier +
+

A string.

+
source origin +
+

An origin.

+
event id +
+

A non-negative 64-bit integer.

+
attribution destination +
+

A site.

+
reporting endpoint +
+

An origin.

+
source type +
+

Either "navigation" or "event".

+
expiry +
+

A length of time.

+
priority +
+

A 64-bit integer.

+
source time +
+

A point in time.

+
number of reports +
+

Number of attribution reports created for this attribution source.

+
dedup keys +
+

ordered set of dedup keys associated with this attribution source.

+
attribution mode +
+

An attribution mode.

+
randomized trigger rate +
+

A number between 0 and 1 (both inclusive).

+
+

6.3. Attribution trigger

+

An attribution trigger is a struct with the following items:

+
+
attribution destination +
+

A site.

+
navigation-source trigger data +
+

A non-negative 64-bit integer.

+
event-source trigger data +
+

A non-negative 64-bit integer.

+
trigger time +
+

A point in time.

+
reporting endpoint +
+

An origin.

+
dedup key +
+

Null or a 64-bit integer.

+
priority +
+

A 64-bit integer.

+
+

6.4. Attribution report

+

An attribution report is a struct with the following items:

+
+
event id +
+

A non-negative 64-bit integer.

+
source type +
+

Either "navigation" or "event".

+
trigger data +
+

A non-negative 64-bit integer.

+
randomized trigger rate +
+

A number between 0 and 1 (both inclusive).

+
reporting endpoint +
+

An origin.

+
attribution destination +
+

A site.

+
report time +
+

A point in time.

+
trigger priority +
+

A 64-bit integer.

+
trigger time +
+

A point in time.

+
source identifier +
+

A string.

+
delivered (default false) +
+

A boolean.

+
report id +
+

A string.

+
+

6.5. Attribution rate-limit record

+

An attribution rate-limit record is a struct with the following items:

+
+
source site +
+

A site.

+
attribution destination +
+

A site.

+
source type +
+

Either "navigation" or "event".

+
trigger time +
+

A point in time.

+
+

7. Storage

+

A user agent holds an attribution source cache, which is an ordered set of attribution sources.

+

A user agent holds an attribution report cache, which is an ordered set of attribution reports.

+

A user agent holds an attribution rate-limit cache, which is an ordered set of attribution rate-limit records.

+

The above caches are collectively known as the attribution caches. The attribution caches are +shared among all environment settings objects.

+

Note: This would ideally use storage bottles to provide access to the attribution caches. +However attribution data is inherently cross-site, and operations on storage would need to span across all storage bottle maps.

+

8. General Algorithms

+

8.1. Obtaining a randomized response

+

To obtain a randomized response given trueValue, a set possibleValues, and a +double randomPickRate:

+
    +
  1. +

    Assert: randomPickRate is between 0 and 1 (both inclusive).

    +
  2. +

    Let r be a random double between 0 (inclusive) and 1 (exclusive) with uniform probability.

    +
  3. +

    If r is less than randomPickRate, return a random item from possibleValues with uniform +probability.

    +
  4. +

    Otherwise, return trueValue.

    +
+

9. Source Algorithms

+

9.1. Obtaining an attribution source’s expiry time

+

An attribution source source’s expiry time is source’s source time + source’s expiry.

+

9.2. Parsing data fields

+

This section defines how to parse strings into integers for event id, navigation-source trigger data, and event-source trigger data.

+

To parse attribution data given a string input modulo an integer maxData perform the following steps. They return a non-negative integer:

+
    +
  1. +

    Let decodedInput be the result of applying the rules for parsing non-negative integers to input.

    +
  2. +

    If decodedInput is an error, return zero.

    +
  3. +

    If decodedInput is greater than 264, return zero.

    +
  4. +

    Let clampedDecodedInput be the remainder when dividing decodedInput by maxData.

    +
  5. +

    Return clampedDecodedInput.

    +
+

9.3. Parsing an attribution destination

+

To parse an attribution destination from a string str:

+
    +
  1. +

    Let url be the result of running the URL parser on the value of +the str.

    +
  2. +

    If url is failure or null, return null.

    +
  3. +

    If url’s origin is an opaque origin, return null.

    +
  4. +

    Return the result of obtaining a site from url’s origin.

    +
+

9.4. Obtaining a random attribution mode

+

To obtain a random attribution mode given a positive integer triggerDataCardinality and a double randomPickRate:

+
    +
  1. +

    Let possibleValues be the set of attribution modes « ("never", null) ».

    +
  2. +

    For each integer i between 0 (inclusive) and triggerDataCardinality (exclusive):

    +
      +
    1. +

      Append the attribution mode ("falsely", i) to possibleValues.

      +
    +
  3. +

    Return the result of obtaining a randomized response with the attribution mode ("truthfully", null), possibleValues, and randomPickRate.

    +
+

9.5. Obtaining an attribution source from an a element

+

To obtain an attribution source from an anchor given an a element anchor:

+
    +
  1. +

    If anchor does not have both an attributiondestination attribute and an attributionsourceeventid attribute, return null.

    +
  2. +

    Let params be an AttributionSourceParams with the following key/value pairs:

    +
    +
    attributionDestination +
    +

    anchor’s attributiondestination attribute

    +
    attributionSourceEventId +
    +

    anchor’s attributionsourceeventid attribute

    +
    attributionReportTo +
    +

    anchor’s attributionreportto attribute

    +
    attributionExpiry +
    +

    anchor’s attributionexpiry attribute

    +
    attributionSourcePriority +
    +

    anchor’s attributionsourcepriority attribute

    +
    +
  3. +

    Return the result of running obtain an attribution source from params with params and anchor’s relevant settings object.

    +
+

9.6. Obtaining an event attribution source from an a element

+

To obtain an event attribution source from an anchor given an a element anchor, run the following steps:

+
    +
  1. +

    If anchor does not have a registerattributionsource attribute, return null.

    +
  2. +

    Let source be the result of running obtain an attribution source from an anchor with anchor.

    +
  3. +

    If source is null, return null.

    +
  4. +

    Return the result of running obtain an event attribution source from a source with source.

    +
+

9.7. Obtaining an event attribution source from a source

+

To obtain an event attribution source from a source given an attribution source source, run the following steps:

+
    +
  1. +

    Let resultSource be a shallow clone of source.

    +
  2. +

    Set resultSource’s source identifier to a new unique opaque string.

    +
  3. +

    Set resultSource’s source type to "event".

    +
  4. +

    Round resultSource’s expiry away from zero to the nearest day (86400 seconds).

    +
  5. +

    Set resultSource’s attribution mode to the result of obtaining a random attribution mode with the user agent’s event-source trigger data cardinality and the user agent’s randomized event-source trigger rate.

    +
  6. +

    Set resultSource’s randomized trigger rate to the user agent’s randomized event-source trigger rate.

    +
  7. +

    Return resultSource.

    +
+

Randomized event-source trigger rate is a vendor-specific double between 0 and 1 (both +inclusive) that controls the randomized response probability for the attribution mode of an attribution source whose source type is "event".

+

9.8. Obtaining an attribution source from AttributionSourceParams

+

To obtain an attribution source from params given an AttributionSourceParams params and an environment settings object settings, run the following steps:

+
    +
  1. +

    Let sourceIdentifier be a new unique string.

    +
  2. +

    Let currentTime be the current time.

    +
  3. +

    Assert: params["attributionDestination"] and params["attributionSourceEventId"] exist.

    +
  4. +

    If settings’s relevant global object's associated Document is +not allowed to use the attribution-reporting policy-controlled feature, return null.

    +
  5. +

    Let attributionDestination be the result of running parse an attribution destination with params["attributionDestination"].

    +
  6. +

    If attributionDestination is null, return null.

    +
  7. +

    Let sourceOrigin be settings’s top-level origin.

    +
  8. +

    If sourceOrigin is an opaque origin, return null.

    +
  9. +

    Let reportingOrigin be sourceOrigin.

    +
  10. +

    If params["attributionReportTo"] exists, then:

    +
      +
    1. +

      Let reportingUrl be the result of running the URL parser with params["attributionReportTo"].

      +
    2. +

      If reportingUrl is failure or null, return null.

      +
    3. +

      If reportingUrl’s origin is an opaque origin, return null.

      +
    4. +

      Set reportingOrigin to reportingUrl’s origin.

      +
    +
  11. +

    Let expiry be 30 days.

    +
  12. +

    If params["attributionExpiry"] exists, +then set expiry to that value.

    +
  13. +

    Let priority be 0.

    +
  14. +

    If params["attributionSourcePriority"] exists, +then set priority to that value.

    +
  15. +

    Let source be a new attribution source struct whose items are:

    +
    +
    source identifier +
    +

    sourceIdentifier

    +
    source origin +
    +

    sourceOrigin

    +
    event id +
    +

    The result of running parse attribution data with params["attributionSourceEventId"] modulo max event id value.

    +
    attribution destination +
    +

    attributionDestination

    +
    reporting endpoint +
    +

    reportingOrigin

    +
    expiry +
    +

    expiry

    +
    priority +
    +

    priority

    +
    source time +
    +

    currentTime

    +
    source type +
    +

    "navigation"

    +
    attribution mode +
    +

    ("truthfully", null)

    +
    randomized trigger rate +
    +

    0

    +
    +
  16. +

    Return source.

    +
+

Max event id value is a vendor-specific integer which controls +the maximum value which can be used as an event id.

+

9.9. Processing an attribution source

+

To maybe process a navigation attribution source given a navigation params navigationParams and browsing context browsingContext, run the following steps:

+
    +
  1. +

    If browsingContext is not a top-level browsing context, return.

    +
  2. +

    Let attributionSource be navigationParams’s attribution source.

    +
  3. +

    If attributionSource is null, return.

    +
  4. +

    If attributionSource’s attribution destination is not same site to navigationParams’s origin, return.

    +
  5. +

    Queue a task to process an attribution source with attributionSource.

    +
+

To process an attribution source given an attribution source source:

+
    +
  1. +

    Let cache be the user agent’s attribution source cache.

    +
  2. +

    Remove all entries in cache where all of the following are true:

    + +

    Note: This causes the user agent to favor triggering newer attribution sources over sources that have already been triggered.

    +
  3. +

    Remove all entries in cache where the entry’s expiry time is less than the current time.

    +
  4. +

    If the size of cache is greater than or equal to the user agent’s max source cache size, return.

    +
  5. +

    If source’s attribution mode[0] is "falsely", then:

    +
      +
    1. +

      Assert: source’s source type is "event".

      +
    2. +

      If the size of the attribution report cache is greater than or equal to the user +agent’s max report cache size, return.

      +
    3. +

      Let fakeTrigger be a new attribution trigger with the items:

      +
      +
      attribution destination +
      +

      source’s attribution destination

      +
      navigation-source trigger data +
      +

      0

      +
      event-source trigger data +
      +

      source’s attribution mode[1]

      +
      trigger time +
      +

      source’s source time

      +
      reporting endpoint +
      +

      source’s reporting endpoint

      +
      dedup key +
      +

      null

      +
      priority +
      +

      0

      +
      +
    4. +

      Let fakeReport be the result of running obtain a report with source and fakeTrigger.

      +
    5. +

      Add fakeReport to the attribution report cache.

      +
    6. +

      Return.

      +
    +
  6. +

    Append source to cache.

    +
+

Should fake reports respect the user agent’s max reports per attribution destination?

+

Max source cache size is a vendor-specific integer which controls how many attribution sources can be in the attribution source cache.

+

10. Triggering Algorithms

+

10.1. Creating an attribution trigger

+

To obtain an attribution trigger given a URL url and an environment settings object environment, run the following steps:

+
    +
  1. +

    Let navigationSourceTriggerData be 0.

    +
  2. +

    If url’s query has a "trigger-data" field, set navigationSourceTriggerData to the result of running parse attribution data with +the value associated with the field modulo the user agent’s trigger data cardinality.

    +
  3. +

    Let eventSourceTriggerData be 0.

    +
  4. +

    If url’s query has an "event-source-trigger-data" field, set eventSourceTriggerData to the result of running parse attribution data with +the value associated with the field modulo the user agent’s event-source trigger data cardinality.

    +
  5. +

    Let dedupKey be null.

    +
  6. +

    If url’s query has a "dedup-key" field, and applying the rules for +parsing integers to the field’s value results in an integer, then set dedupKey to that +value.

    +
  7. +

    Let triggerPriority be 0.

    +
  8. +

    If url’s query has a "priority" field, and applying the rules for parsing integers to the field’s value results +in an integer, set triggerPriority to that value.

    +
  9. +

    Let trigger be a new attribution trigger with the items:

    +
    +
    attribution destination +
    +

    The result of obtaining a site from environment’s top-level origin.

    +
    navigation-source trigger data +
    +

    navigationSourceTriggerData.

    +
    event-source trigger data +
    +

    eventSourceTriggerData.

    +
    trigger time +
    +

    The current time.

    +
    reporting endpoint +
    +

    url’s origin.

    +
    dedup key +
    +

    dedupKey.

    +
    priority +
    +

    triggerPriority.

    +
    +
  10. +

    Return trigger.

    +
+

Trigger data cardinality is a vendor-specific integer that controls the valid range of navigation-source trigger data: +0 <= navigation-source trigger data < trigger data cardinality.

+

Event-source trigger data cardinality is a vendor-specific integer that controls the valid +range of event-source trigger data: +0 <= event-source trigger data < event-source trigger data cardinality.

+

Formalize how to parse the query similar to URLSearchParams.

+

10.2. Should internalResponse to request be blocked as attribution trigger

+

Given a request request:

+
    +
  1. +

    If request’s current URL’s origin is an opaque origin, return allowed.

    +
  2. +

    If request’s current URL’s path is not equal to « ".well-known","attribution-reporting","trigger-attribution" », +return allowed.

    +
  3. +

    Let environment be request’s window.

    +
  4. +

    If environment is not an environment settings object, return allowed.

    +
  5. +

    If environment’s relevant global object's associated Document is not allowed to use the attribution-reporting policy-controlled feature, +return allowed.

    +
  6. +

    If environment’s origin is not a potentially trustworthy origin, return allowed.

    +
  7. +

    If environment’s top-level origin is an opaque origin, return allowed.

    +
  8. +

    If environment’s top-level origin is not a potentially trustworthy origin, return allowed.

    +
  9. +

    If request’s current URL’s origin is not a potentially trustworthy origin, return allowed.

    +
  10. +

    If request’s redirect count is less than 1, return allowed.

    +
  11. +

    Let previousUrl be the second to last URL in request’s URL list.

    +
  12. +

    If request’s current URL’s origin is not same origin with previousUrl’s origin, return allowed.

    +

    Note: The restriction to require a redirect is necessary to ensure that the + request’s origin is aware and in control of the conversion registration. This could also be done with a header-based mechanism.

    +
  13. +

    Let trigger be the result of running obtain an attribution trigger with request’s current URL and environment.

    +
  14. +

    Queue a task to trigger attribution with trigger.

    +
  15. +

    Return blocked.

    +
+

10.3. Should attribution be blocked by rate limit

+

Given an attribution trigger trigger and attribution source sourceToAttribute:

+
    +
  1. +

    Let sourceSite be the result of obtaining a site from sourceToAttribute’s source origin.

    +
  2. +

    Let matchingRateLimitRecords be all entries in the attribution rate-limit cache where all of the following are true:

    + +
  3. +

    If the size of matchingRateLimitRecords is greater than or equal to max attributions per rate-limit window, return blocked.

    +
  4. +

    Return allowed.

    +
+

Attribution rate-limit window is a vendor-specific duration that controls the +rate-limiting window for attribution.

+

Max attributions per rate-limit window is a vendor-specific integer that controls +the maximum number of attributions for a (source site, attribution destination, source type) per attribution rate-limit window.

+

10.4. Triggering attribution

+

To trigger attribution given an attribution trigger trigger run the following steps:

+
    +
  1. +

    Let attributionDestination be trigger’s attribution destination.

    +
  2. +

    Let matchingSources be all entries in the attribution source cache where all of the following are true:

    + +
  3. +

    If matchingSources is empty, return.

    +
  4. +

    Set matchingSources to the result of sorting matchingSources in descending order, with a being less than b if any of the following are true:

    + +
  5. +

    Let sourceToAttribute be the first item in matchingSources.

    +
  6. +

    Assert: sourceToAttribute’s attribution mode[0] is +"truthfully" or "never".

    +
  7. +

    If trigger’s dedup key is not null and sourceToAttribute’s dedup keys contains it, return.

    +
  8. +

    Let numMatchingReports be the number of entries in the attribution report cache whose attribution destination equals attributionDestination.

    +
  9. +

    If numMatchingReports is greater than or equal to the user agent’s max reports per attribution destination, return.

    +
  10. +

    If the result of running should attribution be blocked by rate limit with trigger and sourceToAttribute is blocked, return.

    +
  11. +

    Let report be the result of running obtain a report with sourceToAttribute and trigger.

    +
  12. +

    If sourceToAttribute’s number of reports value is equal to the +user agent’s max reports per source value, then:

    +
      +
    1. +

      Let matchingReports be all entries in the attribution report cache where all of the following are true:

      + +
    2. +

      If matchingReports is empty, then remove sourceToAttribute from the attribution source cache and return.

      +
    3. +

      Set matchingReports to the result of sorting matchingReports in ascending order, with a being less than b if any of the following are true:

      + +
    4. +

      Let lowestPriorityReport be the first item in matchingReports.

      +
    5. +

      If report’s trigger priority is less than or equal to lowestPriorityReport’s trigger priority, return.

      +
    6. +

      Remove lowestPriorityReport from the attribution report cache.

      +
    7. +

      Decrement sourceToAttribute’s number of reports value by 1.

      +
    +
  13. +

    Remove sourceToAttribute from matchingSources.

    +
  14. +

    For each item of matchingSources:

    +
      +
    1. +

      Remove item from the attribution source cache.

      +
    +
  15. +

    If the size of the attribution report cache is greater than or equal to the user +agent’s max report cache size, return.

    +
  16. +

    If sourceToAttribute’s attribution mode[0] is "truthfully", +add report to the attribution report cache.

    +
  17. +

    Increment sourceToAttribute’s number of reports value by 1.

    +
  18. +

    If trigger’s dedup key is not null, append it to sourceToAttribute’s dedup keys.

    +
  19. +

    Let rateLimitRecord be a new attribution rate-limit record with the items:

    +
    +
    source site +
    +

    The result of obtaining a site from sourceToAttribute’s source origin.

    +
    attribution destination +
    +

    attributionDestination

    +
    source type +
    +

    sourceToAttribute’s source type

    +
    trigger time +
    +

    trigger’s trigger time

    +
    +
  20. +

    Add rateLimitRecord to the attribution rate-limit cache.

    +
  21. +

    Remove all entries from the attribution rate-limit cache whose trigger time is at least attribution rate-limit window before the current time.

    +
+

Max reports per attribution destination is a vendor-specific integer which controls how +many attribution reports can be in the attribution report cache for an attribution destination.

+

Max reports per source is a vendor-specific integer which controls how many attribution reports can be created for an attribution source.

+

Max report cache size is a vendor-specific integer which controls how many attribution reports can be in the attribution report cache.

+

Note: This parameter represents a privacy/utility tradeoff. Lower values mean that less trigger-side data +can be associated with a source event id. Larger values allow for more attribution triggers to be reported.

+

10.5. Establishing report delivery time

+

To obtain a report delivery time given an attribution source source and a trigger time triggerTime, perform the following steps. They +return a point in time.

+
    +
  1. +

    If source’s source type is "event", return source’s expiry time + 1 hour.

    +
  2. +

    Let timeToTrigger be the difference between triggerTime and source time.

    +

    Note: timeToTrigger is less than source’s expiry because it is not normally possible to +convert an expired attribution source.

    +
  3. +

    If:

    +
    +
    timeToTrigger <= (2 days - 1 hour) +
    return source time + 2 days. +
    + source’s expiry > (2 days - 1 hour) +
      +
    • +

      and source’s expiry < (7 days - 1 hour)

      +
    • +

      and timeToTrigger <= source’s expiry

      +
    +
    return source’s expiry time + 1 hour. +
    timeToTrigger <= (7 days - 1 hour) +
    return source time + 7 days. +
    Otherwise +
    return source’s expiry time + 1 hour. +
    +
+

10.6. Obtaining a report

+

To obtain a report given an attribution source source and an attribution trigger trigger:

+
    +
  1. +

    Let triggerData be trigger’s trigger data.

    +
  2. +

    If source’s source type is "event", set triggerData to trigger’s event source trigger data.

    +
  3. +

    Let report be a new attribution report struct whose items are:

    +
    +
    event id +
    +

    source’s event id.

    +
    trigger data +
    +

    triggerData.

    +
    randomized trigger rate +
    +

    source’s randomized trigger rate.

    +
    reporting endpoint +
    +

    source’s reporting endpoint.

    +
    attribution destination +
    +

    source’s attribution destination.

    +
    reporting time +
    +

    The result of running obtain a report delivery time with source and trigger’s trigger time.

    +
    trigger priority +
    +

    trigger’s priority.

    +
    trigger time +
    +

    trigger’s trigger time.

    +
    source identifier +
    +

    source’s source identifier.

    +
    report id +
    +

    The result of generating a random UUID.

    +
    +
  4. +

    Return report.

    +
+

11. Report delivery

+

The user agent MUST periodically iterate over its attribution report cache and run queue a report for delivery on each item.

+

To queue a report for delivery given an attribution report report, run the following steps in parallel:

+
    +
  1. +

    If report’s delivered value is true, return.

    +
  2. +

    Set report’s delivered value to true.

    +
  3. +

    If report’s report time is less than the current time, add an implementation-defined random amount to report time.

    +

    Note: On startup, it is possible the user agent will need to send many reports whose report times passed while the browser was + closed. Adding random delay prevents temporal joining of reports from different source origins.

    +
  4. +

    Wait until report’s report time is the current time.

    +
  5. +

    Optionally, wait a further implementation-defined length of time.

    +

    Note: This is intended to allow user agents to optimize device resource usage.

    +
  6. +

    Run attempt to deliver a report with report.

    +
+

11.1. Serialize an integer

+

To serialize an integer, represent it as a string of the shortest possible decimal number.

+

This would ideally be replaced by a more descriptive algorithm in Infra. See infra/201

+

11.2. Serialize attribution report body

+

To serialize an attribution report report, run the following steps:

+
    +
  1. +

    Let destination be report’s attribution destination.

    +
  2. +

    Assert: destination is not an opaque origin.

    +
  3. +

    Let data be a map of the following key/value pairs:

    +
    +
    "attribution_destination" +
    +

    destination, serialized

    +
    "randomized_trigger_rate" +
    +

    report’s randomized trigger rate

    +
    "source_type" +
    +

    report’s source type

    +
    "source_event_id" +
    +

    report’s event id, serialized

    +
    "trigger_data" +
    +

    report’s trigger data, serialized

    +
    "report_id" +
    +

    report’s report id

    +
    +
  4. +

    Return the byte sequence resulting from executing serialize an infra value to JSON bytes on data.

    +
+

Note: The inclusion of "report_id" in the report body is intended to allow the report recipient +to perform deduplication and prevent double counting, in the event that the user agent retries +reports on failure. To prevent the report recipient from learning additional information about +whether a user is online, retries should be limited in number and subject to random delays.

+

11.3. Get report request URL

+

To generate a report URL for a given attribution report report, run the following steps:

+
    +
  1. +

    Let reportUrl be a new URL record.

    +
  2. +

    Let reportingOrigin be report’s reporting endpoint.

    +
  3. +

    Assert: reportingOrigin is not an opaque origin.

    +
  4. +

    Set reportUrl’s scheme to reportingOrigin’s scheme.

    +
  5. +

    Set reportUrl’s host to reportingOrigin’s host.

    +
  6. +

    Set reportUrl’s port to reportingOrigin’s port.

    +
  7. +

    Set reportUrl’s path to «".well-known", "attribution-reporting", "report-attribution"».

    +
  8. +

    Return reportUrl.

    +
+

11.4. Issuing a report request

+

This algorithm constructs a request and attempts to deliver it to report’s reporting endpoint.

+

To attempt to deliver a report given an attribution report report, run the following steps:

+
    +
  1. +

    Let body be the result of executing serialize an attribution report on report.

    +
  2. +

    Let url be the result of executing generate a report URL on report.

    +
  3. +

    Let request be a new request with the following properties:

    +
    +
    method +
    +

    "POST"

    +
    url +
    +

    url

    +
    header list +
    +

    A new header list containing a header named +"Content-Type" whose value is "application/json"

    +
    body +
    +

    A body whose source is body.

    +
    referrer +
    +

    "no-referrer"

    +
    client +
    +

    null

    +
    window +
    +

    "no-window"

    +
    service-workers mode +
    +

    "none"

    +
    initiator +
    +

    ""

    +
    mode +
    +

    "cors"

    +
    unsafe-request flag +
    +

    set

    +
    credentials mode +
    +

    "omit"

    +
    cache mode +
    +

    "no-store"

    +
    +
  4. +

    Queue a task to fetch request with processResponse being these steps:

    +
      +
    1. +

      Queue a task to remove report from the attribution report cache.

      +
    +
+

This fetch should use a network partition key for an opaque origin. <https://github.com/WICG/conversion-measurement-api/issues/220>

+

A user agent MAY retry this algorithm in the event that there was an error.

+

12. Security considerations

+ TODO +

13. Privacy consideration

+ TODO +

13.1. Clearing attribution storage

+

A user agent’s attribution caches contain data about a user’s web activity. When a user agent clears an origin’s storage, +it MUST also remove entries in the attribution caches whose source origin, attribution destination, reporting endpoint, attribution destination, or reporting endpoint is the same as the cleared origin.

+

A user agent MAY clear attribution cache entries at other times. For example, when a user agent clears +an origin from a user’s browsing history.

+
+
+

Conformance

+

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. + The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” + in the normative parts of this document + are to be interpreted as described in RFC 2119. + However, for readability, + these words do not appear in all uppercase letters in this specification.

+

All of the text of this specification is normative + except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

+

Examples in this specification are introduced with the words “for example” + or are set apart from the normative text with class="example", like this:

+
This is an example of an informative example.
+

Informative notes begin with the word “Note” + and are set apart from the normative text with class="note", like this:

+

Note, this is an informative note.

+
+ +

Index

+

Terms defined by this specification

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Terms defined by reference

+ +

References

+

Normative References

+
+
[FETCH] +
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/ +
[HTML] +
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/ +
[INFRA] +
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/ +
[PERMISSIONS-POLICY-1] +
Ian Clelland. Permissions Policy. 16 July 2020. WD. URL: https://www.w3.org/TR/permissions-policy-1/ +
[RFC2119] +
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 +
[SECURE-CONTEXTS] +
Mike West. Secure Contexts. 18 September 2021. CR. URL: https://www.w3.org/TR/secure-contexts/ +
[URL] +
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/ +
[WEBIDL] +
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/ +
+

Informative References

+
+
[STORAGE] +
Anne van Kesteren. Storage Standard. Living Standard. URL: https://storage.spec.whatwg.org/ +
+

IDL Index

+
partial interface HTMLAnchorElement {
+    [CEReactions] attribute USVString attributionDestination;
+    [CEReactions] attribute DOMString attributionSourceEventId;
+    [CEReactions] attribute USVString attributionReportTo;
+    [CEReactions] attribute long long attributionExpiry;
+    [CEReactions] attribute long long attributionSourcePriority;
+    [CEReactions] attribute boolean registerAttributionSource;
+};
+
+dictionary AttributionSourceParams {
+  required USVString attributionDestination;
+  required DOMString attributionSourceEventId;
+  USVString attributionReportTo;
+  long long attributionExpiry;
+  long long attributionSourcePriority;
+};
+
+[Exposed=Window, SecureContext]
+interface AttributionReporting {
+  Promise<undefined> registerAttributionSource(AttributionSourceParams params);
+};
+
+[SecureContext]
+partial interface Window {
+  readonly attribute AttributionReporting attributionReporting;
+};
+
+
+

Issues Index

+
+
Should fake reports respect the user agent’s max reports per attribution destination? ↵
+
Formalize how to parse the query similar to URLSearchParams. ↵
+
This would ideally be replaced by a more descriptive algorithm in Infra. See infra/201 ↵
+
This fetch should use a network partition key for an opaque origin. <https://github.com/WICG/conversion-measurement-api/issues/220> ↵
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 09f04f9cacd0fac69ee8b60b9ee55db5fc3bb2c5 Mon Sep 17 00:00:00 2001 From: Andrew Paseltiner Date: Tue, 3 May 2022 11:39:28 -0400 Subject: [PATCH 2/2] Delete index.html --- index.html | 5154 ---------------------------------------------------- 1 file changed, 5154 deletions(-) delete mode 100644 index.html diff --git a/index.html b/index.html deleted file mode 100644 index 573fec920b..0000000000 --- a/index.html +++ /dev/null @@ -1,5154 +0,0 @@ - - - - Attribution Reporting - - - - - - - - - - - - - - - - - -
-

-

Attribution Reporting

-

Draft Community Group Report,

-
-
-
This version: -
https://wicg.github.io/conversion-measurement-api -
Issue Tracking: -
GitHub -
Inline In Spec -
Editors: -
(Google Inc.) -
(Google Inc.) -
(Google Inc.) -
-
-
-

Copyright © 2022 the Contributors to the Attribution Reporting Specification, published by the Web Platform Incubator Community Group under the W3C Community Contributor License Agreement (CLA). -A human-readable summary is available.

-
-
-
-

Abstract

-

An API to report that an event may have been caused by another cross-site event. These reports are designed to transfer little enough data between sites that the sites can’t use them to track individual users.

-
-
-

Status of this document

-
-

This specification was published by the Web Platform Incubator Community Group. - It is not a W3C Standard nor is it on the W3C Standards Track. - - Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. - - Learn more about W3C Community and Business Groups.

-

-
-
- -
-

1. Introduction

-

This section is non-normative

-

This specification describes how web browsers can provide a mechanism to the -web that supports measuring and attributing conversions (e.g. purchases) to ads -a user interacted with on another site. This mechanism should remove one need -for cross-site identifiers like third-party cookies.

-

1.1. Overview

-

A page can register an attribution source on a site by providing attributionsourceeventid and attributiondestination attributes on an a element. -When such an a element is clicked, and the resulting navigation commits in a document within the same site as -the attributiondestination, the attribution source is stored in UA storage.

-

Alternatively, a page can register an attribution source on a site by providing a registerattributionsource attribute on an a element. When such an a element is added -to the page, the attribution source is stored in UA storage.

-

At a later point, the attributiondestination site may fire an HTTP request to -trigger attribution, which matches an attribution trigger with any previously -stored sources. If a matching source exists, it is scheduled to be -reported at a later time, possibly multiple days in the future.

-

Reports are sent to reporting endpoints that are configured in the attribution source -and attribution trigger.

-

2. HTML monkeypatches

-

2.1. long long reflection

-

Add the following rules for reflecting content attributes:

-

If a reflecting IDL attribute has a signed integer type (long long) then, on getting, the content attribute must be -parsed according to the rules for parsing integers, and if that is successful, and the value is in the -range of the IDL attribute’s type, the resulting value must be returned. If, on the other hand, it fails or returns -an out of range value, or if the attribute is absent, then the default value must be returned instead, or 0 if there -is no default value. On setting, the given value must be converted to the shortest possible string representing the -number as a valid integer and then that string must be used as the new content attribute value.

-

If a reflecting IDL attribute has a signed integer type (long long) that is limited to only non-negative numbers then, -on getting, the content attribute must be parsed according to the rules for parsing non-negative integers, and if -that is successful, and the value is in the range of the IDL attribute’s type, the resulting value must be returned. -If, on the other hand, it fails or returns an out of range value, or if the attribute is absent, the default value -must be returned instead, or −1 if there is no default value. On setting, if the value is negative, the user agent -must throw an "IndexSizeError" DOMException. Otherwise, the given value must be converted to the shortest possible -string representing the number as a valid non-negative integer and then that string must be used as the new content -attribute value.

-

2.2. <a> element

-

Add the following content attributes to the a element:

-
-
attributionsourceeventid -
-

Identifies the declared attribution source

-
attributiondestination -
-

Site which can attribute an event to the declared attribution source

-
attributionreportto -
-

origin to receive attribution reports

-
attributionexpiry -
-

Length of time the attribution souce is valid

-
attributionsourcepriority -
-

The priority of this source relative to other sources when triggering attribution

-
registerattributionsource -
-

Registers an attribution source with a source type "event"

-
-

Extend the a element’s DOM interface to include the following interface:

-
partial interface HTMLAnchorElement {
-    [CEReactions] attribute USVString attributionDestination;
-    [CEReactions] attribute DOMString attributionSourceEventId;
-    [CEReactions] attribute USVString attributionReportTo;
-    [CEReactions] attribute long long attributionExpiry;
-    [CEReactions] attribute long long attributionSourcePriority;
-    [CEReactions] attribute boolean registerAttributionSource;
-};
-
-

The IDL attributes attributionDestination, attributionSourceEventId, attributionReportTo, attributionSourcePriority, registerAttributionSource must reflect the respective -content attributes of the same name.

-

The IDL attribute attributionExpiry must reflect the attributionexpiry content attribute, limited to only non-negative numbers.

-

The attributiondestination attribute is a string -representing an origin that is intended to be same site with the origin -of the final navigation URL resulting from running follow the hyperlink with the a element.

-

The attributionsourceeventid attribute is a string -containing information about the attribution source and will be supplied in the attribution report.

-

The attributionreportto attribute optionally declares the origin to send the attribution report for this source.

-

The attributionexpiry attribute optionally defines the amount -of time in milliseconds the attribution source should be considered for reporting.

-

The attributionsourcepriority attribute optionally defines the -priority of a source relative to other sources when triggering attribution. If not specified, 0 is used as the -priority. An attribution trigger with a given reporting endpoint and attribution destination will always be attributed to the source with the highest priority value that has the same reporting endpoint and attribution destination.

-

The registerattributionsource attribute, if present, registers an -additional source whose source type is "event".

-

Note: One simple priority scheme would be to use the current millisecond timestamp as the priority value.

-

2.3. Navigation

-

This section ensures that an attribution source associated with a navigation -results in a top-level navigation whose final URL is same site with the attribution destination.

-

2.3.1. Navigation Params

-

A navigation params struct has an item:

-
-
attribution source -
-

null or an attribution source declared when initiating a navigation

-
-

2.3.2. Navigate algorithm

-

Modify the navigate algorithm to accept a new optional parameter attributionSource of type attribution source defaulting to null.

-

In navigate, within step

-
-
    -
  1. -

    This is the step that attempts to obtain resource, if necessary. Jump to the first appropriate substep: -...

    -
-
-

in the case where

-
-

If resource is a response

-
-

modify the substep

-
-
    -
  1. -

    Let navigationParams be a new navigation params whose request is null, response is resource -...

    -
-
-

to set the attribution source of navigationParams to attributionSource.

-

In the case where

-
-

If resource is a request whose URL’s scheme is "javascript"

-
-

modify the substep

-
-
    -
  1. -

    Let navigationParams be a new navigation params whose request is resource, -...

    -
-
-

to set the attribution source of navigationParams to attributionSource.

-

In the case where

-
-

If resource is a request whose URL’s scheme is a fetch scheme

-
-

modify the substep to pass attributionSource to the process a navigate fetch algorithm.

-

Note: The final case, where the request is not a javascript or fetch scheme, does not need to be handled - as it will not result in the navigation of a top-level browsing context.

-

2.3.3. Process a navigate fetch

-

Modify the process a navigate fetch algorithm to accept a new optional parameter attributionSource of type attribution source defaulting to null.

-

In process a navigate fetch, modify the step

-
-
    -
  1. -

    Otherwise, if locationURL is a URL whose scheme is a fetch scheme, then run process a navigate fetch with a new request -...

    -
-
-

to also pass attributionSource into the process a navigate fetch algorithm.

-

Modify the step

-
-
    -
  1. -

    Let navigationParams be a new navigation params whose request is request, response is response, -...

    -
-
-

to set the attribution source of navigationParams to attributionSource.

-

2.3.4. Document creation

-

At the time create and initialize a Document object is invoked, the user agent knows the final URL used for the -navigation and can validate the attribution destination.

-

In create and initialize a Document object, before

-
-
    -
  1. -

    Let permissionsPolicy be the result of creating a permissions policy from a response given browsingContext -...

    -
-
-

add the following step:

-
    -
  1. -

    Execute maybe process a navigation attribution source with navigationParams and browsingContext.

    -
- -

Attribution source information declared on the a element needs to be passed to the navigate algorithm.

-

In follow the hyperlink after

-
-
    -
  1. -

    Let historyHandling be "replace" if windowType is not "existing or none"; otherwise, "default".

    -
-
-

add the following steps:

-
    -
  1. -

    Let attributionSource be null.

    -
  2. -

    If subject is an a element, set attributionSource to the result of running obtain an attribution source from an anchor with subject.

    -
-

Modify the step:

-
-
    -
  1. -

    Queue an element task on the DOM manipulation task source given subject to navigate target to request -...

    -
-
-

to call navigate with attributionSource set to attributionSource.

-

3. Fetch monkeypatches

-

In main fetch, within the step:

-
-
    -
  1. -

    If response is not a network error and any of the following returns blocked -...

    -
-
-

add the following check to the list:

- -

4. Attribution Reporting API

-
dictionary AttributionSourceParams {
-  required USVString attributionDestination;
-  required DOMString attributionSourceEventId;
-  USVString attributionReportTo;
-  long long attributionExpiry;
-  long long attributionSourcePriority;
-};
-
-[Exposed=Window, SecureContext]
-interface AttributionReporting {
-  Promise<undefined> registerAttributionSource(AttributionSourceParams params);
-};
-
-[SecureContext]
-partial interface Window {
-  readonly attribute AttributionReporting attributionReporting;
-};
-
-

The registerAttributionSource(params) method steps are:

-
    -
  1. -

    Let source be the result of running obtain an attribution source from params with params and the relevant settings object of this.

    -
  2. -

    If source is null, return a promise rejected with the undefined value.

    -
  3. -

    Set source to the result of running obtain an event attribution source from a source with source.

    -
  4. -

    Queue a task to process an attribution source with source.

    -
  5. -

    Return a promise resolved with the undefined value.

    -
-

Note: This function returns a promise even though the promise is always resolved or rejected by the -time the function returns; in the future, the promise may be resolved with a value that provides -finer-grained detail about other errors that occurred during the process an attribution source step.

-

5. Permissions Policy integration

- This specification defines a policy-controlled feature identified by the string "attribution-reporting". Its default allowlist is *. -

6. Structures

-

6.1. Attribution mode

-

An attribution mode is a tuple consisting of a mode and a random trigger data. The mode is -either "truthfully", "never", or "falsely". The random trigger data is a non-negative 64-bit -integer, if the mode is "falsely", or null otherwise.

-

6.2. Attribution source

-

An attribution source is a struct with the following items:

-
-
source identifier -
-

A string.

-
source origin -
-

An origin.

-
event id -
-

A non-negative 64-bit integer.

-
attribution destination -
-

A site.

-
reporting endpoint -
-

An origin.

-
source type -
-

Either "navigation" or "event".

-
expiry -
-

A length of time.

-
priority -
-

A 64-bit integer.

-
source time -
-

A point in time.

-
number of reports -
-

Number of attribution reports created for this attribution source.

-
dedup keys -
-

ordered set of dedup keys associated with this attribution source.

-
attribution mode -
-

An attribution mode.

-
randomized trigger rate -
-

A number between 0 and 1 (both inclusive).

-
-

6.3. Attribution trigger

-

An attribution trigger is a struct with the following items:

-
-
attribution destination -
-

A site.

-
navigation-source trigger data -
-

A non-negative 64-bit integer.

-
event-source trigger data -
-

A non-negative 64-bit integer.

-
trigger time -
-

A point in time.

-
reporting endpoint -
-

An origin.

-
dedup key -
-

Null or a 64-bit integer.

-
priority -
-

A 64-bit integer.

-
-

6.4. Attribution report

-

An attribution report is a struct with the following items:

-
-
event id -
-

A non-negative 64-bit integer.

-
source type -
-

Either "navigation" or "event".

-
trigger data -
-

A non-negative 64-bit integer.

-
randomized trigger rate -
-

A number between 0 and 1 (both inclusive).

-
reporting endpoint -
-

An origin.

-
attribution destination -
-

A site.

-
report time -
-

A point in time.

-
trigger priority -
-

A 64-bit integer.

-
trigger time -
-

A point in time.

-
source identifier -
-

A string.

-
delivered (default false) -
-

A boolean.

-
report id -
-

A string.

-
-

6.5. Attribution rate-limit record

-

An attribution rate-limit record is a struct with the following items:

-
-
source site -
-

A site.

-
attribution destination -
-

A site.

-
source type -
-

Either "navigation" or "event".

-
trigger time -
-

A point in time.

-
-

7. Storage

-

A user agent holds an attribution source cache, which is an ordered set of attribution sources.

-

A user agent holds an attribution report cache, which is an ordered set of attribution reports.

-

A user agent holds an attribution rate-limit cache, which is an ordered set of attribution rate-limit records.

-

The above caches are collectively known as the attribution caches. The attribution caches are -shared among all environment settings objects.

-

Note: This would ideally use storage bottles to provide access to the attribution caches. -However attribution data is inherently cross-site, and operations on storage would need to span across all storage bottle maps.

-

8. General Algorithms

-

8.1. Obtaining a randomized response

-

To obtain a randomized response given trueValue, a set possibleValues, and a -double randomPickRate:

-
    -
  1. -

    Assert: randomPickRate is between 0 and 1 (both inclusive).

    -
  2. -

    Let r be a random double between 0 (inclusive) and 1 (exclusive) with uniform probability.

    -
  3. -

    If r is less than randomPickRate, return a random item from possibleValues with uniform -probability.

    -
  4. -

    Otherwise, return trueValue.

    -
-

9. Source Algorithms

-

9.1. Obtaining an attribution source’s expiry time

-

An attribution source source’s expiry time is source’s source time + source’s expiry.

-

9.2. Parsing data fields

-

This section defines how to parse strings into integers for event id, navigation-source trigger data, and event-source trigger data.

-

To parse attribution data given a string input modulo an integer maxData perform the following steps. They return a non-negative integer:

-
    -
  1. -

    Let decodedInput be the result of applying the rules for parsing non-negative integers to input.

    -
  2. -

    If decodedInput is an error, return zero.

    -
  3. -

    If decodedInput is greater than 264, return zero.

    -
  4. -

    Let clampedDecodedInput be the remainder when dividing decodedInput by maxData.

    -
  5. -

    Return clampedDecodedInput.

    -
-

9.3. Parsing an attribution destination

-

To parse an attribution destination from a string str:

-
    -
  1. -

    Let url be the result of running the URL parser on the value of -the str.

    -
  2. -

    If url is failure or null, return null.

    -
  3. -

    If url’s origin is an opaque origin, return null.

    -
  4. -

    Return the result of obtaining a site from url’s origin.

    -
-

9.4. Obtaining a random attribution mode

-

To obtain a random attribution mode given a positive integer triggerDataCardinality and a double randomPickRate:

-
    -
  1. -

    Let possibleValues be the set of attribution modes « ("never", null) ».

    -
  2. -

    For each integer i between 0 (inclusive) and triggerDataCardinality (exclusive):

    -
      -
    1. -

      Append the attribution mode ("falsely", i) to possibleValues.

      -
    -
  3. -

    Return the result of obtaining a randomized response with the attribution mode ("truthfully", null), possibleValues, and randomPickRate.

    -
-

9.5. Obtaining an attribution source from an a element

-

To obtain an attribution source from an anchor given an a element anchor:

-
    -
  1. -

    If anchor does not have both an attributiondestination attribute and an attributionsourceeventid attribute, return null.

    -
  2. -

    Let params be an AttributionSourceParams with the following key/value pairs:

    -
    -
    attributionDestination -
    -

    anchor’s attributiondestination attribute

    -
    attributionSourceEventId -
    -

    anchor’s attributionsourceeventid attribute

    -
    attributionReportTo -
    -

    anchor’s attributionreportto attribute

    -
    attributionExpiry -
    -

    anchor’s attributionexpiry attribute

    -
    attributionSourcePriority -
    -

    anchor’s attributionsourcepriority attribute

    -
    -
  3. -

    Return the result of running obtain an attribution source from params with params and anchor’s relevant settings object.

    -
-

9.6. Obtaining an event attribution source from an a element

-

To obtain an event attribution source from an anchor given an a element anchor, run the following steps:

-
    -
  1. -

    If anchor does not have a registerattributionsource attribute, return null.

    -
  2. -

    Let source be the result of running obtain an attribution source from an anchor with anchor.

    -
  3. -

    If source is null, return null.

    -
  4. -

    Return the result of running obtain an event attribution source from a source with source.

    -
-

9.7. Obtaining an event attribution source from a source

-

To obtain an event attribution source from a source given an attribution source source, run the following steps:

-
    -
  1. -

    Let resultSource be a shallow clone of source.

    -
  2. -

    Set resultSource’s source identifier to a new unique opaque string.

    -
  3. -

    Set resultSource’s source type to "event".

    -
  4. -

    Round resultSource’s expiry away from zero to the nearest day (86400 seconds).

    -
  5. -

    Set resultSource’s attribution mode to the result of obtaining a random attribution mode with the user agent’s event-source trigger data cardinality and the user agent’s randomized event-source trigger rate.

    -
  6. -

    Set resultSource’s randomized trigger rate to the user agent’s randomized event-source trigger rate.

    -
  7. -

    Return resultSource.

    -
-

Randomized event-source trigger rate is a vendor-specific double between 0 and 1 (both -inclusive) that controls the randomized response probability for the attribution mode of an attribution source whose source type is "event".

-

9.8. Obtaining an attribution source from AttributionSourceParams

-

To obtain an attribution source from params given an AttributionSourceParams params and an environment settings object settings, run the following steps:

-
    -
  1. -

    Let sourceIdentifier be a new unique string.

    -
  2. -

    Let currentTime be the current time.

    -
  3. -

    Assert: params["attributionDestination"] and params["attributionSourceEventId"] exist.

    -
  4. -

    If settings’s relevant global object's associated Document is -not allowed to use the attribution-reporting policy-controlled feature, return null.

    -
  5. -

    Let attributionDestination be the result of running parse an attribution destination with params["attributionDestination"].

    -
  6. -

    If attributionDestination is null, return null.

    -
  7. -

    Let sourceOrigin be settings’s top-level origin.

    -
  8. -

    If sourceOrigin is an opaque origin, return null.

    -
  9. -

    Let reportingOrigin be sourceOrigin.

    -
  10. -

    If params["attributionReportTo"] exists, then:

    -
      -
    1. -

      Let reportingUrl be the result of running the URL parser with params["attributionReportTo"].

      -
    2. -

      If reportingUrl is failure or null, return null.

      -
    3. -

      If reportingUrl’s origin is an opaque origin, return null.

      -
    4. -

      Set reportingOrigin to reportingUrl’s origin.

      -
    -
  11. -

    Let expiry be 30 days.

    -
  12. -

    If params["attributionExpiry"] exists, -then set expiry to that value.

    -
  13. -

    Let priority be 0.

    -
  14. -

    If params["attributionSourcePriority"] exists, -then set priority to that value.

    -
  15. -

    Let source be a new attribution source struct whose items are:

    -
    -
    source identifier -
    -

    sourceIdentifier

    -
    source origin -
    -

    sourceOrigin

    -
    event id -
    -

    The result of running parse attribution data with params["attributionSourceEventId"] modulo max event id value.

    -
    attribution destination -
    -

    attributionDestination

    -
    reporting endpoint -
    -

    reportingOrigin

    -
    expiry -
    -

    expiry

    -
    priority -
    -

    priority

    -
    source time -
    -

    currentTime

    -
    source type -
    -

    "navigation"

    -
    attribution mode -
    -

    ("truthfully", null)

    -
    randomized trigger rate -
    -

    0

    -
    -
  16. -

    Return source.

    -
-

Max event id value is a vendor-specific integer which controls -the maximum value which can be used as an event id.

-

9.9. Processing an attribution source

-

To maybe process a navigation attribution source given a navigation params navigationParams and browsing context browsingContext, run the following steps:

-
    -
  1. -

    If browsingContext is not a top-level browsing context, return.

    -
  2. -

    Let attributionSource be navigationParams’s attribution source.

    -
  3. -

    If attributionSource is null, return.

    -
  4. -

    If attributionSource’s attribution destination is not same site to navigationParams’s origin, return.

    -
  5. -

    Queue a task to process an attribution source with attributionSource.

    -
-

To process an attribution source given an attribution source source:

-
    -
  1. -

    Let cache be the user agent’s attribution source cache.

    -
  2. -

    Remove all entries in cache where all of the following are true:

    - -

    Note: This causes the user agent to favor triggering newer attribution sources over sources that have already been triggered.

    -
  3. -

    Remove all entries in cache where the entry’s expiry time is less than the current time.

    -
  4. -

    If the size of cache is greater than or equal to the user agent’s max source cache size, return.

    -
  5. -

    If source’s attribution mode[0] is "falsely", then:

    -
      -
    1. -

      Assert: source’s source type is "event".

      -
    2. -

      If the size of the attribution report cache is greater than or equal to the user -agent’s max report cache size, return.

      -
    3. -

      Let fakeTrigger be a new attribution trigger with the items:

      -
      -
      attribution destination -
      -

      source’s attribution destination

      -
      navigation-source trigger data -
      -

      0

      -
      event-source trigger data -
      -

      source’s attribution mode[1]

      -
      trigger time -
      -

      source’s source time

      -
      reporting endpoint -
      -

      source’s reporting endpoint

      -
      dedup key -
      -

      null

      -
      priority -
      -

      0

      -
      -
    4. -

      Let fakeReport be the result of running obtain a report with source and fakeTrigger.

      -
    5. -

      Add fakeReport to the attribution report cache.

      -
    6. -

      Return.

      -
    -
  6. -

    Append source to cache.

    -
-

Should fake reports respect the user agent’s max reports per attribution destination?

-

Max source cache size is a vendor-specific integer which controls how many attribution sources can be in the attribution source cache.

-

10. Triggering Algorithms

-

10.1. Creating an attribution trigger

-

To obtain an attribution trigger given a URL url and an environment settings object environment, run the following steps:

-
    -
  1. -

    Let navigationSourceTriggerData be 0.

    -
  2. -

    If url’s query has a "trigger-data" field, set navigationSourceTriggerData to the result of running parse attribution data with -the value associated with the field modulo the user agent’s trigger data cardinality.

    -
  3. -

    Let eventSourceTriggerData be 0.

    -
  4. -

    If url’s query has an "event-source-trigger-data" field, set eventSourceTriggerData to the result of running parse attribution data with -the value associated with the field modulo the user agent’s event-source trigger data cardinality.

    -
  5. -

    Let dedupKey be null.

    -
  6. -

    If url’s query has a "dedup-key" field, and applying the rules for -parsing integers to the field’s value results in an integer, then set dedupKey to that -value.

    -
  7. -

    Let triggerPriority be 0.

    -
  8. -

    If url’s query has a "priority" field, and applying the rules for parsing integers to the field’s value results -in an integer, set triggerPriority to that value.

    -
  9. -

    Let trigger be a new attribution trigger with the items:

    -
    -
    attribution destination -
    -

    The result of obtaining a site from environment’s top-level origin.

    -
    navigation-source trigger data -
    -

    navigationSourceTriggerData.

    -
    event-source trigger data -
    -

    eventSourceTriggerData.

    -
    trigger time -
    -

    The current time.

    -
    reporting endpoint -
    -

    url’s origin.

    -
    dedup key -
    -

    dedupKey.

    -
    priority -
    -

    triggerPriority.

    -
    -
  10. -

    Return trigger.

    -
-

Trigger data cardinality is a vendor-specific integer that controls the valid range of navigation-source trigger data: -0 <= navigation-source trigger data < trigger data cardinality.

-

Event-source trigger data cardinality is a vendor-specific integer that controls the valid -range of event-source trigger data: -0 <= event-source trigger data < event-source trigger data cardinality.

-

Formalize how to parse the query similar to URLSearchParams.

-

10.2. Should internalResponse to request be blocked as attribution trigger

-

Given a request request:

-
    -
  1. -

    If request’s current URL’s origin is an opaque origin, return allowed.

    -
  2. -

    If request’s current URL’s path is not equal to « ".well-known","attribution-reporting","trigger-attribution" », -return allowed.

    -
  3. -

    Let environment be request’s window.

    -
  4. -

    If environment is not an environment settings object, return allowed.

    -
  5. -

    If environment’s relevant global object's associated Document is not allowed to use the attribution-reporting policy-controlled feature, -return allowed.

    -
  6. -

    If environment’s origin is not a potentially trustworthy origin, return allowed.

    -
  7. -

    If environment’s top-level origin is an opaque origin, return allowed.

    -
  8. -

    If environment’s top-level origin is not a potentially trustworthy origin, return allowed.

    -
  9. -

    If request’s current URL’s origin is not a potentially trustworthy origin, return allowed.

    -
  10. -

    If request’s redirect count is less than 1, return allowed.

    -
  11. -

    Let previousUrl be the second to last URL in request’s URL list.

    -
  12. -

    If request’s current URL’s origin is not same origin with previousUrl’s origin, return allowed.

    -

    Note: The restriction to require a redirect is necessary to ensure that the - request’s origin is aware and in control of the conversion registration. This could also be done with a header-based mechanism.

    -
  13. -

    Let trigger be the result of running obtain an attribution trigger with request’s current URL and environment.

    -
  14. -

    Queue a task to trigger attribution with trigger.

    -
  15. -

    Return blocked.

    -
-

10.3. Should attribution be blocked by rate limit

-

Given an attribution trigger trigger and attribution source sourceToAttribute:

-
    -
  1. -

    Let sourceSite be the result of obtaining a site from sourceToAttribute’s source origin.

    -
  2. -

    Let matchingRateLimitRecords be all entries in the attribution rate-limit cache where all of the following are true:

    - -
  3. -

    If the size of matchingRateLimitRecords is greater than or equal to max attributions per rate-limit window, return blocked.

    -
  4. -

    Return allowed.

    -
-

Attribution rate-limit window is a vendor-specific duration that controls the -rate-limiting window for attribution.

-

Max attributions per rate-limit window is a vendor-specific integer that controls -the maximum number of attributions for a (source site, attribution destination, source type) per attribution rate-limit window.

-

10.4. Triggering attribution

-

To trigger attribution given an attribution trigger trigger run the following steps:

-
    -
  1. -

    Let attributionDestination be trigger’s attribution destination.

    -
  2. -

    Let matchingSources be all entries in the attribution source cache where all of the following are true:

    - -
  3. -

    If matchingSources is empty, return.

    -
  4. -

    Set matchingSources to the result of sorting matchingSources in descending order, with a being less than b if any of the following are true:

    - -
  5. -

    Let sourceToAttribute be the first item in matchingSources.

    -
  6. -

    Assert: sourceToAttribute’s attribution mode[0] is -"truthfully" or "never".

    -
  7. -

    If trigger’s dedup key is not null and sourceToAttribute’s dedup keys contains it, return.

    -
  8. -

    Let numMatchingReports be the number of entries in the attribution report cache whose attribution destination equals attributionDestination.

    -
  9. -

    If numMatchingReports is greater than or equal to the user agent’s max reports per attribution destination, return.

    -
  10. -

    If the result of running should attribution be blocked by rate limit with trigger and sourceToAttribute is blocked, return.

    -
  11. -

    Let report be the result of running obtain a report with sourceToAttribute and trigger.

    -
  12. -

    If sourceToAttribute’s number of reports value is equal to the -user agent’s max reports per source value, then:

    -
      -
    1. -

      Let matchingReports be all entries in the attribution report cache where all of the following are true:

      - -
    2. -

      If matchingReports is empty, then remove sourceToAttribute from the attribution source cache and return.

      -
    3. -

      Set matchingReports to the result of sorting matchingReports in ascending order, with a being less than b if any of the following are true:

      - -
    4. -

      Let lowestPriorityReport be the first item in matchingReports.

      -
    5. -

      If report’s trigger priority is less than or equal to lowestPriorityReport’s trigger priority, return.

      -
    6. -

      Remove lowestPriorityReport from the attribution report cache.

      -
    7. -

      Decrement sourceToAttribute’s number of reports value by 1.

      -
    -
  13. -

    Remove sourceToAttribute from matchingSources.

    -
  14. -

    For each item of matchingSources:

    -
      -
    1. -

      Remove item from the attribution source cache.

      -
    -
  15. -

    If the size of the attribution report cache is greater than or equal to the user -agent’s max report cache size, return.

    -
  16. -

    If sourceToAttribute’s attribution mode[0] is "truthfully", -add report to the attribution report cache.

    -
  17. -

    Increment sourceToAttribute’s number of reports value by 1.

    -
  18. -

    If trigger’s dedup key is not null, append it to sourceToAttribute’s dedup keys.

    -
  19. -

    Let rateLimitRecord be a new attribution rate-limit record with the items:

    -
    -
    source site -
    -

    The result of obtaining a site from sourceToAttribute’s source origin.

    -
    attribution destination -
    -

    attributionDestination

    -
    source type -
    -

    sourceToAttribute’s source type

    -
    trigger time -
    -

    trigger’s trigger time

    -
    -
  20. -

    Add rateLimitRecord to the attribution rate-limit cache.

    -
  21. -

    Remove all entries from the attribution rate-limit cache whose trigger time is at least attribution rate-limit window before the current time.

    -
-

Max reports per attribution destination is a vendor-specific integer which controls how -many attribution reports can be in the attribution report cache for an attribution destination.

-

Max reports per source is a vendor-specific integer which controls how many attribution reports can be created for an attribution source.

-

Max report cache size is a vendor-specific integer which controls how many attribution reports can be in the attribution report cache.

-

Note: This parameter represents a privacy/utility tradeoff. Lower values mean that less trigger-side data -can be associated with a source event id. Larger values allow for more attribution triggers to be reported.

-

10.5. Establishing report delivery time

-

To obtain a report delivery time given an attribution source source and a trigger time triggerTime, perform the following steps. They -return a point in time.

-
    -
  1. -

    If source’s source type is "event", return source’s expiry time + 1 hour.

    -
  2. -

    Let timeToTrigger be the difference between triggerTime and source time.

    -

    Note: timeToTrigger is less than source’s expiry because it is not normally possible to -convert an expired attribution source.

    -
  3. -

    If:

    -
    -
    timeToTrigger <= (2 days - 1 hour) -
    return source time + 2 days. -
    - source’s expiry > (2 days - 1 hour) -
      -
    • -

      and source’s expiry < (7 days - 1 hour)

      -
    • -

      and timeToTrigger <= source’s expiry

      -
    -
    return source’s expiry time + 1 hour. -
    timeToTrigger <= (7 days - 1 hour) -
    return source time + 7 days. -
    Otherwise -
    return source’s expiry time + 1 hour. -
    -
-

10.6. Obtaining a report

-

To obtain a report given an attribution source source and an attribution trigger trigger:

-
    -
  1. -

    Let triggerData be trigger’s trigger data.

    -
  2. -

    If source’s source type is "event", set triggerData to trigger’s event source trigger data.

    -
  3. -

    Let report be a new attribution report struct whose items are:

    -
    -
    event id -
    -

    source’s event id.

    -
    trigger data -
    -

    triggerData.

    -
    randomized trigger rate -
    -

    source’s randomized trigger rate.

    -
    reporting endpoint -
    -

    source’s reporting endpoint.

    -
    attribution destination -
    -

    source’s attribution destination.

    -
    reporting time -
    -

    The result of running obtain a report delivery time with source and trigger’s trigger time.

    -
    trigger priority -
    -

    trigger’s priority.

    -
    trigger time -
    -

    trigger’s trigger time.

    -
    source identifier -
    -

    source’s source identifier.

    -
    report id -
    -

    The result of generating a random UUID.

    -
    -
  4. -

    Return report.

    -
-

11. Report delivery

-

The user agent MUST periodically iterate over its attribution report cache and run queue a report for delivery on each item.

-

To queue a report for delivery given an attribution report report, run the following steps in parallel:

-
    -
  1. -

    If report’s delivered value is true, return.

    -
  2. -

    Set report’s delivered value to true.

    -
  3. -

    If report’s report time is less than the current time, add an implementation-defined random amount to report time.

    -

    Note: On startup, it is possible the user agent will need to send many reports whose report times passed while the browser was - closed. Adding random delay prevents temporal joining of reports from different source origins.

    -
  4. -

    Wait until report’s report time is the current time.

    -
  5. -

    Optionally, wait a further implementation-defined length of time.

    -

    Note: This is intended to allow user agents to optimize device resource usage.

    -
  6. -

    Run attempt to deliver a report with report.

    -
-

11.1. Serialize an integer

-

To serialize an integer, represent it as a string of the shortest possible decimal number.

-

This would ideally be replaced by a more descriptive algorithm in Infra. See infra/201

-

11.2. Serialize attribution report body

-

To serialize an attribution report report, run the following steps:

-
    -
  1. -

    Let destination be report’s attribution destination.

    -
  2. -

    Assert: destination is not an opaque origin.

    -
  3. -

    Let data be a map of the following key/value pairs:

    -
    -
    "attribution_destination" -
    -

    destination, serialized

    -
    "randomized_trigger_rate" -
    -

    report’s randomized trigger rate

    -
    "source_type" -
    -

    report’s source type

    -
    "source_event_id" -
    -

    report’s event id, serialized

    -
    "trigger_data" -
    -

    report’s trigger data, serialized

    -
    "report_id" -
    -

    report’s report id

    -
    -
  4. -

    Return the byte sequence resulting from executing serialize an infra value to JSON bytes on data.

    -
-

Note: The inclusion of "report_id" in the report body is intended to allow the report recipient -to perform deduplication and prevent double counting, in the event that the user agent retries -reports on failure. To prevent the report recipient from learning additional information about -whether a user is online, retries should be limited in number and subject to random delays.

-

11.3. Get report request URL

-

To generate a report URL for a given attribution report report, run the following steps:

-
    -
  1. -

    Let reportUrl be a new URL record.

    -
  2. -

    Let reportingOrigin be report’s reporting endpoint.

    -
  3. -

    Assert: reportingOrigin is not an opaque origin.

    -
  4. -

    Set reportUrl’s scheme to reportingOrigin’s scheme.

    -
  5. -

    Set reportUrl’s host to reportingOrigin’s host.

    -
  6. -

    Set reportUrl’s port to reportingOrigin’s port.

    -
  7. -

    Set reportUrl’s path to «".well-known", "attribution-reporting", "report-attribution"».

    -
  8. -

    Return reportUrl.

    -
-

11.4. Issuing a report request

-

This algorithm constructs a request and attempts to deliver it to report’s reporting endpoint.

-

To attempt to deliver a report given an attribution report report, run the following steps:

-
    -
  1. -

    Let body be the result of executing serialize an attribution report on report.

    -
  2. -

    Let url be the result of executing generate a report URL on report.

    -
  3. -

    Let request be a new request with the following properties:

    -
    -
    method -
    -

    "POST"

    -
    url -
    -

    url

    -
    header list -
    -

    A new header list containing a header named -"Content-Type" whose value is "application/json"

    -
    body -
    -

    A body whose source is body.

    -
    referrer -
    -

    "no-referrer"

    -
    client -
    -

    null

    -
    window -
    -

    "no-window"

    -
    service-workers mode -
    -

    "none"

    -
    initiator -
    -

    ""

    -
    mode -
    -

    "cors"

    -
    unsafe-request flag -
    -

    set

    -
    credentials mode -
    -

    "omit"

    -
    cache mode -
    -

    "no-store"

    -
    -
  4. -

    Queue a task to fetch request with processResponse being these steps:

    -
      -
    1. -

      Queue a task to remove report from the attribution report cache.

      -
    -
-

This fetch should use a network partition key for an opaque origin. <https://github.com/WICG/conversion-measurement-api/issues/220>

-

A user agent MAY retry this algorithm in the event that there was an error.

-

12. Security considerations

- TODO -

13. Privacy consideration

- TODO -

13.1. Clearing attribution storage

-

A user agent’s attribution caches contain data about a user’s web activity. When a user agent clears an origin’s storage, -it MUST also remove entries in the attribution caches whose source origin, attribution destination, reporting endpoint, attribution destination, or reporting endpoint is the same as the cleared origin.

-

A user agent MAY clear attribution cache entries at other times. For example, when a user agent clears -an origin from a user’s browsing history.

-
-
-

Conformance

-

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. - The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” - in the normative parts of this document - are to be interpreted as described in RFC 2119. - However, for readability, - these words do not appear in all uppercase letters in this specification.

-

All of the text of this specification is normative - except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

-

Examples in this specification are introduced with the words “for example” - or are set apart from the normative text with class="example", like this:

-
This is an example of an informative example.
-

Informative notes begin with the word “Note” - and are set apart from the normative text with class="note", like this:

-

Note, this is an informative note.

-
- -

Index

-

Terms defined by this specification

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Terms defined by reference

- -

References

-

Normative References

-
-
[FETCH] -
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/ -
[HTML] -
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/ -
[INFRA] -
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/ -
[PERMISSIONS-POLICY-1] -
Ian Clelland. Permissions Policy. 16 July 2020. WD. URL: https://www.w3.org/TR/permissions-policy-1/ -
[RFC2119] -
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 -
[SECURE-CONTEXTS] -
Mike West. Secure Contexts. 18 September 2021. CR. URL: https://www.w3.org/TR/secure-contexts/ -
[URL] -
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/ -
[WEBIDL] -
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/ -
-

Informative References

-
-
[STORAGE] -
Anne van Kesteren. Storage Standard. Living Standard. URL: https://storage.spec.whatwg.org/ -
-

IDL Index

-
partial interface HTMLAnchorElement {
-    [CEReactions] attribute USVString attributionDestination;
-    [CEReactions] attribute DOMString attributionSourceEventId;
-    [CEReactions] attribute USVString attributionReportTo;
-    [CEReactions] attribute long long attributionExpiry;
-    [CEReactions] attribute long long attributionSourcePriority;
-    [CEReactions] attribute boolean registerAttributionSource;
-};
-
-dictionary AttributionSourceParams {
-  required USVString attributionDestination;
-  required DOMString attributionSourceEventId;
-  USVString attributionReportTo;
-  long long attributionExpiry;
-  long long attributionSourcePriority;
-};
-
-[Exposed=Window, SecureContext]
-interface AttributionReporting {
-  Promise<undefined> registerAttributionSource(AttributionSourceParams params);
-};
-
-[SecureContext]
-partial interface Window {
-  readonly attribute AttributionReporting attributionReporting;
-};
-
-
-

Issues Index

-
-
Should fake reports respect the user agent’s max reports per attribution destination? ↵
-
Formalize how to parse the query similar to URLSearchParams. ↵
-
This would ideally be replaced by a more descriptive algorithm in Infra. See infra/201 ↵
-
This fetch should use a network partition key for an opaque origin. <https://github.com/WICG/conversion-measurement-api/issues/220> ↵
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file