Protected Audience API 竞价报告

衡量 Protected Audience API 竞价数据和结果

本文介绍了向服务器报告 Protected Audience API 竞价数据的各种机制，以及目前可在迁移过程中使用的过渡机制，直到替代解决方案准备就绪。

为了针对从广告竞价中收集的重要指标生成报告，Protected Audience API 可与以下产品搭配使用：

• 不公开汇总：收集竞价信号和结果以生成摘要报告。
• 适用于 Fenced Frames 和 iframe 的 Ads Reporting API，后者是框架内的一个通道，用于与 Protected Audience API Worklet 通信。该 API 允许将事件级数据与竞价信号相关联。Ads Reporting API 的事件级报告是一种过渡机制，直至设计出更注重隐私保护的报告机制为止。
• 归因报告：可让您将转化数据与竞价信号相关联。
• 共享存储空间：将竞价信号写入跨源存储空间，之后您可以使用不公开汇总功能报告这些数据。

注意：我们建议您先阅读私密聚合、围栏框架、共享存储空间和归因报告的相关文档，然后再继续，因为本文档中将对核心概念进行详细介绍。

Protected Audience API 报告概览

Protected Audience 整体工作流

可将 Protected Audience API 竞价流程中的数据报告给服务器的时间主要有三个时间段：从发布商网站执行竞价时的竞价时间、广告呈现到发布商网站上的围栏框架或 iframe 中的呈现时间，以及用户在另一个可归因到竞价的另一网站上执行某项操作时的转化时间。

在竞价期间，您可以使用报告 Workerlet 来报告竞价数据。在呈现期间，您可以通过 iframe 或围栏框架报告互动数据。在转化期间，您可以使用 Attribution Reporting API 报告来自目标网页的归因数据。

报告位置

在竞价中，买方可以报告 generateBid() 和 reportWin() Worklet 中可用的信号，卖方可以报告 scoreAd() 和 reportResult() 中可用的信号。在竞价之外，买卖双方可以报告呈现广告的框架以及发生转化的网站的数据。

时间段	目标网址	位置	有相关数据	可用的报告 API
竞价	采购员	generateBid()	信号、竞价结果和竞价效果	Private Aggregation API
		reportWin()		Private Aggregation API Ads Reporting API
	卖家	scoreAd()		Private Aggregation 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 报告以下数据。

信号

信号是竞价环境数据、用户数据、实时数据和浏览器数据，可供 Worklet 中的买方和卖方在设置出价、给广告评分以及报告竞价结果时使用。

信号	说明	设置位置	用户数	适用的国家/地区
auctionSignals	可在竞价举行的情况下获取的数据。这些数据可能包括网页内容信息、第一方用户数据等。	由卖方在竞价配置中的发布商网站上设置。	买方 卖方	生成出价得分广告 reportWin reportResult
directFromSellerSignals	auctionSignals、perBuyerSignals和sellerSignals的数据相同，但信号必须来自指定的卖方。	通过卖方的 HTTP 响应标头设置	买方 卖方	生成出价得分广告 reportWin reportResult
browserSignals	浏览器提供的各种数据（topWindowHostname、interestGroupOwner、renderUrl、adComponents、biddingDurationMsec、IGJoinCount、IGRecency、modelingSignals）。	由浏览器设置。	买方 卖方	生成出价得分广告 reportWin reportResult
sellerSignals	为进行广告评分而向卖方提供的信号。	由卖方在竞价配置中的发布商网站上设置。	卖家	ScoreAd reportWin reportResult
trustedScoringSignals	向卖方提供的用于广告评分的实时信号。	该网址由卖方在竞价配置中的发布商网站上设置。	卖家	ScoreAd reportResult 类中的方法
perBuyerSignals	向特定买方提供的竞价情境数据。卖方可以在竞价开始前检索买方的值。买方对广告机会的了解。	由卖方在竞价配置中的发布商网站上设置。	采购员	生成出价得分广告 reportWin reportResult
trustedBiddingSignals	为买方提供的用于广告出价的实时信号。	该网址由买方在设置兴趣群体时在广告客户网站上设置。	采购员	generateBid
userBiddingSignals	买方提供的用户数据。	由买方在设置兴趣群体时从广告客户网站中设置。	采购员	generateBid

竞价配置对象是所提供数据的主要来源，这些数据将用作 Worklet 中的信号。发布商和卖方可以在竞价配置中提供情境数据和第一方数据，然后可以使用来自买方的兴趣群体数据、来自广告呈现框架的事件级数据以及来自点击后到达网址的归因数据丰富这些信号。报告的数据可用于买方/卖方报告、结算、预算制定、机器学习模型训练等。

其他可用数据

• 与竞价胜出和落败数据（例如胜出出价和出价遭拒原因）相关的结果数据。
• 性能数据，包含延迟信息，例如提取和执行出价 Worklet 所用的时间。

可在 Protected Audience API 竞价之外获取的数据

除了 Protected Audience API 竞价之外，还有两个时间段的数据可供报告。

在呈现期间，当广告在发布商网站上呈现时，来自 iframe 或围栏框架内的事件级数据可与 Protected Audience API 竞价数据相关联，并报告给您的服务器。事件级数据示例包括广告展示、点击、悬停以及在框架内发生的任何其他事件。

转化期间，如果用户在点击着陆页上执行某项归因于竞价的操作，转化页上的事件级数据可与 Protected Audience API 竞价数据相关联，并报告给您的服务器。

事件级报告

来自一个或多个事件的事件级报告详细信息。事件可以是竞价胜出、广告展示或转化。至少到 2026 年，事件级竞价胜出报告将继续使用，而呈现 Protected Audience 广告将无需使用围栏框架，网络访问权限不受限制的 iframe 可用于事件级报告。此外，Ads Reporting API 适用于围栏框架和 iframe，可让您将竞价和转化数据与该框架中的事件级数据相关联。这旨在让整个生态系统拥有更轻松的迁移路径，因为在将系统迁移到 Protected Audience 期间，至少在 2026 年之前，您可以继续使用现有的报告基础架构。

事件级竞价胜出报告（sendReportTo()）

用于在 Protected Audience 竞价中报告事件级数据的机制是竞价胜出的 sendReportTo() function。该函数在买方和卖方报告 Worklet 中提供，当广告开始呈现时，浏览器会向所提供的网址字符串发出 GET 请求。您可以将 Worklet 中的任何信号编码为网址的查询参数。

例如，买方可以在 reportWin() Worklet 中报告胜出的出价金额，以进行结算：

// Buyer reporting worklet
function reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals, directFromSellerSignals) {
  sendReportTo(`https://buyer-reporting-server.example/reporting?bid=${browserSignals.bid}`);
}

sendReportTo() 函数可用于为卖方生成胜出报告（从 reportResult() 调用）和买方胜出报告（从 reportWin() 调用）。sendReportTo() 函数至少可一直使用到 2026 年，

“互动度”报告

互动报告包含广告素材的事件级数据，例如与呈现广告的 Protected Audience API 竞价的信号相关联的展示或点击数据。由于广告在竞价结束后呈现，因此呈现广告的帧内没有竞价信号。为了将不同时间段的数据关联起来，我们为您提供了两种用于生成参与度报告的过渡机制。

上述 sendReportTo() 函数可用于将竞价数据与来自 iframe 的事件级数据相关联，但不适用于围栏帧，因为无法从嵌入器传入唯一 ID，因为嵌入器与围栏帧之间的通信有限。如需将竞价数据与围栏框架广告中的事件级数据相关联，可以使用 Ads Reporting API。

适用于围栏框架和 iframe 的 Ads Reporting API

适用于围栏框架和 iframe 的 Ads Reporting API 提供了一种机制，可让您将广告框架中的用户事件级数据与 Protected Audience 竞价中的信号相关联。

在 Protected Audience API 报告 Worklet 中，您可以使用 registerAdBeacon() 函数注册广告信标，并将所添加的信号作为查询参数传入报告网址。此外，您还需要指定要与报告网址相关联的自定义事件。然后，当广告呈现在围栏帧中时，您可以通过调用 window.fence.reportEvent() 函数来触发自定义事件。围栏帧中提供的数据可作为载荷添加。

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 年内可用，原因与胜出报告相同。

如需更深入地了解相关信息，请参阅说明。

网络访问不受限制

围栏框架将允许像 iframe 一样加载网络资源，并且您可以将围栏框架内的事件级数据发送到服务器。您可以稍后在服务器端生成事件级报告，方法是将围栏框架中的事件级数据与通过 sendReportTo() 发送的竞价数据相关联（如上文的竞价事件级报告机制部分所述）。

弃用第三方 Cookie 后，网络访问将受到限制。

目前 Protected Audience API 中存在的事件级报告机制是过渡机制，我们制定了替代解决方案，以更好地支持现有用例。

归因报告

通过归因报告，您可以将网站上的转化与从 Protected Audience API 竞价中选择的广告相关联。例如，用户可能点击了您投放的产品广告，被重定向到广告客户的网站并在该网站进行购买，并且您有意将此次购买归因于所展示的广告。Attribution Reporting API 将与 Protected Audience API 集成，以便将来自发布商网站的竞价数据和来自广告客户网站的转化数据合并。

在我们设计一种更持久的解决方案时，您可以将适用于围栏框架的 Ads Reporting API 用作一种过渡机制，通过归因报告生成事件级可汇总报告。请注意，这些报告用于衡量转化情况，与竞价和广告框架生成的事件级互动报告和可汇总的互动报告彼此独立。待就绪后，我们会发布一条说明性消息，以提供更持久的解决方案。

过渡机制

注册广告信标时，您可以使用关键字 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 说明文档中的“归因报告”部分。

互动和转化报告示例

在本示例中，我们将从有意将竞价、广告框架和转化网站中的数据关联起来的买方的角度进行探讨。

在此工作流程中，买方与卖方协调，发送唯一 ID 参与竞价。在竞价过程中，买方会将此唯一 ID 与竞价数据一起发送。在呈现和转化期间，系统也会将来自围栏框架或 iframe 的数据以相同的唯一 ID 发送出去。稍后，您可以使用该唯一 ID 将这些报告关联起来。

工作流程：

1. 在竞价开始之前，买方会在程序化实时出价 (RTB) 出价响应中向卖方发送唯一 ID。可以将 ID 设置为 auctionId 等变量。该 ID 以 perBuyerSignals 的形式在 auctionConfig 中传入，并在买方的 Worklet 中提供。
2. 在竞价期间，买方可以注册要在广告呈现时间和转化期间触发的广告信标 (registerAdBeacon())。
   1. 若要为广告框架事件关联竞价信号，请将 auctionId 设为信标网址的查询参数。
   2. 若要为转化事件关联竞价信号，请在信标网址中设置 auctionId。
3. 在广告呈现期间，系统可以触发您在竞价期间注册的信标或使用事件级数据增强这些信标。
   1. 使用 reportEvent() 触发帧事件，并传入事件级数据。
   2. 使用 setReportEventDataForAutomaticBeacons() 向归因信标添加事件级载荷
   3. 通过使用 Attribution-Reporting-Register-Source 标头响应广告信标请求，向 Attribution Reporting API 注册广告。
4. 在转化期间，您可以触发在竞价期间注册的来源。

完成上述流程后，买方将获得竞价报告、互动度报告和转化报告，这些信息均通过一个可用于相互关联的唯一键绑定在一起。

类似的工作流程也适用于需要访问归因数据的卖方，卖方也可以使用唯一 ID 通过 registerAdBeacon() 发送。在该框架中，reportEvent() 调用包含一个目标属性，可用于将报告同时发送给买方和卖方。请注意，着陆页上还必须包含 SSP，这样触发器才能归因于来源。

汇总 Protected Audience 数据

Private Aggregation API 是一种用于报告 Protected Audience 数据以生成摘要报告的机制。摘要报告是针对存储分区中收集的数据的汇总报告。存储分区由汇总键表示，一些信息可以编码到该键中。

例如，某个广告展示事件可能会计入不同的分桶，其中每个类代表不同的广告系列。摘要报告与事件级报告的不同之处在于，它不会显示有关每个事件的信息。通过事件级报告，您可以确定用户 A、B 和 C 浏览过广告系列 123。通过摘要报告，您可以衡量看到广告系列 123 和添加噪声的用户数，以保护用户隐私。

如需详细了解此 API，请参阅不公开汇总一文。

汇总竞价信号

您可以使用不公开汇总将 Worklet 内提供的信号汇总到服务器。对于信号汇总，您可以使用买方出价 Worklet、卖方评分 worklet 和买方/卖方报告 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) 来汇总竞价胜出或落败事件触发的竞价结果。

不公开汇总提供了一个基准值列表，可供您用来计算贡献量的范围和价值。竞价结果的可用基准值包括：胜出广告的出价值、被评为第二高的出价值，以及相应出价在竞价中被拒绝的原因。

如果提供了某些基准值（例如胜出的出价金额），您可以设置要在该值的基础上增减多少，然后报告最终值。例如，如果以 5 元的胜出出价作为基准价值，您可以将 2 元的出价减去 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 中的不公开汇总功能报告这些值。

您也可以通过 Protected Audience API 出价、评分和报告 Worklet 向共享存储空间写入数据。稍后，您可以使用 不公开汇总 将共享存储空间中的这些值报告给您的服务器。您还可以将存储的值用于网址选择操作。

在 Protected Audience API Worklet 中，您可以将任何键和值写入共享存储空间：

// Protected Audience API worklet
function generateBid() {
  sharedStorage.set('test-bucket', 123);
}

稍后，您可以加载一个共享存储空间 Worklet，以通过不公开汇总读取和发送该值：

// 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 的对话。