Private Aggregation API 總覽

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

為提供網站所需的重要功能，我們已建構 Private Aggregation API，以便以保護隱私權的方式，匯總及回報跨網站資料。

導入狀態

Private Aggregation API 簡介

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

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

舉例來說，如果您先前曾在共用儲存空間中記錄客層和地理資料，就可以使用 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。

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

使用示範

如要查看 Shared Storage 的 Private Aggregation API 示範，請前往 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，然後設定標記。在使用者後續造訪 (包括跨網站造訪) 時，如果已設定標記，您可以檢查共用儲存空間，並略過將報表提交至私人匯總。如要進一步瞭解如何導入這些評估方法，請參閱觸及數白皮書。

客層評估

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

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

K 次以上展示頻率評估

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

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

多接觸點歸因分析

這份指南會發布在開發人員網站上，方便廣告技術人員瞭解如何在 Shared Storage + Private Aggregation 中導入 MTA。

使用 Protected Audience API

Protected Audience API 可用於再指定目標和自訂目標對象用途，而私人匯總功能則可讓您回報買方和賣方工作區塊的事件。這個 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 中呼叫這項 API，以便評估觸及數：

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 評估結果和私人匯總評估結果，還可讓您快速驗證 API 整合作業。

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

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

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

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

// 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 會嵌入透過工作表建立的報表中。您可以在呼叫 run() 或 selectURL() 共用儲存空間方法時，在 privateAggregationConfig 鍵下的選項物件中指定該值。

例如：

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

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

Private Aggregation API 會傳送可匯總報表，但會隨機延遲最多一小時，不過，設定上下文 ID 來驗證報表可縮短這段延遲時間。在這種情況下，從共用儲存空間作業開始起算，會有 5 秒的固定延遲時間。

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

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

結構定義 ID 驗證

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

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

互動並分享意見回饋

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

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