Protected Audience API 竞价报告

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

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

若要针对您通过广告竞价收集的重要指标生成报告，Protected Audience API 可与：

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

Protected Audience API 报告概览

<ph type="x-smartling-placeholder">
</ph> Protected Audience 整体工作流
Protected Audience 整个工作流

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

在竞价期间，您可以使用报告 Worklet 报告竞价数据。在呈现期间，您可以报告来自 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 竞价发生地点时可用的数据。此类数据可能包括网页内容信息、第一方用户数据等。 由卖方在竞价配置中的发布商网站上设置。 买方
卖方		 generateBid ScoreAd reportWin reportResult
directFromSellerSignals auctionSignals、perBuyerSignals 和 sellerSignals 的数据相同，但信号保证来自指定卖方。 通过卖方的 HTTP 响应标头进行设置 买方
卖方		 generateBid ScoreAd reportWin reportResult
browserSignals 浏览器提供的各种数据（topWindowHostname、interestGroupOwner、renderUrl、adComponents、biddingDurationMsec、IGJoinCount、IGRecency、modelingSignals）。 由浏览器设置。 买方
卖方		 generateBid ScoreAd reportWin reportResult
sellerSignals 向卖方提供的用于进行广告评分的信号。 由卖方在竞价配置中的发布商网站上设置。 卖家 scoreAd
reportWin
reportResult
trustedScoringSignals 向卖方提供的实时信号，用于进行广告评分。 此网址由卖方在竞价配置中的发布商网站上设置。 卖家 ScoreAd 报告结果
perBuyerSignals 向特定买方提供的竞价情境数据。卖方可以在竞价开始前检索买方的价值。这是买方对广告机会的了解。 由卖方在竞价配置中的发布商网站上设置。 采购员 generateBid ScoreAd 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 可用于事件级报告。此外，您还可以在围栏框架和 iframe 中使用 Ads Reporting API，以便将竞价和转化数据与框架中的事件级数据关联起来。这样做是为了让整个生态系统采用更轻松的迁移路径，因为在将系统迁移到 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() 发送的竞价数据（如上文竞价事件级报告机制部分中所述）相关联。

网络访问未来会受到限制。

归因报告

借助归因报告，您可以将网站上的转化与通过 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 作为 perBuyerSignals 在 auctionConfig 中传入，并在买方的 Worklet 中提供。
  2. 在竞价期间，买方可以注册要在广告呈现时间和转化时间 (registerAdBeacon()) 期间触发的广告信标。 <ph type="x-smartling-placeholder">
      </ph>
    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 元的出价，从而计算出 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 
    }
  });
}

提交报告时，实际报告的值将为经过调整的 baseValue 后移 offset 值。如需了解详情，请参阅说明。

效果报告

买方和卖方可以报告脚本的执行时间以及提取可信信号所需的时间。卖方可以在获得每个买方的许可后，收集其出价生成时间和可信出价信号时间。

如需了解详情，请参阅说明。

在共享存储空间中存储竞价信号

共享存储空间是可以自由写入的未分区跨源存储空间，但在读取和处理存储的值时受到门槛限制。对于 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 的对话。