api.bs

<pre class=metadata>
Title: Privacy-Preserving Attribution: Level 1
Shortname: Attribution
Repository: private-attribution/api
URL: https://private-attribution.github.io/api/
Editor: Martin Thomson, w3cid 68503, Mozilla https://mozilla.org/, mt@mozilla.com
Editor: Andy Leiserson, w3cid 147715, Mozilla https://mozilla.org/, aleiserson@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 chosen by websites and trusted to perform aggregation within strict limits.  Noise is added to the aggregates produced by this service to provide differential privacy.
Status Text: This specification is a proposal that is intended to be migrated to the W3C standards track. It is not a standard.
Text Macro: LICENSE <a href=http://www.w3.org/Consortium/Legal/2015/copyright-software-and-document>W3C Software and Document License</a>
Complain About: accidental-2119 yes, missing-example-ids yes
Markup Shorthands: markdown yes, css no, dfn yes
Assume Explicit For: yes
Group: patcg
Status: CG-DRAFT
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=] is 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 Details # {#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 `aggregator` member of the
{{PrivateAttributionConversionOptions}} dictionary when calling the
<a method for=PrivateAttribution>measureConversion()</a> method.

<p class=issue>
This section needs to be more precise about [=site=] vs. [=origin=].

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

<p class=issue>Is any additional information required in the
{{PrivateAttributionAggregationService}} dictionary? Do we want
to rename `apiVersion` to `protocol`? And we should definitely
define an enum for it.

The <dfn attribute for=PrivateAttribution>aggregationServices</dfn> attribute
contains a list 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.

<xmp class=idl>
dictionary PrivateAttributionAggregationService {
  required DOMString name;
  required DOMString apiVersion;
};

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

The <a attribute for=PrivateAttribution>aggregationServices</a> attribute
contains the following information about each supported aggregation service:

<dl dfn-for=PrivateAttributionAggregationService dfn-type=dict-member>
  <dt><dfn>name</dfn></dt>
  <dd>
    Name of the aggregation service. This is passed as the `aggregator`
    parameter to <a method for=PrivateAttribution>measureConversion()</a>.
  </dd>
  <dt><dfn>apiVersion</dfn></dt>
  <dd>
    Version of the Private Attribution API supported by this aggregator. Even if
    an aggregator supports multiple versions of the API, it is expected to
    assign a unique aggregation service name for each supported version.
    Thus, the API version is implicit in the aggregator selection
    and does not need to be passed to <a method for=PrivateAttribution>measureConversion()</a>.
  </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=].

<pre>
navigator.privateAttribution.saveImpression({
  histogramIndex: 3,
  ad: "sample-campaign-eijb",
  conversionSite: "advertiser.example",
  lifetimeDays: 7,
});
</pre>

<xmp class=idl>
dictionary PrivateAttributionImpressionOptions {
  required unsigned long histogramIndex;
  required DOMString ad;
  required DOMString conversionSite;
  unsigned long lifetimeDays;
};

[SecureContext, Exposed=Window]
partial interface PrivateAttribution {
  [Throws] 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>ad</dfn></dt>
  <dd>
    A unique <dfn for="" dfn-type=dfn>ad identifier</dfn> for the impression. The
    ad identifier is used to identify which impressions may receive attribution
    from a [=conversion=]. The Private Attribution API does not impose a particular
    format on ad identifiers. If an implementation imposes a maximum ad identifer
    length, it must be at least 64 code points.
  </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 "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>
</dl>

### Operation ### {#save-impression-api-operation}

1.  Collect the implicit API inputs:
    1. The current timestamp
    2. The impression site domain
1.  Validate the page-supplied API inputs
1.  If the private attribution API is 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].


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

<pre>
navigator.privateAttribution.measureConversion({
  // name of the aggregation service
  aggregator: "aggregator.example",

  // the number of buckets in the histogram
  histogramSize: 20,
  // the amount of privacy budget to use
  epsilon: 1,

  // the attribution logic to use
  logic: "last-touch",
  // the value to assign to the histogram index of the impression
  value: 3,

  // only consider impressions within the last N days
  lookbackDays: 30,
  // a list of possible ad identifiers that can be attributed
  ads: ["sample-campaign-eijb"],
  // a list of sites where impressions might have been registered
  impressionSites: ["publisher.example"]
});
</pre>

<xmp class=idl>
dictionary PrivateAttributionConversionOptions {
  required DOMString aggregator;
  double epsilon = 1.0;

  required unsigned long histogramSize;

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

  unsigned long lookbackDays;
  sequence<DOMString> ads = [];
  sequence<DOMString> impressionSites = [];
};

[SecureContext, Exposed=Window]
partial interface PrivateAttribution {
  [Throws] Promise<Uint8Array> 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>aggregator</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>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>lookbackDays</dfn></dt>
  <dd>An integer number of days. Only impressions occurring within the past `lookbackDays` may match this [=conversion=].</dd>
  <dt><dfn>ads</dfn></dt>
  <dd>A list of [=ad identifiers=]. Only [=impressions=] having one of the listed identifiers may match this [=conversion=].</dd>
  <dt><dfn>impressionSites</dfn></dt>
  <dd>A list of impression sites. Only [=impressions=] recorded by one of the impression sites are eligible to match this [=conversion=].</dd>
</dl>


### Operation ### {#measure-conversion-api-operation}

1. Collect the implicit API inputs
    1. The current timestamp
    2. The conversion site domain
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>,
        return an error.
1.  If the private attribution API is enabled,
    invoke the routine to [=fill a histogram using last-touch attribution=].
1. Encrypt the report.
1. Return the encrypted report.


## 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=] must store the following information:

<div link-for=PrivateAttribution>
<pre class=simpledef>
Ad: The [=/ad identifier=] passed to <a>saveImpression()</a>.
Impression Site: The site that called <a>saveImpression()</a>.
Conversion Sites: The conversion site(s) that were passed to <a>saveImpression()</a>.
Timestamp: The time at which <a>saveImpression()</a> was called.
Lifetime: The number of days an [=/impression=] remains eligible for attribution,
Lifetime: either from the call to <a>saveImpression()</a>, or a [=/user agent=]-defined limit.
Histogram Index: 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 <dfn>privacy budget store</dfn> records the state
of the per-[=site=] [=privacy budgets=], and of any
[=safety limits=]. It is updated by [=deduct privacy budget=].

<p class=issue>
The [=privacy budget store=] needs 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.


## 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.
This logic includes how to select impressions,
how to handle weeks in which the [=privacy budget=] is insufficient,
and (optionally) how to process any additional parameters that might be used.


### Last Touch Attribution ### {#logic-last-touch}

The <dfn enum-value for=PrivateAttributionLogic>"last-touch"</dfn> [=attribution logic=]
indicates that the browser should select
the last (most recent) impression that matches the [[#logic-matching|common matching logic]].
The entire [=conversion value=] (up to the maximum imposed by the [[#dp-budget|privacy budget]])
is allocated to the histogram bucket that was saved with the impression.

Last touch attribution does not select any impression
that was saved during a week
that does not have sufficient [=privacy budget=].
If impressions match from a week
that does not have enough [=privacy budget=],
impressions are not matched for any preceding weeks.
That is, once a week has a matching impression
and insufficient budget,
the process will set a value of zero for all histogram buckets.

To <dfn>fill a histogram using last-touch attribution</dfn>,
given <a dictionary lt=PrivateAttributionConversionOptions>|options|</a>:

1.  Initialize |impression| to a null value.

1.  Initialize |value| to |options|.{{PrivateAttributionConversionOptions/value}}.

1.  Let |now| be the current time.<!-- TODO: cite HRTIME spec -->

1.  For each |week| starting from the current week
    to the oldest week supported by the [=user agent=]:

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

    1.  If |impressions| is not empty:

        1.  Retain the value of |week|.

        1.  Set |impression| to the value in |impressions|
            with the most recent |impression|.timestamp.
            <!-- TODO define a type for stored impressions -->

        1.  Exit the loop.

1.  If |impression| is null, let |budgetOk| be false.

1.  Otherwise, let |budgetOk| be the result of [=deduct privacy budget=]
    with |week| and |options|.{{PrivateAttributionConversionOptions/epsilon}}.

1.  If |budgetOk| is false, set |value| to 0.

1.  If |impression|.<var ignore=''>histogramIndex</var>
    is |options|.{{PrivateAttributionConversionOptions/histogramSize}} or greater,
    set |value| to 0.

1.  If |value| is not 0, set |index|
    to |impression|.{{PrivateAttributionImpressionOptions/histogramIndex}}.

1.  Otherwise, set |index| to 0.

1.  Return a histogram containing |options|.{{PrivateAttributionConversionOptions/histogramSize}} values,
    with a value of |value| at an index of |index|
    and a value of zero at all other indices.


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

TODO specify how to match using "lookbackDays", "ads" and "impressionSites".

Discuss "infinite" lookbackDays. Clarify when it apples. When field is missing? Zero?

To perform <dfn>common matching logic</dfn>,
given |options|, |week|, and [=moment=] |now|:

1.  If number of days since the end of |week| exceeds |lookbackDays|,
    return an empty set.

1.  Initialize |matching| to an empty set.

1.  For each |impression| in the saved impressions for the |week|:

    1.  If |now| - |lookbackDays| is after |impression|.timestamp,
        continue the loop.

    1.  If |options|.{{PrivateAttributionConversionOptions/ads}}
        does not contain |impression|.ad,
        continue the loop.

    1.  If |options|.{{PrivateAttributionConversionOptions/impressionSites}}
        does not contain |impression|.impressionSite,
        continue the loop.

    1.  Add |impression| to |matching|.

1.  Return |matching|.


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


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

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

Text fragment moved from privacy section:

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.

Each browser will have different requirements for aggregation.


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

TODO


## Trusted Execution Environments ## {#tee}

TODO


## Conversion Report Encryption ## {#encryption}

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.

TODO


# 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 week,
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 <dfn>week</dfn>.

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

Ideally, the [=privacy unit=] is a single person.
Though ideal, it is not possible to develop a useful system
that guarantees perfect correspondance 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 for the data in every
time internval called and epoch. The epoch length is one week.

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 week 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 weeks has privacy consequences.
A single visit to a website can give that site information
about activities across many weeks.
This only requires that
the conversion site is identified as the destination
for impressions over that entire period.
The number of weeks that can be queried are 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 choice of a week is largely arbitrary.
One week is expected to be enough to allow sites
the ability 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 a <dfn>privacy budget</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 week in which those impressions were saved.
If the privacy budget for that week is not sufficient,
the impressions from that week are not used.

The details of how to <dfn>deduct privacy budget</dfn> 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 weeks 1, 3, 4, and 5.
    No impressions were recorded for week 2,
    so no budget is deducted from that week.
</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 expicit 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 [=week=]).

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


## Ad Identifiers ## {#privacy-ad-identifiers}

It is important that the [=ad identifiers=] used by the Private Attribution
APIs (and stored in the [=impression store=]) not be usable for arbitrary
tracking. The following measures mitigate this risk:

*   The impression store can not be read directly.
    Thus, ad identifiers are only usable for tracking
    to the extent information about them
    is revealed in [=conversion reports=]
*   Ad identifiers are scoped
    to a specific set of impression and conversion sites.
    It is not possible to use the ad identifier for tracking across
    arbitrary sites.
*   Users have the ability to [[#impression-store-clearing|clear the impression store]].
*   Ad identifiers are not written 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=link-defaults>
spec:html; type:dfn; text:site
spec:infra; type:dfn; text:user agent
</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"
  },
  "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"
  }
}
</pre>