評估 Protected Audience API 競價資料和結果
本文概略說明可透過哪些機制向伺服器回報 Protected Audience API 競價資料,以及目前可在遷移期間使用的轉換機制,直到替代解決方案準備就緒為止。
為了針對您從廣告競價收集到的重要指標製作報表,Protected Audience API 可與:
- 私密匯總:收集競價信號和結果,以便產生摘要報表。
- Ads Reporting API:適用於 Fenced Frame 和 iframe,此為影格中的管道,可用來與 Protected Audience API 小程式通訊。API 允許將事件層級資料與競價信號建立關聯。Ads Reporting API 的事件層級報表是一項轉場機制,直到設計出更私密的報表機制為止。
- Attribution Reporting:可讓您將轉換資料與競價信號建立關聯。
- 共用儲存空間:可讓您將競價信號寫入跨來源儲存空間,之後透過私密匯總功能回報這些資料。
Protected Audience API 報表總覽
在下列三個主要時間範圍內,系統會向您的伺服器回報 Protected Audience API 的競價流程資料:競價從發布商網站執行競價時的競價期間、廣告顯示於發布商網站中的圍欄或 iframe 的顯示時間,以及使用者在另一個網站上執行動作時,可歸因於競價。
在競價期間,您可以使用報表範本製作競價資料報表。在轉譯期間,您可以回報 iframe 或圍欄頁框的參與度資料。在轉換期間,您可以使用 Attribution Reporting API 記錄到達網頁的歸因資料。
報表位置
在競價中,買方可以回報 generateBid()
和 reportWin()
工作小程式提供的信號,賣方則可回報 scoreAd()
和 reportResult()
中可用的信號。在競價之外,買方和賣方可以記錄廣告所在的頁框,以及轉換的來源網站資料。
時間範圍 | 目的地 | 位置 | 有可用的資料 | 可使用 Reporting API |
競價廣告空間 | 採購 | generateBid() |
信號、競價結果和競價成效 | 私密匯總 API |
reportWin() |
Private Aggregation API Ads Reporting API |
|||
賣方 | scoreAd() |
私密匯總 API | ||
reportResult() |
Private Aggregation API Ads Reporting API |
|||
算繪 | 買家 / 賣家 | 發布商網站上的頁框 | 廣告頁框中的事件層級資料 | Private Aggregation API Ads Reporting API |
轉換 | 買家 / 賣家 | 轉換網站 | 轉換網站的轉換和事件層級資料 | Attribution Reporting API Private Aggregation API Ads Reporting API |
在所列每個時間範圍內,買方和賣方可以存取各種報表 API 來製作報表,例如競價信號、事件層級資料和轉換資料。
Protected Audience API 競價期間可使用的資料
系統會在競價期間透過 Protected Audience API 工作小程式回報下列資料。
信號
信號是競價情境資料、使用者資料、即時資料和瀏覽器資料,可供買方和賣方在 Worklet 中產生出價、為廣告評分及回報競價結果。
信號 | 說明 | 設定位置 | 使用者 | 適用地區 |
auctionSignals | 系統在競價期間提供的資料。這類資料包括網頁內容資訊、第一方使用者資料等。 | 由賣方在競價設定中由發布商網站設定。 | 買方 賣家 |
generateBid ScoreAd reportWin reportResult |
directFromSellerSignals | auctionSignals 、perBuyerSignals 的資料與 sellerSignals 相同,但信號保證來自指定賣方。 |
透過賣方的 HTTP 回應標頭設定 | 買方 賣家 |
generateBid ScoreAd reportWin reportResult |
browserSignals | 瀏覽器提供的各種資料 (topWindowHostname 、interestGroupOwner 、renderUrl 、adComponents 、biddingDurationMsec 、IGJoinCount 、IGRecency 、modelingSignals )。 |
由瀏覽器設定。 | 買方 賣家 |
generateBid ScoreAd reportWin reportResult |
sellerSignals | 提供給賣方用來廣告評分的信號。 | 由賣方在競價設定中由發布商網站設定。 | 賣方 | ScoreAd reportWin reportResult |
trustedScoringSignals | 向賣方提供廣告評分的即時信號。 | 此網址是由賣方在競價設定中設定, | 賣方 | ScoreAd reportResult |
perBuyerSignals | 提供給特定買方的競價內容相關資料。賣方可以在競價開始前擷取買方的值。這是買方對廣告商機的瞭解。 | 由賣方在競價設定中由發布商網站設定。 | 採購 | generateBid ScoreAd reportWin reportResult |
trustedBiddingSignals | 提供給買方用於廣告出價的即時信號。 | 此網址是由買方在已設定興趣群組時透過廣告客戶網站設定。 | 採購 | generateBid |
userBiddingSignals | 買方提供的使用者資料。 | 設定興趣群組時,由廣告客戶網站的買方設定。 | 採購 | generateBid |
競價設定物件是所提供資料的主要來源,以做為 Worklet 中的信號。發布商和賣方可在競價設定中提供比對內容資料和第一方資料,系統也能利用買方的興趣群組資料、廣告顯示頁框的事件層級資料,以及來自到達網頁的歸因資料,充實這些信號。報表資料可用於買方/賣方報表、帳單、預算、機器學習模型訓練等。
其他可用資料
- 結果資料與競價勝出和損失資料有關,例如得標出價和出價遭拒原因。
- 成效資料,內含延遲時間資訊,例如擷取及執行出價工作小程式所需的時間。
Protected Audience API 競價外取得的資料
除了 Protected Audience API 競價以外,系統在兩個時間範圍內都可回報相關資料。
在算繪期間,當廣告在發布商網站上顯示時,iframe 或 Fenced Frame 內部的事件層級資料可能會與 Protected Audience API 競價資料建立關聯,並回報給伺服器。範例事件層級資料包括廣告曝光、點閱、懸停,以及影格內發生的任何其他事件。
在轉換期間內,當使用者在歸因於競價的到達網頁上採取某些動作時,轉換頁的事件層級資料就可以與 Protected Audience API 競價資料建立關聯,並記錄至您的伺服器。
事件層級報表
事件層級報表提供了一或多個事件的詳細資訊。事件可能是競價勝出、廣告曝光或轉換。至少到 2026 年之前,系統會保留事件層級競價勝出者報表,顯示 Protected Audience 廣告不需要設有圍欄頁框的情況;而具有不受限制網路存取權的 iframe 則可用於事件層級報表。此外,Ads Reporting API 也適用於圍欄頁框和 iframe,可讓您將競價和轉換資料與影格的事件層級資料建立關聯。這套解決方案可讓生態系統更容易遷移,因為在至少 2026 年之前,您可以繼續使用現有的報表基礎架構,並將系統遷移至 Protected Audience。
使用 sendReportTo()
完成事件層級競價勝出報表
系統運用一項機制,在 Protected Audience 競價中回報事件層級資料,是競價勝出情形的 sendReportTo() function
。買方和賣方報表都能使用這個函式,瀏覽器在顯示廣告開始時,向提供的網址字串發出 GET
請求。您可以將 Worklet 中的任何信號編碼為網址的查詢參數。
舉例來說,買方可以回報 reportWin()
工作小程式的得標出價金額,以便計費:
// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}
從 reportResult()
呼叫時,sendReportTo()
函式可用來產生賣方勝出報表,而從 reportWin()
呼叫時,也可以為買方產生勝出報表。sendReportTo()
函式至少可使用至 2026 年,
「參與」報表
參與報表包含廣告素材的事件層級資料,例如曝光或點擊資料,與顯示廣告的 Protected Audience API 競價信號相關聯。由於廣告在競價結束後才顯示,因此顯示廣告的頁框中不會顯示競價信號。為了將這些資料與不同時間範圍建立關聯,我們提供兩種轉換機制來產生參與報表。
上述的 sendReportTo()
函式可用來將競價資料與 iframe 的事件層級資料建立關聯,但不適用於 Fenced Frame,因為嵌入程式與 Fenced Frame 之間的通訊受到限制。如要將競價資料與圍欄頁框廣告的事件層級資料建立關聯,可以使用 Ads Reporting API。
適用於圍欄頁框和 iframe 的 Ads Reporting API
您可以使用 Ads Reporting API,建立圍欄頁框和 iframe 的使用者事件層級資料,與 Protected Audience 競價中的信號建立關聯。
在 Protected Audience API 報表工作流程中,您可以使用 registerAdBeacon()
函式註冊廣告信標,並將加入做為查詢參數的信號傳入報表網址。您也可以指定要與報表網址建立關聯的自訂事件。之後當廣告在圍欄頁框中顯示時,您可以呼叫 window.fence.reportEvent()
函式觸發自訂事件。可以將 Fenced Frame 內可用的資料新增為酬載。
registerAdBeacon()
函式僅適用於報表函式,不適用於買方的出價邏輯和賣方的評分邏輯。
在以下範例中,廣告活動 ID 會與事件層級酬載與點擊座標建立關聯:
// Protected Audience API buyer win reporting worklet
function reportWin(auctionSignals) {
const { campaignId } = auctionSignals
registerAdBeacon({
click: `https://buyer-server.example/report/click?campaignId=${campaignId}`
})
}
// Protected Audience API seller reporting worklet
function reportResult(auctionConfig) {
const { campaignId } = auctionConfig.auctionSignals;
registerAdBeacon({
click: `https://seller-server.example/report/click?campaignId=${campaignId}`
})
}
// Ad frame
window.fence.reportEvent({
eventType: 'click',
eventData: JSON.stringify({'clickX': '123', 'clickY': '456'}),
destination:['buyer', 'seller']
});
Fenced Frames Ads Reporting API 也將於至少 2026 年開放使用,但原因與勝出報表相同。
詳情請參閱說明。
不受限制的網路存取權
Fenced Frame 可讓您使用與 iframe 相同的方式載入網路資源,而且您可以將 Fenced Frame 內的事件層級資料傳送至伺服器。您可以稍後再在伺服器端產生事件層級報表,方法是將圍欄頁框的事件層級資料與與 sendReportTo()
傳送的競價資料建立關聯 (如上方「競價事件層級報表機制」一節所述)。
第三方 Cookie 淘汰之後,網路存取權將受到限制。
Protected Audience API 目前提供的事件層級檢舉機制是轉換機制,另外,還有替代解決方案將能更妥善地支援現有用途。
歸因報表
您可以使用歸因報表,將網站上的轉換與從 Protected Audience API 競價選出的廣告建立關聯。舉例來說,使用者可能會點選您放送的產品廣告,並重新導向至廣告客戶的網站、購買商品,而您想要將購買功勞歸給放送的廣告。Attribution Reporting API 將與 Protected Audience API 整合,以結合發布商網站的競價資料和廣告客戶網站的轉換資料。
在我們設計更具永久性的解決方案時,您可以搭配 Ads Reporting API 使用圍欄頁框,做為轉換機制,運用 Attribution Reporting 產生事件層級和可匯總報表。請注意,這些報表用於評估轉換,與競價和廣告頁框產生的事件層級和可匯總參與報表不同。準備就緒後,我們會發布說明,提供更永久的解決方案。
轉換機制
註冊廣告信標時,您可以使用關鍵字「reserved.top_navigation
」,這項工具會自動加入信標 Attribution-Reporting-Eligible
標頭,藉此登錄為歸因來源。
registerAdBeacon({
'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});
如要將事件層級資料附加至您註冊的信標,您可以透過事件酬載從圍欄頁框呼叫 setReportEventDataForAutomaticBeacons()
。
window.fence.setReportEventDataForAutomaticBeacons({
eventType: 'reserved.top_navigation',
eventData: 'data from the frame',
destination:['seller', 'buyer']
})
詳情請參閱 Ads Reporting API 說明中的 Attribution Reporting 一節。
參與度和轉換報表範例
在本例中,我們將以買方的角度看待如何將競價、廣告頁框和轉換網站的資料建立關聯。
在本工作流程中,買方會與賣方協調,將專屬 ID 傳送給競價。在競價期間,買方會透過競價資料傳送這個專屬 ID。在顯示和轉換期間,系統也會傳送 Fenced Frame 或 iframe 的資料,並使用相同的專屬 ID。日後,這個專屬 ID 可以用來將這些報表連結在一起。
工作流程:
- 競價開始前,買方會在程式輔助即時出價 (「RTB」) 出價回應中,將專屬 ID 傳送給賣方。ID 可以設為
auctionId
等變數。ID 會在auctionConfig
中以perBuyerSignals
傳入,並會顯示在買家的 Worklet 中。 - 在競價期間,買方可以註冊要在廣告顯示時間和轉換時間 (
registerAdBeacon()
) 觸發的廣告信標。- 如要為廣告影格事件建立關聯競價信號,請將
auctionId
設為信標網址的查詢參數。 - 如要為轉換事件建立關聯競價信號,請在信標網址中設定
auctionId
。
- 如要為廣告影格事件建立關聯競價信號,請將
- 在廣告顯示期間,系統可能會透過事件層級資料觸發或加強您在競價期間註冊的信標。
- 使用
reportEvent()
觸發影格事件,並傳入事件層級資料。 - 使用
setReportEventDataForAutomaticBeacons()
將事件層級酬載新增至歸因信標 - 以
Attribution-Reporting-Register-Source
標頭回應廣告信標請求,使用 Attribution Reporting API 註冊廣告。
- 使用
- 在轉換期間,您可以觸發競價期間登錄的來源。
完成上述程序後,買方會有競價報表、參與報表和轉換報表,並以一組專屬鍵連結彼此。
如果賣方需要存取歸因資料,也適用類似的工作流程,而賣方也可以使用專屬 ID 搭配 registerAdBeacon()
傳送。在頁框中,reportEvent()
呼叫包含目的地屬性,可用於將報表傳送給買方和賣方。請注意,到達網頁也必須有賣方平台,觸發條件才會歸因至來源。
匯總 Protected Audience 資料
Private Aggregation API 是 Protected Audience 資料的回報機制,可用來產生摘要報表,後者是彙整區塊中收集到的資料匯總報表,值區以匯總鍵表示,部分資訊則可編碼至鍵中。
舉例來說,系統會將廣告曝光事件歸入不同的值區,而每個區塊都代表不同的廣告活動。摘要報表與事件層級報表不同,不會顯示個別事件的相關資訊。透過事件層級報表,您可以得知使用者 A、B 和 C 看過廣告活動 123。您可以利用摘要報表評估看過廣告活動 123 並新增噪音的使用者人數,以保護使用者隱私。
如要進一步瞭解 API,請參閱私人匯總文章。
匯總競價信號
您可以利用「私密匯總」功能,將 Worklet 中的可用信號匯總至您的伺服器。如要匯總信號,您可以使用買方出價手冊、賣方評分手冊和買方/賣方報表工作流程中的 privateAggregation.contributeToHistogram()
方法。
在這個範例中,得標出價會匯總至興趣群組擁有者值區:
function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}
function reportResult(auctionConfig, browserSignals) {
privateAggregation.contributeToHistogram({
bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
value: convertWinningBidToValue(browserSignals.bid)
});
}
當您要匯總的信號與事件層級資料無關,且並非由競價以外的事件觸發時,就可以使用這個一般機制。如要進一步瞭解如何回報競價信號,請參閱說明。
使用事件資料匯總競價信號
你可以匯總競價信號,針對廣告頁框中發生的事件提供有限資訊。舉例來說,您可以建立代表該廣告活動和點擊事件的值區,匯總評估廣告活動的廣告點擊次數。請注意,您可以在廣告頁框中指定發生的事件,但無法附加事件層級酬載。
如要依事件匯總競價信號,您可以使用 privateAggregation.contributeToHistogramOnEvent(eventType, contribution)
接受字串,用於指定事件類型,以及在觸發該事件時要回報的貢獻。您可以使用自訂事件類型呼叫該方法,然後從廣告頁框呼叫 window.fence.reportEvent(eventType)
來觸發提交報表。
假設您想評估某個廣告活動的廣告獲得的點擊次數。
// Protected Audience API worklet
function getClickReportBucketForCampaign(campaignId) {
// return a bucket for the campaign ID and the click event
}
function generateBid(interestGroup) {
privateAggregation.contributeToHistogramOnEvent('click', {
bucket: getClickReportBucketForCampaign(interestGroup.ads.metadata.campaignId),
value: 1
});
}
在出價產生函式中,您可以將值區定義為廣告活動 ID 和點擊事件的組合,然後在每次觸發事件時,將該區塊的值提高 1。
// Ad frame
window.fence.reportEvent('click');
之後,您可以在廣告頁框中呼叫 reportEvent(eventType)
來觸發報表提交作業:
如要進一步瞭解如何從影格觸發私人匯總貢獻,請參閱說明。
報表競價結果和成效
您也可以在傳遞預訂事件類型關鍵字 (reserved.win, reserved.loss
和 reserved.always
) 時,使用 contributeToHistogramOnEvent(eventType, contribution)
匯總競價勝出或失敗事件所觸發的競價結果,
「私人匯總」會提供基準值清單,您可以計算貢獻內容的值區和價值。競價結果可用的基準值包括勝出廣告的出價值、評為第二高的出價值,以及出價未參與競價的原因。
如有提供特定基準價值 (例如得標出價金額),你可以設定該值的增減量,然後回報最終值。舉例來說,如果得標出價是 NT $150 元做為基本價值,則只要將出價相減 $2 美元,即可算出競價失敗次數,也就是您錯失了 $3 美元的實際價值。
競價結果報表
讓我們用一個範例,瞭解您失去競價的原因,而您想瞭解自己的出價與競價結算價格之間有多少差距。
若要瞭解您贏得競價的程度,請從得標出價中減去出價價格:
function generateBid() {
const bid = calculateBidAmount();
privateAggregation.contributeToHistogramOnEvent('reserved.loss', {
bucket: getBucketForCampaign(interestGroup.ads.metadata.campaignId),
value: {
baseValue: 'winning-bid',
scale: 1 // Scale the value to minimize noise-to-signal ratio
offset: -bid, // Numbers added to browser value after scaling
}
});
}
提交報告後,實際回報的值將由 offset
值調整的 baseValue
值。詳情請參閱說明。
成效報表
買方和賣方可以回報指令碼的執行時間,以及擷取受信任信號所需的時間。賣方可以在獲得許可的情況下,收集每位買方的出價產生時間和受信任出價信號時間。
詳情請參閱說明。
在共用儲存空間中儲存競價信號
「共用儲存空間」是可自由寫入的未分區與跨來源儲存空間,但在讀取和處理儲存的值時,系統會設下閘門。Shared Storage API 可用的其中一個閘道為「私密匯總」。您只能從 Worklet 讀取共用儲存空間中的值,也可以使用 Worklet 中的 Private Aggregation 回報這些值。
您也可以透過 Protected Audience API 出價、評分和報表小工具寫入共用儲存空間。在稍後,您可以使用「私密匯總」功能,將共用儲存空間中的這些值回報給伺服器。您也可以使用儲存的值進行「URL Selection」作業。
透過 Protected Audience API 工作區,您可以將任何鍵和值寫入共用儲存空間:
// Protected Audience API worklet
function generateBid() {
sharedStorage.set('test-bucket', 123);
}
稍後,您可以載入共用儲存空間工作小程式,然後使用「私密匯總」功能讀取並傳送該值:
// Shared Storage worklet
class SendReachReport{
async run() {
const testBucket = await this.sharedStorage.get('test-bucket');
privateAggregation.contributeToHistogram({
bucket: testBucket,
value: 1
});
}
}
register('send-report', SendReachReport);
如要進一步瞭解共用儲存空間,請參閱 Protected Audience API 報表開發人員指南中的共用儲存空間部分、說明、現場示範和 GitHub 上的示範程式碼。
後續步驟
我們希望與您一起討論,確保我們打造出適合所有人的 API。
討論 API
如同其他 Privacy Sandbox API,這個 API 會記錄並公開討論。
使用 API 進行實驗
您可以實驗並參與 Protected Audience API 的討論。