PrivateAggregation interface

syntax

Normative IDL from the final published draft (§ the exposed interface), verbatim:

[Exposed=(InterestGroupScriptRunnerGlobalScope,SharedStorageWorklet),
 SecureContext]
interface PrivateAggregation {
  undefined contributeToHistogram(PAHistogramContribution contribution);
  undefined contributeToHistogramOnEvent(DOMString event,
                                         record<DOMString, any> contribution);
  undefined enableDebugMode(optional PADebugModeOptions options = {});
};

dictionary PAHistogramContribution {
  required bigint bucket;
  required long value;
  bigint filteringId = 0;
};

dictionary PADebugModeOptions {
  required bigint debugKey;
};

The interface was exposed on the Shared Storage worklet global scope and the Protected Audience interest-group script runner global scope only, in secure contexts — never on window. As shipped in Chromium (Shared Storage side, private_aggregation.idl at the M149 branch), verbatim — note the shipped dictionary name PrivateAggregationHistogramContribution and the runtime gate on the on-event method:

[Exposed=(SharedStorageWorklet),
 ContextEnabled=PrivateAggregationInSharedStorage]
interface PrivateAggregation {
  [CallWith=ScriptState, RaisesException]
    void contributeToHistogram(PrivateAggregationHistogramContribution contribution);
  [CallWith=ScriptState, RaisesException,
   RuntimeEnabled=PrivateAggregationApiErrorReporting]
    void contributeToHistogramOnEvent(DOMString event,
                                      PrivateAggregationHistogramContribution contribution);
  [CallWith=ScriptState, RaisesException]
    void enableDebugMode(optional PrivateAggregationDebugModeOptions options);
};

context and exposure

The object was reachable only as privateAggregation on the two worklet globals named in the IDL Exposed attribute. In Chromium the attribute on SharedStorageWorkletGlobalScope was gated by ContextEnabled=PrivateAggregationInSharedStorage (shared_storage_worklet_global_scope.idl), ultimately controlled by the kPrivateAggregationApi base feature with per-context Finch parameters enabled_in_shared_storage / enabled_in_fledge (features.cc, M152 branch). Ordinary documents, workers, and service workers never had access; there was no permissions-policy-gated document surface.

lifecycle of a contribution

Each contributeToHistogram() call queued a histogram contribution inside the worklet invocation; at the end of the invocation the browser assembled contributions into an aggregatable report (encrypted to the aggregation service’s public key), and later sent it to the reporting origin’s fixed .well-known endpoint — the full pipeline, its endpoints, and its sunset are on the aggregatable-reports page. Calls were fire-and-forget: they returned undefined immediately and no handle to the eventual report existed. With the API disabled, the queueing step no longer happens — calls throw TypeError at the property access itself.

contributeToHistogram(contribution)

The core method: queued one histogram contribution for the current worklet invocation.

// REMOVED API — shown for audit/deletion only.
privateAggregation.contributeToHistogram({
  bucket: 123456789n,   // bigint, 0 <= bucket < 2**128
  value: 25,            // long, >= 0
  filteringId: 7n       // optional, defaults to 0n
});

contributeToHistogramOnEvent(event, contribution)

A Protected-Audience-oriented variant that deferred the contribution until a named reportable event occurred (for example the reserved win/loss events of an auction).

// REMOVED API — shown for audit/deletion only.
// Protected Audience auction worklet, deferred to the win event:
privateAggregation.contributeToHistogramOnEvent("reserved.win", {
  bucket: 42n,
  value: 1
});

enableDebugMode(options)

Opted the current context into debug mode: contributions also produced unencrypted, immediately sent debug reports, bypassing the aggregation service’s privacy protections. This is the bridge the deprecation plan told server-side-report users to rely on until full removal.

// REMOVED API — shown for audit/deletion only.
privateAggregation.enableDebugMode({ debugKey: 1234n });

dictionaries

PAHistogramContribution — the contribution shape: bucket (required bigint) identifies the histogram bucket, validated to 0 ≤ bucket < 2¹²⁸; value (required long) is the amount contributed, validated non-negative; filteringId (optional bigint, default 0) lets aggregation-service queries partition results, validated against a context-defined byte bound. PADebugModeOptions — debugKey (required bigint), the marker carried on debug reports. Both dictionaries were input-only: passed by value into the methods above, never returned or observable afterward. Chromium shipped them under the names PrivateAggregationHistogramContribution and PrivateAggregationDebugModeOptions (shipped IDL).

// REMOVED API — dictionary shapes for reference.
// Spec names:              PAHistogramContribution / PADebugModeOptions
// Shipped Chromium names:  PrivateAggregationHistogramContribution /
//                          PrivateAggregationDebugModeOptions
{ bucket: 99n, value: 10, filteringId: 0n }   // PAHistogramContribution
{ debugKey: 1234n }                            // PADebugModeOptions

examples

A complete Shared Storage usage as it would have appeared before deprecation — kept for auditing existing code; the guard pattern beneath is the only snippet that should survive:

// REMOVED API — historical usage, for audit only.
class ReachMeasurer {
  async run(data) {
    const bucket = BigInt(data.campaignId);
    privateAggregation.contributeToHistogram({ bucket, value: 1 });
  }
}
register("reach-measurer", ReachMeasurer);

// Transition-safe guard (the only pattern to keep):
if (typeof privateAggregation !== "undefined") {
  privateAggregation.contributeToHistogram({ bucket: 1n, value: 1 });
}

browser compatibility

Interim table. No BCD entry exists for PrivateAggregation (checked in the BCD api/ directory, 2026-07-29) and webstatus.dev has no feature. Compiled from the linked primary sources:

security and privacy

• Trust boundary: contributions were encrypted to the aggregation service’s key; the reporting origin could not read individual contributions (draft).
• Debug mode weakened that boundary deliberately — unencrypted per-event reports — which is why its use was limited to debugging and, in the deprecation plan, to a short bridge for former server-side-report users (feature notes).
• Removal adds no new data flow; any code path that keeps calling the API simply fails closed (TypeError).