PrivateAggregation API 不属于 HTML5 标准，而是 Chrome 实验性隐私沙盒 API，需 HTTPS、用户手势触发、权限策略及浏览器启用，通过上报→服务端聚合→异步交付实现隐私优先统计。

HTML5 标准本身不包含 PrivateAggregation API。它不是 HTML5 规范的一部分，而是 Chrome 浏览器在 Privacy Sandbox 计划下实验性引入的私有聚合 API（Private Aggregation API），属于 Web Platform APIs 的扩展提案，目前仍处于草案阶段（W3C 工作草案），尚未被所有浏览器支持，也未纳入 HTML5 正式标准。

因此，严格来说——
❌ 不能通过“HTML5”原生能力直接使用 PrivateAggregation；
✅ 它是基于现代浏览器（当前仅 Chromium 系统如 Chrome、Edge 120+）提供的、需显式启用且受严格限制的 JavaScript API，目标是在不暴露个体用户行为的前提下，实现跨站点、隐私优先的汇总统计（如广告归因、转化率分析、人群特征聚合等）。

下面分三部分说明如何实际使用该 API，并强调关键前提与安全边界：

---

H3：前提条件：环境、权限与启用状态

• 仅限安全上下文：必须运行在 https:// 协议下（localhost 除外）；
• 需要用户参与或触发：API 调用必须发生在用户手势（如点击、键盘输入）后的短生命周期内（通常 ≤ 30 秒），不可在页面加载时静默调用；
• 需启用相关实验性功能：
  • Chrome 中需开启 chrome://flags/#enable-privacy-sandbox-apis；
  • 或通过 --enable-features=PrivacySandboxAdsAPIsOverride,OverridePrivacySandboxSettingsLocalTesting 启动；
• 网站需注册为可信赖的来源（Trust Tokens 或 Permissions Policy）：
  在响应头中声明许可：

  Permissions-Policy: private-aggregation=*

---

H3：基本使用流程：注册、上报、聚合

该 API 不提供实时查询，而是采用“上报 → 后端聚合服务处理 → 异步获取结果”模式：

1. 前端注册聚合源（Source）
   在用户交互后，调用 navigator.privateAggregation.sendHistogramReport() 上报一个带标签的计数（如转化事件）：

   document.getElementById('buy-btn').addEventListener('click', async () => {
     try {
       await navigator.privateAggregation.sendHistogramReport({
         bucket: { value: 12345n, bitLength: 32 }, // 分桶 ID（需哈希/编码）
         value: 1, // 计数值（整数，范围 0–65536）
         sourceEventId: 123n, // 可选：用于关联事件链
         filterData: { campaign: 'spring_sale' }, // 可选过滤键值对
         aggregatableValues: { conversions: 1 } // 主聚合指标
       });
     } catch (e) {
       console.warn('Private Aggregation not supported or blocked:', e);
     }
   });

2. 聚合由浏览器后台调度，经可信服务器（如 Google 的 Aggregation Service）处理

   

   html-to-pptx

   将多页 HTML 演示文稿转换为美化的 PPTX 文件，便于分享和分发。

   下载

   立即学习“前端免费学习笔记（深入）”；

   • 浏览器将多个用户的类似上报进行差分隐私加噪 + 汇总；
   • 输出是去标识化、带噪声的聚合直方图（例如：“约 2300–2500 名来自 spring_sale 活动的用户完成了购买”）；
   • 原始单个用户数据永不离开设备，也不上传原始 ID 或明细。

3. 结果不返回给网页，而是由广告平台或分析方在服务端接收

   • 网页代码无法直接读取聚合结果；
   • 结果通过独立的、受控的聚合服务端点（如 /aggregation-service/v1/report）交付给授权方；
   • 需配合 Attribution Reporting API 或 Protected Audience API 构建完整隐私沙盒链路。

---

H3：关键限制与隐私保障机制

• 无用户级数据泄露风险：
  • 所有桶（bucket）和值（value）均经过混淆、截断与差分隐私噪声注入；
  • 最小报告阈值（如 ≥ 100 用户才触发聚合）防止小群体推断；
• 跨站点隔离严格：
  • 上报只能发往与当前页面同源或预注册的、符合 Privacy Sandbox 政策的聚合服务；
  • 第三方脚本默认无权调用，除非明确获得 private-aggregation 权限策略授权；
• 不可绕过用户控制：
  • 用户可在 Chrome 设置中完全关闭 Privacy Sandbox 功能；
  • 浏览器会提示并记录聚合上报行为（chrome://settings/privacySandbox）。

---

不复杂但容易忽略：它不是“前端统计工具”，而是一套以隐私为默认设计原则的数据协作协议。开发者真正要做的，是理解其适用场景（如合规广告效果衡量），放弃传统像素追踪思路，并与支持 Privacy Sandbox 的分析平台协同落地。