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

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.

trigger data

A non-negative 64-bit integer.

event source trigger data

A non-negative 64-bit integer.

randomized trigger data rate

A number between 0 and 1 (both inclusive).

randomized event-source trigger data rate

A number between 0 and 1 (both inclusive).

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 data rate

A number between 0 and 1 (both inclusive).

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, 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 responsible 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

      trigger data

      0

      event source trigger data

      source’s attribution mode[1]

      randomized trigger data rate

      The user agent’s randomized trigger data rate.

      randomized event-source trigger data rate

      The user agent’s randomized event-source trigger data rate.

      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. Noising trigger data

This section defines how to noise trigger data and event source trigger data.

To noise trigger data given an integer input, integer cardinality, and double randomPickRate, run the following steps:

  1. Let possibleValues be a set containing the integers between 0 (inclusive) and cardinality (exclusive).

  2. Return the result of obtaining a randomized response with input, possibleValues, and randomPickRate.

10.2. 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 triggerData be 0.

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

  3. Set triggerData to the result of running noise trigger data with triggerData, the user agent’s trigger data cardinality, and the user agent’s randomized trigger data rate.

  4. Let eventSourceTriggerData be 0.

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

  6. Set eventSourceTriggerData to the result of running noise trigger data with eventSourceTriggerData, the user agent’s event-source trigger data cardinality, and the user agent’s randomized event-source trigger data rate.

  7. Let dedupKey be null.

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

  9. Let triggerPriority be 0.

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

  11. Let trigger be a new attribution trigger with the items:

    attribution destination

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

    trigger data

    triggerData.

    event source trigger data

    eventSourceTriggerData.

    randomized trigger data rate

    The user agent’s randomized trigger data rate.

    randomized event-source trigger data rate

    The user agent’s randomized event-source trigger data rate.

    trigger time

    The current time.

    reporting endpoint

    url’s origin.

    dedup key

    dedupKey.

    priority

    triggerPriority.

  12. Return trigger.

Trigger data cardinality is a vendor-specific integer that controls the valid range of trigger data: 0 <= 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.

Randomized trigger data rate is a vendor-specific double between 0 and 1 (both inclusive) that controls the randomized response probability for trigger data.

Randomized event-source trigger data rate is a vendor-specific double between 0 and 1 (both inclusive) that controls the randomized response probability for event source trigger data.

Formalize how to parse the query similar to URLSearchParams.

10.3. 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 responsible 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.4. 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.5. 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.6. 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.7. 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. Let randomizedTriggerDataRate be trigger’s randomized trigger data rate.

  3. If source’s source type is "event":

    1. Set triggerData to trigger’s event source trigger data.

    2. Set randomizedTriggerDataRate to trigger’s randomized event-source trigger data rate.

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

    event id

    source’s event id.

    trigger data

    triggerData.

    randomized trigger data rate

    randomizedTriggerDataRate.

    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.

  5. 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_data_rate"

    report’s randomized trigger data rate

    "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. [Issue #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

Document conventions

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.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

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://datatracker.ietf.org/doc/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. [Issue #220]