Private Aggregation API 總覽

使用 Protected Audience 的資料和共用儲存空間中的跨網站資料，產生匯總資料報表。

為了提供網路仰賴的重要功能，我們打造了 Private Aggregation API，以保護隱私權的方式匯總及回報跨網站資料。

導入狀態

建議採行的做法 狀態
透過共用儲存空間報表驗證功能，防止無效的 Private Aggregation API 報表
說明		 可透過 Chrome 使用
私人匯總偵錯模式可用性取決於 3PC 資格條件
GitHub 問題		 適用於 Chrome M119
縮短報表延遲時間
說明		 適用於 Chrome M119
支援 Google Cloud 的 Private Aggregation API 和匯總服務
說明		 適用於 Chrome M121
可匯總報表酬載的邊框間距
說明		 適用於 Chrome M119
適用於競價報表買方報表的私人匯總偵錯模式
說明		 預計在 Chrome M123 中推出
支援篩選 ID
說明		 我們預計在 2024 年第 2 季於 Chrome 中首次推出。

什麼是 Private Aggregation API

開發人員可以透過 Private Aggregation API，使用 Protected Audience API 的資料和共用儲存空間中的跨網站資料產生匯總資料報表。

這個 API 目前只提供一項作業 (sendHistogramReport())，但日後可能會支援更多作業。直方圖作業可讓您匯總定義的各值區內使用者的資料 (在 API 中稱為匯總鍵)。直方圖呼叫會累積值，並以摘要報表的形式傳回雜訊的匯總結果。舉例來說，這份報表可能會顯示每位使用者看過您內容的網站數量，或是在第三方指令碼中發現錯誤。這項作業會在其他 API 的小程式中執行。

舉例來說，如果您先前曾在「共用儲存空間」中記錄客層和地理資料，就可以使用 Private Aggregation API 建立直方圖，掌握有多少紐約市的概略使用者人數跨網站看過您的內容。如要匯總這項評估結果，您可以將地理位置維度編碼成匯總鍵，然後計算可匯總值中的使用者數。

核心概念

當您使用匯總鍵和可匯總值呼叫 Private Aggregation API 時，瀏覽器會產生可匯總報表。

可匯總報表會傳送至您的伺服器，以便收集和批次處理。匯總服務會在稍後處理批次報表，然後產生摘要報表。

如要進一步瞭解 Private Aggregation API 的相關重要概念，請參閱 Private Aggregation API 基礎知識文件。

與歸因報表的差異

Private Aggregation API 與 Attribution Reporting API 有許多相似之處。Attribution Reporting 是專門用來評估轉換的獨立 API，「私人匯總」則是用來搭配 Protected Audience API 和 Shared Storage 等 API 進行跨網站評估。這兩個 API 都會產生可匯總的報表，供匯總服務後端使用以產生摘要報表。

歸因報表會連結曝光事件和轉換事件在不同時間發生的轉換事件。「私人匯總」會評估單一跨網站事件，

測試這個 API

只要在 chrome://flags/#privacy-sandbox-ads-apis 啟用 Privacy Sandbox Ads API 實驗標記，即可在本機測試 Private Aggregation API。

將 Privacy Sandbox Ads API 實驗設為啟用以使用這些 API
將 Privacy Sandbox Ads API 實驗設為啟用，即可使用這些 API

進一步瞭解實驗功能和參與測試。

使用試用版

如要查看共用儲存空間專用 Private Aggregation API 示範，請前往 goo.gle/shared-storage-demo，如需取得程式碼，請前往 GitHub。這個示範會實作用戶端作業，並產生可匯總報表，傳送至您的伺服器。

我們日後會發布 Protected Audience API 的 Private Aggregation API 示範。

應用情境

「私人匯總」是可用於跨網站評估的一般用途 API，可用於 Shared Storage 和 Protected Audience API 工作套件。首先，您必須精確決定要收集的資訊。這些資料點是匯總鍵的基礎。

附共用儲存空間

共用儲存空間可讓您在安全環境中讀取及寫入跨網站資料，防止資料外洩；Private Aggregation API 則可讓您評估儲存在「共用儲存空間」的跨網站資料。

不重複觸及率評估

建議您評估有多少不重複使用者看過他們的內容。Private Aggregation API 可為您提供解答，例如：「發現 Content ID 861 的不重複使用者人數約為 317 人」。

您可以在「共用儲存空間」中設定旗標，表明使用者是否已看過該內容。在第一個造訪不存在該旗標的情況下，系統會呼叫私密匯總，然後設定旗標。當使用者後續造訪 (包括跨網站造訪) 時，只要檢查「共用儲存空間」，即可略過已設定的旗標回報作業。

客層評估

你可能會想評估在不同網站上看過你內容的使用者客層。

「私人匯總」可以提供答案，例如「約 317 位不重複使用者來自 18 到 45 歲，且來自德國」。使用共用儲存空間存取第三方內容的客層資料。日後，您可以在匯總鍵中將年齡層和國家/地區維度編碼，以產生「私人匯總」報表。

K+ 頻率評估

建議您將預先選擇的值 K ，評估在特定瀏覽器看過內容或廣告至少 K 次的使用者人數。

「私人匯總」可以提供答案，例如「約 89 位使用者看過 Content ID 581 至少 3 次」。您可以從不同網站的「共用儲存空間」中增加計數器，也可以在工作小程式中讀取。當數量達到 K 個時，您就能透過「私密匯總」功能提交報表。

使用 Protected Audience API

Protected Audience API 支援指定舊訪客和自訂目標對像用途，私人匯總功能則可讓您回報買方和賣方研討會的事件。此 API 可用於評估競價出價分佈情形等工作。

在 Protected Audience API 工作區中，您可以直接使用 sendHistogramReport() 匯總資料，並使用 reportContributionForEvent() (這是 Protected Audience API 的特殊擴充功能) 根據觸發條件回報資料。

可用的函式

「共用儲存空間」和「Protected Audience API」工作流程中的 privateAggregation 物件提供下列函式。

contributeToHistogram()

您可以呼叫 privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })，其中匯總鍵為 bucket，而可匯總值為 value。bucket 參數必須要有 BigInt。若是 value 參數，必須提供整數。

以下範例說明如何在「共用儲存空間」中呼叫此資料，以便評估觸及率：

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await this.sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

上述程式碼範例會在每次載入跨網站 iframe 內容時呼叫私人匯總。iframe 程式碼會載入工作小程式，這個工作程式會使用內容 ID 轉換為匯總鍵 (值區) 來呼叫 Private Aggregation API。

contributeToHistogramOnEvent()

在 Protected Audience API 工作小程式中，我們提供了以觸發條件為基礎的機制，以便只在發生特定事件時傳送報表。透過這個函式，您也可以根據競價當下尚未可用的信號，決定值區和值。

privateAggregation.reportContributionForEvent(eventType, contribution) 方法接受用來指定觸發事件的 eventType，以及在事件觸發時要提交的 contribution。觸發事件可能來自競價結束後的競價本身 (例如競價勝出或損失事件)，也可能來自帶出廣告的圍欄頁框。 如要傳送競價事件的報表，您可以使用兩個保留關鍵字：reserved.win、reserved.loss 和 reserved.always。如要提交由圍欄頁框的事件觸發的報表，請定義自訂事件類型。如要從圍欄頁框觸發事件，請使用 Fenced Frames Ads Reporting API 提供的 fence.reportEvent() 方法。

以下範例會在競價勝出事件觸發時傳送曝光報表，並在顯示廣告的圍欄頁框觸發 click 事件時傳送點擊報表。這兩個值可用來計算點閱率。

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

詳情請參閱擴充私人匯總報表說明。

enableDebugMode()

雖然第三方 Cookie 仍可使用，但我們會提供暫時性機制，讓偵錯模式能簡化偵錯和測試作業。偵錯報表在比較以 Cookie 為基礎的評估結果與私人匯總評估結果時相當實用，也能讓您快速驗證 API 整合情形。

在工作小程式中呼叫 privateAggregation.enableDebugMode() 會啟用偵錯模式，讓可匯總報表納入未加密 (明文) 酬載。接著，您可以使用匯總服務的本機測試工具處理這些酬載。

偵錯模式僅適用於允許存取第三方 Cookie 的呼叫端。如果呼叫端無法存取第三方 Cookie，enableDebugMode() 將失敗，且不會顯示通知。這表示在第三方 Cookie 淘汰後，偵錯模式將不再提供使用。

您也可以呼叫 privateAggregation.enableDebugMode({ <debugKey: debugKey> }) 來設定偵錯金鑰，其中 BigInt 可用於做為偵錯金鑰。偵錯金鑰可用來連結以 Cookie 為基礎的評估資料，以及私人匯總評估資料。每個內容只能呼叫一次。系統會忽略任何後續呼叫。

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

檢舉驗證報表

針對共用儲存空間，您可以在共用儲存空間作業呼叫中新增內容 ID，以驗證您收到的可匯總報表合法。這組 ID 會附加至已傳送的報表，稍後您就可以使用這組 ID 確認報表是否傳送自共用儲存空間作業。

這項功能可在 Chrome M114 以上版本中進行測試。Protected Audience API 的報告驗證功能目前還未開放測試。

詳情請參閱報表驗證說明。

互動並提供意見

Private Aggregation API 目前正在積極討論，日後可能會有變更。如果您已經試用過這個 API，並提供寶貴意見，我們非常樂意聽聽您的想法。