api.bs

<pre class=metadata>
Title: Attribution Level 1
Shortname: attribution
Repository: w3c/attribution
URL: https://w3c.github.io/attribution/
Status: w3c/WD
Group: patwg
TR: https://www.w3.org/TR/attribution/
Editor: Andrew Paseltiner, w3cid 131329, Google https://www.google.com/, apaseltiner@chromium.org
Editor: Andy Leiserson, w3cid 147715, Mozilla https://mozilla.org/, aleiserson@mozilla.com
Editor: Benjamin Case, w3cid 128082, Meta https://www.meta.com/, bmcase@meta.com
Editor: Benjamin Savage, w3cid 114877, Meta https://www.meta.com/, btsavage@meta.com
Editor: Charlie Harrison, w3cid 110615, Google https://www.google.com/, csharrison@chromium.org
Editor: Martin Thomson, w3cid 68503, Mozilla https://mozilla.org/, mt@mozilla.com
Abstract: This specifies a browser API for the measurement of advertising performance.  The goal is to produce aggregate statistics about how advertising leads to conversions, without creating a risk to the privacy of individual web users.  This API collates information about people from multiple web origins, which could be a significant risk to their privacy.  To manage this risk, the information that is gathered is aggregated using an aggregation service that is trusted by the user-agent to perform aggregation within strict limits.  Noise is added to the aggregates produced by this service to provide differential privacy. Websites may select an aggregation service from the list of approved aggregation services provided by the user-agent.
Complain About: accidental-2119 yes, missing-example-ids yes
Markup Shorthands: markdown yes, css no, dfn yes
Assume Explicit For: yes
Org: W3C
Level: None
</pre>


# Introduction # {#intro}

This document defines a simple API for browsers
that enables the collection of aggregated, differentially-private metrics.

The goal of this API is to enable attribution for advertising.


## Attribution ## {#s-attribution}

In advertising, <dfn id=concept-attribution lt=attribution|attributed>attribution</dfn>
is the process of identifying [=actions=]
that precede an [=outcome=] of interest,
and allocating value to those [=actions=].

<dfn lt=actions>Actions</dfn> that are of interest to advertisers
are primarily the showing of advertisements
(also referred to as <dfn lt=impression>impressions</dfn>).
Other actions include ad clicks (or other interactions)
and opportunities to show ads that were not taken.

Desired <dfn>outcomes</dfn> for advertising are more diverse,
as they include any result that an advertiser seeks to improve
through the showing of ads.
A desirable outcome might also be referred to as a <dfn>conversion</dfn>,
which refers to "converting" a potential customer
into a customer.
What counts as a conversion could include
sales, subscriptions, page visits, and enquiries.

For this API, [=actions=] and [=outcomes=] are both
events: things that happen once.
What is unique about attribution for advertising
is that these events might not occur on the same [=site=].
Advertisements are most often shown on sites
other than the advertiser's site.

The primary challenge with attribution is in maintaining privacy.
Attribution involves connecting activity on different sites.
The goal of attribution is to find an impression
that was shown to the same person before the conversion occurred.

If attribution information were directly revealed,
it would enable unwanted
[=cross-context recognition=],
thereby enabling [[UNSANCTIONED-TRACKING|tracking]].

This document avoids cross-context recognition by ensuring that
attribution information is aggregated using an [=aggregation service=].
The aggregation service is trusted to compute an aggregate
without revealing the values that each person contributes to that aggregate.

Strict limits are placed on the amount of information that each browser instance
contributes to the aggregates for a given site.
Differential privacy is used to provide additional privacy protection for each contribution.

Details of aggregation service operation are included in [[#aggregation]].
The differential privacy design used is outlined in [[#dp]].


## Background ## {#background}

From the early days of the Web,
advertising has been widely used to financially support the creation of sites.

One characteristic that distinguished the Web from other venues for advertising
was the ability to obtain information about the effectiveness of advertising campaigns.

Web advertisers were able to measure key metrics like reach (how many people saw an ad),
frequency (how often each person saw an ad),
and [=conversions=] (how many people who saw the ad then later took the action that the ad was supposed to motivate).
In comparison, these measurements were far more timely and accurate than for any other medium.

The cost of measurement performance was privacy.
In order to produce accurate and comprehensive information,
advertising businesses performed extensive tracking of the activity of all Web users.
Each browser was given a tracking identifier,
often using cookies that were logged by cross-site content.
Every action of interest was logged against this identifier,
forming a comprehensive record of a person's online activities.

Having a detailed record of a person's actions allowed advertisers to infer characteristics about people.
Those characteristics made it easier to choose the right audience for advertising,
greatly improving its effectiveness.
This created a strong incentive to gather more information.

Online advertising is intensely competitive.
Sites that show advertising seek to obtain the most money for each ad placement.
Advertisers seek to place advertising where it will have the most effect relative to its cost.
Any competitive edge gained by these entities--
and the intermediaries that operate on their behalf--
depends on having more comprehensive information about a potential audience.

Over time, actions of interest expanded to include nearly every aspect of online activity.
Methods were devised to correlate that information with activity outside of the Web.
An energetic trade has formed,
with multiple purveyors of personal information that is traded for various purposes.


## Goals ## {#goals}

The goal of this document is to define a means of performing [=attribution=]
for advertising
that does not enable tracking.


## End-User Benefit ## {#user-benefit}

The measurement of advertising performance creates new cross-site flows of information.
That information flow creates a privacy risk or cost--
of [=cross-context recognition=]--
that needs to be justified in terms of benefits to end users.

Any benefits realized by end users through the use of [=attribution=] are indirect.

End users that visit a website
pay for "free" content or services
primarily through their attention
to any advertisements the site shows them.
This "value" accrues to the advertiser,
who in turn pays the site.
The site is expected to use this money to
support the provision of their content or services.

<figure>
<pre class=include-raw>
path:images/value.svg
</pre>
<figcaption>Value exchange for advertising-supported content and services</figcaption>
</figure>

Participation in an [=attribution=] measurement system
would comprise a secondary cost to Web users.

Support for attribution enables more effective advertising,
largely by informing advertisers about what ads perform best,
and in what circumstances.
Those circumstances might include
the time and place that the ad is shown,
the person to whom the ad is presented, and
the details of the ad itself.

Connecting that information to outcomes
allows an advertiser to learn what circumstances most often lead
to the outcomes they most value.
That allows advertisers to spend more on effective advertising
and less on ineffective advertising.
This lowers the overall cost of advertising
relative to the value obtained. [[ONLINE-ADVERTISING]]

Sites that provide advertising inventory,
such as content publishers and service providers,
indirectly benefit from more efficient advertising.
Venues for advertising that are better able to
show ads that result in
the outcomes that advertisers seek
can charge more for ad placements.

Sites that obtain support through the placement of advertisements
are better able to provide quality content or services.
Importantly, that support is derived unevenly from their audience.
This can be more equitable than other forms of financial support.
Those with a lower tendency or ability to spend on advertised goods
obtain the same ad-supported content and services
as those who can afford to pay. [[EU-AD]][[COPPACALYPSE]]

The ability to supply "free" services
supported by advertising
has measurable economic benefit
that derives from the value of those services. [[FREE-GDP]]


## Collective Privacy Effect ## {#collective}

The use of aggregation--
if properly implemented--
ensures that information provided to sites is about groups and not individuals.

The introduction of this mechanism therefore represents collective decision-making,
in line with the idea of [=collective privacy=].

Participation in attribution measurement carries a lower privacy cost
when the group that participates is larger.
This is due to the effect of aggregation on
the ability of sites to
extract information about individuals from aggregates.
This is especially true for central [[#dp|differential privacy]],
which is the mathematical basis for the privacy design used
in this specification.

Larger cohorts of participants also produce more representative--
and therefore more useful--
statistics about the advertising that is being measured.

If attribution is justified,
both these factors motivate the enablement of attribution for all users.

Acting to enable attribution measurement by user agents
will not be positively received by some people.
Different people perceive the costs and benefits
that come from engaging with advertising differently.
The proposed design allows people the option of appearing to participate in attribution
without revealing that choice to sites; see [[#opt-out]].


## Attribution Using Histograms ## {#histograms}

[=Attribution=] attempts to measure correlation
between one or more ad placements ([=impressions=])
and the [=outcomes=] that an advertiser desires.

When considered in the aggregate,
information about individuals is not useful.
Actions and outcomes need to be grouped.

The simplest form of attribution splits impressions into a number of groupings
according to the attributes of the advertisement
and counts the number of conversions.
Groupings might be formed from attributes such as
where the ad is shown,
what was shown (the "creative"),
when the ad was shown,
or to whom.

These groupings
and the tallies of conversions attributed to each
form a histogram.
Each bucket of the histogram counts the conversions
for a group of ads.

<figure>
<pre class=include-raw>
path:images/histogram.svg
</pre>
<figcaption>Sample histogram for conversion counts,
  grouped by the site where the impressions were shown</figcaption>
</figure>

Different groupings might be used for different purposes.
For instance, grouping by creative (the content of an ad)
might be used to learn which creative works best.

Adding a value greater than one at each conversion
enables more than simple counts.
Histograms can also aggregate values,
which might be used to differentiate between different outcomes.
The value that is allocated to impressions
is called a <dfn>conversion value</dfn>.
A higher conversion value might be used for larger purchases
or any outcome that is more highly valued.
A conversion value might also be split between multiple impressions
to split credit.

<!-- TODO
* Compatibility with privacy-preserving aggregation services
* Flexibility to assign buckets
* As histogram size increases, noise becomes a problem
-->


# Overview of Operation # {#overview}

The Attribution API provides aggregate information about the
association between two classes of events: [=impressions=] and [=conversions=].

An [=impression=] is any action that an advertiser takes on any website.
The API does not constrain what can be recorded as an impression.
Typical actions that an advertiser might seek to measure include:

*   Displaying an advertisement.
*   Having a user interact with an advertisement in some way.
*   Not displaying an advertisement (especially for controlled experiments that seek to confirm whether an advertising campaign is effective).

For the API, a [=conversion=] is an [=outcome=] that is being measured.
The API does not constrain what might be considered to be an outcome.
Typical outcomes that advertisers might seek to measure include:

*   Making a purchase.
*   Signing up for an account.
*   Visiting a webpage.

The remainder of this section describes
how the Attribution API operates
in conjunction with an [=aggregation service=]
to produce an aggregate attribution measurement.
That operation is illustrated in the following figure.

<figure>
<pre class=include-raw>
path:images/overview.svg
</pre>
<figcaption>Overview of Attribution Operation</figcaption>
</figure>

When an [=impression=] occurs,
the <a method for=Attribution>saveImpression()</a> method can be used
to request that the browser save information.
This includes an identifier for the impression
and some additional information about the impression.
For instance, advertisers might use additional information
to record whether the impression was an ad view or an ad click.

At [=conversion=] time, a [=conversion report=] is created.
A <dfn>conversion report</dfn> is an encrypted histogram contribution
that includes information from any [=impressions=] that the browser previously stored.

The <a method for=Attribution>measureConversion()</a> method accepts a simple query that is used
to tell the browser how to construct a [=conversion report=].
That includes a simple query that selects from the [=impressions=]
that the browser has stored,
a [=conversion value=] that is allocated to the selected impression(s),
and other information needed to construct the [=conversion report=].

The histogram created by the [=conversion report=] is constructed as follows:

*   If the query found no impressions,
    or the [=privacy budget=] for the site is exhausted,
    a histogram consisting entirely of zeros (0) is constructed.

*   If one or more matching impressions is found, the browser runs the last-n-touch
    attribution logic to select the relevant impression(s). The provided conversion
    value is added to a histogram at the bucket that was specified at the time of the
    attributed impression(s). All other buckets are set to zero.

The browser updates the [=privacy budget store=] to reflect the reported conversion.

The resulting histogram is prepared for aggregation according to the requirements
of the chosen [=aggregation service=] and returned to the site.
This minimally involves encryption of the histogram.

<p class=note>A site that invokes this API will always receive a valid conversion report.
As a result, sites learn nothing about what happened on other sites from this interaction.

The site can collect the encrypted histograms it receives from calls to this API
and submit them to the aggregation service.

Upon receiving a set of encrypted histograms from a site, the aggregation service:

1.  confirms that it has not
    previously computed an aggregate
    from the provided inputs
    and that there are enough conversion reports,

2.  adds the histograms, including sufficient [[#dp|noise]],
    to produce a differentially-private aggregate histogram, and

3.  returns the aggregate to the site.

We refer to the final output as an <dfn>attribution result</dfn>.


# API Usage # {#api}

A site using the Attribution API will typically register either
[=impressions=] or [=conversions=], but in some cases the same site may
do both.

To register an impression, a site calls
<a method for=Attribution>saveImpression()</a>. No preparation is
required to use this API beyond collecting parameter values, although
it may be useful to examine the supported
<a attribute for=Attribution>aggregationServices</a> in deciding
whether to use the Attribution API.

It is also possible to register an impression by including the
[:Save-Impression:]
header in the HTTP response when serving a resource to the user agent.

To request a conversion report, a site calls
<a method for=Attribution>measureConversion()</a>.
Before calling this API, a site must
select a supported [=aggregation service=].
The page may select any of the supported services found in
<a attribute for=Attribution>aggregationServices</a>.
The name of the selected service must be supplied as
the {{AttributionConversionOptions/aggregationService}} member of the
{{AttributionConversionOptions}} dictionary when calling the
<a method for=Attribution>measureConversion()</a> method.

## Site Identities ## {#sites}

This API relies on the HTML definition of [=site=]
as the primary scope over which it operates.
Three types of sites are recognized:

*   An <dfn>impression site</dfn> is the [=site=]
    that registers an impression.
    This [=impression site=] is derived from the [=top-level origin=]
    of the [=relevant settings object=]
    at the time that {{Attribution/saveImpression()}}
    is invoked to store an [=impression=].

*   A <dfn>conversion site</dfn> is the [=site=]
    where a conversion occurs.
    The [=conversion site=] is derived from the [=top-level origin=]
    of the [=relevant settings object=]
    at the time that {{Attribution/measureConversion()}} is invoked.

*   An <dfn local-lt=intermediary|intermediaries>intermediary site</dfn> is a [=site=]
    that calls the API from any cross-site frame, such as an [=iframe=].
    The [=intermediary site=] is derived from the [=origin=]
    of the [=relevant settings object=]
    at the time that either {{Attribution/saveImpression()}}
    or {{Attribution/measureConversion()}} is invoked,
    unless this origin is [=same site=] with the [=impression site=]
    or [=conversion site=], respectively.

This API uses [=site=] rather than [=origin=]
because it depends on associating all activity
that might have privacy consequences with a single entity.
Features like cookies allow privacy-relevant information
to be exchanged freely by [=same site=] [=origins=],
which could otherwise be used to exceed [=privacy budgets=].


## Navigator Interface ## {#navigator-interface}

All functionality for this API is attached
to the <code>{{Navigator|navigator}}.{{Navigator/attribution|attribution}}</code> attribute.

<xmp class=idl>
partial interface Navigator {
  [SecureContext, SameObject] readonly attribute Attribution attribution;
};
</xmp>

This provides three key functions:

* A list of browser-supported aggregation functions ([[#find-aggregation-service]])
* A means of asking the browser to save impressions ([[#save-impression-api]])
* A method to request conversion measurement ([[#measure-conversion-api]])


## Finding a Supported Aggregation Service ## {#find-aggregation-service}

The <dfn attribute for=Attribution>aggregationServices</dfn> attribute
contains a set of aggregation services supported by the [=user agent=]. The page
must select and specify one of these services when calling the
<a method for=Attribution>measureConversion()</a> method.
It may also be useful to query the supported services
before registering an impression,
but that is not required,
and impressions are not scoped to a single aggregation service.

<div class=example id=ex-find-service>

  A site might have a preference order
  for the aggregation services that it uses.
  The following code iterates over a preference list
  and finds one that the user agent supports.

  <xmp highlight=js>
  const preferredServices = [
    "https://aggregator.example/tee",
    "https://aggregator.example/dap",
    "https://example.com/aggregator",
  ];
  const supportedServices = navigator.attribution?.aggregationServices;
  const serviceUrl = preferredServices.find(url => supportedServices?.has(url));
  </xmp>

  If the user agent supports the URL
  and if it includes one of the preferred services,
  the first preferred service is saved
  in a variable named `serviceUrl`.
  Otherwise, `serviceUrl` will remain `undefined`.

</div>

<xmp class=idl>
enum AttributionAggregationProtocol { "dap-18-histogram" };

dictionary AttributionAggregationService {
  required AttributionAggregationProtocol protocol;
};

[SecureContext, Exposed=Window]
interface AttributionAggregationServices {
  readonly maplike<USVString, AttributionAggregationService>;
};

[SecureContext, Exposed=Window]
interface Attribution {
  readonly attribute AttributionAggregationServices aggregationServices;
};
</xmp>

The <a attribute for=Attribution>aggregationServices</a> attribute is
a mapping from URLs that identify an [=aggregation service=] to metadata about
that service:

<dl dfn-for=AttributionAggregationService dfn-type=dict-member>
  <dt><dfn>protocol</dfn></dt>
  <dd>
    The {{AttributionAggregationProtocol|protocol}} that the [=aggregation service=] uses.
    Different versions of the same protocol use different values.
    Even if a single service provider supports multiple protocols,
    each needs to use a different URL.
    This ensures that each can be uniquely identified by URL
    without also specifying the choice of protocol.
  </dd>
</dl>

The URL is passed as the {{AttributionConversionOptions/aggregationService}} parameter
to <a method for=Attribution>measureConversion()</a> to select the identified aggregation service.

The <dfn enum>AttributionAggregationProtocol</dfn> describes the submission protocol
used by different [=aggregation services=]. This document defines two protocols:

<dl dfn-for=AttributionAggregationProtocol dfn-type=enum-value>
  <dt><dfn>dap-18-histogram</dfn></dt>
  <dd>A DAP-based protocol [[DAP]] that uses [=MPC=]; see [[#s-mpc]].</dd>
</dl>

## Saving Impressions ## {#save-impression-api}

The <a method for=Attribution>saveImpression()</a> method requests
that the [=user agent=] record an [=impression=] in the [=impression store=].

<div class=example id=ex-save-impression>
  A site that shows an advertisement for an advertiser
  can save an impression.

  In this case, the site saves the impression directly,
  identifying the advertiser (`advertiser.example`)
  and including information that is negotiated by the advertiser.
  In the following example,
  this includes the {{AttributionImpressionOptions/matchValue}} value (2)
  that the advertiser might later use to select this advertisement,
  the index of the histogram ({{AttributionImpressionOptions/histogramIndex}} = 3)
  into which to include any attributed value,
  and a retention period ({{AttributionImpressionOptions/lifetimeDays}} = 7)
  that is at least as long as the advertiser requires.

  <xmp highlight=js>
    navigator.attribution.saveImpression({
      histogramIndex: 3,
      matchValue: 2,
      conversionSites: ["advertiser.example"],
      lifetimeDays: 7,
    });
  </xmp>

  Alternatively, an intermediary,
  such as a Supply-Side Platform (SSP) or Demand-Side Platform (DSP),
  might call the same API from an [=child navigable|iframe=].
  Making the same API call from a frame
  results in saving the [=intermediary site=] identity with the impression.

</div>

<xmp class=idl>
dictionary AttributionImpressionOptions {
  required unsigned long histogramIndex;
  unsigned long matchValue = 0;
  sequence<USVString> conversionSites = [];
  sequence<USVString> conversionCallers = [];
  unsigned long lifetimeDays = 30;
  long priority = 0;
};

dictionary AttributionImpressionResult {
};

[SecureContext, Exposed=Window]
partial interface Attribution {
  Promise<AttributionImpressionResult> saveImpression(AttributionImpressionOptions options);
};
</xmp>

The arguments to <a method for=Attribution>saveImpression()</a> are as follows:

<dl dfn-for=AttributionImpressionOptions dfn-type=dict-member>
  <dt><dfn>histogramIndex</dfn></dt>
  <dd>
    If <a method for=Attribution>measureConversion()</a> matches this
    [=impression=] with a subsequent [=conversion=], the [=conversion value=]
    will be added to the histogram bucket identified by this index.
  </dd>
  <dt><dfn>matchValue</dfn></dt>
  <dd>
    An optional piece of metadata associated with the impression. The value
    can be used to identify which impressions may receive attribution
    from a [=conversion=].
  </dd>
  <dt><dfn>conversionSites</dfn></dt>
  <dd>
    The top-level [=conversion sites=] where [=conversions=] for this impression may occur,
    identified by their domain names.
    The <a method for=Attribution>measureConversion()</a> method
    will only attribute to this impression when called by one of the indicated sites.
    If empty, any [=conversion site=] will match.
  <dt><dfn>conversionCallers</dfn></dt>
  <dd>
    The [=intermediary sites=] or [=conversion sites=]
    that are able to [=common matching logic|select=] this impression for [=conversion=],
    identified by their domain names.
    The <a method for=Attribution>measureConversion()</a> method
    will only attribute to this impression when called by one of the indicated sites.
    This option includes both [=conversion sites=] and [=intermediary sites=].
    If empty, any site that invokes the API will match.
  <dt><dfn>lifetimeDays</dfn></dt>
  <dd>
    A positive "time to live" (in days) after which the [=impression=] can no
    longer receive attribution.
    The [=user agent=] should impose an upper limit on the lifetime,
    and silently reduce the value specified here if it exceeds that limit.
  </dd>
  <dt><dfn>priority</dfn></dt>
  <dd>
    An integer used to sort [=impressions=] during attribution.
  </dd>
</dl>

## Requesting Attribution for a Conversion ## {#measure-conversion-api}

The <a method for=Attribution>measureConversion()</a> method
requests that the [=user agent=] perform [=attribution=] for a [=conversion=],
and return a [=conversion report=].

The <a method for=Attribution>measureConversion()</a> method
always returns a conversion report,
regardless of whether matching [=impression|impression(s)=] are found.
If there is no match, or if [[#dp|differential privacy]] disallows
reporting the attribution, the returned conversion report will not
contribute to the histogram, i.e., will be uniformly zero.

<div class=example id=ex-measure-conversion>
  A site that observes a [=conversion=]
  might choose to request the measurement
  of the effect of different [=impression store|stored=] [=impressions=].

  To request the creation of an encrypted measurement,
  the site invokes the {{Attribution/measureConversion()}} method.

  This function takes four different types of input:

  1.  The selected aggregation service,
      which is identified using a URL.
      The <a href=#ex-find-service>example process for selecting an aggregation service</a>
      shows how to select a service that the browser supports.

      <xmp highlight=js>
        const serviceDetails = {
          aggregationService: serviceUrl,
        };
      </xmp>

  1.  Details of the aggregated measurement.
      These values will be consistent for all invocations of the API
      across multiple browsers.
      This includes the size of the histogram
      and the amount of [=privacy budget=] that might have been expended.

      <xmp highlight=js>
        const aggregatedMeasurementDetails = {
          histogramSize: 20,
          epsilon: 1,
        };
      </xmp>

  1.  A set of attributes,
      all <span class=allow-2119>optional</span>,
      that select the [=impressions=] to consider.
      This includes how old impressions can be
      ({{AttributionConversionOptions/lookbackDays}}),
      the [=impression sites=] that might have saved impressions
      ({{AttributionConversionOptions/impressionSites}}),
      the [=intermediary sites=] that might have saved impressions
      ({{AttributionConversionOptions/impressionCallers}}),
      and the choice of {{AttributionConversionOptions/matchValues}}.

      <xmp highlight=js>
        const selectionDetails = {
          lookbackDays: 14,
          impressionSites: ["publisher.example", "other.example"],
          impressionCallers: ["ad-tech.example"],
          matchValues: [2],
        };
      </xmp>

  1.  The [=attribution logic=] parameters.

      <xmp highlight=js>
        const attributionDetails = {
          // top impression's histogram index gets 50% of value, the next two 25% each
          credit: [.5, .25, .25],
          value: 3,
          maxValue: 7,
        };
      </xmp>

  Once these values are decided,
  the site invokes the API to obtain an encrypted [=conversion report=].

  <xmp highlight=js>
    const measurement = await navigator.attribution.measureConversion({
      ...serviceDetails,
      ...aggregatedMeasurementDetails,
      ...selectionDetails,
      ...attributionDetails,
    });
    sendReportToServer(measurement.report);
  </xmp>

  This [=conversion report|report=] can be collected,
  along with other reports from this browser and other browsers.
  Collected reports can then all be submitted to an [=aggregation service=]
  to obtain an [[#histograms|aggregate histogram]].

</div>

<xmp class=idl>
dictionary AttributionConversionOptions {
  required USVString aggregationService;
  double epsilon = 1.0;

  required unsigned long histogramSize;

  unsigned long lookbackDays;
  sequence<unsigned long> matchValues = [];
  sequence<USVString> impressionSites = [];
  sequence<USVString> impressionCallers = [];

  sequence<double> credit;
  unsigned long value = 1;
  unsigned long maxValue = 1;
};

dictionary AttributionConversionResult {
  required Uint8Array report;
};

[SecureContext, Exposed=Window]
partial interface Attribution {
  Promise<AttributionConversionResult> measureConversion(AttributionConversionOptions options);
};
</xmp>

The arguments to <a method for=Attribution>measureConversion()</a> are as follows:

<dl dfn-for=AttributionConversionOptions dfn-type=dict-member>
  <dt><dfn>aggregationService</dfn></dt>
  <dd>
    A selection from the [=aggregation services=] that can be found in <a
    attribute for=Attribution>aggregationServices</a>.
  </dd>
  <dt><dfn>epsilon</dfn></dt>
  <dd>The amount of [=privacy budget=] to expend on this [=conversion report=].</dd>
  <dt><dfn>histogramSize</dfn></dt>
  <dd>The number of histogram buckets to use in the [=conversion report=].</dd>
  <dt><dfn>lookbackDays</dfn></dt>
  <dd>A positive integer number of days. Only impressions occurring within the past `lookbackDays` may match this [=conversion=]. If omitted, it is equivalent to the [=maximum lookback=].</dd>
  <dt><dfn>matchValues</dfn></dt>
  <dd>A [=set=] of match values that can be used to select this [=impression=].</dd>
  <dt><dfn>impressionSites</dfn></dt>
  <dd>
    A [=set=] of impression sites.
    Only [=impressions=] recorded where the [=impression site=] is in this set
    are eligible to match this [=conversion=].
    If empty, any site will match.
  </dd>
  <dt><dfn>impressionCallers</dfn></dt>
  <dd>
    A [=set=] of sites,
    both [=impression sites=] and [=intermediary sites=],
    that might have called the <a method for=Attribution>saveImpression()</a> API.
    If not empty,
    only [=impressions=] recorded by one of the listed sites
    are eligible to match this [=conversion=].
  </dd>
  <dt><dfn>credit</dfn></dt>
  <dd>A [=list=] of numbers.</dd>
  <dt><dfn>value</dfn></dt>
  <dd>
    The [=conversion value=]. If an attribution is made and [[#dp|privacy]]
    restrictions are satisfied, this value will be encoded into the [=conversion report=].
  </dd>
  <dt><dfn>maxValue</dfn></dt>
  <dd>
    The maximum [=conversion value=] across all contributions included in the aggregation.
    Together with epsilon, this is used to calibrate the distribution of random noise that
    will be added to the outcome. It is also used to determine the amount of [=privacy budget=]
    to expend on this [=conversion report=].
  </dd>
</dl>


## Role of Intermediaries ## {#intermediaries}

This API has support for its operation by [=intermediaries=]
on behalf of [=top-level origin|top-level=] [[#sites|sites]].
Advertising is frequently delegated to independent operators
that are responsible for placement, bidding, and measurement.

[=Impressions=] that are saved by an intermediary
record the identity of the [=intermediary site=].
When [[#logic-matching|selecting]] impressions
for [[#measure-conversion-api-operation|conversion measurement]],
the [=intermediary site|intermediary site identity=] can be used to select impressions.


## Histogram Construction ## {#histogram-definition}

Conceptually, each saved [=impression=] has a single histogram definition.
Each [=impression=] has a single [=impression/Histogram Index=] attribute
that determines where the [=validated conversion options/Value|value=]
allocated to that [=impression=] appears in [[#histograms|the resulting histogram]].

Each invocation of {{Attribution/measureConversion()}}
therefore needs to select [=impressions=] that have the same histogram definition.
Though this applies to all uses of the API,
consistent definition of histograms is especially important when [=impressions=]
are [[#save-impression-api|saved]] and [[#measure-conversion-api|measured]]
by multiple [=intermediaries=].

All [=impressions=] that might be [=common matching logic|selected=]
when invoking {{Attribution/measureConversion()}}
need to use the same histogram definition.
The API provides several tools
for ensuring that only the right [=impressions=] are chosen.

For saved [=impressions=]:

*   [=impression/Match Value|Match values=] can be used to separate [=impressions=]
    by histogram definition.

*   Use of an [=impression=] for [=conversion=] can be restricted
    to be visible only to {{Attribution/measureConversion()}}
    on a [=impression/Conversion Sites|set of conversion sites=].

*   Use of an [=impression=] for [=conversion=] can be restricted
    to be visible only to {{Attribution/measureConversion()}}
    invoked by a [=impression/Conversion Callers|set of sites=].

As part of [=common matching logic=] at the point of [=conversion=]:

*   [=validated conversion options/Match Values|a set of match values=],
    limits the set of [=impressions=].

*   A set of [=validated conversion options/Impression Sites=],
    restricts the [=impression sites=] where [=impressions=] were saved.

*   A set of [=validated conversion options/Impression Callers=],
    restricts the set of [=conversion sites=] or [=intermediary sites=]
    that saved [=impressions=].

These options provide sites with flexibility in how attribution selects histograms.
It does not preclude the use of different histograms by a [=conversion site=].
Multiple [=impressions=] can be saved
with different histogram definitions
provided that {{Attribution/measureConversion()}} invocations
never [=common matching logic|select=] [=impressions=] with different histogram definitions.
This ensures that [=conversions=] can be [=attribution|attributed=] to multiple histograms
by invoking {{Attribution/measureConversion()}} multiple times.


## Permissions Policy Integration ## {#permission-policy}

The ability to delegate to an intermediary
is controlled by [[#permission-policy|Permission Policy]].

This specification defines two [=policy-controlled features=]:

*   Invocation of the <a method for=Attribution>saveImpression()</a> API,
    identified by the string "<code><dfn export for="PermissionPolicy"
    enum-value>save-impression</dfn></code>".
*   Invocation of the <a method for=Attribution>measureConversion()</a> API,
    identified by the string "<code><dfn export for="PermissionPolicy"
    enum-value>measure-conversion</dfn></code>".

The [=policy-controlled feature/default allowlist=] for both of these features is
<code><a dfn for="default allowlist">*</a></code>.

<p class=note>Having separate permissions for
<a method for=Attribution>saveImpression()</a> and
<a method for=Attribution>measureConversion()</a>
allows pages that do both to limit subresources
to the expected kind of activity.

<p class=note>Enabling permissions by default
simplifies the task of integrating external services.

<p class=note>Permissions policy provides only all-or-nothing control;
it does not enable delegation of a portion of privacy budget.


# API Internals # {#api-internals}

## Impression Store ## {#s-impression-store}

The <dfn>impression store</dfn> is used by the <a method
for=Attribution>measureConversion()</a> method to find matching
[=impressions=].

<p class=note>
Though this API enables the storage of data by sites,
the [=impression store=] does not use a [=storage key=].


### Contents ### {#impression-store-contents}

The [=impression store=] is a [=set=] of [=impression|impressions=]:

<div dfn-for=impression link-for-hint=Attribution>
<pre class=simpledef>
<dfn>Match Value</dfn>: The {{AttributionImpressionOptions/matchValue}} passed to <a>saveImpression()</a>.
<dfn>Impression Site</dfn>: The [=impression site=] where <a>saveImpression()</a> was called.
<dfn>Intermediary Site</dfn>: The [=intermediary site=] that called <a>saveImpression()</a>,
    or `undefined` if the API was invoked by the [=impression site=].
<dfn>Conversion Sites</dfn>: The [=set=] of [=conversion sites=] that were passed to <a>saveImpression()</a>.
<dfn>Conversion Callers</dfn>: The [=set=] of sites,
    either [=conversion sites=] or [=intermediary sites=],
    that can select this [=impression=] when invoking <a>measureConversion()</a>.
<dfn>Timestamp</dfn>: The time at which <a>saveImpression()</a> was called.
<dfn>Lifetime</dfn>: The [=duration=] an [=/impression=] remains eligible for attribution, either from the call to <a>saveImpression()</a>, or a [=/user agent=]-defined limit.
<dfn>Histogram Index</dfn>: The histogram index passed to <a>saveImpression()</a>.
<dfn>Priority</dfn>: An integer used to sort [=/impressions=] during attribution.
</pre>
</div>


### Maintenance ### {#impression-store-maintenance}

The [=user agent=] should periodically use
the [=impression/timestamp=] and [=impression/lifetime=] values
to identify and delete any [=impressions=] in the [=impression store=]
that have expired.

It is not necessary to remove [=impressions=] immediately upon expiry,
as long as <a method for=Attribution>measureConversion()</a>
excludes expired [=impressions=] from [=attribution=]. However, the
[=user agent=] should not retain expired [=impressions=] indefinitely.


### `Clear-Site-Data` Integration ### {#impression-store-clear}

The [:Clear-Site-Data:] field [[CLEAR-SITE-DATA]]
gives sites the ability to remove state maintained by a [=user agent=].
The \``"impressions"`\` type is added to the list of recognized types,
defined in [[CLEAR-SITE-DATA#header]].

When the [[CLEAR-SITE-DATA#clear-response|clear site data for response]] algorithm is invoked,
if the list of types [=set/contains=] \``"impressions"`\`,
the [=clear impressions for a site=] is invoked,
passing the <var ignore=''>origin</var>.

<div algorithm>
To <dfn>clear impressions for a site</dfn>,
given an [=origin=] |origin|,
run these steps:

1.  If |origin| is not a [=tuple origin=], return.

1.  Let |site| be the value returned
    by invoking [=registrable domain|obtain a registrable domain=],
    passing |origin|'s [=host=] part.

1.  [=set/iterate|For each=] [=impression=] |impression| of
    the [=impression store=]:

    1.  If |impression|'s [=impression/Intermediary Site=] is `undefined` and
        its [=impression/Impression Site=] is equal to |site|,
        [=set/remove=] |impression| from the [=impression store=] and [=iteration/continue=].

    1.  If |impression| has an [=impression/Intermediary Site=] equal to |site|,
        [=set/remove=] |impression| from the [=impression store=] and [=iteration/continue=].

    1.  If |impression|'s [=impression/Conversion Sites=] [=set/contains=] |site|:

        1.  [=set/Remove=] |site| from |impression|'s [=impression/Conversion Sites=].

        1.  If |impression|'s [=impression/Conversion Sites=] [=set/is empty=],
            [=set/remove=] |impression| from the [=impression store=] and
            [=iteration/continue=].

    1.  If |impression|'s [=impression/Conversion Callers=] [=set/contains=] |site|:

        1.  [=set/Remove=] |site| from |impression|'s [=impression/Conversion Callers=].

        1.  If |impression|'s [=impression/Conversion Callers=] [=set/is empty=],
            [=set/remove=] |impression| from the [=impression store=] and
            [=iteration/continue=].

<p class=note>This process does not remove impressions
that are saved with an empty [=set=] of [=impression/Conversion Sites=].

</div>

### Site Names ### {#site-name-algorithm}

The [=impression store=] saves information
about three types of [=site=]:
the [=impression/impression site=],
an optional [=impression/intermediary site=],
and a [=set=] of [=impression/conversion sites=].

These [=sites=] MUST all be in [=scheme-and-host=] form,
with a [=scheme=] of "`https`".
This means that a simple string serialization of a [=host=]
is sufficient to identify the site.
The API is therefore able to use a simple [=string=]
to represent [=sites=].

<p class=note>
It is also possible for an implementation to internally represent sites
using just the [=host=] part of the tuple.
</p>

<div algorithm>
To <dfn>parse a site</dfn>,
returning either [=site=] or failure,
given a [=string=] |input|,
run these steps:

1.  Let |host| be the value returned by invoking [=host parser=],
    passing |input|.

1.  If |host| is failure, return failure.

1.  Let |site| be the value returned by [=registrable domain|obtain a registrable domain=],
    passing |host|.

1.  If |site| is null, return failure.

1.  If |site| is "`localhost`" or if |site| [=code unit suffix|ends with=] "`.localhost`",
    return failure.

1.  Return a [=scheme-and-host=] tuple of ("`https`", |site|).

<p class=note>
This algorithm successfully produces a site from strings
that contain more [=domain labels=] than the [=registrable domain=].
For example, "`extra.example.com`" is parsed as "`example.com`".
</p>

<p class=note>
This algorithm does not accept localhost domains [[RFC6761]],
which results in any algorithm that depends on extracting a site name
failing when a localhost domain is mentioned
or when the current site (top-level or framed) is a localhost domain.
This can make using local servers for testing and development challenging.
Implementations could offer a configuration that disables the localhost check
to aid in testing and development.
</p>

</div>

## State For Privacy Budget Management ## {#privacy-state}

[=User agents=] maintain several pieces of state
that are used to manage the expenditure of [=privacy budgets=]:

*   The [=privacy budget store=] records the state
    of the per-[=site=] and per-[=epoch=] [=privacy budgets=].

*   The [=global privacy budget store=] records the state
    of the per-[=epoch=] global [=privacy budget=]
    that applies across all [=sites=].

*   The [=impression site quota store=] records the state
    of per-[=impression site=] and per-[=epoch=] quota for comsuming from the [=global privacy budget store=].

*   The [=epoch start time=] is used to determine when [=epochs=] start.
    This value is initialized as a side effect
    of invoking <a method for=Attribution>measureConversion()</a>.

*   A singular [=last browsing history clear=] value
    that tracks when the browsing activity for a [=site=] was last cleared.

*   A singular <dfn>attribution budget lock</dfn> is a boolean flag
    that is used to prevent concurrent operations
    on privacy budget stores,
    which might otherwise lead to overexpenditure of budgets.

The [=privacy budget store=], [=global privacy budget store=],
and [=impression site quota store=] are updated by [=deduct privacy and safety budgets=].

<p class=note>
Like the [=impression store=],
the [=privacy budget store=] and related stores do not use a [=storage key=].
These stores have some additional constraints
on how information is cleared;
see [[#clear-budget-store]] for details.

<p class=note>
The choice to define the [=attribution budget lock=] as a boolean flag
is a matter of specification expediency.
Implementations might be better served by an alternative construct.
Implementations might be able to partition this value,
such as by [=epoch=],
to reduce the scope of any contention.


### Privacy Budget Store ### {#s-privacy-budget-store}

A <dfn>privacy budget key</dfn> is a [=tuple=] consisting of the following items:

<dl dfn-for="privacy budget key">
: <dfn ignore>epoch index</dfn>
:: An [=epoch index=]
: <dfn ignore>site</dfn>
:: A [=site=]

</dl>


The <dfn>privacy budget store</dfn> is a [=map=] whose keys are
[=privacy budget keys=] and whose values are [=32-bit unsigned integers=].
These [=32-bit unsigned integer|integers=] store a value
in units [=microepsilons=].
A <dfn>microepsilon</dfn> is one-millionth of the unitary epsilon value
used in differential privacy [[DP]].

<p class=note>The choice of a 32-bit integer restricts the setting of epsilon to
be less than or equal to the <dfn>maximum epsilon</dfn> of 4294.
This <span class=allow-2119>should</span> be more than sufficient for implementations.

The <dfn>global privacy budget store</dfn> is a [=map=] whose keys are
[=epoch indices=] and whose values are [=32-bit unsigned integers=]
in units of [=microepsilons=].

The [=global privacy budget store=] tracks expenditure of a single [=privacy budget=]
that applies across all [=sites=]
and refreshes each [=epoch=].
This provides a [=safety limit=] against adversaries
that can correlate activity for the same person across multiple [=sites=].

<p class=note>Unlike the per-[=site=] [=privacy budget store=],
the [=global privacy budget store=] is keyed only by [=epoch index=],
not by [=site=].

The <dfn>impression site quota store</dfn> is a [=map=] whose keys are
[=privacy budget keys=] and whose values are [=32-bit unsigned integers=]
in units of [=microepsilons=].

The [=impression site quota store=] limits the amount of "stock"
(privacy budget related to [=impressions=])
that any single [=impression site=] can contribute in an [=epoch=].
This prevents a single [=impression site=]
from consuming excessive amounts
from the [=global privacy budget store|global limit=]
that could be maliciously triggered.

<div algorithm>
To <dfn>deduct privacy and safety budgets</dfn>
given a [=privacy budget key=] |key|,
[=set=] of [=impressions=] |impressions|,
[[WEBIDL#idl-double|double]] |epsilon|,
integer |value|,
integer |maxValue|,
boolean |isSingleEpoch|,
integer |l1Norm|,
[=set=] of [=privacy budget keys=] |deductedImpressionQuotas|
and a [=set=] of [=epoch indices=] |deductedGlobalBudgets|:

1.  Let |l1NormSensitivity| be |l1Norm| if |isSingleEpoch|, 2 * |value| otherwise.

1.  Let |valueSensitivity| be 2 * |value|.

1.  Let |noiseScale| be 2 * |maxValue| / |epsilon|.

1.  Let |l1NormDeductionFp| be |l1NormSensitivity| / |noiseScale|.

1.  Let |valueDeductionFp| be |valueSensitivity| / |noiseScale|.

    <p class=note>Single-epoch attributions
    do not cause any cascading effects across epochs.
    Attribution that involves multiple epochs consumes double the budget
    because of the potential for one change to affect attribution across epochs.
    Doubling the deduction assumes that Laplace noise
    proportional to |maxValue| / |epsilon|
    is added to the aggregated histogram.

1.  Let |l1NormDeduction| be |l1NormDeductionFp| * 1000000, rounded towards positive Infinity.

1.  Let |valueDeduction| be |valueDeductionFp| * 1000000, rounded towards positive Infinity.

1.  If [=attribution budget lock=] is true,
    wait until the value becomes false,
    then set the value to true.

1.  If the result of invoking [=check for available privacy budget|checking for available privacy budget=]
    with |key|, |l1NormDeduction|, |valueDeduction|,
    |impressions|, and |isSingleEpoch|
    is false, perform the following steps:

    1.  Set [=attribution budget lock=] to false.

    1.  Return false.

1.  All budget checks passed, so perform the deductions:

    1.  If |isSingleEpoch| let |deduction| be |l1NormDeduction| else let |deduction| be |valueDeduction|.

    1.  Let |currentValue| be the result of [=map/get|getting the value=] of |key|
        in the [=privacy budget store=]
        with a default of the [=per-site privacy budget=].

    1.  [=map/set|Set=] the value of |key| in the [=privacy budget store=]
        to |currentValue| − |deduction|.

    1.  Let |epoch| be the [=epoch index=] component of |key|.

    1.  If |deductedGlobalBudgets| does not [=set/contain=] |epoch|,
        [=set/append=] |deductedGlobalBudgets| with |epoch|
        and decrement [=global privacy budget store=]\[|epoch|] by |valueDeduction|.

    1.  [=list/iterate|For each=] |impression| in |impressions|:

        1.  Let |impressionSite| be |impression|'s [=impression/impression site=].

        1.  Let |impressionQuotaKey| be an [=privacy budget key=]
            whose items are |epoch| and |impressionSite|.

            <p class=note>The below ensures that we do not deduct budget
            more than once from the same impression site quota
            when there are multiple impressions for the site.

        1.  If |deductedImpressionQuotas| does not [=map/contain=] |impressionQuotaKey|:

            1.  [=set/Append=] |deductedImpressionQuotas| with |impressionQuotaKey|.

            1.  Let |currentImpressionQuotaValue| be the result of [=map/get|getting the value=] of |impressionQuotaKey|
                in the [=impression site quota per epoch=]
                with a default of the [=impression site quota per epoch=].

            1.  [=map/set|Set=] the value of [=impression site quota per epoch=]\[|impressionQuotaKey|\]
                to |currentImpressionQuotaValue| − |valueDeduction|.

1.  Set [=attribution budget lock=] to false.

1.  Return true.

</div>

<div algorithm>
To <dfn>check for available privacy budget</dfn>
given a [=privacy budget key=] |key|, integer |l1NormDeduction|,
integer |valueDeduction|,
[=set=] of [=impressions=] |impressions| and boolean |isSingleEpoch|:

1.  If |isSingleEpoch| let |deduction| be |l1NormDeduction| else let |deduction| be |valueDeduction|.

1.  Let |currentValue| be set to the value of [=map/get|getting the value=] of |key|
    from [=privacy budget store=],
    with a default of the [=per-site privacy budget=].

1.  If |deduction| is greater than |currentValue|, return false.

1.  Let |epoch| be the [=epoch index=] component of |key|.

1.  Let |currentGlobalValue| be set to the value of [=map/get|getting the value=]
    of |epoch| from the [=global privacy budget store=],
    with a default of the [=global privacy budget
    per epoch=].

1. If |valueDeduction| is greater than |currentGlobalValue|, return false.

1.  [=list/iterate|For each=] |impression| in |impressions|:

    1.  Let |impressionSite| be |impression|'s [=impression/impression site=].

    1.  Let |impressionQuotaKey| be an [=privacy budget key=]
        whose items are |epoch| and |impressionSite|.

    1.  Let |currentImpressionQuotaValue| be set to the value of [=map/get|getting the value=]
        of |impressionQuotaKey| from the [=impression site quota store=], with a default of
        the [=impression site quota per epoch=].

    1. If |valueDeduction| is greater than |currentImpressionQuotaValue|, return false.

1.  Return true.

</div>


### Attribution API Activation ### {#s-api-activation}

The Attribution API is like a [=transient activation-consuming API=],
with a number of differences
in terms of how activation state is tracked.

*   Any [=activation triggering input event|user activation=]
    makes the Attribution API available for a short period.

*   Additionally, when [=navigate|navigation=] is initiated
    by a user
    (that is, where the [=user navigation involvement=] is "browser UI"),
    the Attribution API is available for a short period.

*   The first attempt to access the API by invoking
    either <a for=Attribution>saveImpression()</a>
    or <a for=Attribution>measureConversion()</a>
    within an [=implementation-defined=] duration of the last activation,
    enables the API.

*   Like [=transient activation=],
    using the API consumes the activation.

*   When activation is consumed,
    the API is enabled for use by all [=descendent navigables=]
    of the [=top-level traversable=]'s [=active document=]
    (that is, all frames on the current page)
    until the next cross-site navigation.

*   Any [=navigate|navigation=] of the [=top-level traversable=]
    to a different [=site=] disables the API.
    However, any [=activation triggering input event|activation=],
    which might include the action that initiated the navigation,
    could make the API available again.

This is similar in effect to [=transient activation=].
However, attribution activation uses separate state from [=transient activation=]
and has the following notable differences:

*   Attribution activation state is tracked on the [=top-level traversable=],
    rather than affected {{Window}}s.

*   Attribution activation persists through [=navigate|navigations=],
    enabling use of the API for a short period
    after loading a new page
    in the case where the activation leads to navigation.

Having separate state ensures that
attribution activation does not interact with other [=transient activation-consuming APIs=].
An API that [=consume user activation|consumes activation=]
will not prevent the Attribution API from being available;
similarly, using the Attribution API will not prevent
a [=transient activation-consuming API=] from being available.

Separate state tracking ensures that user actions
that [=consume user activation=] can be independently measured
with the Attribution API.

Retaining activation across navigations enables common patterns in advertising.
Sites can use the Attribution API to examine actions
either from the site where an interaction occurred
or on subsequent sites.

To implement this,
each [=top-level traversable=] tracks two pieces of state
for the Attribution API:

1.  The <dfn>attribution enabled flag</dfn> is a boolean value
    that tracks whether the API is enabled.
    This value is initialized to false.

1.  The <dfn>attribution activation timestamp</dfn> is a [=moment=]
    that tracks the last [=activation triggering input event|user activation=].
    This value is initialized to the [=current high resolution time=].

Implementations also configure <dfn>attribution activation duration</dfn>
as an [=implementation-defined=] [=duration=].
This should be no less than the [=transient activation duration=],
though a larger value
might be advisable to ensure that delays from [=navigate|navigation=]
do not cause the Attribution API to become inaccessible.

<p class=note>
Implementations might choose to extend the time allowed
to account for the delays involved in page loading time.
A fixed value might not account for performance differences
in devices or in the network they use.
Implementations could extend the value of [=attribution activation duration=]
based on an understanding of performance chararacteristics.
Alternatively, an implementation might suspend any timer
during page load.

<div algorithm="attribution activation">
When a user interaction causes firing of an [=activation triggering input event=]
in a {{Document}} |document|,
the user agent [=must=] perform the steps below--
in addition to the [=activation notification=] steps--
before dispatching the event.
In this case, set [=navigable=] |navigable| to null.

Alternatively, when [=navigate|navigation starts=],
and the [=user navigation involvement=] is `"browser UI"`,
perform the steps below
setting |navigable| to the affected [=navigable=]
and setting |document| to null.

The steps are:

1.  If |navigable| is not null, let |n| be |navigable|.

1.  Otherwise, let |n| be the result of getting |document|'s [=node navigable=].

1.  Let |top| be the result of getting |n|'s [=top-level traversable=].

1.  Set |top|'s [=attribution activation timestamp=]
    to the [=current high resolution time=].

</div>

<div algorithm="attribution navigation">
When a [=top-level traversable=], |top|, is [=navigate|navigated=],
as part of the [=navigate=] algorithm,
after the [=document state=], |documentState|, is finalized,
and the [=origin=] of the [=response=], |responseOrigin|, is known,
perform the following steps:

1.  If |documentState|'s [=initiator origin=]
    is [=same site=] with |responseOrigin|, return.

1.  Set |top|'s [=attribution enabled flag=] to false.

</div>

<div algorithm="check attribution API activation">
To <dfn>check attribution API activation</dfn>,
given a {{Document}} |document|,
throwing a {{"NotAllowedError"}} {{DOMException}} on failure:

1.  Let |n| be the result of getting |document|'s [=node navigable=].

1.  Let |top| be the result of getting |n|'s [=top-level traversable=].

1.  If |top|'s [=attribution enabled flag=] is true, return.

1.  Let |lastActivation| be |top|'s [=attribution activation timestamp=].

1.  If |lastActivation| plus the [=attribution activation duration=]
    is less than the [=current high resolution time=],
    throw a {{"NotAllowedError"}} {{DOMException}}.

1.  Set |top|'s [=attribution enabled flag=] to true.

</div>


### Epoch Start Time ### {#s-epoch-start}

A <dfn local-lt=epoch>privacy budget epoch</dfn> (or [=epoch=])
identifies a period of time.
The length of an [=epoch=] is fixed at one week or 7 [=days=],
where a <dfn>day</dfn> is defined as 86400 seconds.

The <dfn>epoch start time</dfn> is a [=moment=]
from the [=wall clock=].
An [=epoch=] starts at a randomly-selected hour of the week
for each [=user agent=].
This ensures that any bias in aggregates
that arises from a [=privacy budget=] reaching zero
is averaged across all the contributions from all [=users=].

<div class=note>On the same device,
all privacy budgets and quotas
refresh at the same time based on the epoch start time.
</div>

The start time
is chosen randomly by the [=user agent=] when an epoch is first needed--
as a side effect of invoking the [=get the current epoch=] algorithm.

An <dfn local-lt="epoch indices">epoch index</dfn> is an integer
that refers to a given [=epoch=].
An [=epoch index=] is used to access
the [=impression store|impression=]
and [=epoch start time=].

<div class=note>
In the same way that a [=moment=] is an abstract concept
that can only be expressed as a [=duration=]
relative to another [=moment=],
[=epochs=] are abstract.

[=Epoch indices=] are stored as integers
relative to a set reference point.
The [=epoch indices=] in this specification
use the [=epoch start time=]
as a reference point.
A [=user agent=] could choose to use a different [=moment=]
to indicate a "zero" or reference [=epoch=].
</div>

The algorithms in this specification all use concrete [=epoch indices=],
rather than the more abstract [=epoch=].
[=moment|Points in time=] are translated to an [=epoch index=]
for the corresponding [=epoch=]
using the [=get the current epoch=] algorithm.

<div algorithm>
To <dfn>get the current epoch</dfn>
given a [=moment=] |t|,
returning an [=epoch index=]:

1.  Let |period| be the [=duration=] of one [=epoch=].

1.  If the [=epoch start time=] is not set,
    set it to a randomly selected hour within the last [=epoch=]
    as follows:

    1.  Let |rand| be |t| minus a [=duration=]
        that is randomly selected
        from between 0 (inclusive) and |period| (exclusive).

    1.  Let |ms| be the number of milliseconds in
        the [=duration from=] the [=Unix epoch=] to |rand|.

    1.  Let |hour| be |ms| divided by 3600000
        (one hour in milliseconds)
        rounded towards zero
        then multiplied by 3600000.

    1.  Set the [=epoch start time=] to the [=Unix epoch=]
        plus |hour| as a [=duration=].

1.  Let |start| be the [=epoch start time=].

1.  Let |elapsed| be (|t| − |start|) / |period|.

1.  Return |elapsed| as an integer, rounded towards negative Infinity.

</div>


### Last Browsing History Clear Time ### {#last-clear}

The <dfn>last browsing history clear</dfn> is a [=moment=]
using the [=wall clock=]
that tracks when browsing history was last cleared.
The [=last browsing history clear=] value is updated
to the [=current coarsened wall time=]
when any [=site=]-level state is cleared
at the request of a [=user=].
The value is initially unset.

As an optional optimization,
updating the [=last browsing history clear=] can be skipped if
all of the following are true:

*   All interactions that are cleared are with [=sites=]
    that have other uncleared interactions.
*   All cleared interactions occurring during [=epochs=]
    where other interactions with the same [=site=] were retained.
*   The [=epoch start time=] is set.

If all three conditions are true,
the [=last browsing history clear=] does not need to be updated.
Instead, the [=privacy budget store=] must be updated
by [=map/set|setting=] a value of 0
for all [=privacy budget key=] combinations that can be formed
from every affected [=site=] and [=epoch=]
(using the [=get the current epoch|corresponding=] [=epoch index=]).

<p class=note>
This optimization relies on the [=user agent=]
having retained information
about interactions with affected [=sites=]
in the affected [=epochs=].
This only works because any of the retained interactions
could have resulted in exhausting the budget.
Resetting the budget is necessary to ensure
that no information about the gap in browsing history
is exposed.

<div algorithm="get the starting epoch for attribution">
To <dfn>get the starting epoch for attribution</dfn>
given [=moment=] |now|,
returning an [=epoch index=]:

1.  Let |earliestEpochIndex| be the result of [=get the current epoch=]
    with |now| − the [=maximum lookback=] [=days=].

    <p class=note>
    This ensures that all possible [=impressions=] can be queried.

1.  Let |startEpoch| be |earliestEpochIndex|.

1.  If the [=last browsing history clear=] is set,
    perform the following steps:

    1.  Let |clearEpoch| be the result of [=get the current epoch=]
        with the value of [=last browsing history clear=].

        <p class=note>
        This use of [=get the current epoch=]
        can return a negative value.
        This is because the [=epoch start time=]
        is likely to be set to a time after history was last cleared.

    1.  Set |clearEpoch| to |clearEpoch| + 1.

        <p class=note>
        Adding <em>one</em> is necessary so that the [=epoch=] range for attribution
        does not overlap with an [=epoch=]
        before browsing history was cleared.

    1.  If |clearEpoch| is greater than |startEpoch|,
        return |clearEpoch|.

1.  Return |startEpoch|.

</div>

<div algorithm="clear browsing history for attribution">
To <dfn>clear browsing history for attribution</dfn>,
given a [=set=] of [=sites=] |sites|,
a [=boolean=] <dfn for="clear browsing history for attribution"><var>forgetVisits</var></dfn>,
and a [=moment=] |now|:

1.  If |forgetVisits| is false:

    1.  [=Assert=]: |sites| [=set/is empty|is not empty=].

    1.  [=set/iterate|For each=] |site| in |sites|:

        1.  Let |startingEpoch| be the result of
            invoking [=get the starting epoch for attribution=]
            given |now|.

        1.  Let |currentEpoch| be the result of
            invoking [=get the current epoch=]
            given |now|.

        1.  [=set/iterate|For each=] |epoch| in [=the inclusive range=]
            from |startingEpoch| to |currentEpoch|:

            1.  Let |key| be the [=privacy budget key=] formed
                from |site| and |epoch|.

            1.  [=map/Set=] [=privacy budget store=]\[|key|] to 0.

    1.  Return.

1.  If |sites| [=set/is empty=]:

    1.  [=set/empty|Clear=] the [=impression store=].

    1.  [=map/clear|Clear=] the [=privacy budget store=].

    1.  [=map/clear|Clear=] the [=impression site quota store=].

    1.  [=map/clear|Clear=] the [=global privacy budget store=].

1.  If |sites| [=set/is empty|is not empty=]:

    1.  [=set/iterate|For each=] |impression| in the [=impression store=],
        if |sites| [=set/contains=] |impression|'s [=impression/impression site=],
        [=set/remove=] |impression| from the [=impression store=].

    1.  [=set/iterate|For each=] |key| in the [=map/getting the keys|keys=]
        of the [=privacy budget store=],
        if |sites| [=set/contains=] the [=site=] component of |key|,
        [=map/remove=] [=privacy budget store=]\[|key|].

    1.  [=set/iterate|For each=] |key| in the [=map/getting the keys|keys=]
        of the [=impression site quota store=],
        if |sites| [=set/contains=] the [=site=] component of |key|,
        [=map/remove=] [=impression site quota store=]\[|key|].

        <p class=note>
        This process does not touch the [=global privacy budget store=].
        Primarily, this is to ensure that [=privacy budget=],
        once expended, is not forgotten.

1.  Set the [=last browsing history clear=] to |now|.

    <p class=note>Setting the [=last browsing history clear=]
    while only clearing state for some sites
    (that is, when |sites| [=set/is empty|is not empty=])
    will make some impressions unreachable for sites that are not present in that set.
    Implementations could also remove any unusable impressions
    and any budget records
    (such as those in the [=global privacy budget store=])
    that cannot be used as a result.

</div>


## Save Impression Algorithm ## {#save-impression-api-operation}

<div algorithm>
The <dfn method for=Attribution>saveImpression(|options|)</dfn> method steps are:

1.  Let |implicitInputs| be the result of [=obtaining the implicit API inputs=] from [=this=].
1.  [=Assert=]: |implicitInputs| is not null.
1.  Return the result of running [=save an impression=] with |options| and |implicitInputs|.

</div>

<div algorithm>
To <dfn>save an impression</dfn> given {{AttributionImpressionOptions}} |options|
and [=implicit API inputs=] |implicitInputs|:

1.  Let |document| be |implicitInputs|'s [=implicit API inputs/associated document=].
1.  Let |realm| be |document|'s [=relevant realm=].
1.  If |document| is not [=allowed to use=] the [=policy-controlled feature=] named
    "{{PermissionPolicy/save-impression}}", return [=a promise rejected with=]
    a {{"NotAllowedError"}} {{DOMException}} in |realm|.
1.  [=check attribution API activation|Check attribution API activation=]
    given |document|, returning [=a promise rejected with=] any thrown reason.
1.  Validate the page-supplied API inputs:
    1.  If |options|.{{AttributionImpressionOptions/histogramIndex}} is
        greater than or equal to the [=implementation-defined=] [=maximum histogram size=],
        return [=a promise rejected with=] a {{RangeError}} in |realm|.
    1.  If |options|.{{AttributionImpressionOptions/lifetimeDays}} is 0,
        return [=a promise rejected with=] a {{RangeError}} in |realm|.
    1.  Clamp |options|.{{AttributionImpressionOptions/lifetimeDays}} to
        the [=maximum lookback=].
    1.  If the [=list/size=] of
        |options|.{{AttributionImpressionOptions/conversionSites}} is
        greater than the [=implementation-defined=]
        [=maximum number of conversion sites per impression=],
        return [=a promise rejected with=] a {{RangeError}} in |realm|.
    1.  Let |conversionSites| be the [=set=] that is the result
        of invoking [=parse a site=]
        for each value in |options|.{{AttributionImpressionOptions/conversionSites}}.
    1.  If any result in |conversionSites| is failure, return
        [=a promise rejected with=] a {{"SyntaxError"}} {{DOMException}} in |realm|.
    1.  If the [=list/size=] of
        |options|.{{AttributionImpressionOptions/conversionCallers}} is
        greater than the [=implementation-defined=]
        [=maximum number of conversion callers per impression=],
        return [=a promise rejected with=] a {{RangeError}} in |realm|.
    1.  Let |conversionCallers| be the [=set=] that is the result
        of invoking [=parse a site=]
        for each value in |options|.{{AttributionImpressionOptions/conversionCallers}}.
    1.  If any result in |conversionCallers| is failure, return
        [=a promise rejected with=] a {{"SyntaxError"}} {{DOMException}} in |realm|.
1.  Run the following steps [=in parallel=]:
     1.  Construct |impression| as a [=impression|saved impression=] comprising:
         :   [=impression/Match Value=]
         ::  |options|.{{AttributionImpressionOptions/matchValue}}
         :   [=impression/Impression Site=]
         ::  |implicitInputs|' [=implicit API inputs/top-level site=]
         :   [=impression/Intermediary Site=]
         ::  |implicitInputs|' [=implicit API inputs/intermediary site=]
         :   [=impression/Conversion Sites=]
         ::  |conversionSites|
         :   [=impression/Conversion Callers=]
         ::  |conversionCallers|
         :   [=impression/Timestamp=]
         ::  |implicitInputs|' [=implicit API inputs/timestamp=]
         :   [=impression/Lifetime=]
         ::  |options|.{{AttributionImpressionOptions/lifetimeDays}} [=days=]
         :   [=impression/Histogram Index=]
         ::  |options|.{{AttributionImpressionOptions/histogramIndex}}
         :   [=impression/Priority=]
         ::  |options|.{{AttributionImpressionOptions/priority}}
     1.  If the Attribution API is [[#opt-out|enabled]],
        save |impression| to the [=impression store=].

1.  Let |result| be a new {{AttributionImpressionResult}}.
1.  Return [=a promise resolved with=] |result| in |realm|.

<p class=advisement><a method for=Attribution>saveImpression()</a>
does not return a status indicating whether the impression was recorded.
This minimizes the ability to detect when the Attribution
API is [[#opt-out|disabled]].

<p class=advisement>Implementations MUST attempt to mitigate [=side channels=]
that can reveal API state. For example, resolution of the returned promise is
not predicated on saving |impression| to the [=impression store=] to ensure that
the amount of time it takes to resolve is not dependent on the number of
existing impressions or whether the API is enabled.

</div>

The <dfn>implicit API inputs</dfn> is a [=struct=] with the following fields:

<div dfn-for="implicit API inputs">
<pre class=simpledef>
<dfn>Top-Level Site</dfn>: A [=site=].
<dfn>Intermediary Site</dfn>: A [=site=] or `undefined`.
<dfn>Timestamp</dfn>: A [=moment=].
<dfn>Associated Document</dfn>: A {{Document}}.
</pre>
</div>

<div algorithm>
To <dfn>obtain the implicit API inputs</dfn> from [=realm=] |realm| with
optional [=origin=] (default null):

1.  Let |window| be |realm|'s [=realm/global object=].
1.  If |window| is not a {{Window}}, return null.
1.  Let |settings| be |realm|'s [=realm/settings object=].
1.  Let |timestamp| be |settings|' [=environment settings object/current wall time=].
1.  Let |topLevelOrigin| be |settings|' [=environment/top-level origin=].
1.  If |origin| is null, set |origin| to |settings|' [=environment settings object/origin=].
1.  Let |topLevelSite| be the result of [=obtain a site|obtaining a site=] from |topLevelOrigin|.
1.  Let |intermediarySite| be:
    1.   a value of `undefined` if |origin| is [=same site=] with |topLevelOrigin|,
    1.   otherwise, the result of [=obtain a site|obtaining a site=] from |origin|.
1.  Return an [=implicit API inputs=] with the following fields:
    :   [=implicit API inputs/top-level site=]
    ::  |topLevelSite|
    :   [=implicit API inputs/intermediary site=]
    ::  |intermediarySite|
    :   [=implicit API inputs/timestamp=]
    ::  |timestamp|
    :   [=implicit API inputs/associated document=]:
    ::  |window|'s [=associated document=]

</div>

## Measure Conversion Algorithm ## {#measure-conversion-api-operation}

The <a method for=Attribution>measureConversion()</a> method completes
asynchronously, queuing work on the <dfn>Attribution [=task source=]</dfn>.

<div algorithm>
The <dfn method for=Attribution>measureConversion(|options|)</dfn> method steps are:

1.  Let |implicitInputs| be the result of [=obtaining the implicit API inputs=] from [=this=].
1.  [=Assert=]: |implicitInputs| is not null.
1.  Return the result of running [=measure a conversion=] with |options| and |implicitInputs|.

</div>

<div algorithm>
To <dfn>measure a conversion</dfn> given {{AttributionConversionOptions}} |options|
and [=implicit API inputs=] |implicitInputs|:

1.  Let |document| be |implicitInputs|'s [=implicit API inputs/associated document=].
1.  Let |realm| be |document|'s [=relevant realm=].
1.  If |document| is not [=allowed to use=] the [=policy-controlled feature=] named
    "{{PermissionPolicy/measure-conversion}}", return [=a promise rejected with=]
    a {{"NotAllowedError"}} {{DOMException}} in |realm|.
1.  [=check attribution API activation|Check attribution API activation=]
    given |document|, returning [=a promise rejected with=] any thrown reason.
1.  Let |validatedOptions| be the result of
    [=validate AttributionConversionOptions|validating=] |options|,
    returning [=a promise rejected with=] any thrown reason.
1.  Let |promise| be [=a new promise=] in |realm|.
1.  Run the following steps [=in parallel=]:
     1.  Let |report| be the result of invoking [=create an all-zero histogram=] with
         |validatedOptions|' [=validated conversion options/histogram size=].
     1.  If the Attribution API is [[#opt-out|enabled]],
         set |report| to the result of [=do attribution and fill a histogram=] with
         |validatedOptions|,
         |implicitInputs|' [=implicit API inputs/top-level site=],
         |implicitInputs|' [=implicit API inputs/intermediary site=], and
         |implicitInputs|' [=implicit API inputs/timestamp=].
     1.  Let |aggregationService| be |validatedOptions|'s [=validated conversion options/aggregation service=].
     1.  Switch on the value of |aggregationService|.{{AttributionAggregationService/protocol}}:
         <dl class="switch">
            :   <a enum-value for=AttributionAggregationProtocol>`dap-18-histogram`</a>
            ::  Perform the following steps:
                1.  Let |encryptedReport| be the result of invoking <a>construct a DAP report</a>,
                    given |validatedOptions|,
                    |implicitInputs|' [=implicit API inputs/top-level site=],
                    |implicitInputs|' [=implicit API inputs/intermediary site=],
                    |implicitInputs|' [=implicit API inputs/timestamp=], and |report|.
         </dl>
     1.  Let |result| be a {{AttributionConversionResult}} with the following items:
          : {{AttributionConversionResult/report}}
          :: |encryptedReport|
     1.  [=Queue a task=] on the [=Attribution task source=] to
         [=resolve=] |promise| with |result|.
1. Return |promise|.

<p class=advisement>Implementations MUST attempt to mitigate [=side channels=]
that can reveal API state. For example, ideally the amount of time it takes to
resolve the returned promise would not depend on the number of stored or matched
impressions or whether the API is enabled.

</div>

<dfn>Validated conversion options</dfn> is a [=struct=] with the following fields:

<div dfn-for="validated conversion options">
<pre class=simpledef>
<dfn>Aggregation Service</dfn>: An instance of {{AttributionAggregationService}}.
<dfn>Epsilon</dfn>: A finite positive number.
<dfn>Histogram Size</dfn>: A [=32-bit unsigned integer=].
<dfn>Lookback</dfn>: A positive [=duration=].
<dfn>Match Values</dfn>: A [=set=] of [=32-bit unsigned integers=].
<dfn>Impression Sites</dfn>: A [=set=] of [=sites=].
<dfn>Impression Callers</dfn>: A [=set=] of [=sites=].
<dfn>Credit</dfn>: A [=list=] of numbers.
<dfn>Value</dfn>: A [=32-bit unsigned integer=].
<dfn>Max Value</dfn>: A [=32-bit unsigned integer=].
</pre>
</div>

<div algorithm="validate AttributionConversionOptions">
To <dfn>validate {{AttributionConversionOptions}}</dfn> |options|:

1.  If <a attribute for=Attribution>aggregationServices</a> does not [=map/exist|contain=]
    an [=map/entry=] with a [=map/key=] of |options|.{{AttributionConversionOptions/aggregationService}},
    throw a {{ReferenceError}}.
1.  Let |aggregationService| be the result of [=map/get|getting the value=]
    from {{AttributionAggregationServices}},
    given |options|.{{AttributionConversionOptions/aggregationService}}.
1.  If |options|.{{AttributionConversionOptions/epsilon}}
    is less than or equal to 0 or is greater than [=maximum epsilon=],
    throw a {{RangeError}}.
1.  If |options|.{{AttributionConversionOptions/histogramSize}}
    is 0 or greater than the [=implementation-defined=] [=maximum histogram size=],
    or is greater than the [=maximum aggregation-service histogram size=],
    if any, for |options|.{{AttributionConversionOptions/aggregationService}},
    throw a {{RangeError}}.
1.  If |options|.{{AttributionConversionOptions/value}} is 0,
    throw a {{RangeError}}.
1.  If |options|.{{AttributionConversionOptions/value}}
    is greater than |options|.{{AttributionConversionOptions/maxValue}},
    throw a {{RangeError}}.
1.  Let |credit| be |options|.{{AttributionConversionOptions/credit}} if it [=map/exists=], «1» otherwise.
1.  If |credit| [=list/is empty=], throw a {{RangeError}}.
1.  If any of the [=list/items=] of |credit| are less than or equal to 0, throw a {{RangeError}}.
1.  If the [=list/size=] of |credit| exceeds the [=implementation-defined=]
    [=maximum number of credit values=], throw a {{RangeError}}.
1.  Let |lookback| be |options|.{{AttributionConversionOptions/lookbackDays}} [=days=]
    if it [=map/exists=], the [=maximum lookback=] [=days=] otherwise.
1.  Set |lookback| to the [=maximum lookback=] [=days=]
    if it is larger than that maximum.
1.  If |lookback| is 0 [=days=], throw a {{RangeError}}.
1.  If the [=list/size=] of
    |options|.{{AttributionConversionOptions/matchValues}} is
    greater than the [=implementation-defined=] [=maximum number of match values=],
    throw a {{RangeError}}.
1.  Let |matchValues| be the result of running [=set/create|creating a set=] with
    |options|.{{AttributionConversionOptions/matchValues}}.
1.  If the [=list/size=] of
    |options|.{{AttributionConversionOptions/impressionSites}} is greater than
    the [=implementation-defined=] [=maximum number of impression sites for conversion=],
    throw a {{RangeError}}.
1.  Let |impressionSites| be the [=set=] that is the result
    of invoking [=parse a site=]
    for each value in |options|.{{AttributionConversionOptions/impressionSites}}.
1.  If any result in |impressionSites| is failure, throw a {{"SyntaxError"}} {{DOMException}}.
1.  If the [=list/size=] of
    |options|.{{AttributionConversionOptions/impressionCallers}} is greater than
    the [=implementation-defined=] [=maximum number of impression callers for conversion=],
    throw a {{RangeError}}.
1.  Let |impressionCallers| be the [=set=] that is the result
    of invoking [=parse a site=]
    for each value in |options|.{{AttributionConversionOptions/impressionCallers}}.
1.  If any result in |impressionCallers| is failure, throw a {{"SyntaxError"}} {{DOMException}}.
1.  Return a [=validated conversion options=] with the following fields:
    : [=validated conversion options/Aggregation Service=]
    :: |aggregationService|
    : [=validated conversion options/Epsilon=]
    :: |options|.{{AttributionConversionOptions/epsilon}}
    : [=validated conversion options/Histogram Size=]
    :: |options|.{{AttributionConversionOptions/histogramSize}}
    : [=validated conversion options/Lookback=]
    :: |lookback|
    : [=validated conversion options/Match Values=]
    :: |matchValues|
    : [=validated conversion options/Impression Sites=]
    :: |impressionSites|
    : [=validated conversion options/Impression Callers=]
    :: |impressionCallers|
    : [=validated conversion options/Credit=]
    :: |credit|
    : [=validated conversion options/Value=]
    :: |options|.{{AttributionConversionOptions/value}}
    : [=validated conversion options/Max Value=]
    :: |options|.{{AttributionConversionOptions/maxValue}}

</div>


### Attribution Logic ### {#s-logic}

<dfn>Attribution logic</dfn> determines how the [=conversion value=] is allocated to histogram buckets.

<div algorithm>
To <dfn>do attribution and fill a histogram</dfn>, given
  [=validated conversion options=] |options|,
  [=site=] |topLevelSite|,
  [=site=] or `undefined` |intermediarySite|, and
  [=moment=] |now|:

1.  Let |currentEpoch| be the result of [=get the current epoch=]
    with |now|.

1.  Let |startEpoch| be the result of [=get the starting epoch for attribution=]
    with |now|.

1.  Let |earliestEpoch| be the result of calling [=get the current epoch=],
    passing (|now| − |options|' [=validated conversion options/lookback=]).

1.  Let |isSingleEpoch| be true if |currentEpoch| is equal to |earliestEpoch|, false otherwise.

1.  Let |l1Norm| be 0.

1.  If |isSingleEpoch| is true:
    1.  Let |impressions| be the result of invoking [=common matching logic=]
        with |options|, |topLevelSite|, |intermediarySite|, |currentEpoch|, and |now|.

    1.  If |impressions| [=set/is empty=], return the result of invoking
          [=create an all-zero histogram=] with
          |options|' [=validated conversion options/histogram size=].

    1.  Let |histogram| be the result of [=fill a histogram with last-n-touch attribution=] with |impressions|,
        |options|' [=validated conversion options/histogram size=],
        |options|' [=validated conversion options/value=], and
        |options|' [=validated conversion options/credit=].

    1.  Set |l1Norm| be the sum of the [=list/items=] in |histogram|.

    1.  [=Assert=]: |l1Norm| is less than or equal to |options|' [=validated conversion options/value=].

1.  Let |deductedImpressionQuotas| be a new [=set=].

1.  Let |deductedGlobalBudgets| be a new [=set=].

1.  Let |matchedImpressions| be an [=set/is empty|empty=] [=set=].

1.  For each |epoch| from |startEpoch| to |currentEpoch|, inclusive:

    1.  Let |impressions| be the result of invoking [=common matching logic=]
        with |options|, |topLevelSite|, |intermediarySite|, |epoch|, and |now|.

        <p class=note>In the single-epoch case, this is recomputing |matchedImpressions|.
        Implementations will want to avoid doing that work twice.

    1.  If |impressions| [=set/is empty|is not empty=]:

        1.  Let |key| be a [=privacy budget key=] whose items are |epoch| and |topLevelSite|.

        1.  Let |budgetAndSafetyOk| be the result of invoking [=deduct privacy and safety budgets=]
            with |key|, |impressions|,
            |options|' [=validated conversion options/epsilon=],
            |options|' [=validated conversion options/value=],
            |options|'s [=validated conversion options/max value=],
            |isSingleEpoch|, |l1Norm|, |deductedImpressionQuotas|, and |deductedGlobalBudgets|.

        1.  If |budgetAndSafetyOk| is true,
            [=set/extend=] |matchedImpressions| with |impressions|.

1.  If |matchedImpressions| [=set/is empty=], return the result of invoking
    [=create an all-zero histogram=] with
    |options|' [=validated conversion options/histogram size=].

1.  Let |histogram| be the result of [=fill a histogram with last-n-touch attribution=] with |matchedImpressions|,
    |options|' [=validated conversion options/histogram size=],
    |options|' [=validated conversion options/value=], and
    |options|' [=validated conversion options/credit=].

1.  Return |histogram|.

</div>

<div algorithm>
To <dfn>create an all-zero histogram</dfn>, given an integer |size|:

1.  Return a [=list=] of [=list/size=] |size|, whose [=list/items=] are all 0.

</div>

### Common Impression Matching Logic ### {#logic-matching}

<div algorithm>
To perform <dfn>common matching logic</dfn>, given
[=validated conversion options=] |options|,
[=site=] |topLevelSite|,
[=site=] or `undefined` |intermediarySite|,
[=epoch index=] |epoch|, and [=moment=] |now|:

1.  Let |matching| be an [=set/is empty|empty=] [=set=].

1.  [=set/iterate|For each=] |impression| in the [=impression store=]:

    1.  Let |impressionEpoch| be the result of calling [=get the current epoch=],
        passing |impression|'s [=impression/timestamp=].

    1.  If |impressionEpoch| is not equal to |epoch|, [=iteration/continue=].

    1.  If |now| is after |impression|'s [=impression/timestamp=]
        plus |impression|'s [=impression/lifetime=],
        [=iteration/continue=].

    1.  If |now| is after |impression|'s [=impression/timestamp=] plus |options|' [=validated conversion options/lookback=],
        [=iteration/continue=].

    1.  If |impression|'s [=impression/conversion sites=] [=set/is empty|is not empty=]
        and [=set/contains|does not contain=] |topLevelSite|,
        [=iteration/continue=].

    1.  Let |conversionCaller| be |intermediarySite| if it is not `undefined`,
        |topLevelSite| otherwise.

    1.  If |impression|'s [=impression/conversion callers=] [=set/is empty|is not empty=]
        and [=set/contains|does not contain=] |conversionCaller|,
        [=iteration/continue=].

    1.  If |options|' [=validated conversion options/match values=] [=set/is empty|is not empty=]
        and [=set/contains|does not contain=] |impression|'s [=impression/match value=],
        [=iteration/continue=].

    1.  If |options|' [=validated conversion options/impression sites=]
        [=list/is empty|is not empty=] and
        [=list/contains|does not contain=] |impression|'s [=impression/impression site=],
        [=iteration/continue=].

    1.  Let |impressionCaller| be |impression|'s [=impression/intermediary site=]
        if it is not `undefined`, |impression|'s [=impression/impression site=] otherwise.

    1.  If |options|' [=validated conversion options/impression callers=] [=set/is empty|is not empty=]
        and [=set/contains|does not contain=] |impressionCaller|,
        [=iteration/continue=].

    1.  [=set/Append=] |impression| to |matching|.

1.  Return |matching|.

</div>

#### Last-N-Touch Attribution #### {#last-n-touch-attribution}

<div algorithm>
To <dfn>fairly allocate credit</dfn>, given a [=list=] of doubles |credit| and an integer |value|:
1.  [=Assert=]: |credit| is not [=list/is empty|empty=].
1.  Let |sumCredit| be the sum of |credit|'s [=list/items=].
1.  Let |roundedCredit| be a new [=list=].
1.  [=list/iterate|For each=] |item| of |credit|:
    1.  Let |normalizedCredit| be |value| * |item| / |sumCredit|.
    1.  [=list/append|Append=] |normalizedCredit| to |roundedCredit|.
1.  Let |idx1| be 0.
1.  [=list/iterate|For each=] |n| of [=list/get the indices=] of |roundedCredit|, removing the first [=list/item=]:
    1.  Let |idx2| be |n|.
    1.  Let |frac1| be |roundedCredit|[|idx1|] − floor(|roundedCredit|[|idx1|]).
    1.  Let |frac2| be |roundedCredit|[|idx2|] − floor(|roundedCredit|[|idx2|]).
    1.  If |frac1| and |frac2| are both equal to zero, [=iteration/continue=].
    1.  If |frac1| + |frac2| is greater than 1, let |incr1| be 1 − |frac1| and |incr2| be 1 − |frac2|.
    1.  Otherwise, let |incr1| be −|frac1| and |incr2| be −|frac2|.
        <p class=note>|incr1| denotes the amount to increment |roundedCredit|[|idx1|] so that it is integral, and similar for |incr2| and |idx2|.
        Note that these values can be negative.

    1.  Let |p1| be |incr2| / (|incr1| + |incr2|).
        <p class=note>The value |p1| denotes the probability that the [=list/item=] in |idx1| is rounded to an integer.
        Divide by zero occurs when |incr1| + |incr2| is 0, which is only possible if both |frac1| and |frac2|
        are integers (either both 0 or 1 exactly). In this case |idx2| does not need to be rounded, so we just skip it.

    1.  Let |r| be a random double between 0 and 1 (inclusive).
    1.  If |r| is less than |p1|, let |incr| be |incr1| and swap the values of |idx1| and |idx2|.
    1.  Otherwise, let |incr| be |incr2|.
    1.  Increment |roundedCredit|[|idx2|] by |incr|.
    1.  Decrement |roundedCredit|[|idx1|] by |incr|.
1.  Let |integerCredit| be the result of converting [=list/iterate|every=] [=list/item=] from |roundedCredit| into an integer by rounding to the nearest integer,
    and rounding halfway cases away from zero.
1.  Return |integerCredit|.
    <p class=note>This final rounding step is only here in cases where tiny floating-point addition and subtraction errors do not completely remove
    the fractional part for |roundedCredit|[|idx1|]. The rounding mode at half will never actually occur, and is chosen to match C++ <code>std::round</code>
    behavior for ease of implementation.

    <p class=note>The algorithm aims to 1) allocate exactly |value| total value across assignments,
    2) maintain the property that the expected value of |integerCredit| is exactly equal to the normalized credit
    (i.e. |credit| * |value| / |sumCredit| where * denotes element-wise multiplication)
    3) never incur an error greater than 1 to any assignment.


</div>

<div algorithm>
To <dfn>fill a histogram with last-n-touch attribution</dfn>, given a [=set=] of
  [=impressions=] |matchedImpressions|, an integer |histogramSize|, an integer |value|, and
  a [=list=] of doubles |credit|:

1.  [=Assert=]: |matchedImpressions| is [=set/is empty|not empty=].
1.  Let |sortedImpressions| be |matchedImpressions|, [=list/sorted in descending order=]
    by [=impression/priority=], then by [=impression/timestamp=].
1.  Let |N| be the minimum of the [=list/size=] of |credit|, and the [=list/size=] of |sortedImpressions|.
1.  Let |lastNImpressions| be the first |N| entries of |sortedImpressions|.
1.  [=list/remove|Remove=] all but the first |N| entries of |credit|.
1.  Let |normalizedCredit| be the result of [=fairly allocate credit|fairly allocating credit=] with |credit| and |value|.
1.  Let |histogram| be the result of invoking [=create an all-zero histogram=]
    with |histogramSize|.

1. [=list/iterate|For each=] |i| of [=list/get the indices|the indices=] of |lastNImpressions|:
    1.  Let |impression| be |lastNImpressions|[|i|].
    1.  Let |value| be |normalizedCredit|[|i|].
    1.  Let |index| be |impression|'s [=impression/histogram index=].
    1.  If |index| is less than |histogram|'s [=list/size=], increment |histogram|[|index|] by |value|.

1.  Return |histogram|.

</div>

## Setting Implementation-Defined Values ## {#impl-def}

This specification identifies several [=implementation-defined=] values.
This section includes some recommendations for implementations
regarding how to best set those values.

An implementation sets an [=implementation-defined=] <dfn>maximum lookback</dfn>
for {{AttributionImpressionOptions/lifetimeDays}} and
{{AttributionConversionOptions/lookbackDays}}.
[=Maximum lookback=] is a positive integer number of [=days=].
There is no point to having different maximum values for
these values as the smaller of the two values
will determine which saved [=impressions=] are available for conversions.

Implementations [=must=] set a [=maximum lookback=] of at least 30 days.
Within this period, implementations [=should=] attempt to retain
at least 1000 impressions per [=impression site=].

Implementations [=should=] retain impressions
beyond these recommended limits on time and number where possible.
Available capacity for storing impressions depends on both
the storage necessary to retain impression data
and the processing time needed to [=measure a conversion|produce a conversion report=].
An implementation [=may=] discard impressions before these limits are reached
if a site requests storage of impressions in excess of available capacity,
if requested by a user (see [[#opt-out]]),
or for [=implementation-defined=] reasons.

<p class=note>One possible reason an implementation might choose not to retain impressions
is that the site has not received sufficient user engagement.

An [=implementation-defined=] value is chosen for the lists of sites
passed to <a method for=Attribution>saveImpression()</a>
and <a method for=Attribution>measureConversion()</a>.
The <dfn>maximum number of conversion sites per impression</dfn>
is a limit on the number of values for {{AttributionImpressionOptions/conversionSites}};
implementations [=must=] set this value to at least 5.
The <dfn>maximum number of conversion callers per impression</dfn>
and <dfn>maximum number of impression callers for conversion</dfn>
are limits on the number of values for {{AttributionImpressionOptions/conversionCallers}}
and {{AttributionConversionOptions/impressionCallers}} respectively;
implementations [=must=] set each of these values to at least 10.
The <dfn>maximum number of impression sites for conversion</dfn>
is a limit on the number of values for {{AttributionConversionOptions/impressionSites}};
implementations [=must=] set this value to at least 30.

An [=implementation-defined=] value is chosen for
the <dfn>maximum number of credit values</dfn>,
which is a limit on the number of values for {{AttributionConversionOptions/credit}};
implementations [=must=] set this value to at least 10.
An [=implementation-defined=] value is chosen for
the <dfn>maximum number of match values</dfn>,
which is a limit on the number of values for {{AttributionConversionOptions/matchValues}};
implementations [=must=] set this value to at least 30.

The size of histograms
produced by <a method for=Attribution>measureConversion()</a>
is subject to both an [=implementation-define=] <dfn>maximum histogram size</dfn>
and <dfn>maximum aggregation-service histogram size</dfn>.
No minimum value for the [=maximum histogram size=] is set
as the expectation is that the choice of aggregation technology
will set a limit.
The [=maximum aggregation-service histogram size=]
will be a fixed value that is determined
by the choice of technology used by the [=aggregation service=];
it is not [=implementation-defined=].

### Privacy and Safety Limit Parameter Configuration ### {#safety-limits-configuration}

[=User agents=] configure the [=privacy budget=] and [=safety limits=] by defining values
for the following:

*   The <dfn>per-site privacy budget</dfn> (&epsilon;<sub>site</sub>) is [=implementation-defined=].
    Experiments with differentially private aggregates have shown
    that reasonable performance can be achieved with values in the range
    between 1 (more private) and 10 (more performance).

*   The <dfn>global privacy budget per epoch</dfn> (&epsilon;<sub>global</sub>) which is
    the maximum privacy budget available across all [=sites=] per [=epoch=],
    specified in [=microepsilons=].
    Implementations [=should=] set this value as a multiple of
    the per-[=site=] [=privacy budget=] per [=epoch=].

*   The <dfn>impression site quota per epoch</dfn> (&epsilon;<sub>imp-quota</sub>) which is
    the maximum privacy budget that a single [=impression site=]
    can enable to be consumed from the [=global privacy budget store|global privacy budget=] per [=epoch=],
    specified in [=microepsilons=].
    Implementations [=should=] set this value as a multiple of
    the per-[=site=] [=privacy budget=] per [=epoch=].

<p class=note> Configuring [=safety limits=] as multiples of the per-[=site=] budget determines
how the API can be used by multiple sites.
In setting this multiple,
implementations need to consider what they expect to be
the number of sites that might use their budget,
maybe adjusted downward to allow for sites
that do not fully use their budget.

<p class=note>Setting [=safety limits=] as multiples of the per-[=site=] budget
ensures that exhausting shared limits requires coordination by many sites,
making them primarily useful as a means of protecting against abuse
rather than as a primary privacy mechanism.



# HTTP API # {#http-api}

## Saving impressions ## {#http-api-impressions}

\`<dfn http-header><code>Save-Impression</code></dfn>\` is a
[=structured header/dictionary|Dictionary Structured Header=]
set on a response requesting that the user agent invoke the
<a method for=Attribution>saveImpression()</a> API.

<div class=example id=ex-save-impression-header>
This is the HTTP equivalent of <a href=#ex-save-impression>the JavaScript `saveImpression` example</a>:
<xmp highlight=http>
Save-Impression: histogram-index=3, match-value=2, conversion-sites=("advertiser.example"), lifetime-days=7
</xmp>
</div>

The following keys are defined, corresponding to the members of
the {{AttributionImpressionOptions}} dictionary passed to
<a method for=Attribution>saveImpression()</a>. Default values for omitted
optional keys are treated the same way as the corresponding
{{AttributionImpressionOptions}} field. Unknown dictionary keys are ignored,
as are unknown parameters.

<dl dfn-for=save-impression>
  <dt><dfn noexport><code>conversion-sites</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionImpressionOptions>conversionSites</a>,
    an [=structured header/inner list=] containing [=structured header/string|strings=].
    Each string value includes a domain name using A-labels only;
    [[RFC5890|Internationalized Domain Names]] therefore need to use [[RFC3492|punycode]].
    This key is optional.
  </dd>
  <dt><dfn noexport><code>conversion-callers</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionImpressionOptions>conversionCallers</a>,
    an [=structured header/inner list=] containing [=structured header/string|strings=].
    Each string value includes a domain name using A-labels only;
    [[RFC5890|Internationalized Domain Names]] therefore need to use [[RFC3492|punycode]].
    This key is optional.
  </dd>
  <dt><dfn noexport><code>histogram-index</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionImpressionOptions>histogramIndex</a>,
    an [=structured header/integer=] in the [=32-bit unsigned integer=] range. This key is required.
  </dd>
  <dt><dfn noexport><code>priority</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionImpressionOptions>priority</a>,
    an [=structured header/integer=] in the [=32-bit signed integer=] range. This key is optional.
  </dd>
  <dt><dfn noexport><code>match-value</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionImpressionOptions>matchValue</a>,
    an [=structured header/integer=] in the [=32-bit unsigned integer=] range. This key is optional.
  </dd>
  <dt><dfn noexport><code>lifetime-days</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionImpressionOptions>lifetimeDays</a>,
    a positive [=structured header/integer=]. This key is optional.
  </dd>
</dl>

<div algorithm>
To <dfn noexport>parse a `Save-Impression` header</dfn> given a [=header value=]
|input|, run these steps:

1.  Let |dict| be the result of [=structured header/parsing structured fields=]
    with <var ignore>input_bytes</var> set to |input| and
    <var ignore>field_type</var> set to "`dictionary`".
1.  If parsing failed, return an error.
1.  Let |histogramIndex| be |dict|["<code>[=save-impression/histogram-index=]</code>"] [=map/with default=] `undefined`.
1.  If |histogramIndex| is not an [=structured header/integer=] in the [=32-bit unsigned integer=] range, return an error.
1.  Let |opts| be a new {{AttributionImpressionOptions}} with the following items:
     : {{AttributionImpressionOptions/histogramIndex}}
     :: |histogramIndex|
1.  If |dict|["<code>[=save-impression/conversion-sites=]</code>"] [=map/exists=]:
     1.  Let |conversionSites| be its [=map/value=].
     1.  If |conversionSites| is not an [=structured header/inner list=], or if any of
         |conversionSites|' [=list/items=] is not a [=structured header/string=],
         return an error.
     1.  Set |opts|.{{AttributionImpressionOptions/conversionSites}} to |conversionSites|.
1.  If |dict|["<code>[=save-impression/conversion-callers=]</code>"] [=map/exists=]:
     1.  Let |conversionCallers| be its [=map/value=].
     1.  If |conversionCallers| is not an [=structured header/inner list=], or if any of
         |conversionCallers|' [=list/items=] is not a [=structured header/string=],
         return an error.
     1.  Set |opts|.{{AttributionImpressionOptions/conversionCallers}} to |conversionCallers|.
1.  If |dict|["<code>[=save-impression/match-value=]</code>"] [=map/exists=]:
     1.  Let |matchValue| be its [=map/value=].
     1.  If |matchValue| is not an [=structured header/integer=] in the [=32-bit unsigned integer=] range, return an error.
     1.  Set |opts|.{{AttributionImpressionOptions/matchValue}} to |matchValue|.
1.  If |dict|["<code>[=save-impression/lifetime-days=]</code>"] [=map/exists=]:
     1.  Let |lifetimeDays| be its [=map/value=].
     1.  If |lifetimeDays| is not a positive [=structured header/integer=], return an error.
     1.  Set |opts|.{{AttributionImpressionOptions/lifetimeDays}} to |lifetimeDays|.
1.  If |dict|["<code>[=save-impression/priority=]</code>"] [=map/exists=]:
     1.  Let |priority| be its [=map/value=].
     1.  If |priority| is not an [=structured header/integer=] in the [=32-bit signed integer=] range, return an error.
     1.  Set |opts|.{{AttributionImpressionOptions/priority}} to |priority|.
1.  Return |opts|.

</div>

## Measuring Conversions ## {#http-api-conversions}

\`<dfn http-header><code>Measure-Conversion</code></dfn>\` is a
[=structured header/dictionary|Dictionary Structured Header=]
set on a response requesting that the user agent invoke the
<a method for=Attribution>measureConversion()</a> API.

<div class=example id=ex-measure-conversion-header>
This is the HTTP equivalent of <a href=#ex-measure-conversion>the JavaScript `measureConversion` example</a>,
with the addition of a `report-url` to which the resulting report will be `POST`ed:
<xmp highlight=http>
Measure-Conversion: aggregation-service="https://aggregator.example/tee", histogram-size=20, epsilon=1.0, lookback-days=14, impression-sites=("publisher.example" "other.example"), impression-callers=("ad-tech.example"), match-values=(2), credit=(0.25 0.25 0.5), value=3, max-value=7, report-url="https://report-handler.example/foo"
</xmp>
</div>

The following keys are defined, corresponding to the members of
the {{AttributionConversionOptions}} dictionary passed to
<a method for=Attribution>measureConversion()</a>. Default values for omitted
optional keys are treated the same way as the corresponding
{{AttributionConversionOptions}} field. Unknown dictionary keys are ignored, as
are unknown parameters.

<dl dfn-for=measure-conversion>
  <dt><dfn noexport><code>aggregation-service</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>aggregationService</a>,
    a [=structured header/string=]. This key is required.
  </dd>
  <dt><dfn noexport><code>epsilon</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>epsilon</a>,
    a positive [=structured header/decimal=] or [=structured header/integer=]. This key is optional.
  </dd>
  <dt><dfn noexport><code>histogram-size</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>histogramSize</a>,
    a positive [=structured header/integer=]. This key is required.
  </dd>
  <dt><dfn noexport><code>lookback-days</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>lookbackDays</a>,
    a positive [=structured header/integer=]. This key is optional.
  </dd>
  <dt><dfn noexport><code>match-values</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>matchValues</a>,
    an [=structured header/inner list=] containing non-negative [=structured header/integer|integers=].
    This key is optional.
  </dd>
  <dt><dfn noexport><code>impression-sites</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>impressionSites</a>,
    an [=structured header/inner list=] containing [=structured header/string|strings=].
    Each string value includes a domain name using A-labels only;
    [[RFC5890|Internationalized Domain Names]] therefore need to use [[RFC3492|punycode]].
    This key is optional.
  </dd>
  <dt><dfn noexport><code>impression-callers</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>impressionCallers</a>,
    an [=structured header/inner list=] containing [=structured header/string|strings=].
    Each string value includes a domain name using A-labels only;
    [[RFC5890|Internationalized Domain Names]] therefore need to use [[RFC3492|punycode]].
    This key is optional.
  </dd>
  <dt><dfn noexport><code>credit</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>credit</a>,
    an [=structured header/inner list=] containing positive [=structured header/decimal|decimals=]
    or positive [=structured header/integer|integers=]. This key is optional.
  </dd>
  <dt><dfn noexport><code>value</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>value</a>,
    a positive [=structured header/integer=]. This key is optional.
  </dd>
  <dt><dfn noexport><code>max-value</code></dfn></dt>
  <dd>
    Value of <a dict-member for=AttributionConversionOptions>maxValue</a>,
    a positive [=structured header/integer=]. This key is optional.
  </dd>
  <dt><dfn noexport><code>report-url</code></dfn></dt>
  <dd>
    A [=structured header/string=] containing the [=potentially trustworthy URL=]
    to which the resulting report, if any, will be `POST`ed. The URL may be
    relative to the response URL. Its [=url/scheme=] must be "`https`".
    This key is required.
  </dd>
</dl>

<div algorithm>
To <dfn noexport>parse a `Measure-Conversion` header</dfn> given a [=header value=]
|input| and [=URL=] |baseUrl|, run these steps:

1.  Let |dict| be the result of [=structured header/parsing structured fields=]
    with <var ignore>input_bytes</var> set to |input| and
    <var ignore>field_type</var> set to "`dictionary`".
1.  If parsing failed, return an error.
1.  Let |aggregationService| be |dict|["<code>[=measure-conversion/aggregation-service=]</code>"] [=map/with default=] `undefined`.
1.  If |aggregationService| is not a [=structured header/string=], return an error.
1.  Let |histogramSize| be |dict|["<code>[=measure-conversion/histogram-size=]</code>"] [=map/with default=] `undefined`.
1.  If |histogramSize| is not a positive [=structured header/integer=] in the [=32-bit unsigned integer=] range, return an error.
1.  Let |reportUrlString| be |dict|["<code>[=measure-conversion/report-url=]</code>"] [=map/with default=] `undefined`.
1.  If |reportUrlString| is not a [=structured header/string=], return an error.
1.  Let |reportUrl| be the result of applying the [=URL parser=] to |reportUrlString|, with |baseUrl|.
1.  If |reportUrl| is failure, return an error.
1.  If |reportUrl| is not a [=potentially trustworthy URL=], return an error.
1.  If |reportUrl|'s [=url/scheme=] is not "`https`", return an error.
1.  Let |opts| be a new {{AttributionConversionOptions}} with the following items:
     : {{AttributionConversionOptions/aggregationService}}
     :: |aggregationService|
     : {{AttributionConversionOptions/histogramSize}}
     :: |histogramSize|
1.  If |dict|["<code>[=measure-conversion/epsilon=]</code>"] [=map/exists=]:
     1.  Let |epsilon| be its [=map/value=].
     1.  If |epsilon| is not a [=structured header/decimal=] or [=structured header/integer=], return an error.
     1.  Set |opts|.{{AttributionConversionOptions/epsilon}} to |epsilon|.
1.  If |dict|["<code>[=measure-conversion/lookback-days=]</code>"] [=map/exists=]:
     1.  Let |lookbackDays| be its [=map/value=].
     1.  If |lookbackDays| is not a positive [=structured header/integer=], return an error.
     1.  Set |opts|.{{AttributionConversionOptions/lookbackDays}} to |lookbackDays|.
1.  If |dict|["<code>[=measure-conversion/match-values=]</code>"] [=map/exists=]:
     1.  Let |matchValues| be its [=map/value=].
     1.  If |matchValues| is not an [=structured header/inner list=], or if any of
         |matchValues|' [=list/items=] is not an [=structured header/integer=] in
         the [=32-bit unsigned integer=] range, return an error.
     1.  Set |opts|.{{AttributionConversionOptions/matchValues}} to |matchValues|.
1.  If |dict|["<code>[=measure-conversion/impression-sites=]</code>"] [=map/exists=]:
     1.  Let |impressionSites| be its [=map/value=].
     1.  If |impressionSites| is not an [=structured header/inner list=], or if any of
         |impressionSites|' [=list/items=] is not a [=structured header/string=],
         return an error.
     1.  Set |opts|.{{AttributionConversionOptions/impressionSites}} to |impressionSites|.
1.  If |dict|["<code>[=measure-conversion/impression-callers=]</code>"] [=map/exists=]:
     1.  Let |impressionCallers| be its [=map/value=].
     1.  If |impressionCallers| is not an [=structured header/inner list=], or if any of
         |impressionCallers|' [=list/items=] is not a [=structured header/string=],
         return an error.
     1.  Set |opts|.{{AttributionConversionOptions/impressionCallers}} to |impressionCallers|.
1.  If |dict|["<code>[=measure-conversion/credit=]</code>"] [=map/exists=]:
     1.  Let |credit| be its [=map/value=].
     1.  If |credit| is not an [=structured header/inner list=], or if any of
         |credit|'s [=list/items=] is not a [=structured header/decimal=] or
         [=structured header/integer=], return an error.
     1.  Set |opts|.{{AttributionConversionOptions/credit}} to |credit|.
1.  If |dict|["<code>[=measure-conversion/value=]</code>"] [=map/exists=]:
     1.  Let |value| be its [=map/value=].
     1.  If |value| is not a positive [=structured header/integer=] in the
         [=32-bit unsigned integer=] range, return an error.
     1.  Set |opts|.{{AttributionConversionOptions/value}} to |value|.
1.  If |dict|["<code>[=measure-conversion/max-value=]</code>"] [=map/exists=]:
     1.  Let |maxValue| be its [=map/value=].
     1.  If |maxValue| is not a positive [=structured header/integer=] in the
         [=32-bit unsigned integer=] range, return an error.
     1.  Set |opts|.{{AttributionConversionOptions/maxValue}} to |maxValue|.
1.  Return (|opts|, |reportUrl|).

</div>

<div algorithm>
To <dfn noexport>send a report</dfn> given a [=byte sequence=] |report|,
a [=URL=] |url|, and an [=environment settings object=] |settings|:

1.  [=Assert=]: |url| is a [=potentially trustworthy URL=].
1.  [=Assert=]: |url|'s [=url/scheme=] is "`https`".
1.  Let |headers| be a new [=header list=] containing a [=header=] named
    `"Content-Type"` whose value is
    "<code>[[DAP#name-application-dap-report-medi|application/dap-report]]</code>".

    Note: This will need to be updated if {{AttributionAggregationProtocol}}
    ever gains a value other than {{AttributionAggregationProtocol/dap-18-histogram}}.
1.  Let |request| be a new [=request=] with the following properties:
    :   [=request/method=]
    ::  "`POST`"
    :   [=request/URL=]
    ::  |url|
    :   [=request/header list=]
    ::  |headers|
    :   [=request/body=]
    ::  |report|
    :   [=request/client=]
    ::  |settings|
    :   [=request/mode=]
    ::  "`cors`"
    :   [=request/cache mode=]
    ::  "`no-store`"
    :   [=request/keepalive=]
    ::  true
    :   [=request/credentials mode=]
    ::  "`omit`"
    :   [=request/referrer=]
    ::  |url|
1.  [=Fetch=] |request|, optionally retrying in the event of an error.

</div>

## Fetch monkey patches ## {#fetch-monkey-patches}

<div algorithm>
To <dfn noexport>handle Attribution headers</dfn> given a [=request=] |request|
and [=response=] |response|, run these steps:

1.  If |request|'s [=request/destination=] is not one of the following,
    return: `""`, `"audio"`, `"image"`, `"script"`, `"track"`, `"video"`.

1.  If |request|'s [=request/client=] is not a [=secure context=], return.

1.  If |response|'s [=response/URL=] is not a [=potentially trustworthy URL=], return.

1.  If |response|'s [=response/URL=]'s [=url/scheme=] is not "`https`", return.

1.  Let |implicitInputs| be the result of [=obtaining the implicit API inputs=] from |request|'s [=request/client=]
    with |response|'s [=response/URL=]'s [=url/origin=].

1.  If |implicitInputs| is null, return.

1.  Let |saveImpressionHeader| be the result of [=header list/get|getting=] <code>[:Save-Impression:]</code> from |response|'s [=response/header list=].

1.  If |saveImpressionHeader| is not null:

    1.  Let |impressionOptions| be the result of [=parse a Save-Impression header|parsing=] |saveImpressionHeader|.

    1.  If |impressionOptions| is not an error, [=save an impression|Save=] |impressionOptions| with |implicitInputs|.

1.  Let |measureConversionHeader| be the result of [=header list/get|getting=] <code>[:Measure-Conversion:]</code> from |response|'s [=response/header list=].

1.  If |measureConversionHeader| is not null:

    1.  Let |parseConversionResult| be the result of [=parse a Measure-Conversion header|parsing=] |measureConversionHeader|.

    1.  If |parseConversionResult| is not an error:

        1.  Let (|conversionOptions|, |reportUrl|) be |parseConversionResult|.

        1.  Let |reportPromise| be the result of running [=measure a conversion=] with |conversionOptions| and |implicitInputs|.

        1.  [=In parallel=]:
            1.  [=Upon fulfillment=] of |reportPromise|, let |result| be the fulfilled value.
            1.  [=Send a report=] with |result|.{{AttributionConversionResult/report}}, |reportUrl|, and
                |request|'s [=request/client=].

</div>

Modify [=HTTP-network fetch=] as follows:

<div algorithm=fetch-monkey-patch>
After the step

> If <var ignore>includeCredentials</var> is true, then the user agent should parse and store response `Set-Cookie` headers given |request| and |response|.

add the step

1. [=Handle Attribution headers=] with |request| and |response|.

</div>

# Implementation Considerations # {#implementation-considerations}

* Management and distribution of values for the following:
    * Histogram size
    * [=Conversion site=] for [=impressions=]
    * [=Impression site=] for [=conversions=]
    * [=impression/histogram index|Histogram indexes=]


# Aggregation # {#aggregation}

An <dfn>aggregation service</dfn> takes multiple pieces of attribution information
and produces an aggregate metric.

User agent implementations will have different requirements for aggregation.
However, the aggregation process has some common elements.

Firstly, user agents will need to be configured with,
or otherwise obtain,
information about the aggregation service.
This includes the aggregation methods that are supported
and any configuration that is required.

Each aggregation method needs to define
how a histogram is:

* prepared for aggregation,
* encrypted,
* annotated with any necessary metadata, and
* submitted to the aggregation service for aggregation.

The aggregation method also needs to define
how the aggregated result is obtained by a site.


## Multi-Party Computation Aggregation ## {#s-mpc}

A <dfn lt=MPC>Multi-Party Computation (MPC)</dfn> system is one that
involves multiple independent entities
that cooperatively compute an agreed function.

This specification uses an MPC system based on Prio [[PRIO]]
and the <dfn lt=DAP ignore>Distributed Aggregation Protocol (DAP)</dfn> [[DAP]].
This is a two-party MPC system that is characterized by
its reliance on client-provided proofs of correctness for inputs.
This allows for very efficient MPC operation
at a modest cost in the size of submissions to the system.

An aggregation service that uses MPC
comprises two or more independent services
that cooperate to compute a predefined function.

The basic guarantee provided by MPC
is that only the defined outputs of a function,
plus well-defined leakage,
is revealed to any entity.

The MPC guarantees hold only to the extent that
a subset of the entities that participate are honest.
For the two-party MPC used in Prio,
privacy--
that is, the confidentiality of inputs--
is maintained
as long as either MPC operator remains honest.
This MPC configuration does not protect
against the corruption of the outputs
by either MPC operator.


### Prio and DAP ### {#prio}

The <a enum-value for=AttributionAggregationProtocol>`dap-18-histogram`</a>
aggregation method uses Prio [[PRIO]]
and the Distributed Aggregation Protocol (DAP) [[DAP]].
Specifically, this aggregation method uses
the <dfn>Prio3L1BoundSum</dfn> instantiation [[PRIO-L1]]
of the Prio3 Verifiable Distributed Aggregation Function (VDAF) [[VDAF]].

DAP and the [=Prio3L1BoundSum=] instantiation define how a report is prepared,
encrypted, and submitted for aggregation.
DAP also defines how an aggregate is obtained
and what configuration is necessary
for a user agent to obtain about the aggregation service.

In using [=Prio3L1BoundSum=],
reports contain a distributed zero-knowledge proof
that allows the nodes that participate in the MPC
to confirm that the sum of the submitted histogram is less than a set value.
[=Prio3L1BoundSum=] can only validate that the histogram sum
is strictly less than a power of two.
That is, proofs confirm that
the sum is less than 2<sup><var>n</var></sup> for positive integer values of |n|.

To construct a report,
proofs are generated based on a value
that is the next power of two
greater than {{AttributionConversionOptions/maxValue}}.
This means that the [=aggregation service=] is unable to reject reports
between {{AttributionConversionOptions/maxValue}}
and the next power of two.
Consequently, a malicious [=user agent=] might generate a report
that contributes as much as double the value of {{AttributionConversionOptions/maxValue}}
to the aggregate histogram.
The proof ensures that there is no opportunity for excess contributions
when {{AttributionConversionOptions/maxValue}} is equal to 2<sup><var>n</var></sup> − 1;
the relative effect of any such attack can be reduced
by setting {{AttributionConversionOptions/maxValue}}
as close to 2<sup><var>n</var></sup> − 1 as other constraints allow.


### DAP Extensions ### {#dap-extensions}

Extensions to DAP [[DAP-ATTRIBUTION]] are necessary for this application:

*   [[DAP-ATTRIBUTION#collector-id|Collector identity]]
    (`collector_identity`)
    identifies the entity that is responsible
    for requesting aggregates.
    The value for this extension encodes the identity of the API caller,
    either an [=intermediary site=] or the [=conversion site=].
    The collector identity extension applies to an entire DAP task.

*   [[DAP-ATTRIBUTION#budget-source|Budget source]]
    (`budget_source`)
    identifies the entity that has expended [=privacy budget=].
    The value for this extension encodes the identity of the [=conversion site=].
    The budget source extension applies to an entire DAP task.

*   [[DAP-ATTRIBUTION#dp|Privacy budget]]
    (`privacy_budget`)
    ensures that the aggregation service does not aggregate reports
    that received less privacy budget
    than the aggregation task was configured with.
    The privacy budget extension applies to each report.

User agents use these extensions to construct
the reports that they generate.


### Report Encryption For DAP ### {#encrypt-dap}

<div algorithm>
To <dfn>construct a DAP report</dfn>,
producing a [=byte sequence=] |report|,
given [=validated conversion options=] |options|,
[=site=] |topLevelSite|,
[=site=] or `undefined` |intermediarySite|,
[=moment=] |now|,
and a [=list=] of [=integers=] |histogram|:

1.  Let |field| be Field128,
    as defined in [Section 6.1.3](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-vdaf-18#section-6.1.3)
    of [[VDAF]].

1.  Let |length| be the [=list/size=] of |histogram|.

1.  Let |maxValue| be |options|.[=validated conversion options/max value=].

1.  Let |chunkLength| be the square root of ([Math.ceil](https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-math.ceil)([log2](https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-math.log2)(|maxValue| + 1)) + 1) * |length|,
    rounded to the nearest integer.

1.  Let |vdaf| be a new PrioL1BoundSum VDAF [[PRIO-L1]] instance,
    passing |field|, |length|, |maxValue|, and |chunkLength|.

1.  Let |microEpsilon| be |options|.[=validated conversion options/epsilon=]
    multiplied by 1,000,000, then rounded toward positive Infinity.

1.  Let |caller| be |intermediarySite|,
    if |intermediarySite| is not `undefined`,
    otherwise |topLevelSite|.

1.  Let |taskConfig| be the [=byte sequences=] produced by encoding a `TaskConfiguration` instance
    as defined in [Section 4.2](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#section-4.2)
    of [[DAP]], with the following values:

    1.  An empty `task_info`.

    1.  A `leader_aggregator_endpoint` set to the URL of the DAP Leader,
        taken from the [=implementation-defined=] definition
        of the selected [=aggregation service=]
        in |options|.[=validated conversion options/Aggregation Service=].
        The encoded value is produced by invoking the [=URL serializer=]
        with the configured URL and `false` (for [=URL serializer/exclude fragment=]).

    1.  A `helper_aggregator_endpoint` set to the URL of the DAP Helper,
        taken from the [=implementation-defined=] definition
        of the selected [=aggregation service=]
        in |options|.[=validated conversion options/Aggregation Service=],
        produced using the same process as the `leader_aggregator_endpoint` value.

    1.  A `time_precision` value of 5.

    1.  A `min_batch_size` value of 20.

    1.  A `batch_mode` value of TBD (see [[DAP-ATTRIBUTION#batch-mode]]).

    1.  An empty `batch_config`.

    1.  A `vdaf_type` value of 7 (see [[PRIO-L1#dap]]).

    1.  A `vdaf_configuration` encoded according to PrioL1BoundSum [[PRIO-L1#dap]],
        with |length|, |maxValue|, and |chunkLength|.

    1.  A set of task extensions, `extensions`,
        a [=map=] of [=16-bit unsigned integers=] to [=byte sequences=]:

        *   The extension codepoint for [[DAP-ATTRIBUTION#collector-id|Collector identity]],
            mapped to the [=host serializer|serialized=] [=host=] component of |caller|.

        *   The extension codepoint for [[DAP-ATTRIBUTION#budget-source|privacy budget source]],
            mapped to the [=host serializer|serialized=] [=host=] component of |topLevelSite|.

1.  Let |taskID| be the [=byte sequence=] produced by the process described in [[DAP-TASKPROV#task-id]],
    passing |taskConfig|.

1.  Let |ctx| be the [=byte sequence=] formed by concatenating
    the [=isomorphic encode|encoded=] string `dap-18`
    and |taskID|,
    as defined in [Section 4.4.2.1](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#client-behavior)
    of [[DAP]].

1.  Let |reportID| be 16 bytes sampled from a cryptographically-secure random source [[RFC4086]].

1.  Let |rand| be 128 bytes sampled from a cryptographically-secure random source [[RFC4086]].

1.  Let |publicShare|, |inputShares| be the result of invoking |vdaf|.[`shard()`](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-vdaf-18#sec-def-shard),
    as defined in [Section 4.1](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-vdaf-18#section-4.1)
    of [[VDAF]],
    with |ctx|, |histogram|, |reportID| (as the VDAF "nonce" parameter), and |rand|.

1.  Let |time| be the integer resulting from dividing
    the [=duration from=] the [=Unix epoch=] to |now|
    by a [=duration=] of 5 seconds,
    rounding towards negative Infinity.

1.  Let |extensions| be a [=map=] of [=16-bit unsigned integers=] to [=byte sequences=],
    comprised of:

    *   The extension codepoint for [[DAP-ATTRIBUTION#dp|privacy budget]],
        mapped to the value of |microEpsilon|,
        encoded by invoking [`NumericToRawBytes`](https://tc39.es/ecma262/multipage/structured-data.html#sec-numerictorawbytes)
        with [UINT32](https://tc39.es/ecma262/multipage/indexed-collections.html#table-the-typedarray-constructors),
        the value |microEpsilon|,
        and `false` (for `isLittleEndian`).

1.  Let |reportMetadata| be encoded DAP [`ReportMetadata`](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#section-4.4.2)
    generated from |reportID|, |time|, and |extensions|.

1.  Let |encryptedInputShares| be an [=list/is empty|empty=] [=list=].

1.  [=list/iterate|For each=] |share| of |inputShares|,
    follow the method for encrypting shares
    described in [Section 4.4.2.1](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#section-4.4.2.1):

    1.  Let |pkR| be the public key of the corresponding role from
        the [=aggregation service=] [HPKE configuration](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#section-4.5.1)
        obtained for the [=aggregation service=]
        indicated by |options|.[=validated conversion options/Aggregation Service=].

        <p class=note>The URL for <a enum-value for=AttributionAggregationProtocol>"dap-18-histogram"</a> is expected to identify the DAP Leader role.
        Implementations need to obtain HPKE configuration for both Aggregators statically.
        The HPKE configuration <span class=allow-2119>must not</span> be fetched on demand,
        as the time that takes will leak information
        to callers of {{Attribution/measureConversion()}}.

    1.  Let |serverRole| be 2 for the first item (the Leader)
        and 3 for the second (the Helper).

    1.  Let |info| be the [=byte sequence=] formed by concatenating:
        the [=isomorphic encode|encoded=] value of the string `dap-18 input share`,
        a byte with the value 0x01, and |serverRole|.

    1.  Let |inputShareAAD| be constructed from
        |taskID|, |reportMetadata|, |publicShare|, and |taskConfig|
        following the structure for [`InputShareAad`](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#section-4.4.2.1).

    1.  Let |plaintextShare| be constructed from
        an empty set (for `private_extensions`) and |share| (for `payload`),
        following the structure for [`PlaintextInputShare`](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#section-4.4.2.1).

    1.  Let |hpke| be an HPKE [[RFC9180]] configuration
        that is based on the same [HPKE configuration](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#section-4.4.1).

    1.  Let |encryptedShare| be the result of invoking |hpke|.[`Seal<mode_base>()`](https://hpkewg.github.io/hpke/draft-ietf-hpke-hpke.html#section-6.1),
        passing |pkR|, |info|, |inputShareAAD|, and |plaintextShare|.

    1.  [=list/Append=] |encryptedShare| to |encryptedInputShares|.

1.  Let |report| be an encoded DAP [`Report`](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#section-4.4.2)
    generated from |reportMetadata|, |publicShare|, |encryptedInputShares|
    (the two values being the leader and helper encrypted input shares respectively),
    and [=aggregation service=] [HPKE configuration](https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-18#section-4.4.1)
    obtained from the DAP aggregators.

1.  Return |report|.

</div>


## Anti-Replay Requirements ## {#anti-replay}

[=Conversion reports=] generated by browsers are bound
to the amount of [=privacy budget=]
that was expended by the site that requested the report.

An [=aggregation service=] MUST guarantee
that it does not accept the same report more than once.


# Differential Privacy # {#dp}

This design uses the concept of [=differential privacy=]
as the basis of its privacy design. [[PPA-DP]]

<dfn lt='differential privacy'>Differential privacy</dfn>
is a mathematical definition of privacy
that can guarantee the amount of private information
that is revealed by a system. [[DP]]
Differential privacy is not the only means
by which privacy is protected in this system,
but it is the most rigorously defined and analyzed.
As such, it provides the strongest privacy guarantees.

Differential privacy uses randomized noise
to hide private data contributions
to an aggregated dataset.
The effect of noise is to hide
individual contributions to the dataset,
but to retain the usefulness of any aggregated analysis.

To apply differential privacy,
it is necessary to define what information is protected.
In this system, the protected information is
the [=impressions=] of a single user profile,
on a single [=user agent=],
over a single [=epoch=],
for a single website that registers [=conversions=].
[[#dp-unit]] describes the implications of this design
in more detail.

This attribution design uses a form of differential privacy
called <dfn>individual differential privacy</dfn>.
In this model, user agents are each separately responsible
for ensuring that they limit the information
that is contributed.

The [=individual differential privacy=] design of this API
has three primary components:

1.  User agents limit (using the [=privacy budget=]) the amount of information
    about [=impressions=] that leaves the device through [=conversion reports=].
    [[#dp-budget]] explores this in greater depth.

2.  [=Aggregation services=] ensure that any given [=conversion report=] is
    only used in accordance with the [=privacy budget=] that was accounted for it
    by the user agent.
    [[#anti-replay]] describes requirements on aggregation services
    in more detail.

3.  Noise is added by [=aggregation services=].
    [[#dp-mechanism]] details the mechanisms that might be used.

Together, these measures place limits
on the information that is released for each [=privacy unit=].


## Privacy Unit ## {#dp-unit}

An implementation of differential privacy
requires a clear definition for what is protected.
This is known as the <dfn>privacy unit</dfn>,
which represents the entity that receives privacy protection.

This system adopts a [=privacy unit=]
that is the combination of three values:

1.  A user agent profile.
    That is, an instance of a user agent,
    as used by a single person.

2.  The [=site=] that requests information about [=impressions=] (the [=conversion site=]).

    <p class=note>The sites that register impressions (the [=impression site=])
    are not considered.
    Those sites do not receive information from this system directly.

3.  The current [=epoch=].

A change to any of these values produces a new privacy unit,
which results in a separate [=privacy budget=].
Each site that a person visits receives a bounded amount of information
for each [=epoch=].

Ideally, the [=privacy unit=] is a single person.
Though ideal, it is not possible to develop a useful system
that guarantees perfect correspondence with a person,
for a number of reasons:

*   People use multiple browsers and multiple devices,
    often without coordination.

*   A unit that covered all websites
    could be exhausted by one site,
    denying other sites any information.

*   Advertising is an ongoing activity.
    Without allocating [=privacy budget=] for new data,
    sites could exhaust their budget forever.

### Formal Analysis of Privacy Properties and Their Limitations ### {#formal-analysis}

The privacy protections in Attribution are multi-layered:
1.  Per-site budgets limit how much can be learned about a user by any one conversion site.
1.  The global budget provides a backstop limit on how much can be learned about a user by all sites.
1.  Impression-site quotas limit how much conversion sites can learn about a user’s activity on any one impression site.
1.  A counter maintained after each user action limits how many sites can store data into or learn from API.

The formal privacy analysis in this specification is based on two papers.
The first [[PPA-DP]] establishes the theory
for on-device Individual DP accounting. The second [[PPA-DP-2]] expands the analysis to
the mathematical privacy guarantees afforded by per-site budgets and by the global budget.

The per-site budgets should be seen as the primary privacy protection. Per-site budgets should be configured to provide a meaningful DP guarantee.
However, the analysis in [[PPA-DP-2]] identified two assumptions that limit these guarantees:

1.  *No cross-site adaptivity in data generation.* A site's queryable data stream (impressions
    and conversions) <span class=allow-2119>must</span> be generated independently of past DP [=attribution results=] from other sites.
1.  *No leakage through cross-site shared limits.* Queries from one site <span class=allow-2119>must not</span> affect which
    reports are emitted to others.

In short, neither assumption can hold in practice.

An assumption of no cross-site adaptivity is necessary because the system involves multiple sites that could interact
with the same user over time.
Sites will change the ads they show to the user based on each other’s DP measurements. For example, if one advertiser
learns, from [=attribution results=], how to make better ads, some users could convert on their site
rather than a competitor’s. In this case, what one site learns -- counted only against
its own per-site budget -- alters the data (or absence of data) visible to their competitors, yet
this is not accounted for in the per-site budget of those competitors.

Any system that provides continuous measurement has this property, so the only conclusion can be to accept this limitation. That limitation is part of what justifies having a global DP budget and shared quotas, which lead to the second assumption.

An assumption of no cross-site leakage is necessary when we have shared limits that span multiple sites. An example of
such shared limits are the global safety limits that aim to provide a global DP guarantee.
If <a method for=Attribution>measureConversion()</a> requests from some sites cause a shared limit
to be reached, reports to other sites may be
filtered. For instance, a site that knows it has impressions learns something about whether the shared limit has been reached. Though this information is aggregated and noisy, it is information about the site that exhausted its budget, in excess of the per-site budget for that site.

Leakage through shared limits motivates using those limits only as a means of limiting abuse. Setting shared limits that are large multiples of the per-site budget makes it so that seeking to exploit shared limits requires coordination by at least that many sites. Larger multiples makes shared limits less useful as a privacy means of privacy protection and more suited as a means of protecting against denial of service or similar forms of abuse.

By contrast, the analysis shows that *the global budget* can be implemented to deliver *sound global individual
DP guarantees* without these limitations. However, to support the usage of the API by many sites, the global budget needs to be configured to be a significant multiple of the per-site budget.  This means that the DP guarantee it provides, while independent of any assumptions, cannot provide a meaningful DP protection alone. Therefore, per-site budgets provide the primary DP guarantee. The global budget can be viewed as a fallback in case of coordinated attack by malicious sites.

A global DP budget also safeguards against sites that are able to link user identity across many sites to combine per-site budgets. Per-site models do not account for this possibility, though it is common for some sites to have this capability. Notably, this includes identity providers, sites that receive user identifiers (such as email addresses or phone numbers), sites that successfully use navigation tracking [[NAV-TRACKING-MITIGATIONS]], and sites that are able to use cross-site cookies for any reason [[WEB-WITHOUT-3P-COOKIES]].  Using Attribution across multiple sites can present a coordination challenge for such sites, but the potential for sites to have the capability to link activity to a single person cannot be disregarded in any holistic analysis of the privacy of the system.


### Browser Instances ### {#dp-instance}

Each browser instance manages a separate [=privacy budget=].

Coordination between browser instances might be possible,
but not expected.
That coordination might allow privacy to be improved
by reducing the total amount of information that is released.
It might also improve the utility of attribution
by allowing impressions on one browser instance
to be converted on another.

Coordination across different implementations
is presently out of scope for this work.
Implementations can perform some coordination
between instances that are known to be for the same person,
but this is not mandatory.


### Per-Site Limits ### {#dp-site}

The information released to websites is done on the basis of [=site=].
This aligns with the same boundary used in other privacy-relevant functions.

A finer privacy unit, such as an [=origin=],
would make it trivial to obtain additional information.
Information about the same person could be gathered
from multiple origins.
That information could then be combined
by exploiting the free flow of information within the site,
using cookies [[COOKIES]] or similar.

[[#dp-safety]] discusses attacks that exploit this limit
and some additional [=safety limits=] that might be implemented
by user agents
to protect against those attacks.


### Privacy Budget Epochs ### {#dp-refresh}

Sites receive a separate differential privacy budget
that is used to query [=impressions=] recorded
in each [=privacy budget epoch=]
(or [=epoch=]).

This budget applies to the [=impressions=]
that are registered with the [=user agent=]
and later queried,
not [=conversions=].

From the perspective of the analysis [[PPA-DP]]
each [=epoch=] of [=impressions=] forms a separate database.
A finite [=privacy budget=] is enforced across all the queries made on each database.

Having a [=conversion report=] produced from [=impressions=]
that span multiple [=epochs=] has privacy consequences.
A single visit to a website can give that site information
about activities across many [=epochs=].
This only requires that
the [=conversion site=] is identified as the destination
for [=impressions=] over that entire period.
The number of [=epochs=] that can be queried is limited by [=user agents=].

The goal is to set an [=epoch=]
that is as large as feasible.
A longer period of time allows for a better privacy/utility balance
because sites can be allocated a larger overall budget
at any point in time,
while keeping the overall rate of privacy loss low.
However, a longer interval means that it is easier to
exhaust a privacy budget completely,
yielding no information until the next refresh.

The decision to set the [=epoch=] duration to a week is largely arbitrary.
One week is expected to be enough to allow sites
some flexibility to make decisions about how to spend [=privacy budgets=]
without careful planning that needs to account for
changes that might occur days or weeks in the future.

[[#dp-budget]] describes the process for budgeting in more detail.


## Privacy Budgets ## {#dp-budget}

Browsers maintain <dfn>privacy budgets</dfn>,
which are a means of limiting the amount of privacy loss.

This specification uses an individual form
of (&epsilon;, &delta;)-differential privacy as its basis.
In this model, privacy loss is measured using the value &epsilon;.
The &delta; value is handled by the [=aggregation service=]
when adding noise to aggregates.

Each user agent instance is responsible for
managing privacy budgets.

Each [=conversion report=] that is requested specifies an &epsilon; value
that represents the amount of privacy budget
that the report consumes and a maximum on the value that can be returned in the
conversion report.


### Privacy Budget Deduction ### {#dp-deduction}

When searching for [=impressions=] for the conversion report,
the user agent deducts the specified &epsilon; value from
the budget for the [=privacy budget epoch=] in which those impressions were saved.
If the [=privacy budget=] for that [=epoch=] is not sufficient,
the impressions from that [=epoch=] are not used.

Each time a [=conversion site=] invokes <a method for=Attribution>measureConversion()</a>
the [=deduct privacy and safety budgets|privacy budget is deducted=]
for [=epochs=] from which the [=attribution logic=] selected [=impressions=].

<div class=example id=ex-budget>
    In the following figure,
    impressions are recorded from a number of different sites,
    shown with circles.

    <figure>
    <pre class=include-raw>
    path:images/budget.svg
    </pre>
    <figcaption>An example of a store of impressions over time</figcaption>
    </figure>

    A [=conversion report=] might be requested at the time marked with "now".
    That conversion report selects impressions marked with black circles,
    corresponding to impressions from Sites B, C, and E.

    As a result, [=privacy budget=] for the [=conversion site=]
    is [=deduct privacy and safety budgets|deducted=]
    from [=epochs=] 1, 3, 4, and 5.
    No impressions were recorded for [=epoch=] 2,
    so no [=privacy budget|budget=] is deducted from that [=epoch=].
</div>

How a [=user agent=] manages exhaustion of a [=privacy budget=]
depends on the [=attribution logic=] that was chosen.


### Safety Limits ### {#dp-safety}

The basic [=privacy unit=] is vulnerable to attack
by an adversary that is able to correlate activity for the same person
across multiple [=sites=].

Groups of sites can sometimes coordinate their activity,
such as when they have shared ownership or strong agreements.
A group of sites that can be sure that particular visitor is the same person--
using any means, including something like FedCM [[FEDCM]]--
can combine information gained from this API.

This can be used to increase the rate
at which a site gains information from attribution,
proportional to the number of sites
across which coordination occurs.
The default privacy unit places no limit on the information released
in this way.

To counteract this effect, user agents can implement <dfn>safety limits</dfn>,
which are additional privacy budgets that do not consider site.
Safety limits might be significantly higher than per-site budgets,
so that they are not reached for most normal browsing activity.
The goal would be to ensure that they are only effective
for intensive activity or when being attacked.

Like the per-site privacy budget,
it is critical that sites be unable to determine
whether their request for a [=conversion report=] has caused
a safety limit to be exceeded.


## Differential Privacy Mechanisms ## {#dp-mechanism}

The differential privacy mechanism--
that is, the specific method by which noise is added--
can be chosen by the [=aggregation service=].

Adding Laplacian noise is expected to produce good results,
balancing the overall magnitude of noise
and the simplicity of implementation and analysis.
The current design uses a DP sensitivity based on an L1 norm,
which supports Laplace noise added in the aggregation.
Supporting other noise mechanisms may require additional changes
to how sensitivity is computed and signaled.

The addition of noise in a central location,
as defined for any of these aggregation services,
ensures that the total amount of noise does not increase
as the total number of reports increases.
This provides a utility benefit over differential privacy designs
that apply noise at the point that a report is generated
(that is, a local differential privacy model)
where noise increases in proportion to the total number of reports.


# Security Considerations # {#security}


## Impression Store ## {#security-impression-store}

The [=impression store=] used by the Attribution API
holds information related to browsing activity
and persists across browsing sessions.
Although the flow of information
through the impression store is strictly controlled,
it carries some amount of information across origins.

The following measures limit the possibility
of harmful information flow through the impression store:

*   Websites cannot read from the impression store.
    Information from the impression store
    is released only via encrypted [=conversion reports=].
    [[#dp|Differential privacy]], provided by a combination
    of functionality in the user agent
    and in the [=aggregation service=],
    provides a rigorous bound on
    the probability that the aggregated information
    output by the aggregation service
    is distinguishable from the value it would have
    absent any user's contribution.
*   Users can explicitly
    [[#removing-impressions|clear stored impressions]].
*   It is recommended that user agents limit how long
    data can persist in the impression store,
    even absent explicit user action,
    by imposing a maximum value of
    <a dict-member for=AttributionImpressionOptions>lifetimeDays</a>.


## Side Channel Risks in Implementation ## {#security-api-implementation}

The Attribution APIs must be implemented with care
for maintaining the required security and privacy properties.
A site calling the APIs cannot learn:

*   Whether the Attribution APIs are [[#opt-out|enabled]].
*   Whether an attribution occurred.
*   Whether the [=privacy budget=] is exhausted.
*   Whether the [=conversion report=] reflects a non-zero
    [=conversion value=].
*   Which <a dict-member for=AttributionImpressionOptions>histogramIndex</a>
    is assigned the [=conversion value=].
*   The [=epoch start time|time=] that [=epochs=] start.

Note that explicit return values or thrown exceptions
are not the only way that a site can learn from
the Attribution APIs.
It may be possible to infer sensitive information from
<dfn>side channels</dfn> like:

*   Variation in the time it takes for the APIs to complete.
*   Consumption of shared resources by the API,
    such as memory, storage, network, and CPU.
    This includes any enforcement of any limits on that consumption,
    if that could be observed by the site.

Variation in the execution time
of the functions in the API
is the primary consideration for maintaining guarantees.
There are two factors of particular concern for execution time:

*   The number of impressions that
    <a method for=Attribution>measureConversion()</a> handles.
    Because sites control how many impressions are saved
    and the logic for selecting them,
    this creates a significant exposure to sites
    creating cross-site timing side channels.

*   Access to shared global state.
    Concurrent access to the API is governed
    by a single [=attribution budget lock=]
    to safeguard against correctness errors.
    That lock creates a means of information leakage
    between sites that concurrently access the API.

The shared global state
in the [=global privacy budget store=],
the [=impression site quota store=],
and [=epoch start time=]
are less of a risk
as those values never directly affect algorithm run time.
Implementations still need to ensure that any global state
does not contribute to a [=fingerprint=]
or other information leakage.

While complete elimination of all side channels is impractical,
implementations must make reasonable efforts to prevent
leakage of sensitive information from the attribution APIs.
Strategies to prevent leakage include:

*   Fully validating all API inputs, even when the API
    is disabled.
*   Avoiding conditional logic. For example,
    <a method for=Attribution>measureConversion()</a>
    should always go through the full process of constructing
    a conversion report, even when the [=conversion value=] to be
    reported is zero.
*   Setting a fixed running time for certain operations.


## Aggregation Services ## {#security-aggregation-services}

Although not part of the web platform,
security of aggregation services is quite important
to the overall security of the Attribution mechanism.
[=Conversion reports=]
produced by <a method for=Attribution>measureConversion()</a>
are encrypted using cryptographic key(s) of the aggregation service.
Thus, much of the potential for disclosure
of the information contained in these reports
depends on the details of the aggregation service.

[=User agent=] developers should carefully consider
the design of an aggregation service
and the trustworthiness of the aggregation service operator
before adding it as a supported service for the Attribution API.
Additional discussion of these issues
may be found in [[#aggregation]] and [[#privacy]].


## Combining Reports from Multiple Sites ## {#security-multiple-sites}

The privacy mechanisms in the Attribution API
operate primarily at the granularity of [=sites=].
A malicious operator
may attempt to register [=impressions=] for multiple sites,
thus exceeding the amount of information that would otherwise
be released through attribution.
[[#dp-safety]] discusses establishing additional cross-site
privacy budgets to mitigate this possibility.


## Ad Fraud ## {#security-ad-fraud}

As with many technologies,
advertising on the web
has been the subject of various kinds of fraud.

Fraudulent registration of impressions
is a particular concern with the Attribution API,
because impressions are stored only on the device.
It is not possible to apply server-side intelligence
to identify fraudulent impressions and exclude them
from attribution. Conversely, even though [=conversion reports=]
are encrypted, because the reports are sent
to a server, the server can make a determination that
the conversion is likely fraudulent and exclude it from
aggregation.

An important mitigation against malicious use
of the Attribution APIs is the explicit specification
of eligible conversion sites when registering an impression,
and of eligible impression sites and [=impression/histogram indexes=]
when registering a conversion.
This prevents impressions on arbitrary malicious sites
from interfering with attribution to the intended set
of candidate impressions.


# Privacy Considerations # {#privacy}

The main privacy goal of this API is
to ensure that providing sites with the ability to perform attribution
does not improve their ability to perform [=cross-site recognition=].

This section provides more information
about the protections necessary to achieve this goal.
Additional discussion talks about secondary privacy goals,
such as the prevention of [=same-site recognition=].


## Information Exposed by the Attribution API ## {#privacy-exposure}

The [=impression store=] and [=privacy budget store=]
contain information about a cross-section of browsing activity.
As use of the API increases,
so does the scope of this information.
However, most of the information written to these stores
is never disclosed.
Because attribution is performed on the device
(<dfn ignore=''>on-device attribution</dfn>),
only information about attributed conversions is exposed by the
Attribution API. This contrasts with other schemes in which
information about both impressions and conversions is sent to the
aggregation service for <dfn ignore=''>off-device attribution</dfn>.
In the latter class of schemes, the amount of information
that could be revealed in a compromise of the aggregation service
(or in a compromise of communication with the aggregation service)
is significantly larger.

When the Attribution API makes an attribution, information
about that attribution is released from the device
only to the extent the [[#dp|differential privacy]] restrictions allow.

While the Attribution API is intended to measure
the association of relatively infrequent conversion events
with a limited set of related impression candidates,
it is important to consider how the API might be misused
for larger-scale data collection.
The requirement that impressions enumerate
the possible [=conversion sites=] (and vice-versa)
has an important role in preventing misuse of the API
for mass data collection, and in making attempts
at such misuse more visible.


## Disabling the Attribution API ## {#opt-out}

User agents [=must=] provide controls
for users to disable the Attribution API.

The Attribution API
is designed to reveal only aggregate information.
The use of [[#dp|differential privacy]]
limits the chance of determining whether any particular user
contributed to the aggregated output.
However, some users may still prefer
not to participate in attribution measurement.

Implementations can offer users a choice to opt out
using a dedicated control for the Attribution API,
or through a consolidated privacy control that applies to multiple features.

User agent developers should consider interaction
of other privacy modes with the Attribution API.
For example, attribution might be disabled in a private browsing mode,
or it might be disabled
if the user has opted out of collection of diagnostic data.

By design, whether a user has opted out is not detectable by websites.

To minimize the risk of [=fingerprinting=],
and to prevent discrimination
against users who choose to disable the Attribution API,
sites <span class=allow-2119>must not</span> be able to detect that the API is disabled.
Specifically, all calls to the Attribution API
that are otherwise valid
complete successfully, even when the API is disabled.
The only difference in behavior
is that [=conversion reports=] returned when the API is disabled
will never report any [=conversion value=].
Because the reports are encrypted,
this difference cannot be detected
by the site receiving the conversion report.


## Visibility ## {#visibility}

Implementations [=should=] offer users a way
to view the status of the impression store
and to review past report submissions.

These interfaces might be limited to summary information that
show aggregate use of the Attribution API by sites.
Interfaces to examine the details of impressions and submitted reports
could enable diagnosing the operation of the API
by both users and web developers.


## Unconfigured Browsers ## {#unconfigured}

This API assumes that [=user agent=] instances
have all of the configuration necessary
to answer requests to <a for=Attribution>measureConversion()</a>.

If the [=aggregation service=] configuration necessary
for invoking <a for=Attribution>measureConversion()</a>
is either absent or out of date,
that could be observable to sites.

If the retrieval of configuration
could delay the resolution of a call to <a for=Attribution>measureConversion()</a>,
this creates a timing side channel.
If a fake response is generated instead, differences between
a response from a properly configured [=user agent=]
and a fake response
might be observable.
This might be the use of key identifiers or
other unencrypted metadata.
A difference in ciphertext length might also reveal changes to what is encrypted
or changes in choice of algorithm.

Detecting stale or absent configuration might be used
to [=fingerprint=] the [=user agent=].

A [=user agent=] [=should=] therefore
prioritize the acquisition of [=aggregation service=] configuration
in a way that is not observable to sites.
This might be achieved by obtaining configuration at startup,
before starting to load any content.

If the necessary configuration cannot be obtained,
or is obviously stale,
an implementation might choose to immediately reject
when <a for=Attribution>measureConversion()</a> is invoked.
This leaks information,
but it could leak less than attempting to generate a fake value.


## Including Identifying Information with Saved Impressions ## {#privacy-impression-store}

Sites are able to encode some amount of data
in impressions,
using {{AttributionImpressionOptions/matchValue}}
or other fields.
The API does not prevent sites from encoding user identifiers
in these fields.
The attribution process can use this data
when constructing a [=conversion report=],
which implies some risk of that identifying information
becoming available to the site that receives that report.
The following measures mitigate this risk:

*   The [=impression store=] cannot be read directly.
    Thus, identifiers are only usable for tracking
    to the extent information about them
    is revealed in [=conversion reports=].
*   The information in [=conversion reports=] is only revealed
    after aggregation and the addition of noise.
*   Users have the ability to [[#removing-impressions|clear the impression store]].
*   No impressions are saved to the impression store
    when the Attribution API is [[#opt-out|disabled]].


## Use in Third-party Contexts ## {#privacy-third-party-contexts}

The Attribution API is available even in third-party contexts.
In particular, a third-party iframe
may call <a method for=Attribution>saveImpression()</a>.
Note, however, that the impression is recorded with the [=site=]
of the top-level navigation context, not the [=origin=] of the iframe.

While the availability of the API in third-party contexts
carries some increase in privacy risk,
this support is deemed necessary
because iframes are commonly used to display advertisements.


## Clearing API State ## {#clear-budget-store}

A [=user agent=] might present the option to clear storage.
These exist for two reasons:

*   Privacy toward sites,
    so that the sites cannot recognize the [=user=] in future interactions
    (that is, to prevent [=same-site recognition=]).

*   Removing traces of activity locally,
    so that other users of a computer
    cannot access browsing history.

Clearing the state that tracks [=privacy budget=] expenditure
has an adverse effect on privacy toward sites.
Sites would then be able to gain more information
from attribution.

A [=user agent=] may clear data
from the [=privacy budget store=] and [=epoch start time=]
when the API is [[#opt-out|disabled]].
In that case, if the API is re-enabled,
there is no way to determine what budget was expended
prior to the API being [[#opt-out|disabled]].
In that case, a [=user agent=] can update
the value of [=last browsing history clear=]
to ensure that [=privacy budgets=] are not inadvertently exceeded.


### Clearing Site Data ### {#clear-site-data}

When clearing site data at the request of a [=user=],
but retaining browsing history,
a [=user agent=] invokes [=clear browsing history for attribution=],
given the [=set=] of affected [=sites=],
false (for [=clear browsing history for attribution/forgetVisits=]),
and the time that the action was taken.
This sets the privacy budget for that site to zero,
preventing any use of conversion measurement on that site.
This does not remove saved impressions from the [=impression store=];
logically, impressions are transferred to the [=conversion site=]
at the time they are saved.

When clearing site data at the request of a [=site=],
through the use of the [:Clear-Site-Data:] header,
a [=user agent=] only [=clear impressions for a site|removes impressions=],
without altering either the [=privacy budget store=]
or the [=epoch start time=].


### Clearing Browsing History ### {#clear-browsing-history}

Updating the [=privacy budget store=] is insufficient
when clearing browsing history.
Retaining per-[=site=] information
necessary to prevent privacy loss toward sites
leaves information about visits to sites
for other users of a computer to discover.

A user agent that clears browsing history
invokes [=clear browsing history for attribution=],
given the [=set=] of affected [=sites=],
true (for [=clear browsing history for attribution/forgetVisits=]),
and the time that the operation was initiated.

When clearing browsing history,
[=user agents=] need to
remove all per-[=site=] [=privacy budget=] information
(that is, remove entries from the [=privacy budget store=]).
[=User agents=] also need to ensure that
any subsequent [=privacy budget=] expenditure
cannot cause privacy loss in excess of configured limits
as a result of losing that information.

This can be achieved by disabling attribution
for the [=epoch=]
in which browsing history was discarded.
Otherwise, a [=site=] that expends its budget
immediately prior to the clearing of history
would be able to learn more through the API
than it could without the clearing of state.

<p class=note>
This disables the API for the remainder of the [=epoch=]
for affected [=sites=].
Because the [=epoch start time=] is not cleared,
the [=epoch=] timeline remains continuous.

A [=user agent=] remembers when history was last cleared
in the [=last browsing history clear=] value.
This is used to prevent [=privacy budget|budget=] expenditure
until it is guaranteed that a [=site=] cannot exceed
the [=user agent=]-chosen maximum allowed [=privacy budget=].

The [=get the starting epoch for attribution=] algorithm
ensures that a [=conversion site=]
cannot query [=impressions=] from any [=epoch=]
that starts within one [=epoch=] [=duration=]
from when state is cleared.


### Clearing Impressions ### {#removing-impressions}

A mechanism must be provided to clear the [=impression store=].
For example, the impression store could be cleared
upon activation of the control that
[[#opt-out|disables]] the Attribution API.

It is recommended that any mechanism a [=user agent=] provides
to clear stored data (history, cookies, etc.)
be extended to cover the impression store.
[[#clear-budget-store]] provides more detailed information
on the clearing of stored data.

A [=user agent=] that clears state for a [=site=]
must discard all [=impression store|saved impressions=]
that were saved during the affected period
with a [=same site|matching=] [=impression/impression site=]
or [=impression/conversion site=].
For an [=impression site=],
these [=impressions=] relate to activity that was cleared.
A [=conversion site=] that has had state cleared
will not be able to use these [=impressions=].

[=Impressions=] that have a [=same site|matching=] [=impression/intermediary site=]
may be retained.


## Choice of Clock ## {#why-wall-clock}

This API uses a [=wall clock=] as its basis for time.
This is primarily because the API relies on a persistent notion of time.
A [=monotonic clock=] is only defined during a single execution of a [=user agent=],
so it has no guarantee of consistency if a [=user agent=] is restarted.

A [=wall clock=] can be adjusted to account for errors that might accumulate
due to clock drift.
A [=wall clock=] therefore is not guaranteed to always advance at a consistent rate,
including the possibility that it might sometimes decrease.

Decreases in the [=wall clock=] do not affect the privacy guarantees
that this API provides.
Only increases in the [=wall clock|clock=],
can have an adverse privacy effect.
Increases above the normal progress of time
might result in the renewal of [=privacy budget=]
more quickly than intended.

For a clock that undergoes corrections within each [=epoch=],
clock adjustments will have no privacy effect.
A single correction that is sufficiently large
might cause [=privacy budgets=] to be renewed
ahead of schedule,
resulting in a one-time increase in privacy loss.
Continuous large corrections have the most serious effect on privacy,
as each transition between epochs
will release additional [=privacy budget=].

<p class=note>A very large increase in time
that skips entire [=epochs=]
does not result in additional privacy loss.
No privacy loss is possible
unless an [=impression=] can be [[#save-impression-api|saved]].

Of course, any [=user agent=] that has a need for large
or continuous
corrections to its clock will likely be highly identifiable
as a result of the time that it reports.
That alone is likely enough to enable unwanted [=cross-site recognition=].


# Acknowledgements # {#ack}

This specification is the result of a lot of work from many people.
The broad shape of this level of the API is based on an idea from Luke Winstrom.
The privacy architecture is courtesy of the authors of [[PPA-DP]].


<pre class=anchors>
urlPrefix: https://fetch.spec.whatwg.org/; spec: html; type: dfn
    text: request origin; url: #concept-request-origin
    text: HTTP-network fetch; url: #concept-http-network-fetch
urlPrefix: https://html.spec.whatwg.org/; spec: html; type: dfn
    text: active document; url: #nav-document
    text: activation notification
    text: activation triggering input event
    text: descendent navigables
    text: document state
    text: host; url: #concept-origin-host
    text: initiator origin; url: #document-state-initiator-origin
    text: obtain a site
    text: origin; url: #concept-origin
    text: relevant settings object
    text: same site
    text: scheme; url: #concept-origin-scheme
    text: scheme-and-host
    text: site
    text: top-level origin; url: #concept-environment-top-level-origin
    text: top-level traversable; url: #nav-top
    text: transient activation duration
    text: iframe; url: #child-navigable
urlPrefix: https://infra.spec.whatwg.org/; spec: infra; type: dfn;
    text: set; url: #sets
    text: string
    text: user agent
urlPrefix: https://storage.spec.whatwg.org/; spec: storage; type: dfn;
    text: storage key
urlPrefix: https://url.spec.whatwg.org/; spec: url; type: dfn;
    text: domain label
    text: host parser; url: #concept-host-parser
    text: host serializer; url: #concept-host-serializer
    text: registrable domain; url: #host-registrable-domain
urlPrefix: https://w3ctag.github.io/privacy-principles/; type: dfn;
    text: collective privacy
    text: cross-context recognition; url: #dfn-cross-context-recognition
    text: cross-site recognition; url: #dfn-cross-site-recognition
    text: same-site recognition; url: #dfn-same-site-recognition
urlPrefix: https://www.w3.org/TR/fingerprinting-guidance/; type: dfn;
    text: fingerprint; url: #dfn-browser-fingerprinting
    text: fingerprinting; url: #dfn-browser-fingerprinting
urlPrefix:https://tc39.es/ecma262/#;type:dfn;spec:ecma-262
    url:realm;text:realm
</pre>
<pre class=anchors>
spec:structured header; type:dfn; urlPrefix: https://httpwg.org/specs/rfc9651;
    text: structured header; url: #name-introduction
    for: structured header
        text: decimal; url: #decimal
        text: dictionary; url: #dictionary
        text: parse structured fields; url: #text-parse
        text: string; url: #string
        text: integer; url: #integer
        text: item; url: #item
        text: inner list; url: #inner-list
</pre>
<pre class=link-defaults>
spec:css-2025; type:dfn; text:user
</pre>
<pre class=biblio>
{
  "coppacalypse": {
    "authors": [
      "Garrett Johnson",
      "Tesary Lin",
      "James C. Cooper",
      "Liang Zhong"
    ],
    "title": "COPPAcalypse? The Youtube Settlement's Impact on Kids Content",
    "href": "https://papers.ssrn.com/sol3/papers.cfm?abstract_id=4430334",
    "date": "2024-03-14"
  },
  "dap": {
    "authors": [
      "Tim Geoghegan",
      "Christopher Patton",
      "Brandon Pitman",
      "Eric Rescorla",
      "Christopher A. Wood"
    ],
    "date": "2024-04-29",
    "href": "https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-16",
    "title": "Distributed Aggregation Protocol for Privacy Preserving Measurement",
    "publisher": "IETF"
  },
  "dap-attribution": {
    "authors": [
      "Martin Thomson"
    ],
    "title": "Distributed Aggregation Protocol (DAP) Extensions for the Attribution API",
    "date": "2025-01-15",
    "href": "https://datatracker.ietf.org/doc/html/draft-thomson-ppm-dap-attribution-00"
  },
  "dap-taskprov": {
    "authors": [
      "Shan Wang",
      "Christopher Patton"
    ],
    "title": "Task Binding and In-Band Provisioning for DAP",
    "date": "2025-09-05",
    "href": "https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-taskprov-03"
  },
  "dp": {
    "authors": [
      "Cynthia Dwork",
      "Aaron Roth"
    ],
    "date": "2014",
    "href": "https://doi.org/10.1561/0400000042",
    "title": "The Algorithmic Foundations of Differential Privacy",
    "publisher": "now, Foundations and Trends in Theoretical Computer Science, Vol. 9, Nos. 3–4"
  },
  "eu-ad": {
    "authors": [
      "Niklas FOURBERG",
      "Serpil TAŞ",
      "Lukas WIEWIORRA",
      "Ilsa GODLOVITCH",
      "Alexandre DE STREEL",
      "Hervé JACQUEMIN",
      "Jordan HILL",
      "Madalina NUNU",
      "Camille BOURGUIGON",
      "Florian JACQUES",
      "Michèle LEDGER",
      "Michael LOGNOUL"
    ],
    "title": "Online advertising: the impact of targeted advertising on advertisers, market access and consumer choice",
    "href": "https://www.europarl.europa.eu/thinktank/en/document/IPOL_STU(2021)662913",
    "publisher": "European Parliament",
    "date": "2021-06"
  },
  "free-gdp": {
    "authors": [
      "Leonard Nakamura",
      "Jon D. Samuels",
      "Rachel Soloveichik"
    ],
    "title": "Measuring the \"Free\" Digital Economy within the GDP and Productivity Accounts",
    "href": "https://www.bea.gov/research/papers/2017/measuring-free-digital-economy-within-gdp-and-productivity-accounts",
    "publisher": "Bureau of Economic Analysis",
    "date": "2017-10"
  },
  "online-advertising": {
    "authors": [
      "Avi Goldfarb",
      "Catherine Tucker"
    ],
    "title": "Online Advertising",
    "href": "https://doi.org/10.1016/B978-0-12-385514-5.00006-9",
    "edDraft": "http://www-2.rotman.utoronto.ca/~agoldfarb/OnlineAdvertising.pdf",
    "publisher": "Elsevier"
  },
  "ppa-dp": {
    "authors": [
      "Pierre Tholoniat",
      "Kelly Kostopoulou",
      "Peter McNeely",
      "Prabhpreet Singh Sodhi",
      "Anirudh Varanasi",
      "Benjamin Case",
      "Asaf Cidon",
      "Roxana Geambasu",
      "Mathias Lécuyer"
    ],
    "href": "https://arxiv.org/abs/2405.16719",
    "title": "Cookie Monster: Efficient On-device Budgeting for Differentially-Private Ad-Measurement Systems",
    "publisher": "SOSP'24"
  },
  "ppa-dp-2": {
    "authors": [
      "Pierre Tholoniat",
      "Alison Caulfield",
      "Giorgio Cavicchioli",
      "Mark Chen",
      "Nikos Goutzoulias",
      "Benjamin Case",
      "Asaf Cidon",
      "Roxana Geambasu",
      "Mathias Lécuyer",
      "Martin Thomson"
    ],
    "href": "https://arxiv.org/abs/2506.05290",
    "title": "Big Bird: Privacy Budget Management for W3C's Privacy-Preserving Attribution API"
  },
  "prio": {
    "authors": [
      "Henry Corrigan-Gibbs",
      "Dan Boneh"
    ],
    "title": "Prio: Private, Robust, and Scalable Computation of Aggregate Statistics",
    "date": "2017-03-14",
    "href": "https://crypto.stanford.edu/prio/paper.pdf"
  },
  "prio-l1": {
    "authors": [
      "Martin Thomson",
      "David Cook"
    ],
    "title": "A Prio Instantiation for Vector Sums with an L1 Norm Bound on Contributions",
    "date": "2024-10-21",
    "href": "https://datatracker.ietf.org/doc/draft-thomson-ppm-l1-bound-sum/"
  },
  "vdaf": {
    "authors": [
      "Richard L. Barnes",
      "David Cook",
      "Christopher Patton",
      "Phillipp Schoppmann"
    ],
    "title": "Verifiable Distributed Aggregation Functions",
    "date": "2026-01-30",
    "href": "https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-vdaf-18"
  },
  "WEB-WITHOUT-3P-COOKIES": {
    "title": "A Web Without Third-Party Cookies",
    "href": "https://www.w3.org/2001/tag/doc/web-without-3p-cookies/",
    "publisher": "W3C TAG"
  }
}
</pre>