Private Aggregation API 基礎知識

Private Aggregation API 的重要概念

這份文件的用途為何？

Private Aggregation API 可從具備跨網站資料存取權的 Worklet 中匯總資料收集資料。開發人員在 Shared Storage 和 Protected Audience API 中建構報表功能時，這裡分享的概念非常重要。

  • 如果您是「開發人員」，並建立跨網站評估專用的報表系統，
  • 如果您是「行銷人」、「數據資料學家」或其他摘要報告使用者，瞭解這些機制將有助於您制定設計決策，擷取最佳化摘要報表。

重要詞彙

在閱讀本文件之前，建議您先熟悉重要詞彙與概念。我們會在此詳細說明上述所有字詞。

  • 「匯總鍵」 (也稱為值區) 是預先決定的資料點集合。舉例來說，您可以收集位置資料值區，讓瀏覽器回報國家/地區名稱。匯總鍵可能包含多個維度 (例如內容小工具的國家/地區和 ID)。
  • 「可匯總值」是收集至匯總鍵的個別資料點。如要評估有多少來自法國的使用者看過您的內容，則 France 是匯總鍵中的維度，而 1 的 viewCount 是可匯總值。
  • 可匯總報表是在瀏覽器內產生並加密。若是 Private Aggregation API，則包含單一事件的相關資料。
  • 「匯總服務」會處理可匯總報表的資料，以建立摘要報表。
  • 摘要報表是匯總服務的最終輸出內容，包含套用雜訊的匯總使用者資料和詳細轉換資料。
  • 「Worklet」是一個基礎架構，可讓您執行特定 JavaScript 函式，並將資訊傳回要求者。您可以在 Worklet 中執行 JavaScript，但無法與外部網頁互動或通訊。

私人匯總工作流程

當您使用匯總鍵和可匯總值呼叫 Private Aggregation API 時，瀏覽器會產生可匯總報表。這些報表會傳送至您的伺服器，批次處理報表。批次處理的報表會由匯總服務處理，然後產生摘要報表。

資料從用戶端傳送到收集器，再傳送到匯總服務，以產生摘要報表。
  1. 當您呼叫 Private Aggregation API 時，用戶端 (瀏覽器) 會產生可匯總報表，並傳送至您的伺服器進行收集。
  2. 您的伺服器會從用戶端收集報表，並批次處理這些報表，以傳送至匯總服務。
  3. 收集到足夠的報表後，即可批次處理並傳送至匯總服務 (在受信任的執行環境中執行)，以產生摘要報表。

本節所述的工作流程與 Attribution Reporting API 類似。不過，歸因報表會連結曝光事件和轉換事件在不同時間發生的轉換。私人匯總功能會評估單一的跨網站事件。

匯總鍵

「匯總鍵」(簡稱「鍵」) 代表用來累計可匯總值的值區。您可以將一或多個維度編碼至鍵中。維度代表您想要深入瞭解的部分，例如使用者年齡層或廣告活動的曝光次數。

例如，您可能將某個小工具嵌入多個網站，並想要分析看過該小工具的使用者所在的國家/地區。您會瞭解各種問題，例如「有多少使用者看過我的小工具來自 X 國家/地區？」。如要製作這個問題的報表，您可以設定對兩個維度 (小工具 ID 和國家/地區 ID) 編碼的匯總鍵。

提供給 Private Aggregation API 的金鑰是 BigInt，由多個維度組成。在本例中，維度為小工具 ID 和國家/地區 ID。假設小工具 ID 長度最多為 4 位數，例如 1234，且每個國家/地區都會依字母順序對應數字，例如 Afghanistan 為 1，法國是 61，Zimbabwe 為「195」。因此，可匯總金鑰的長度為 7 位數，其中前 4 個字元會保留給 WidgetID 使用，最後 3 個字元會保留給 CountryID。

假設鍵代表的法國使用者 (國家/地區 ID 061) 已看過小工具 ID 3276，匯總鍵為 3276061。

匯總鍵
小工具 ID 國家/地區 ID
3276 061

您也可以使用雜湊機制 (例如 SHA-256) 產生匯總鍵。舉例來說，{"WidgetId":3276,"CountryID":67} 字串可以先經過雜湊處理，再轉換為 42943797454801331377966796057547478208888578253058197330928948081739249096287n 的 BigInt 值。如果雜湊值超過 128 位元，您可以將其截斷，確保值不會超過 2^128−1 所允許的最大值區值。

在共用儲存空間工作流程中，您可以存取 crypto 和 TextEncoder 模組，以便產生雜湊。如要進一步瞭解如何產生雜湊，請查看 MDN 上的 SubtleCrypto.digest()。

以下範例說明如何透過雜湊值產生值區鍵：

async function convertToBucket(data) {
  // Encode as UTF-8 Uint8Array
  const encodedData = new TextEncoder().encode(data);

  // Generate SHA-256 hash
  const hashBuffer = await crypto.subtle.digest('SHA-256', encodedData);

  // Truncate the hash
  const truncatedHash = Array.from(new Uint8Array(hashBuffer, 0, 16));

  // Convert the byte sequence to a decimal
  return truncatedHash.reduce((acc, curr) => acc * 256n + BigInt(curr), 0n);
}

const data = {
  WidgetId: 3276,
  CountryID: 67
};

const dataString = JSON.stringify(data);
const bucket = await convertToBucket(dataString);

console.log(bucket); // 126200478277438733997751102134640640264n

可匯總值

系統會向許多使用者計算各鍵的可匯總值，以在摘要報表中以摘要值的形式產生匯總深入分析。

現在，回到前面提出的問題範例：「有多少使用者看過我的小工具來自法國？」這個問題的答案應類似「看過我的小工具 ID 3276 的使用者約有 4881 位」。每位使用者的可匯總值為 1，「4881 使用者」則是匯總值，也就是該匯總鍵所有可匯總值的總和。

匯總鍵 可匯總值
小工具 ID 國家/地區 ID 觀看次數
3276 061 1

在本例中，我們會將每個看到小工具的使用者值增加 1。在實務上，您可以對可匯總值進行資源調度，以提高訊號雜訊比率。

貢獻預算

每次呼叫 Private Aggregation API 都稱為「貢獻」。為保護使用者隱私，可向個人收集的內容數量有限。

加總所有匯總鍵的所有可匯總值時，總和必須小於貢獻預算。預算範圍是以每項工作小來源的每日為單位，在 Protected Audience API 和共用儲存空間工作小程式中則獨立計算。當天會使用約過去 24 小時的滾動週期。假如新的可匯總報表會導致預算超出預算，系統就不會製作報表。

捐款預算會以參數 L1 表示，且設為每天 216 (65,536)，倒停止率為 220。

(1,048,576)。如要進一步瞭解這些參數，請參閱說明。

貢獻預算的價值不會改變，但雜訊也會按比例調整。您可以使用此預算，最大化匯總值上的信號雜訊比率 (詳情請參閱雜訊和資源調度一節)。

如要進一步瞭解捐款預算，請參閱說明。如需更多指引，請參閱「貢獻預算」一文。

可匯總報表

使用者叫用 Private Aggregation API 後，瀏覽器會產生可匯總報表，供匯總服務稍後處理，以產生摘要報表。可匯總報表採用 JSON 格式，內含經過加密的貢獻清單，每個貢獻項目都是 {aggregation key, aggregatable value} 配對。可匯總報表最多延遲 1 小時傳送。

貢獻內容會經過加密，而且無法在匯總服務外讀取。匯總服務會將報表解密，並產生摘要報表。瀏覽器的加密金鑰和匯總服務的解密金鑰是由協調者核發，後者是金鑰管理服務。協調器會保留服務映像檔的二進位雜湊清單，驗證呼叫端是否獲準接收解密金鑰。

啟用偵錯模式的可匯總報表範例：

  "aggregation_service_payloads": [
    {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAE0mlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "2cc72b6a-b92f-4b78-b929-e3048294f4d6",
      "payload": "a9Mk3XxvnfX70FsKrzcLNZPy+00kWYnoXF23ZpNXPz/Htv1KCzl/exzplqVlM/wvXdKUXCCtiGrDEL7BQ6MCbQp1NxbWzdXfdsZHGkZaLS2eF+vXw2UmLFH+BUg/zYMu13CxHtlNSFcZQQTwnCHb"
    }
  ],
  "debug_key": "777",
  "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"5bc74ea5-7656-43da-9d76-5ea3ebb5fca5\",\"reporting_origin\":\"https://localhost:4437\",\"scheduled_report_time\":\"1664907229\",\"version\":\"0.1\"}"

您可以透過 chrome://private-aggregation-internals 頁面檢查可匯總報表：

Private Aggregation API 內部頁面的螢幕截圖

為了進行測試，您可以使用「傳送所選報表」按鈕，立即將報表傳送至伺服器。

收集並批次處理可匯總報表

瀏覽器使用列出的已知路徑，將可匯總報表傳送至包含 Private Aggregation API 呼叫的 Worklet 來源：

  • 共用儲存空間：/.well-known/private-aggregation/report-shared-storage
  • 針對 Protected Audience： /.well-known/private-aggregation/report-protected-audience

在這些端點中，您必須操作伺服器 (做為收集器)，接收用戶端傳送的可匯總報表。

然後伺服器應批次回報，並將批次資料傳送至匯總服務。根據可匯總報表未加密酬載中的可用資訊 (例如 shared_info 欄位) 建立批次。在理想情況下，批次應包含 100 份以上的報表。

您可以選擇每天或每週進行批次作業。此策略富有彈性，您可以針對預期量較多的特定事件 (例如一年當中預計會增加曝光次數的時段) 變更批次處理策略。批次應納入相同 API 版本的報表、報表來源和排定報表時間。

匯總服務

服務在 TEE 中執行，會將可匯總報表解密，並加入雜訊來建立最終摘要報表。

匯總服務會從收集器接收已加密的可匯總報表，並產生摘要報表。

為瞭解密報表酬載，匯總服務會從協調工具中擷取解密金鑰。服務會在受信任的執行環境 (TEE) 中執行，該環境提供了資料完整性、資料機密性和程式碼完整性的保證。雖然您是自有自營服務，但您將無法查看 TEE 內處理的資料。

摘要報表

摘要報表可讓您查看隨著加入雜訊而收集到的資料。您可以要求一組指定索引鍵的摘要報表。

摘要報表內含一組 JSON 字典式的鍵/值組合。每個組合都包含：

  • bucket：以二進位數字字串表示的匯總鍵。如果使用的匯總鍵為「123」，則值區為「1111011」。
  • value：特定評估目標的匯總值，從所有加入雜訊的可用可匯總報表中加總。

例如：

[
  {"bucket":` `"111001001",` `"value":` `"2558500"},
  {"bucket":` `"111101001",` `"value":` `"3256211"},
  {"bucket":` `"111101001",` `"value":` `"6536542"},
]

雜訊和縮放

為保護使用者隱私，匯總服務會在每次要求摘要報表時，在每個匯總值中加入雜訊一次。雜訊值是從Laplace 機率分佈隨機擷取。雖然您無法直接控制加入雜訊的方式，但可能會影響雜訊對評估資料的影響。

無論所有可匯總值的總和，雜訊分佈都相同。因此，可匯總值越高，雜訊造成的影響就越少。

舉例來說，假設雜訊分佈是標準差 100，並以零為中心。如果收集到的可匯總報表值 (或「可匯總值」) 只有 200，則雜訊的標準差為匯總值的 50%。但是，如果可匯總值是 20,000，則雜訊的標準差將只有匯總值的 0.5%。因此，20,000 的可匯總值，訊號雜訊比率也要高得多。

因此，請將可匯總值乘以縮放比例係數，有助於減少雜訊。縮放比例係數代表您想針對特定可匯總值調度資源的程度。

無論匯總值為何，雜訊都會保持不變。

選擇較大的縮放因數可減少相對雜訊，來向上擴充值。然而，這也會導致所有值區的總貢獻數加總，更快達到貢獻預算上限。選擇較小的資源調度因數常數會增加相對雜訊，藉此縮減值，但會降低達到預算限制的風險。

將可匯總的值調整成貢獻預算。

如要計算適當的縮放比例係數，請將貢獻預算除以所有鍵的可匯總值上限總和。

詳情請參閱捐款預算說明文件。

互動並提供意見

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