Protected Audience API 竞价报告

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

本文将简要介绍可用于向服务器报告 Protected Audience API 出价数据的各种机制，以及在迁移期间可供您使用的过渡机制，直到替代解决方案准备就绪为止。

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

• Private Aggregation，用于收集竞价信号和结果以生成摘要报告。
• 适用于 Fenced Frames 和 iframe 的 Ads Reporting API，该 API 是框架内与 Protected Audience API 工作程序通信的渠道。该 API 允许将事件级数据与竞价信号相关联。在设计出更注重隐私保护的报告机制之前，广告报告 API 的事件级报告是一种过渡机制。
• 归因报告，可让您将转化数据与竞价信号相关联。
• 共享存储空间：您可将竞价信号写入跨源存储空间，然后使用 Private Aggregation 稍后报告该数据。

Protected Audience API 报告概览

在 Protected Audience API 竞价流程中，有三个主要时间段可以将数据报告给您的服务器：竞价时间（当竞价在发布商网站上执行时）、呈现时间（当广告在发布商网站上的受限框架或 iframe 中呈现时）和转化时间（当用户在另一个网站上执行可归因于竞价的操作时）。

在竞价期间，您可以使用报告工作单元报告竞价数据。在渲染时，您可以报告来自 iframe 或受限框架的互动数据。在转化时，您可以使用 Attribution Reporting API 报告来自目标网页的归因数据。

报告位置

在竞价中，买方可以报告 generateBid() 和 reportWin() 工作区中提供的信号，而卖方可以报告 scoreAd() 和 reportResult() 中提供的信号。在竞价之外，买方和卖方可以报告呈现广告的框架中的数据，以及促成转化的网站中的数据。

在列出的每个时间段内，买方和卖方都可以使用各种报告 API 来报告数据，例如竞价信号、事件级数据和转化数据。

Protected Audience API 竞价中可用的数据

在竞价期间，Protected Audience API 工作单元可以报告以下数据。

信号

信号是指在工作程序中可供买方和卖方用于生成出价、为广告评分和报告竞价结果的竞价情境数据、用户数据、实时数据和浏览器数据。

竞价配置对象是提供给工作程序以作为信号使用的主要数据源。发布商和卖方可以在竞价配置中提供上下文数据和第一方数据，并且这些信号可以与买方的兴趣群体数据、广告呈现框架中的事件级数据以及点击后到达网页中的归因数据进行丰富。报告的数据可用于买方/卖方报告、结算、预算规划、机器学习模型训练等。

其他可用数据

• 与竞价胜出和落败数据相关的结果数据，例如胜出出价和出价遭拒原因。
• 包含延迟时间信息的效果数据，例如提取和执行出价工作程序的时长。

Protected Audience API 竞价之外可用的数据

在 Protected Audience API 竞价之外，有两个时间段可用于报告数据。

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

在转化时，当用户在归因于竞价的点击后到达网页上执行某些操作时，转化网页中的事件级数据可以与 Protected Audience API 竞价数据相关联，并报告给您的服务器。

事件级报告

事件级报告会详细列出一个或多个事件的信息。事件可以是竞价胜出、广告展示或转化。至少在 2026 年之前，事件级竞价胜出报告将继续存在，呈现 Protected Audience 广告不需要使用受限框架，并且可以使用不受限网络访问权限的 iframe 进行事件级报告。此外，您还可以在受限框架和 iframe 中使用 Ads Reporting API，将竞价和转化数据与框架中的事件级数据相关联。这样做的目的是让生态系统更轻松地完成迁移，因为在将系统迁移到 Protected Audience 之前，您至少可以继续使用现有的报告基础架构，直到 2026 年。

利用 sendReportTo() 生成事件级竞价胜出报告

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

例如，买方可以出于结算目的，从 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 的广告报告 API

适用于受限框架和 iframe 的广告报告 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() 发送的竞价数据相关联，从而在服务器端生成事件级报告，如上文竞价事件级报告机制部分中所述。

未来，网络访问权限将受到限制。

归因报告

借助归因报告，您可以将网站上的转化与通过 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 与竞价数据一起发送。在呈现和转化期间，围栏框架或 iframe 中的数据也会以相同的唯一 ID 发送出去。之后，您可以使用唯一 ID 将这些报告关联起来。

工作流：

1. 在竞价开始之前，买方在程序化实时出价（“RTB”）出价响应中向卖方发送唯一 ID。该 ID 可以设置为变量，如 auctionId。此 ID 会在 auctionConfig 中以 perBuyerSignals 的形式传入，并在买方的工作单元中提供。
2. 在竞价期间，买方可以注册要在广告呈现期间和转化时间 (registerAdBeacon()) 触发的广告信标。
   1. 若要为广告框架事件关联竞价信号，请将 auctionId 设置为信标网址的查询参数。
   2. 若要为转化事件关联竞价信号，请在 Beacon 网址中设置 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 中提供的 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) 来触发报告提交：

如需详细了解如何从框架触发 Private Aggregation 贡献，请参阅说明。

报告竞价结果和效果

当您传入预留的事件类型关键字（reserved.win, reserved.loss 和 reserved.always）时，如果因赢得或输掉竞价而触发了竞价结果事件，您还可以使用 contributeToHistogramOnEvent(eventType, contribution) 汇总竞价结果。

Private Aggregation 提供一系列基本值，您可以根据这些值计算出贡献的桶和值。竞价结果的可用基本值包括胜出广告的出价价值、被评为第二高分的出价价值，以及出价被拒于竞价之外的原因。

如果提供了某个基本值（例如胜出出价金额），您可以设置在该值上增加或减去多少，然后报告最终值。例如，如果胜出出价为 5 美元，并作为基本价值提供，您可以减去自己的出价 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 中存储竞价信号

共享存储空间是一种未分区且跨源的存储空间，您可以随意写入数据，但在读取和处理存储的值时会受到门控的保护。Shared Storage API 的可用门控之一是 Private Aggregation。您只能从工作程序内部读取共享存储空间中的值，并且可以使用工作程序中的 Private Aggregation 报告这些值。

您还可以通过 Protected Audience API 出价、评分和报告工作程序写入共享存储空间。在稍后的时间点，您可以使用 Private Aggregation 将共享存储空间中的这些值报告给服务器。您还可以将存储的值用于网址选择操作。

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

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

稍后，您可以加载共享存储区 worklet，以使用 Private Aggregation 读取并发送该值：

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