Private Aggregation API 的重要概念
這份文件適用對象
Private Aggregation API 可讓可存取跨網站資料的工作程式收集匯總資料。 此處分享的概念對於開發人員建構報表非常重要 函式。
- 如果您是開發人員,為跨網站建立報表系統 成效評估方式
- 如果您是行銷人員、數據資料學家或其他摘要報表 瞭解這些機制有助於規劃設計方式 取得最佳化摘要報表
重要詞彙
閱讀這份文件前,請先熟悉 重要詞彙及概念這裡將詳細說明本條款。
- 匯總鍵 (也稱為值區) 是 以預先決定的資料點集合舉例來說 收集位置資料值區,供瀏覽器回報國家/地區 名稱。匯總鍵可能包含多個維度 (例如 內容小工具的國家/地區和 ID)。
- 可匯總值是個別資料點
匯總到匯總鍵中如要評估
瀏覽你的內容,則
France
是 匯總鍵,而1
的viewCount
是可匯總值。 - 可匯總報表是由瀏覽器產生並加密。對於 Private Aggregation API,包含單一事件的相關資料。
- 匯總服務 處理可匯總報表中的資料以建立摘要報表。
- 摘要報表是匯總服務的最終輸出結果。 包含雜訊的匯總使用者資料和詳細的轉換資料。
- 「健身單」 可讓您執行特定的 JavaScript 函式 將資訊傳回要求者在 Worklet 中,您可以執行 JavaScript,但無法與外部網頁互動或通訊。
私密匯總工作流程
如果您使用匯總鍵和 瀏覽器產生可匯總報表。報表 傳送到您的伺服器,以便批次報告。批次報表 然後產生摘要報表
![資料從用戶端傳送到收集器,再流向匯總
用於產生摘要報表的服務。](https://developers.google.cn/static/privacy-sandbox/assets/images/data-flows-the-client-t-ebd6f5c55d92f.png?authuser=9&hl=zh-tw)
- 當您呼叫 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 |
您也可以使用雜湊機制產生匯總鍵,例如
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 小時。如果是 可匯總報表會造成預算超出預算, 已建立。
貢獻預算會以參數 L1 表示, 設為每天 10 分鐘 216 (65,536),且反向停止為 220
(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 內部頁面的螢幕截圖](https://developers.google.cn/static/privacy-sandbox/assets/images/screenshot-the-private-a-132a69aaab759.png?authuser=9&hl=zh-tw)
為了進行測試,可用來傳送 向伺服器回報
收集及批次匯總可匯總報表
瀏覽器將可匯總報表傳送至工作程式來源 包含對 Private Aggregation API 的呼叫 路徑:
- 共用儲存空間:
/.well-known/private-aggregation/report-shared-storage
- 針對 Protected Audience:
/.well-known/private-aggregation/report-protected-audience
在這些端點上,您需要充當收集器來操作伺服器。 接收來自用戶端傳送的可匯總報表。
接著,伺服器應批次回報資料,並將批次資料傳送至匯總頁面
售後服務根據未加密中的資訊建立批次
可匯總報表的酬載,例如 shared_info
欄位。理想情況下
每個批次應包含 100 份以上的報表。
您可以選擇每天或每週進行批次處理。這項策略很有彈性 您可以針對預期內的特定事件變更批次策略 流量升幅,例如一年中預期曝光次數會較多。 批次檔案應包含來自相同 API 版本、報表來源及 排定報表時間。
匯總服務
![服務在 TEE 中執行,系統會解密可匯總報表,並在
產生最終摘要報表](https://developers.google.cn/static/privacy-sandbox/assets/images/the-service-runs-a-tee-746adddcc2c6.png?authuser=9&hl=zh-tw)
匯總服務 從收集器接收經過加密的可匯總報表,並生成摘要 報表。
為了將報表酬載解密,匯總服務會擷取解密金鑰 從協調者開始這項服務在受信任的執行環境 (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 的信號雜訊比。
因此,將可匯總值乘以縮放係數,將有助於 減少雜訊縮放比例係數代表您希望特定資源縮放的比例 可匯總的值
![無論匯總值為何,雜訊都維持不變。](https://developers.google.cn/static/privacy-sandbox/assets/images/noise-is-constant-regardl-6c311a31c1292.png?authuser=9&hl=zh-tw)
選擇較大的縮放比例係數來擴充值,進而減少 雜訊不過,這也會導致所有值區的總貢獻數總和 更快達到貢獻預算上限將值縮減為 選擇較小的縮放比例係數常數會提高相對雜訊 可能會達到預算上限的風險
![將可匯總的值調整至貢獻預算。](https://developers.google.cn/static/privacy-sandbox/assets/images/scale-aggregatable-value-b7347ae673f12.png?authuser=9&hl=zh-tw)
如要計算適當的調整比例係數,請將貢獻預算除以 所有鍵的可匯總值總和上限。
查看捐款預算 說明文件 。
互動及分享意見回饋
Private Aggregation API 仍在討論階段, 未來的發展方向如果您試用這個 API 並有意見,請不吝與我們分享。
- GitHub:閱讀 釋疑影片 提出疑問並參與 討論。 * 開發人員支援:您可以提問或參與 Privacy Sandbox 開發人員支援 。 * 加入 Shared Storage API 群組 和 Protected Audience API 群組 取得與「私人匯總」相關的最新公告。