针对 Protected Audience 的调试报告

Protected Audience 调试报告让广告技术平台开发者可以声明远程网址,以便在竞价胜出或落败时从设备接收 GET 请求。它支持以下使用情形:

  • 接收竞价结果为胜出和落败的报告。
  • 了解竞价落败的原因。例如:了解问题是在于出价或评分脚本实现还是核心逻辑问题上。
  • 在 JavaScript 逻辑更新时发现问题

事件级调试报告适用于 Privacy Sandbox 开发者预览版 9 中的测试。具备广告 ID 的所有设备均支持调试报告。

长期计划是使平台借助不公开汇总服务报告竞价结果。这可确保事后报告无法用于将单个用户的自定义受众群体加入发布商的应用。事件级报告是临时的,在足够的报告框架发布后将停用。

详细了解 Chrome 原始 FLEDGE 源试用提案中的调试报告

使用情况

使用以下 JavaScript API 实现调试报告,这两个 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 指定的服务器。
  • 每个请求代表一个事件级调试报告:一项广告竞价胜出或竞价落败。
  • 每个请求都没有正文。所有数据都包含在查询参数中。
  • 较大的响应载荷可能会对性能和流量消耗产生不利影响,因此会被忽略。