本頁面由 Cloud Translation API 翻譯而成。

Private Aggregation API 基礎知識

Private Aggregation API 的重要概念

這份文件的適用對象

Private Aggregation API 可讓您從可存取跨網站資料的 worklet 收集匯總資料。此處分享的概念對於開發人員建構報表非常重要函式。

如果您是開發人員，並正在建構跨網站評估的報表系統。
如果您是行銷人員、數據資料學家或其他摘要報表瞭解這些機制有助於規劃設計方式 取得最佳化摘要報表

重要詞彙

閱讀本文前，請先熟悉關鍵字詞和概念。我們將在本文中詳細說明每個術語。

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

「私密匯總」工作流程

如果您使用匯總鍵和瀏覽器產生可匯總報表。報表傳送到您的伺服器，以便批次報告。匯總服務稍後會處理批次報表，並產生摘要報表。

當您呼叫 Private Aggregation API 時，用戶端 (瀏覽器) 會產生，並將可匯總報表傳送到你的伺服器以便收集。
您的伺服器會收集用戶端的報表，並將報表批次傳送至匯總服務。
收集足夠的報表後，您會將報表批次處理並傳送至匯總服務，在可信執行環境中執行，以產生摘要報表。

本節所述的工作流程與歸因報表類似 API。但歸因分析報表會將從曝光事件收集到的資料與轉換建立關聯並在不同的時間啟動事件私密匯總會衡量單一跨網站事件

匯總鍵

匯總鍵 (簡稱「鍵」) 代表可匯總的值一或多個維度可以編碼複製到鍵中維度代表您想深入瞭解的某些面向，例如使用者的年齡層或廣告活動的曝光次數。

舉例來說，您可能會在多個網站上嵌入小工具，並想分析看過小工具的使用者所在國家/地區。你正在看著回答問題，例如「有多少使用者看過我的小工具來自 Country X？」如要回報這項問題，您可以設定匯總鍵，用於編碼兩個維度：小工具 ID 和國家/地區 ID。

提供給 Private Aggregation API 的金鑰 BigInt, 包含多種維度在本範例中，維度是小工具 ID 和國家/地區 ID。假設小工具 ID 最多可達 4 位數，例如 1234，而每個國家/地區都會依照字母順序對應到一個數字，例如阿富汗是 1、法國是 61、辛巴威是「195」。因此，可匯總鍵的長度為 7 位數，其中前 4 個為 WidgetID 保留字元，最後 3 個字元供 CountryID 使用。

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

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

範例：如果維度有可用的鍵空間，但該值較少，並在前面加上零。舉例來說，如果國家/地區 ID 允許使用 3 位數字，阿爾及利亞的國家/地區 ID 就是 003。

您也可以使用雜湊機制 (例如 SHA-256) 產生匯總鍵。例如： {"WidgetId":3276,"CountryID":67} 可以進行雜湊處理，然後轉換成 BigInt值為 42943797454801331377966796057547478208888578253058197330928948081739249096287n。如果雜湊值超過 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

可匯總值

可匯總值是許多使用者的每個鍵的總和，以產生匯總摘要報表會以摘要值的形式呈現

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

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

在這個範例中，我們會針對每位看到小工具的使用者，將值增加 1。實務上，您可以調整可匯總的值以改善信號雜訊比率。

貢獻預算

每個 Private Aggregation API 呼叫都稱為貢獻。為保護使用者隱私，我們限制了可向個人收集的貢獻數量。

將所有匯總鍵的所有可匯總值加總時，總和必須必須低於捐款預算預算的分配範圍僅限於每個工作 origin (每天)，且為 Protected Audience API 和 Shared Storage 操作程式的兩個步驟。系統會使用大約過去 24 小時的滾動視窗來計算當天的數據。如果是可匯總報表會造成預算超出預算，已建立。

貢獻預算由參數 L₁ 代表，並設為每天每 10 分鐘 2¹⁶ (65,536)，且有 2²⁰ 的備用值

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

貢獻預算的值為任意值，但雜訊會依此調整。您可以利用這筆預算，盡可能提高摘要值的信號雜訊比 (詳情請參閱雜訊和縮放一節)。

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

每份報表的貢獻數量上限

貢獻限制可能因呼叫端而異。目前為 Shared Storage API 呼叫端產生的每份報表最多可貢獻 20 項貢獻。另一方面，Protected Audience API 呼叫端上限為 100 項貢獻每份報表。這些限制的目的在於平衡可嵌入的貢獻數量與酬載大小。

在共用儲存空間中，單一 run() 或 selectURL() 作業內的貢獻會批次匯入一份報表。在 Protected Audience 中，單一來源在競價中做出的貢獻會一起分批處理。

加上邊框間距的貢獻

使用邊框間距功能可進一步修改貢獻內容。填充酬載的行為可保護可匯總報表中嵌入的貢獻內容實際數量的資訊。邊框間距透過 null 項貢獻來擴增酬載 (例如值為 0) 來達到固定長度。

可匯總報表

使用者叫用 Private Aggregation API 後，瀏覽器就會產生匯總服務稍後處理的可匯總報表即時產生摘要報表。可匯總的報表採用 JSON 格式，並包含加密的貢獻清單，每個清單都是 {aggregation key, aggregatable value} 組合。可匯總報表會在隨機延遲最多一小時後傳送。

貢獻內容會經過加密，且無法在匯總服務外讀取。匯總服務會將報表解密並產生摘要報表。瀏覽器的加密金鑰和匯總服務的解密金鑰，是由協調器 (做為金鑰管理服務) 發出。協調工具會保留服務映像檔的二進位雜湊清單，以便進行驗證呼叫端允許接收解密金鑰。

含有偵錯的可匯總報表範例模式：

  "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 呼叫的 worklet 來源：

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

在這些端點上，您需要扮演收集器的角色來操作伺服器。接收來自用戶端傳送的可匯總報表。

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

您可以選擇每天或每週進行批次處理。這項策略很有彈性您可以針對預期內的特定事件變更批次策略流量升幅，例如一年中預期曝光次數會較多。批次應包含相同 API 版本、報表來源和排程報表時間的報表。

匯總服務

匯總服務從收集器接收經過加密的可匯總報表，並生成摘要報表。

匯總服務會從協調器擷取解密金鑰，以便解密報表酬載。這項服務在受信任的執行環境 (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 並有意見，請不吝與我們分享。

GitHub：閱讀釋疑影片提出疑問並參與討論。 * 開發人員支援：在 Privacy Sandbox 開發人員支援專案中提問並參與討論。* 如要取得與 Private Aggregation 相關的最新公告，請加入 Shared Storage API 群組和 Protected Audience API 群組。