api.bs

<pre class=metadata>
Title: Privacy-Preserving Attribution: Level 1
Shortname: ppa
Repository: w3c/ppa
URL: https://w3c.github.io/ppa/
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 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
Status: ED
Level: None
</pre>
<style>
@media (prefers-color-scheme: dark) {
  figure svg { background: white }
}
</style>


# Introduction # {#intro}

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

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


## Attribution ## {#s-attribution}

In advertising, <dfn 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
[[PRIVACY-PRINCIPLES#dfn-cross-context-recognition|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 is 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 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 lodged 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 aspects 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 [[PRIVACY-PRINCIPLES#dfn-cross-context-recognition|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,
as described in [[PRIVACY-PRINCIPLES#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,
though this capability is not presently supported in the API.

* Compatibility with privacy-preserving aggregation services
* Flexibility to assign buckets

* As histogram size increases, noise becomes a problem


# Overview of Operation # {#overview}

The private 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 Private 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 Private Attribution Operation</figcaption>
</figure>

When an [=impression=] occurs,
the <a method for=PrivateAttribution>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=PrivateAttribution>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 attribution
    logic (default last-touch) to select the most recent impression. The provided conversion
    value is added to a histogram at the bucket that was specified at the time of the
    attributed impression. 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.



# API Usage # {#api}

A site using the Private 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=PrivateAttribution>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=PrivateAttribution>aggregationServices</a> in deciding
whether to use the Private Attribution API.

To request a conversion report, a site calls
<a method for=PrivateAttribution>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=PrivateAttribution>aggregationServices</a>.
The name of the selected service must be supplied as
the {{PrivateAttributionConversionOptions/aggregationService}} member of the
{{PrivateAttributionConversionOptions}} dictionary when calling the
<a method for=PrivateAttribution>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=]
    derived from the [=top-level origin=]
    of the [=relevant settings object=]
    at the time that {{PrivateAttribution/saveImpression()}}
    is invoked to store an [=impression=].

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

*   An <dfn>intermediary site</dfn> is the [=site=]
    derived from the [=origin=]
    of the [=relevant settings object=]
    at the time that either {{PrivateAttribution/saveImpression()}}
    or {{PrivateAttribution/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}

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

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

The <dfn attribute for=PrivateAttribution>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=PrivateAttribution>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.privateAttribution?.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 PrivateAttributionProtocol { "dap-12-histogram", "tee-00" };

dictionary PrivateAttributionAggregationService {
  required DOMString protocol;
};

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

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

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

<dl dfn-for=PrivateAttributionAggregationService dfn-type=dict-member>
  <dt><dfn>protocol</dfn></dt>
  <dd>
    The {{PrivateAttributionProtocol|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 {{PrivateAttributionConversionOptions/aggregationService}} parameter
to <a method for=PrivateAttribution>measureConversion()</a> to select the identified aggregation service.

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

<dl dfn-for=PrivateAttributionProtocol dfn-type=enum-value>
  <dt><dfn>dap-12-histogram</dfn></dt>
  <dd>A DAP-based protocol [[DAP]] that uses [=MPC=]; see [[#s-mpc]].</dd>
  <dt><dfn>tee-00</dfn></dt>
  <dd>A protocol for submission to a [=TEE=]; see [[#s-tee]].</dd>
</dl>

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

The <dfn method for=PrivateAttribution>saveImpression()</dfn> 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 {{PrivateAttributionImpressionOptions/filterData}} value (2)
  that the advertiser might later use to select this advertisement,
  the index of the histogram ({{PrivateAttributionImpressionOptions/histogramIndex}} = 3)
  into which to include any attributed value,
  and a retention period ({{PrivateAttributionImpressionOptions/lifetimeDays}} = 7)
  that is at least as long as the advertiser requires.

  <xmp highlight=js>
    navigator.privateAttribution.saveImpression({
      histogramIndex: 3,
      filterData: 2,
      conversionSite: "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 PrivateAttributionImpressionOptions {
  required unsigned long histogramIndex;
  unsigned long filterData = 0;
  required USVString conversionSite;
  unsigned long lifetimeDays = 30;
};

[SecureContext, Exposed=Window]
partial interface PrivateAttribution {
  undefined saveImpression(PrivateAttributionImpressionOptions options);
};
</xmp>

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

<dl dfn-for=PrivateAttributionImpressionOptions dfn-type=dict-member>
  <dt><dfn>histogramIndex</dfn></dt>
  <dd>
    If <a method for=PrivateAttribution>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>filterData</dfn></dt>
  <dd>
    An optional piece of metadata associated with the impression. The filterData
    can be used to identify which impressions may receive attribution
    from a [=conversion=].
  </dd>
  <dt><dfn>conversionSite</dfn></dt>
  <dd>
    The site where [=conversions=] for this impression may occur, identified by
    its domain name. The <a method for=PrivateAttribution>measureConversion()</a>
    method will only attribute to this impression when called by the indicated
    site.
  <dt><dfn>lifetimeDays</dfn></dt>
  <dd>
    A positive "time to live" (in days) after which the [=impression=] can no
    longer receive attribution.
    If not specified, the default is 30 days.
    The [=user agent=] should impose an upper limit on the lifetime,
    and silently reduce the value specified here if it exceeds that limit.
  </dd>
</dl>

The <dfn for=PrivateAttribution method>saveImpression(|options|)</dfn> method
causes the user agent to invoke the [=save an impression=] algorithm
with [=this=]'s [=relevant settings object=]
and the provided |options|.


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

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

The <a method for=PrivateAttribution>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 {{PrivateAttribution/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
      ({{PrivateAttributionConversionOptions/lookbackDays}}),
      the [=impression sites=] that might have saved impressions
      ({{PrivateAttributionConversionOptions/impressionSites}}),
      the [=intermediary sites=] that might have saved impressions
      ({{PrivateAttributionConversionOptions/intermediarySites}}),
      and the choice of {{PrivateAttributionConversionOptions/filterData}}.

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

  1.  The choice of [=attribution logic=]
      that the browser will apply,
      plus any parameters that the logic needs.

      <xmp highlight=js>
        const attributionDetails = {
          logic: "last-touch",
          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.privateAttribution.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 PrivateAttributionConversionOptions {
  required USVString aggregationService;
  double epsilon = 1.0;

  required unsigned long histogramSize;

  unsigned long lookbackDays;
  unsigned long filterData;
  sequence<USVString> impressionSites = [];
  sequence<USVString> intermediarySites = [];

  PrivateAttributionLogic logic = "last-touch";
  unsigned long value = 1;
  unsigned long maxValue = 1;
};

dictionary PrivateAttributionConversionResult {
  required Uint8Array report;
};

[SecureContext, Exposed=Window]
partial interface PrivateAttribution {
  Promise<PrivateAttributionConversionResult> measureConversion(PrivateAttributionConversionOptions options);
};
</xmp>

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

<dl dfn-for=PrivateAttributionConversionOptions dfn-type=dict-member>
  <dt><dfn>aggregationService</dfn></dt>
  <dd>
    A selection from the [=aggregation services=] that can be found in <a
    attribute for=PrivateAttribution>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 an [=implementation-defined=] maximum.</dd>
  <dt><dfn>filterData</dfn></dt>
  <dd>Only [=impressions=] having a filterData value matching this value will be eligible to match this [=conversion=].</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=].</dd>
  <dt><dfn>intermediarySites</dfn></dt>
  <dd>
    A [=set=] of sites which called the <a method for=PrivateAttribution>saveImpression()</a> API.
    Only [=impressions=] recorded by scripts originating from one of the [=intermediary sites=]
    are eligible to match this [=conversion=].
  </dd>
  <dt><dfn>logic</dfn></dt>
  <dd>
    A selection from <a enum>PrivateAttributionLogic</a> indicating the
    [=attribution logic=] to use.
  </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>

The <dfn for=PrivateAttribution method>measureConversion(|options|)</dfn> method
causes the user agent to invoke the [=measure a conversion=] algorithm
with [=this=]'s [=relevant settings object=]
and the provided |options|.


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

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

*   Invocation of the <a method for=PrivateAttribution>saveImpression()</a> API,
    identified by the string "<code><dfn export for="PermissionPolicy"
    enum-value>save-impression</dfn></code>".
*   Invocation of the <a method for=PrivateAttribution>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=PrivateAttribution>saveImpression()</a> and
<a method for=PrivateAttribution>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=PrivateAttribution>measureConversion()</a> method to find matching
[=impressions=].


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

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

<div dfn-for=impression link-for-hint=PrivateAttribution>
<pre class=simpledef>
<dfn>Filter Data</dfn>: The {{PrivateAttributionConversionOptions/filterData}} value 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>Timestamp</dfn>: The time at which <a>saveImpression()</a> was called.
<dfn>Lifetime</dfn>: The number of days 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>.
</pre>
</div>


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

The [=user agent=] should periodically use
the timestamp and 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=PrivateAttribution>measureConversion()</a>
excludes expired [=impressions=] from [=attribution=]. However, the
[=user agent=] should not retain expired [=impressions=] indefinitely.


### Clearing ### {#impression-store-clearing}

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 Private Attribution API.
It is recommended that any mechanism a user agent provides
to clear stored browsing data (history, cookies, etc.)
be extended to cover the impression store.


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

<!--
Added this here for symmetry with the impression store and with the philosophy
that "just tell me how to implement" goes in the API section. But I'd also be
fine with putting this in the DP section.
-->

The [=privacy budget store=] records the state
of the per-[=site=] [=privacy budgets=].
It is updated by [=deduct privacy budget=].

<p class=issue>
The [=safety limits=] need to be described in more detail.
Some references to clearing
the [=impression store=] may need to be
updated to refer to the [=privacy budget store=] as well.


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

<dl dfn-for="privacy budget key">
: <dfn ignore>epoch</dfn>
:: A [=privacy budget epoch=]
: <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 [=floats=].

To <dfn>deduct privacy budget</dfn> given a [=privacy budget key=] |key|,
[=float=] |epsilon|, integer |sensitivity|, and integer |globalSensitivity|:

1.  If the [=privacy budget store=] does not [=map/contain=] |key|, [=map/set=]
     its value of |key| to be a [=user agent=]-defined value.

1.  Let |currentValue| be the result of [=map/get|getting the value=] of |key|
    in the [=privacy budget store=].

1.  If |currentValue| is less than or equal to 0, return false.

1.  Let |newValue| be |currentValue| - |epsilon| * |sensitivity| / |globalSensitivity|.

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

1.  Return whether |newValue| is greater than or equal to 0.



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

To <dfn>save an impression</dfn>,
given an [=environment settings object=] |settings|
and given <a dictionary lt=PrivateAttributionImpressionOptions>|options|</a>:

1.  Collect the implicit API inputs from |settings|:
    1.  The timestamp is set to the [=current high resolution time=].
    1.  The [=impression site=] is set to the result of
        [=obtain a site|obtaining a site=] from the [=top-level origin=].
    1.  The [=intermediary site=] is set to
        1.   a value of `undefined` if the [=origin=] is [=same site=]
             with the [=top-level origin=],
        1.   otherwise, the result of
             [=obtain a site|obtaining a site=] from the [=origin=].
1.  Validate the page-supplied API inputs:
    1. If |options|.{{PrivateAttributionImpressionOptions/lifetimeDays}} is 0,
        throw a {{RangeError}}.
    1. Clamp |options|.{{PrivateAttributionImpressionOptions/lifetimeDays}} to
        the [=user agent=]'s upper limit.
1.  If the private attribution API is [[#opt-out|enabled]], save the impression
    to the [=impression store=].

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


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

To <dfn>measure a conversion</dfn>,
given a [=environment settings object=] |settings|
and <a dictionary lt=PrivateAttributionConversionOptions>|options|</a>:

1.  Collect the implicit API inputs from |settings|:
    1.  Let |now| be the [=current high resolution time=].
    1.  Let |topLevelSite| (the [=conversion site=]) be the result of
        [=obtain a site|obtaining a site=] from the [=top-level origin=].
    1.  The [=intermediary site=] is set to
        1.   a value of `undefined` if the [=origin=] is [=same site=]
             with the [=top-level origin=],
        1.   otherwise, the result of
             [=obtain a site|obtaining a site=] from the [=origin=].
        <!-- TODO: the intermediary site is currently unused -->
1. Validate the page-supplied API inputs:
    1.  If <a dict-member for=PrivateAttributionConversionOptions>logic</a>
        is specified, and the value is anything other than
        <a enum-value for=PrivateAttributionLogic>"last-touch"</a>,
        throw a {{TypeError}}.
    1. If |options|.{{PrivateAttributionConversionOptions/lookbackDays}} is 0,
        throw a {{RangeError}}.
1.  Let |report| be an [=create an all-zero histogram|all-zero histogram=].
1.  If the private attribution API is [[#opt-out|enabled]], set |report| to the
    result of [=do attribution and fill a histogram=] with |options|,
    |topLevelSite|, and |now|.
1. Let |encryptedReport| be the result of encrypting |report|.
<!-- TODO: Define "encrypting" -->
1. Return |encryptedReport|.


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

A site that measures conversions can specify <dfn>attribution logic</dfn>,
which determines how the [=conversion value=] is allocated to histogram buckets.
The <a method for=PrivateAttribution>measureConversion()</a> function
accepts a <a dict-member for=PrivateAttributionConversionOptions>logic</a> parameter
that specifies the [=attribution logic=].

<xmp class=idl>
enum PrivateAttributionLogic {
  "last-touch",
};
</xmp>

Each attribution logic specifies a process for allocating values to histogram buckets,
after the [=common matching logic=] is applied, and privacy budgeting occurs.


To <dfn>do attribution and fill a histogram</dfn>, given
  <a dictionary lt=PrivateAttributionConversionOptions>|options|</a>,
  [=site=] |topLevelSite|, and [=moment=] |now|:

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

1.  For each |epoch| starting from the oldest [=epoch=] supported by the
    [=user agent=] to the current [=privacy budget epoch=]:
    <!-- TODO: Clarify how epoch iteration works. -->

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

    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 |budgetOk| be the result of [=deduct privacy budget=]
            with |key|, |options|.{{PrivateAttributionConversionOptions/epsilon}},
            |options|.{{PrivateAttributionConversionOptions/value}},
            and |options|.{{PrivateAttributionConversionOptions/maxValue}}.

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

1.  If |matchedImpressions| [=set/is empty=], return the the result of invoking
    [=create an all-zero histogram=] with
    |options|.{{PrivateAttributionConversionOptions/histogramSize}}.

1.  Switch on |options|.{{PrivateAttributionConversionOptions/logic}}:
      <dl class="switch">
      : <a enum-value for=PrivateAttributionLogic>"last-touch"</a>
      :: Return the result of [=fill a histogram with last-touch attribution=] with |matchedImpressions|,
        |options|.{{PrivateAttributionConversionOptions/histogramSize}}, and
        |options|.{{PrivateAttributionConversionOptions/value}}.

      </dl>


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

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

1.  Let |impression| be the value in |matchedImpressions| with the most recent
    [=impression/timestamp=].

1.  Let |histogram| be the result of invoking [=create an all-zero histogram=]
    with |histogramSize|.

1.  Let |index| be |impression|'s [=impression/histogram index=].

1.  If |index| is less than |histogram|'s [=list/size=], set |histogram|[|index|] to |value|.

1.  Return |histogram|.


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.

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

To perform <dfn>common matching logic</dfn>, given
<a dictionary lt=PrivateAttributionConversionOptions>|options|</a>, |epoch|, and
[=moment=] |now|:

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

1.  Let |lookbackDays| be |options|.{{PrivateAttributionConversionOptions/lookbackDays}}
    if it [=map/exists=], the [=implementation-defined=] maximum otherwise.

1.  If the number of [=days=] since the end of |epoch| exceeds |lookbackDays|,
    return |matching|.

1.  [=set/iterate|For each=] |impression| in the [=impression store=] for the |epoch|:
<!-- TODO: Clarify "for the |epoch|" -->

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

    1.  If |options|.{{PrivateAttributionConversionOptions/filterData}} [=map/exists=],
        and it is not equal to |impression|'s [=impression/filter data=],
        [=iteration/continue=].

    1.  If |options|.{{PrivateAttributionConversionOptions/impressionSites}}
        does not [=list/contain=] |impression|'s [=impression/impression site=],
        [=iteration/continue=].

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

1.  Return |matching|.

## User Control and Visibility ## {#user-control}

<p class=issue>
Consider merging this section with [[#privacy-opt-out]].

### Optional Participation ### {#opt-out}


* Users should be able to opt out. Opt out should be undetectable.

This mechanism may be a dedicated control
for the Private Attribution API,
or it may be a consolidated privacy control
that applies to multiple features,
including private attribution.
Further, user agent developers should consider interaction
of other privacy modes with the Private 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.

### Visibility ### {#visibility}

* User ability to view the impression store and past report submissions.


# Implementation Considerations # {#implementation-considerations}

* Management and distribution of values for the following:
    * Histogram size
    * [=Conversion site=] for [=impressions=]
    * [=Impression site=] for [=conversions=]
    * Ad IDs

# 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 Multi-Party Computation (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=PrivateAttributionProtocol>"dap-12-histogram"</a>
aggregation method uses Prio [[PRIO]]
and the Distributed Aggregation Protocol (DAP) [[DAP]].
Specifically, this aggregation method uses
the Prio3L1BoundSum 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.

Several extensions to DAP [[DAP-EXT]] are necessary for this application:

*   [[DAP-EXT#name-late-task-binding|Late task binding]]
    improves the ability of a site to collect reports
    and aggregate them as needed.

*   [[DAP-EXT#name-requester-website-identity|Website identity]]
    is critical to ensure
    that differential privacy protections are effective.
    This prevents a malicious actor
    that is able to correlate user identity across multiple sites
    from exceeding the sensitivity bounds for that user
    by aggregating reports from multiple sites together.

*   [[DAP-EXT#name-privacy-budget-consumption|Privacy budget consumption]]
    ensures that the aggregation service does not aggregate reports
    that received less privacy budget
    than the aggregation task was configured with.

User agents need to include all of these extensions in reports
that they generate.


## Trusted Execution Environments ## {#s-tee}

A <dfn lt=TEE>Trusted Execution Environment (TEE)</dfn> uses specialized hardware
to ensure that computation is isolated
from other programs that run on the same hardware.

TODO


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

    <p class=note>The sites that register impressions
    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.


### 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 time interval.
This period is called a <dfn local-lt=epoch>privacy budget epoch</dfn>
(or simply [=epoch=])
and its duration is one week (7 days), where a <dfn>day</dfn> is 86400 seconds.

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,
yield 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 is 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 max 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 [=privacy budget epoch|epoch=] is not sufficient,
the impressions from that [=privacy budget epoch|epoch=] are not used.

The details of how to [=deduct privacy budget=] is given below ... WIP

<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 Site B, C, and E.

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

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


### 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 specific mechanisms that are used
depend on the type of [=aggregation service=].



# Security Considerations # {#security}


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

The [=impression store=] used by the Private 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
    [[#impression-store-clearing|clear the impression store]].
*   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=PrivateAttributionImpressionOptions>lifetimeDays</a>.


## API Implementation ## {#security-api-implementation}

The Private Attribution APIs must be implemented carefully
to maintain the required security and privacy properties.
A site calling the APIs must not be able to learn:

*   Whether the Private 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=PrivateAttributionImpressionOptions>histogramIndex</a>
    is assigned the conversion value.

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

*   Variation in the time it takes for the APIs to complete.
*   Consumption of memory or storage by the API, if that
    consumption is somehow observable by the site.

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=PrivateAttribution>measureConversion()</a>
    should always go through the full process of constructing
    a conversion report, even when the conversion value to be
    reported is zero.


## 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 Private Attribution mechanism.
[=Conversion reports=]
produced by <a method for=PrivateAttribution>measureConversion()</a>
are encrypted to 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 Private 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 Private 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 private attribution.
[[#dp-safety]] discusses establishing additional cross-site
privacy budgets to mitigate this possibility.

<p class=issue>
Rate limits on calls to the Private Attribution APIs
could also be an effective mechanism to prevent
harvesting information through overuse of the APIs.


## 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 Private 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 Private Attribution APIs is the explicit specification
of eligible conversion sites when registering an impression,
and of eligible impression sites and ad IDs
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}


## Information Exposed by the Private 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
Private 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 Private 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 Private 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.

<p class=issue>
It is unclear whether the [=privacy budget store=] should be cleared whenever
the impression store is cleared. On one hand, it contains information about
browsing activity, so is desirable to include it when clearing browsing activity.
On the other hand, it is only possible to strictly adhere to the requirements of
the differential privacy mechanism, if information about a fully- or partially-
depleted privacy budget is maintained until that budget is no longer relevant
(i.e. the end of the [=privacy budget epoch=]).

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

The Private 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.
As discussed in [[#opt-out]], the user agent must provide
a mechanism for the user to disable the Private Attribution API.

To minimize the risk of fingerprinting,
and to prevent discrimination
against users who choose to disable the Private Attribution API,
sites must not be able to detect that the API is disabled.
Specifically, all calls to the Private Attribution API
that are otherwise valid,
must 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.


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

Sites are able to encode some amount of data
in impressions,
using {{PrivateAttributionConversionOptions/filterData}}
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 [[#impression-store-clearing|clear the impression store]].
*   No impressions are saved to the impression store
    when the Private Attribution API is [[#opt-out|disabled]].


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

The Private Attribution API is available even in third-party contexts.
In particular, a third-party iframe
may call <a method for=PrivateAttribution>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.


# 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://html.spec.whatwg.org/; spec: html; type: dfn
    text: obtain a site
    text: origin; url: #concept-origin
    text: relevant settings object
    text: same site
    text: site
    text: top-level origin; url: #concept-environment-top-level-origin
    text: iframe; url: #child-navigable
urlPrefix: https://infra.spec.whatwg.org/; spec: infra; type: dfn;
    text: user agent
    text: set; url: #sets
</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-10-10",
    "href": "https://datatracker.ietf.org/doc/html/draft-ietf-ppm-dap-12",
    "title": "Distributed Aggregation Protocol for Privacy Preserving Measurement",
    "publisher": "IETF"
  },
  "dap-ext": {
    "authors": [
      "Martin Thomson"
    ],
    "title": "Distributed Aggregation Protocol (DAP) Extensions for Improved Application of Differential Privacy",
    "date": "2024-10-18",
    "href": "https://datatracker.ietf.org/doc/draft-thomson-ppm-dap-dp-ext/"
  },
  "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"
  },
  "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": "2024-10-04",
    "href": "https://datatracker.ietf.org/doc/draft-irtf-cfrg-vdaf/"
  }
}
</pre>