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

Private Aggregation API 基礎知識

Private Aggregation API 的重要概念

這份文件適用對象

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

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

重要詞彙

閱讀這份文件前，請先熟悉重要詞彙及概念這裡將詳細說明本條款。

匯總鍵 (也稱為值區) 是以預先決定的資料點集合舉例來說收集位置資料值區，供瀏覽器回報國家/地區名稱。匯總鍵可能包含多個維度 (例如內容小工具的國家/地區和 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：061) 看過小工具 ID 3276 的使用者，匯總鍵為 3276061。

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

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

您也可以使用雜湊機制產生匯總鍵，例如 SHA-256。例如： {"WidgetId":3276,"CountryID":67} 可以進行雜湊處理，然後轉換成 BigInt值為 42943797454801331377966796057547478208888578253058197330928948081739249096287n。如果雜湊值超過 128 位元，您可以截斷值，確保不會發生超過允許的區間值上限 (2^128−1)。

在「共用儲存空間」小程式中 crypto 和 TextEncoder 個模組來產生雜湊值如要進一步瞭解如何產生雜湊，請前往已開啟 SubtleCrypto.digest() MDN。

以下範例說明如何透過經過雜湊處理的雜湊值產生值區金鑰值：

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)。詳情請參閱說明進一步瞭解這些參數

貢獻預算可自由調整，但系統會根據雜訊進行調整。您可以利用這筆預算，盡可能提高摘要值的信號雜訊比 (詳情請參閱雜訊和縮放一節)。

若要進一步瞭解貢獻預算，請參閱說明。您也可以參閱這篇文章預算當中有更多指引

可匯總報表

使用者叫用 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 的呼叫路徑：

共用儲存空間：/.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 的可匯總值為 20,000 的信號雜訊比。

因此，將可匯總值乘以縮放係數，將有助於減少雜訊縮放比例係數代表您希望特定資源縮放的比例可匯總的值

選擇較大的縮放比例係數來擴充值，進而減少雜訊不過，這也會導致所有值區的總貢獻數總和更快達到貢獻預算上限將值縮減為選擇較小的縮放比例係數常數會提高相對雜訊可能會達到預算上限的風險

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

查看捐款預算說明文件。

互動及分享意見回饋

Private Aggregation API 仍在討論階段，未來的發展方向如果您試用這個 API 並有意見，請不吝與我們分享。

GitHub：閱讀釋疑影片提出疑問並參與討論。 * 開發人員支援：您可以提問或參與 Privacy Sandbox 開發人員支援。 * 加入 Shared Storage API 群組和 Protected Audience API 群組取得與「私人匯總」相關的最新公告。