Private Aggregation API 總覽

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

為了提供網路仰賴的重要功能，「私人匯總」 API 專為在 隱私權保護方法。

導入狀態

什麼是 Private Aggregation API？

Private Aggregation API 可讓開發人員產生匯總資料報表 運用 Protected Audience API 的資料，以及 來自共用儲存空間的跨網站資料。

這個 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，可用於評估轉換，而私密匯總功能則適用於跨網站評估作業，並搭配 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 示範。

用途

「私人匯總」是用於跨網站評估的一般用途 API，可用於共用儲存空間和 Protected Audience API 工作工具。首先，您必須決定要收集哪些資訊。這些資料點是匯總鍵的基礎。

有共用儲存空間

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

不重複觸及率評估

建議你評估看過他們內容的不重複使用者人數。Private Aggregation API 可提供答案，例如「大約有 317 位不重複使用者看過 Content ID 861」。

您可以在 Shared Storage 中設定旗標，表示使用者是否已看過內容。在沒有標記存在的情況下第一次造訪時，系統會呼叫 Private Aggregation，然後設定標記。之後，使用者下次造訪 (包括跨網站造訪) 時，就可以查看「共用儲存空間」，如果已設定旗標，即可略過提交至私人匯總報表。如要進一步瞭解導入這些評估的方法，請參閱我們的觸及率白皮書。

客層評估

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

私人匯總功能可提供答案，例如「大約 317 位不重複使用者年齡介於 18 至 45 歲，來自德國。」使用共用儲存空間存取第三方情境的客層資料。您之後可以在匯總鍵中將年齡層和國家/地區維度編碼，藉此產生私密匯總報表。

K+ 頻率評估

假設您想以 K 的前期值，評估在特定瀏覽器上看過某內容或廣告至少 K 次的使用者人數。

私人匯總功能可提供答案，例如「約 89 位使用者至少看過 3 次內容 ID 581」。您可以從不同網站在「共用儲存空間」中遞增計數器，還可以在工作程式中讀取計數器。如果數量達到 K，則可透過私人匯總功能提交報告。

多接觸點歸因分析

本指南僅在開發網站發布，方便廣告技術瞭解如何在共用儲存空間 + 私人匯總中導入 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 參數必須為整數。

以下舉例說明在共用儲存空間中呼叫觸及率的方式：

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';

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

register('reach-measurement', ReachMeasurementOperation);

上述程式碼範例會在載入跨網站 iframe 內容時呼叫私人匯總。iframe 程式碼會載入 Worklet，而工作程式會使用 Content ID 呼叫 Private Aggregation API，並將內容 ID 轉換為匯總鍵 (值區)。

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() 會失敗，而且不會顯示相關通知。也就是說 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，確認收到的可匯總報表是否正當可靠。編號會附加在傳送的報表中，您稍後可以使用該編號確認報表是否從共用儲存空間作業寄出。

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

互動及分享意見回饋

Private Aggregation API 目前仍在積極討論，日後可能會有變動。如果您試用這個 API 並有意見，請不吝與我們分享。

• GitHub：閱讀說明、提出問題並參與討論。
• 開發人員支援：在 Privacy Sandbox 開發人員支援存放區中提問或加入討論。
• 加入 Shared Storage API 群組和 Protected Audience API 群組，以接收與私人匯總相關的最新公告。