Protected Audience API 竞价报告

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

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

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

• 私下汇总，用于收集竞价信号和结果以生成摘要报告。
• 适用于围栏框架和iframe的 Ads Reporting API，它是框架中用于与 Protected Audience API worklet 通信的渠道。该 API 允许将事件级数据与竞价信号相关联。在设计出更注重隐私保护的报告机制之前，Ads Reporting API 的事件级报告是一种过渡机制。
• 归因报告，可让您将转化数据与竞价信号相关联。
• 共享存储空间，可让您将竞价信号写入跨源存储空间，然后您可以稍后使用“不公开汇总”功能报告这些数据。

Protected Audience API 报告概览

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

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

报告位置

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

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

Protected Audience API 竞价中提供的数据

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

信号

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

auction config 对象是提供的数据的主要来源，可在 worklet 中作为信号使用。发布商和卖方可以在竞价配置中提供情境数据和第一方数据，这些信号可以通过买方的兴趣群体数据、广告呈现框架中的事件级数据以及点击到达页面的归因数据进行丰富。报告的数据可用于买方/卖方报告、结算、预算、机器学习模型训练等。

其他可用数据

• 与竞价中标和未中标数据相关的结果数据，例如胜出出价的价格和出价遭拒原因。
• 效果数据，其中包含延迟时间信息，例如提取和执行出价工作流程所花的时间。

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

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

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

在转化期间，如果用户在点击后的页面上执行了某些操作，而这些操作可归因于竞价，那么转化页面中的事件级数据可与 Protected Audience API 竞价数据相关联，并报告给您的服务器。

事件级报告

事件级报告详细说明一个或多个事件中的信息。事件可以是竞价胜出、广告展示或转化。至少在 2026 年之前，事件级竞价胜出报告将保持不变，无需使用围栏框架即可呈现 Protected Audience 广告，并且可以使用具有无限制网络访问权限的 iframe 生成事件级报告。此外，Ads Reporting API 可在围栏框架和 iframe 中使用，以便您将竞价和转化数据与框架中的事件级数据相关联。这样一来，生态系统就可以更轻松地进行迁移，因为您至少可以一直使用现有的报告基础架构，直到 2026 年，同时将您的系统迁移到 Protected Audience。

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

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

例如，买方可以从 reportWin() 工作流程报告胜出出价金额，以便进行结算：

// 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']
});

出于与胜出报告相同的原因，至少在 2026 年之前，Fenced Frames Ads Reporting API 也将继续提供。

如需更深入地了解，请参阅说明。

无限制的网络访问

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

未来将限制网络访问权限。

归因报告

借助归因报告，您可以将网站上的转化与从 Protected Audience API 竞价中选择的广告相关联。例如，用户点击您投放的商品广告后，会被重定向到广告客户的网站，并在该网站上进行购买。您希望将这笔购买交易归因于所展示的广告。Attribution Reporting API 将与 Protected Audience API 集成，以便将发布商网站上的竞价数据与广告客户网站上的转化数据合并。

在我们设计更为永久的解决方案期间，您可以使用广告报告 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 会在 auctionConfig 中以 perBuyerSignals 的形式传入，并在买方的 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 中提供的 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 美元减去，以计算出价差的实际价值为 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 的一个可用门限是 Private Aggregation。您只能从 worklet 内部读取共享存储空间中的值，并且可以使用 worklet 中的私有汇总功能报告这些值。

您还可以通过 Protected Audience API 出价、评分和报告工作流写入共享存储空间。稍后，您可以使用“私密汇总”将共享存储空间中的这些值报告给服务器。您还可以将存储的值用于网址选择操作。

您可以通过 Protected Audience API Worklet 将任何键值对写入共享存储空间：

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