Protected Audience 的偵錯報表

Protected Audience 偵錯報表可讓廣告技術開發人員宣告遠端網址，在競價勝出或失敗時接收來自裝置的 GET 要求。相關用途包括：

  • 接收報表，瞭解競價的勝出/失敗結果。
  • 瞭解競價失敗的原因，例如出價/評分指令碼實作的問題，還是核心邏輯問題。
  • 找出 JavaScript 邏輯更新時的問題

在 Privacy Sandbox 開發人員預覽版 9 中，您可以透過事件層級偵錯報表執行測試。只要是支援廣告 ID 的裝置，都可以使用偵錯報表。

我們的長期計畫是希望讓平台透過「私密匯總」服務回報競價結果。如此一來，就能確保事後產生的報表無法用於將個別使用者的自訂目標對象加入發布商的應用程式。請注意，事件層級報表是在足夠的報表架構發布之前，臨時提供的報表。

進一步瞭解 Chrome 原始 FLEDGE 來源試用提案的偵錯報表。

使用方法

製作偵錯報表時，系統會使用下列兩個 JavaScript API 擷取網址字串引數：

  • forDebuggingOnly.reportAdAuctionWin(String url)
  • forDebuggingOnly.reportAdAuctionLoss(String url)

以下示例回報了勝出出價的廣告競價損失，以及一個內部變數。這項資料隨後就會用於偵錯。

let someDebuggableVariable = 123;
const url = "https://example.com/reportLoss?winningBid=${winningBid}&someDebuggableVariable=" + someDebuggableVariable;
forDebuggingOnly.reportAdAuctionLoss(url);

競價完成後，${winningBid} 範本會替換為實際值。

賣方可以選擇從自身的 scoreAds 函式傳回 rejectReason：

function scoreAd(ad, bid, auction_config, seller_signals,
                 trusted_scoring_signals, contextual_signal,
                 custom_audience_signal) {
  let score = ...
  return {
    'status': 0,
    'score': score,
    'rejectReason': 'blocked-by-publisher'
  }
}

如果賣方未設定拒絕原因，系統會改為傳送 not-available。

網址變數

可新增至偵錯網址的變數應與 Chrome 中的相應變數一致 (不過 ${topLevelWinningBid} 和 ${topLevelMadeWinningBid} 無法使用，因為元件競價的概念不適用於 Android)。

變數名稱 說明
winningBid 贏得出價的值。
madeWinningBid 這是一個布林值，表示這個自訂目標對象的買方，是透過這個自訂目標對象，還是同一買方的其他自訂目標對象贏得出價。
highestScoringOtherBid 賣方 scoreAd 指令碼評為第二高分的出價值。請注意，這不一定是次高的出價值，因為分數和出價可能各自獨立。
madeHighestScoringOtherBid 這是一個布林值，表示這個自訂目標對象的買方，是透過這個自訂目標對象，還是同一買方的其他自訂目標對象執行 ${highestScoringOtherBid} 出價。
rejectReason 賣方可選擇設定的字串，用來說明他們為何拒絕出價。這可以是下列任一值：

  • not-available
  • invalid-bid
  • bid-below-auction-floor
  • pending-approval-by-exchange
  • disapproved-by-exchange
  • blocked-by-publisher
  • language-exclusions
  • category-exclusions

限制

  • 網址主機必須與已註冊的 Privacy Sandbox 網域相符。
  • 網址 (含網域) 不得超過 4096 個半形字元 (https://) 開頭，以及替換的競價資料
  • 在日後推出的版本中，只有在連上 Wi-Fi 時才會傳送偵錯連線偵測 (ping)。

裝置端行為

在行動通訊環境中，核心要務是保護記憶體和網路使用安全。因此，偵錯報表會分批產生。

下列系統屬性可控管分批頻率和每批次大小，這也可以根據開發需求調整成較低的值：

  • fledge_event_level_debug_reporting_batching_rate
  • fledge_event_level_debug_reporting_batch_size

競價完成後，系統會產生偵錯報表，延遲時間預計落在 15 到 60 分鐘之間。

我們沒辦法無條件保證偵錯報表一定完整無缺。如果在系統傳送對伺服器發出的呼叫之前，裝置已重新啟動，或者廣告服務程序異常終止，系統就不會在報表中記錄這類事件。

在每次競價中，每個廣告技術最多只能註冊 75 個偵錯網址。達到此上限後，無論註冊多少網址，都會以無通知的方式遭到捨棄。

最後，如果使用者停用廣告 ID，那麼偵錯報表就會傳送。這項功能在開發人員預覽版 9 中尚未推出，但會在日後的版本中推出。

廣告技術伺服器行為

廣告技術伺服器應符合下列行為才能使用偵錯報表：

  • 裝置會將 GET 要求傳送至您使用 forDebuggingOnly.* API 指定的伺服器。
  • 每個要求都代表單一的事件層級偵錯報表：單一廣告競價勝出或競價失敗。
  • 每個要求都沒有內文。所有資料都位於查詢參數中。
  • 大型回應酬載可能會對效能和數據用量造成負面影響，因此會遭到忽略。