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 的工作小程式中執行。

舉例來說，如果您先前已在 Shared Storage 中記錄人口統計和地理區域資料，可以使用 Private Aggregation API 建構直方圖，瞭解紐約市約有多少使用者看過您的跨網站內容。如要匯總這項評估指標，您可以將地理位置維度編碼至匯總鍵，並計算可匯總值中的使用者人數。

核心概念

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

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

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

與 Attribution Reporting 的差異

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 是一種一般用途的跨網站評估 API，可在 Shared Storage 和 Protected Audience API 工作單元中使用。第一步是具體決定要收集哪些資訊。這些資料點是匯總鍵的基礎。

使用共用儲存空間

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

不重複觸及評估

您可能想評估看過內容的不重複使用者人數，Private Aggregation API 可提供「大約有 317 位不重複使用者看過內容 ID 861」等答案。

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

客層評估

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

私有匯總可提供答案，例如「約有 317 位來自德國的不重複使用者，年齡為 18 至 45 歲」。使用 Shared Storage 存取第三方環境中的目標對象統計資料。稍後，您可以將年齡層和國家/地區維度編碼至匯總鍵，藉此使用 Private Aggregation 產生報表。

K+ 展示頻率評估

您可能想針對預先選擇的 K 值，評估在特定瀏覽器上至少看過 K 次內容或廣告的使用者人數。

私有匯總可提供「大約有 89 位使用者看過 Content ID 581 至少 3 次」等答案。計數器可在共用儲存空間中從不同網站遞增，並在工作單元中讀取。當計數達到 K 時，即可使用 Private Aggregation 提交報表。

多接觸點歸因分析

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

使用 Protected Audience API

Protected Audience API 可用於再指定目標和自訂目標對象用途，Private Aggregation 則可讓您回報買方和賣方工作集中的事件。這項 API 可用於測量競價出價的分配情形等工作。

您可以使用 Protected Audience API 的工作單元，直接透過 contributeToHistogram() 匯總資料，並根據觸發條件使用 contributeToHistogramOnEvent() 回報資料。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 程式碼會載入工作單元，而工作單元會呼叫 Private Aggregation API，並將內容 ID 轉換為匯總鍵 (buckets)。

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
  });

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

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 呼叫產生，讓不肖分子難以偽造報表。
• 防止重複使用報表：偵測並拒絕任何重複使用舊報表的嘗試，確保每份報表只會列入匯總結果一次。

共用儲存空間

使用 Shared Storage 執行可傳送可彙整報表的操作時，您可以在工作子外設定無法預測的 ID。

這個 ID 會嵌入從工作單建立的報表。呼叫 run() 或 selectURL() Shared Storage 方法時，您可以在 privateAggregationConfig 鍵底下的選項物件中指定。

例如：

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

設定這個 ID 後，您就能用來驗證報表是否是從共用儲存空間作業傳送。為防止資訊洩漏，每個共用儲存空間作業只會傳送一份報表 (即使沒有任何貢獻)，無論 contributeToHistogram() 呼叫次數為何。

Private Aggregation API 會隨機延遲最多一小時，才傳送可匯總報表。不過，設定內容 ID 來驗證報表可減少這類延遲。在本例中，從 Shared Storage 作業開始到延遲，時間固定為 5 秒。

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

1. 系統會使用 Private Aggregation 設定執行 Shared Storage 作業，指定內容 ID 並產生可匯總的報表。
2. 系統會將內容 ID 內嵌在產生的可匯總報表中，並傳送至您的伺服器。
3. 伺服器會收集產生的可匯總報表。
4. 伺服器上的程序會根據您儲存的內容 ID，檢查每個可匯總報表中的內容 ID，確認有效性，然後將報表分批傳送至匯總服務。

結構定義 ID 驗證

傳送至收集器伺服器的報表可透過幾種不同方式驗證，再傳送至匯總服務。如果內容 ID 屬於下列情況，系統可能會拒絕這類報告：

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

參與討論及分享意見

Private Aggregation API 目前仍在討論階段，日後可能會有變動。如果您試用過這項 API，歡迎提供意見。

• GitHub：閱讀說明、提出問題並參與討論。