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

Private Aggregation API 基礎知識

Private Aggregation API 的重要概念

這份文件的適用對象

Private Aggregation API 可讓您從可存取跨網站資料的 worklet 收集匯總資料。對於開發人員來說，這裡分享的概念對於在 Shared Storage 和 Protected Audience API 中建構報表功能非常重要。

如果您是開發人員，並正在建構跨網站評估的報表系統。
如果您是行銷人員、數據科學家或其他摘要報表使用者，瞭解這些機制有助於您做出設計決策，以便擷取最佳化的摘要報表。

重要詞彙

閱讀本文前，建議您先熟悉關鍵字詞和概念。以下將詳細說明每個條款。

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

私密匯總工作流程

當您使用匯總鍵和可匯總值呼叫 Private Aggregation API 時，瀏覽器會產生可匯總報表。系統會將報表傳送到您的伺服器，以便將報表匯出。匯總服務稍後會處理批次報表，並產生摘要報表。

資料會從用戶端流向收集器，然後流向匯總服務，以產生摘要報表。 — 從用戶端到收集器的資料流程。

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

本節所述的工作流程與 Attribution Reporting API 相似。不過，歸因報表會將來自曝光事件和轉換事件的資料建立關聯，而這兩種事件發生的時間可能不同。私密匯總會評估單一跨網站事件。

匯總鍵

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

舉例來說，您可能會在多個網站上嵌入小工具，並想分析看過小工具的使用者所在國家/地區。您想解答的問題包括：「有多少使用者看過我的小工具，且來自 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} 可以經過雜湊處理，然後轉換為 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

可匯總的值

系統會將許多使用者的每個鍵值加總起來，在摘要報表中以摘要值的形式產生匯總洞察資料。

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

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

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

貢獻預算

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

當您將所有匯總鍵的所有可匯總值加總時，總和必須小於貢獻預算。預算範圍為每個工作區塊的來源，每天一次，且 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
適用於受保護的目標對象： /.well-known/private-aggregation/report-protected-audience

在這些端點中，您需要運作伺服器 (做為收集器)，以便接收來自用戶端的可匯總報表。

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

您可以選擇每天或每週執行批次作業。這項策略相當靈活，您可以針對預期有更多流量 (例如預期有更多曝光的特定日子) 變更批次處理策略。批次應包含相同 API 版本、報表來源和排程報表時間的報表。

篩選 ID

私人匯總 API 和匯總服務可使用篩選 ID，以更精細的層級 (例如個別廣告活動) 處理評估結果，而非處理較大查詢的結果。

如要立即開始使用這項功能，請參考以下大致步驟，將其套用至目前的實作。

共用儲存空間步驟

如果您在流程中使用Shared Storage API：

定義要宣告及執行新共用儲存空間模組的位置。在以下範例中，我們將模組檔案命名為 filtering-worklet.js，並註冊在 filtering-example 下。
```
(async function runFilteringIdsExample () {
await window.sharedStorage.worklet.addModule('filtering-worklet.js');
await window.sharedStorage.run('filtering-example', {
  keepAlive: true,
  privateAggregationConfig: {
    contextId: 'example-id',
    filteringIdMaxBytes: 8 // optional
  }
}});
})();
```
請注意，filteringIdMaxBytes 可針對每份報表進行設定，如果未設定，預設值為 1。這個預設值可避免不必要地增加酬載大小，進而增加儲存和處理成本。請參閱彈性貢獻說明，進一步瞭解相關資訊。

在 filtering-worklet.js 中，如果您在共用儲存空間工作區中將貢獻內容傳遞至 privateAggregation.contributeToHistogram(...)，可以指定篩選 ID。

// Within  filtering-worklet.js
class FilterOperation {
  async run() {
    let contributions = [{
      bucket: 1234n,
      value: 56,
      filteringId: 3n // defaults to 0n if not assigned, type bigint
    }];

    for (const c of contributions) {
      privateAggregation.contributeToHistogram(c);
    }
    …
}
});

register('filtering-example', FilterOperation);

系統會將可匯總報表傳送至您定義的端點 /.well-known/private-aggregation/report-shared-storage。請繼續參閱篩選 ID 指南，瞭解匯總服務工作參數中需要的變更。

批次處理完成並傳送至已部署的匯總服務後，篩選結果應會顯示在最終摘要報表中。

Protected Audience 步驟

如果您在流程中使用 Protected Audience API：

在目前的 Protected Audience 導入作業中，您可以設定下列項目，以連結至 Private Aggregation。與共用儲存空間不同，目前無法設定篩選 ID 的大小上限。根據預設，篩選 ID 的大小上限為 1 個位元組，並會設為 0n。請注意，這些值會在Protected Audience 回報函式 (例如 reportResult() 或 generateBid()) 中設定。
```
const contribution = {
  ...
  filteringId: 0n
};

privateAggregation.contributeToHistogram(contribution);
```
系統會將可匯總報表傳送至您定義的端點 /.well-known/private-aggregation/report-protected-audience。批次處理完成並傳送至已部署的匯總服務後，篩選結果應會顯示在最終摘要報表中。以下是 Attribution Reporting API 和 Private Aggregation API 的說明，以及初步提案。

請繼續參閱匯總服務中的篩選 ID 指南，或前往「Attribution Reporting 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 會有更高的訊噪比。

因此，將可匯總的值乘上縮放比例係數，有助於減少雜訊。比例因數代表您要將特定可匯總值擴大多少倍。

選擇較大的縮放因數來縮放值，可減少相對雜訊。不過，這也會導致所有分桶中所有貢獻值的總和更快達到貢獻預算上限。選擇較小的縮放因子常數來縮小值，雖然會增加相對雜訊，但可降低達到預算限制的風險。

如要計算適當的縮放因數，請將貢獻預算除以所有鍵可匯總值的最大總和。

詳情請參閱貢獻預算說明文件。

互動及分享意見回饋

我們正在積極討論私密匯總 API，因此這項 API 日後可能會有所變動。如果您試用這個 API 後有任何意見，歡迎與我們分享。

GitHub：請參閱說明文章，提出問題並參與討論。
- 開發人員支援：在 Privacy Sandbox 開發人員支援存放區中提問及參與討論。
加入 Shared Storage API 群組和 Protected Audience API 群組，即可接收與 Private Aggregation 相關的最新公告。

Private Aggregation API 基礎知識 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

這份文件的適用對象

重要詞彙

私密匯總工作流程

匯總鍵

可匯總的值

貢獻預算

每份報表的貢獻數量上限

含邊框間距的貢獻

可匯總報表

收集及批次匯總報表

篩選 ID

共用儲存空間步驟

Protected Audience 步驟

匯總服務

摘要報表

雜訊和縮放

互動及分享意見回饋

Private Aggregation API 基礎知識