Private Aggregation API 總覽

使用 Protected Audience 的資料和 Shared Storage 的跨網站資料，產生匯總資料報表。

為提供網站所需的重要功能，我們已建構私密匯總 API，以便以保護隱私權的方式匯總跨網站資料並產生報表。

導入狀態

Private Aggregation API 簡介

Private Aggregation API 可讓開發人員使用 Protected Audience API 的資料和 Shared Storage 的跨網站資料，產生匯總資料報表。

這個 API 的主要函式稱為 contributeToHistogram()。您可以使用直方圖運算，在您定義的每個桶 (在 API 中稱為匯總鍵) 中，匯總各使用者的資料。直方圖呼叫會累積值，並以摘要報表的形式傳回經過雜訊處理的匯總結果。舉例來說，報表可能會顯示每位使用者在哪些網站上看過您的內容，或是在第三方指令碼中遇到錯誤。這項作業會在其他 API 的 worklet 中執行。

舉例來說，如果您先前曾在 Shared Storage 中記錄客層和地理資料，就可以使用 Private Aggregation API 建立統計圖，瞭解紐約市有多少使用者在跨網站看到您的內容。如要針對這項評估進行匯總，您可以將地理區域維度編碼為匯總鍵，並計算匯總值中的使用者。

核心概念

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

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

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

與歸因報表的差異

Private Aggregation API 與 Attribution Reporting API 有很多相似之處。Attribution Reporting 是專為評估轉換而設計的獨立 API，而 Private Aggregation 則是為了跨網站評估而設計，可與 Protected Audience API 和 Shared Storage 等 API 搭配使用。這兩個 API 都會產生可匯總報表，匯總服務後端會使用這些報表產生摘要報表。

歸因報表會將來自曝光事件和轉換事件的資料彼此關聯，而這兩種事件發生的時間可能不同。「私密匯總」會評估單一跨網站事件。

測試這個 API

如要在本機測試 Private Aggregation API，請啟用 chrome://settings/adPrivacy 下方的所有廣告隱私權 API。

如要進一步瞭解如何進行測試，請參閱「實驗和參與」一文。

使用示範

如要查看 Private Aggregation API 適用於 Shared Storage 的示範，請前往 goo.gle/shared-storage-demo，程式碼則可在 GitHub 上找到。這個示範會實作用戶端作業，並產生可匯總的報表，傳送至您的伺服器。

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

用途

Private Aggregation 是一種一般用途 API，可用於跨網站評估，並可用於 Shared Storage 和 Protected Audience API 工作區塊。第一步是明確決定要收集哪些資訊。這些資料點是匯總鍵的基礎。

使用共用儲存空間

Shared Storage 可讓您在安全環境中讀取及寫入跨網站資料，以防資料外洩。Private Aggregation API 則可讓您評估儲存在 Shared Storage 中的跨網站資料。

不重複觸及評估

您可能想評估有多少不重複使用者看過內容。Private Aggregation API 可提供解答，例如「約 317 位不重複使用者看過 Content ID 861」。

您可以在 Shared Storage 中設定旗標，表示使用者是否已看過內容。在第一次造訪時，如果沒有標記，系統會呼叫 Private Aggregation，然後設定標記。在使用者後續造訪 (包括跨網站造訪) 時，如果已設定標記，您可以檢查共用儲存空間，並略過將報表提交至 Private Aggregation。如要進一步瞭解實作這些評估指標的方法，請參閱觸及數白皮書。

客層評估

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

私人匯總功能可以提供答案，例如：「約 317 位不重複使用者，年齡介於 18 至 45 歲，且來自德國」。使用 Shared Storage 存取第三方內容中的客層資料。日後，您可以透過在匯總鍵中編碼年齡層和國家/地區維度，產生 Private Aggregation 報表。

K+ 展示頻率評估

您可能想評估在特定瀏覽器上，有多少使用者至少看過 K 次某項內容或廣告，其中 K 為預先選擇的值。

私人匯總功能可提供答案，例如「約 89 位使用者至少看過 3 次內容 ID 581」。計數器可在不同網站的 Shared Storage 中遞增，並可在 worklet 中讀取。當計數達到 K 時，您就可以使用 Private Aggregation 提交報表。

多接觸點歸因分析

行銷歸因是廣告主用來判斷行銷策略和後續廣告互動對銷售或轉換的貢獻程度的方法。

使用 Protected Audience API

Protected Audience API 可用於再指定目標和自訂目標對象用途，而 Private Aggregation 則可讓您回報買方和賣方工作區的事件。這個 API 可用於評估競價分布的情形。

您可以透過 Protected Audience API 工作區塊，直接使用 contributeToHistogram() 匯總資料，並使用 contributeToHistogramOnEvent() (Protected Audience API 的特殊擴充功能) 根據觸發條件回報資料。

可用的函式

下列函式可用於 Shared Storage 和 Protected Audience API 工作區中的 privateAggregation 物件。

contributeToHistogram()

您可以呼叫 privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })，其中匯總鍵為 bucket，可匯總值為 value。針對 bucket 參數，必須使用 BigInt。value 參數必須為整數。

以下範例說明如何在 Shared Storage 中呼叫這項事件，以便評估觸及數：

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 sharedStorage.get(key) === 'true';

    // Don't 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 sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

上述程式碼範例會在載入跨網站 iframe 內容時呼叫 Private Aggregation。iframe 程式碼會載入 worklet，而 worklet 會呼叫 Private Aggregation API，並將內容 ID 轉換為匯總鍵 (bucket)。

contributeToHistogramOnEvent()

我們只會在 Protected Audience API 工作區中提供觸發事件機制，只有在發生特定事件時才會傳送報表。這個函式還可讓值和值區塊取決於競價期間尚未提供的信號。

privateAggregation.contributeToHistogramOnEvent(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
  });

詳情請參閱Extended Private Aggregation Reporting 說明文件。

enableDebugMode()

雖然第三方 Cookie 仍可使用，但我們會提供暫時性機制，讓您啟用偵錯模式，更輕鬆地進行偵錯和測試。偵錯報表可用於比較以 Cookie 為基礎的評估結果與 Private Aggregation 評估結果，也能讓您快速驗證 API 整合作業。

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

只有可存取第三方 Cookie 的呼叫端才能使用偵錯模式。如果呼叫端沒有第三方 Cookie 存取權，enableDebugMode() 會在背景中失敗。

您也可以呼叫 privateAggregation.enableDebugMode({ <debugKey: debugKey> }) 來設定偵錯鍵，其中 BigInt 可用於偵錯鍵。您可以使用偵錯鍵，將 Cookie 評估和私密匯總評估的資料建立關聯。

每個情境只能呼叫一次。後續的任何呼叫都會擲回例外狀況。

// Enables debug mode
privateAggregation.enableDebugMode();

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

檢舉驗證

Private Aggregation API 可讓您進行跨網站評估，同時保護使用者隱私。不過，惡意行為人可能會試圖操控這些評估的準確度。為避免這種情況發生，您可以使用情境 ID 驗證報表的真實性。

設定內容 ID 有助於確保資料在提供最終匯總結果時準確無誤。這項功能的運作方式如下：

• 防止不當或偽造的報表：請確保報表是透過合法且真實的 API 呼叫產生，讓不肖人士難以偽造報表。
• 防止重播報表：偵測並拒絕任何重複使用舊報表的嘗試，確保每份報表只會列入匯總結果一次。

共用儲存空間

使用共用儲存空間執行可傳送可匯總報表的作業時，您可以在工作區塊外設定不可預測的 ID。

這個 ID 會嵌入透過工作表建立的報表中。您可以在 privateAggregationConfig 鍵下的選項物件中，呼叫 run() 或 selectURL() 共用儲存空間方法時指定該值。

例如：

sharedStorage.run('measurement-operation', {
  privateAggregationConfig: {
    contextId: 'exampleId123456789abcdeFGHijk'
  }
});

設定這個 ID 後，您就可以使用這個 ID 驗證報表是否是由共用儲存空間作業傳送。為避免資訊外洩，每個共用儲存空間作業都會傳送一則報表 (即使沒有貢獻內容也一樣)，不受 contributeToHistogram() 呼叫次數影響。

Private Aggregation API 會以隨機延遲時間 (最多一小時) 傳送可匯總報表。不過，設定上下文 ID 來驗證報表，可以縮短這段延遲時間。在這種情況下，Shared Storage 作業開始後，會出現 5 秒的固定延遲時間。

工作流程範例 (如上圖所示)：

1. 執行 Shared Storage 作業時，會使用 Private Aggregation 設定指定內容 ID，並產生可匯總的報表。
2. 系統會將內容 ID 嵌入傳送至伺服器的可匯總報表中。
3. 伺服器會收集產生的可匯總報表。
4. 伺服器上的程序會檢查每份可匯總報表中的內容 ID，並與儲存的內容 ID 進行比對，確保其有效性，然後再將報表匯出並傳送至匯總服務。

結構定義 ID 驗證

收集器伺服器收到的報表可透過幾種不同的方式進行驗證，然後再傳送至匯總服務。如果含有無效的內容 ID 的報表符合下列情況，可能會遭到拒絕：

• 不明：如果報表附帶的內容 ID 並非系統建立，您可以捨棄該報表。這可防止不明或惡意人士將資料插入匯集管道。
• 重複：如果您收到兩份 (或更多) 使用相同內容 ID 的報表，就必須選擇要捨棄哪些報表。
• 垃圾內容偵測標記：
  • 如果在處理使用者檢舉時，偵測到使用者的可疑活動 (例如使用者活動突然改變)，您可以捨棄該檢舉。
  • 您可以將報表與其內容 ID 和任何相關信號 (例如使用者代理程式、推薦來源等) 一併儲存。日後，當您分析使用者行為並找出新的垃圾內容指標時，可以根據相關聯的內容 ID 和信號重新評估已儲存的報表。這樣一來，即使使用者一開始並未標示可疑活動，您還是可以捨棄他們的檢舉。

互動並分享意見回饋

我們目前正積極討論私密匯總 API，這項 API 日後可能會有變動。如果您試用這個 API 後有任何意見，歡迎與我們分享。

• GitHub：閱讀說明文章，提出問題並參與討論。
• 開發人員支援：在 Privacy Sandbox 開發人員支援存放區中提問及參與討論。
• 加入 Shared Storage API 群組和 Protected Audience API 群組，即可接收與 Private Aggregation 相關的最新公告。