使用 Protected Audience 的資料和共用儲存空間中的跨網站資料,產生匯總資料報表。
為了提供網路仰賴的重要功能,我們打造了 Private Aggregation API,以保護隱私權的方式匯總及回報跨網站資料。
導入狀態
Proposal | Status |
---|---|
Prevent invalid Private Aggregation API reports with report verification for Shared Storage Explainer |
Available in Chrome |
Private Aggregation debug mode availability dependent on 3PC eligibility GitHub issue |
Available in Chrome M119 |
Reducing report delay Explainer |
Available in Chrome M119 |
Support for Private Aggregation API and Aggregation Service for Google Cloud Explainer |
Available in Chrome M121 |
Padding for aggregatable report payloads Explainer |
Available in Chrome M119 |
Private Aggregation debug mode available for auctionReportBuyers reporting Explainer |
Expected in Chrome M123 |
Filtering ID support Explainer |
Initial launch expected in Chrome in Q2 2024. |
什麼是 Private Aggregation API
開發人員可以透過 Private Aggregation API,使用 Protected Audience API 的資料和共用儲存空間中的跨網站資料產生匯總資料報表。
這個 API 目前只提供一項作業 (sendHistogramReport()
),但日後可能會支援更多作業。直方圖作業可讓您匯總定義的各值區內使用者的資料 (在 API 中稱為匯總鍵)。直方圖呼叫會累積值,並以摘要報表的形式傳回雜訊的匯總結果。舉例來說,這份報表可能會顯示每位使用者看過您內容的網站數量,或是在第三方指令碼中發現錯誤。這項作業會在其他 API 的小程式中執行。
舉例來說,如果您先前曾在「共用儲存空間」中記錄客層和地理資料,就可以使用 Private Aggregation API 建立直方圖,掌握有多少紐約市的概略使用者人數跨網站看過您的內容。如要匯總這項評估結果,您可以將地理位置維度編碼成匯總鍵,然後計算可匯總值中的使用者數。
核心概念
當您使用匯總鍵和可匯總值呼叫 Private Aggregation API 時,瀏覽器會產生可匯總報表。
可匯總報表會傳送至您的伺服器,以便收集和批次處理。匯總服務會在稍後處理批次報表,然後產生摘要報表。
如要進一步瞭解 Private Aggregation API 的相關重要概念,請參閱 Private Aggregation API 基礎知識文件。
與歸因報表的差異
Private Aggregation API 與 Attribution Reporting API 有許多相似之處。Attribution Reporting 是專門用來評估轉換的獨立 API,「私人匯總」則是用來搭配 Protected Audience API 和 Shared Storage 等 API 進行跨網站評估。這兩個 API 都會產生可匯總的報表,供匯總服務後端使用以產生摘要報表。
歸因報表會連結曝光事件和轉換事件在不同時間發生的轉換事件。「私人匯總」會評估單一跨網站事件,
測試這個 API
只要在 chrome://flags/#privacy-sandbox-ads-apis
啟用 Privacy Sandbox Ads API 實驗標記,即可在本機測試 Private Aggregation API。
進一步瞭解實驗功能和參與測試。
使用試用版
如要查看共用儲存空間專用 Private Aggregation API 示範,請前往 goo.gle/shared-storage-demo,如需取得程式碼,請前往 GitHub。這個示範會實作用戶端作業,並產生可匯總報表,傳送至您的伺服器。
我們日後會發布 Protected Audience API 的 Private Aggregation API 示範。
應用情境
「私人匯總」是可用於跨網站評估的一般用途 API,可用於 Shared Storage 和 Protected Audience API 工作套件。首先,您必須精確決定要收集的資訊。這些資料點是匯總鍵的基礎。
附共用儲存空間
共用儲存空間可讓您在安全環境中讀取及寫入跨網站資料,防止資料外洩;Private Aggregation API 則可讓您評估儲存在「共用儲存空間」的跨網站資料。
不重複觸及率評估
建議您評估有多少不重複使用者看過他們的內容。Private Aggregation API 可為您提供解答,例如:「發現 Content ID 861 的不重複使用者人數約為 317 人」。
您可以在「共用儲存空間」中設定旗標,表明使用者是否已看過該內容。在第一個造訪不存在該旗標的情況下,系統會呼叫私密匯總,然後設定旗標。當使用者後續造訪 (包括跨網站造訪) 時,只要檢查「共用儲存空間」,即可略過已設定的旗標回報作業。
客層評估
你可能會想評估在不同網站上看過你內容的使用者客層。
「私人匯總」可以提供答案,例如「約 317 位不重複使用者來自 18 到 45 歲,且來自德國」。使用共用儲存空間存取第三方內容的客層資料。日後,您可以在匯總鍵中將年齡層和國家/地區維度編碼,以產生「私人匯總」報表。
K+ 頻率評估
建議您將預先選擇的值 K ,評估在特定瀏覽器看過內容或廣告至少 K 次的使用者人數。
「私人匯總」可以提供答案,例如「約 89 位使用者看過 Content ID 581 至少 3 次」。您可以從不同網站的「共用儲存空間」中增加計數器,也可以在工作小程式中讀取。當數量達到 K 個時,您就能透過「私密匯總」功能提交報表。
使用 Protected Audience API
Protected Audience API 支援指定舊訪客和自訂目標對像用途,私人匯總功能則可讓您回報買方和賣方研討會的事件。此 API 可用於評估競價出價分佈情形等工作。
在 Protected Audience API 工作區中,您可以直接使用 sendHistogramReport()
匯總資料,並使用 reportContributionForEvent()
(這是 Protected Audience API 的特殊擴充功能) 根據觸發條件回報資料。
可用的函式
「共用儲存空間」和「Protected Audience API」工作流程中的 privateAggregation
物件提供下列函式。
contributeToHistogram()
您可以呼叫 privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> })
,其中匯總鍵為 bucket
,而可匯總值為 value
。bucket
參數必須要有 BigInt
。若是 value
參數,必須提供整數。
以下範例說明如何在「共用儲存空間」中呼叫此資料,以便評估觸及率:
iframe.js
// Cross-site iframe code
async function measureReach() {
// Register worklet
await window.sharedStorage.worklet.addModule('worklet.js');
// Run reach measurement operation
await window.sharedStorage.run('reach-measurement', {
data: { contentId: '1234' }
});
}
measureReach();
worklet.js
// Shared storage worklet code
function convertContentIdToBucket(campaignId){
// Generate aggregation key
}
// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling"
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;
class ReachMeasurementOperation {
async run(data) {
const key = 'has-reported-content';
// Read the flag from Shared Storage
const hasReportedContent = await this.sharedStorage.get(key) === 'true';
// Do not send report if the flag is set
if (hasReportedContent) {
return;
}
// Send histogram report
// Set the aggregation key in `bucket`
// Bucket examples: 54153254n or BigInt(54153254)
// Set the scaled aggregatable value in `value`
privateAggregation.contributeToHistogram({
bucket: convertContentIdToBucket(data.contentId),
value: 1 * SCALE_FACTOR
});
// Set the flag in Shared Storage
await this.sharedStorage.set(key, true);
}
}
register('reach-measurement', ReachMeasurementOperation);
上述程式碼範例會在每次載入跨網站 iframe 內容時呼叫私人匯總。iframe 程式碼會載入工作小程式,這個工作程式會使用內容 ID 轉換為匯總鍵 (值區) 來呼叫 Private Aggregation API。
contributeToHistogramOnEvent()
在 Protected Audience API 工作小程式中,我們提供了以觸發條件為基礎的機制,以便只在發生特定事件時傳送報表。透過這個函式,您也可以根據競價當下尚未可用的信號,決定值區和值。
privateAggregation.reportContributionForEvent(eventType, contribution)
方法接受用來指定觸發事件的 eventType
,以及在事件觸發時要提交的 contribution
。觸發事件可能來自競價結束後的競價本身 (例如競價勝出或損失事件),也可能來自帶出廣告的圍欄頁框。
如要傳送競價事件的報表,您可以使用兩個保留關鍵字:reserved.win
、reserved.loss
和 reserved.always
。如要提交由圍欄頁框的事件觸發的報表,請定義自訂事件類型。如要從圍欄頁框觸發事件,請使用 Fenced Frames Ads Reporting API 提供的 fence.reportEvent()
方法。
以下範例會在競價勝出事件觸發時傳送曝光報表,並在顯示廣告的圍欄頁框觸發 click
事件時傳送點擊報表。這兩個值可用來計算點閱率。
function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
// …
privateAggregation.contributeToHistogramOnEvent("reserved.win", {
bucket: getImpressionReportBucket(),
value: 1
});
privateAggregation.contributeToHistogramOnEvent("click", {
bucket: getClickReportBuckets(), // 128-bit integer as BigInt
value: 1
});
詳情請參閱擴充私人匯總報表說明。
enableDebugMode()
雖然第三方 Cookie 仍可使用,但我們會提供暫時性機制,讓偵錯模式能簡化偵錯和測試作業。偵錯報表在比較以 Cookie 為基礎的評估結果與私人匯總評估結果時相當實用,也能讓您快速驗證 API 整合情形。
在工作小程式中呼叫 privateAggregation.enableDebugMode()
會啟用偵錯模式,讓可匯總報表納入未加密 (明文) 酬載。接著,您可以使用匯總服務的本機測試工具處理這些酬載。
偵錯模式僅適用於允許存取第三方 Cookie 的呼叫端。如果呼叫端無法存取第三方 Cookie,enableDebugMode()
將失敗,且不會顯示通知。這表示在第三方 Cookie 淘汰後,偵錯模式將不再提供使用。
您也可以呼叫 privateAggregation.enableDebugMode({ <debugKey: debugKey> })
來設定偵錯金鑰,其中 BigInt
可用於做為偵錯金鑰。偵錯金鑰可用來連結以 Cookie 為基礎的評估資料,以及私人匯總評估資料。每個內容只能呼叫一次。系統會忽略任何後續呼叫。
// Enables debug mode
privateAggregation.enableDebugMode();
// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });
檢舉驗證報表
針對共用儲存空間,您可以在共用儲存空間作業呼叫中新增內容 ID,以驗證您收到的可匯總報表合法。這組 ID 會附加至已傳送的報表,稍後您就可以使用這組 ID 確認報表是否傳送自共用儲存空間作業。
這項功能可在 Chrome M114 以上版本中進行測試。Protected Audience API 的報告驗證功能目前還未開放測試。
詳情請參閱報表驗證說明。
互動並提供意見
Private Aggregation API 目前正在積極討論,日後可能會有變更。如果您已經試用過這個 API,並提供寶貴意見,我們非常樂意聽聽您的想法。
- GitHub:閱讀說明、提出問題並參與討論。
- 開發人員支援:前往 Privacy Sandbox 開發人員支援存放區提問及參與討論。
- 歡迎加入 Shared Storage API 群組和 Protected Audience API 群組,掌握私人匯總的最新公告。