Protected Audience API auction reporting

この記事では、Protected Audience API のオークション データをサーバーにレポートするために利用できるさまざまなメカニズムの概要と、代替ソリューションの準備ができるまで、現時点で移行中に使用できる移行メカニズムについて説明します。

広告オークションから収集した重要な指標についてレポートするために、Protected Audience API は以下と連携します。

• プライベート集計: オークション シグナルと結果を収集して要約レポートを生成します。
• Fenced Frames と iframe に使用する Ads Reporting API: Protected Audience API ワークレットと通信するためのフレーム内のチャネルです。API を使用すると、イベント レベルのデータをオークション シグナルに関連付けることができます。Ads Reporting API のイベント レベルのレポートは、よりプライベートなレポート メカニズムが設計されるまでの移行メカニズムです。
• アトリビューション レポート: コンバージョン データをオークション シグナルに関連付けることができます。
• 共有ストレージ: クロスオリジン ストレージにオークション シグナルを書き込み、後でプライベート集計を使用してそのデータをレポートすることができます。

# Protected Audience API レポートの概要

Protected Audience API のオークション フローからのデータをサーバーにレポートできる主な期間は 3 つあります。オークションがサイト運営者サイトから実行されるときのオークション時間、広告がサイト運営者サイトの Fenced Frame または iframe にレンダリングされるときのレンダリング時間、およびユーザーが別のサイトでオークションに起因すると考えられる何らかのアクションを実行したときのコンバージョン時間です。

オークション時間中には、レポートワークレットを使用してオークション データをレポートできます。レンダリング時間中には、iframe または Fenced Frame からエンゲージメント データをレポートできます。コンバージョン時間中には、Attribution Reporting API を使用して、宛先ページからアトリビューション データをレポートできます。

# Reporting locations

オークション内では、買い手は generateBid() および reportWin() ワークレットで利用可能なシグナルをレポートでき、売り手は scoreAd() および reportResult() で利用可能なシグナルをレポートできます。オークションの外では、買い手と売り手は、広告をレンダリングしたフレームやコンバージョンが行われたサイトからのデータをレポートできます。

リストされているそれぞれの期間中に、買い手と売り手は、オークション シグナル、イベントレベルのデータ、コンバージョン データなどのデータをレポートするために利用できるさまざまなレポート API にアクセスできます。

# Protected Audience API オークション内で利用可能なデータ

The following data are available to be reported from a Protected Audience API worklet during the auction.

# Signals

シグナルは、ワークレット内のバイヤーとセラーが入札の生成、広告のスコアリング、およびオークション結果のレポートを行う上で利用できるオークション コンテキスト データ、ユーザーデータ、リアルタイムデータ、およびブラウザデータです。

オークション構成オブジェクトは、ワークレットでシグナルとして使用できるようにするために提供されるデータの主なソースです。サイト運営者と売り手はオークション構成でコンテキスト データとファーストパーティ データを提供でき、これらのシグナルは、買い手からのインタレスト グループデータ、広告レンダリング フレームからのイベントレベル データ、およびクリックスルー ページからのアトリビューション データで強化されます。レポートされたデータは、買い手/売り手のレポート、請求、予算編成、ML モデルのトレーニングなどに使用できます。

# Other available data

• Results data that relates to auction win and loss data such as winning bid price and bid rejection reason.
• パフォーマンス データ: 入札ワークレットの取得と実行にかかった時間などの遅延情報を含むデータ。

# Data available outside a Protected Audience API auction

Outside of a Protected Audience API auction, there are two time periods where data is available to be reported.

広告がサイト運営者サイトでレンダリングされるレンダリング時間中には、iframe または Fenced Frame 内のイベントレベルのデータを Protected Audience API のオークション データに関連付けて、サーバーにレポートできます。イベントレベルのデータの例には、広告のインプレッション、クリックスルー、ホバー、およびフレーム内で発生するその他のイベントが含まれます。

ユーザーがオークションに起因するクリックスルー ページで何らかのアクションを実行するコンバージョン時間中には、コンバージョン ページからのイベントレベル データを Protected Audience API のオークション データに関連付けて、サーバーにレポートできます。

# イベントレベル レポート

イベントレベル レポートは、1 つ以上のイベントからの詳細情報をレポートします。イベントには、オークションの落札、広告インプレッション、またはコンバージョンが含まれます。少なくとも 2026 年までは、イベントレベルのオークション落札レポートは維持され、Protected Audience 広告のレンダリングには Fenced Frame は不要となり、イベントレベル レポートには制約のないネットワーク アクセスを持つ iframe を使用できます。また、Ads Reporting API は Fenced Frame と iframe で利用でき、オークション データとコンバージョン データをフレームのイベントレベルのデータに関連付けることができます。これは、システムを Protected Audience に移行する間、エコシステムの移行が容易になるように少なくとも 2026 年までは既存のレポート インフラストラクチャを引き続き使用できるように設計されています。

# Event-level auction win reporting with sendReportTo()

Protected Audience オークション内のイベントレベルのデータをレポートするために利用できるメカニズムは、オークション落札時の [sendReportTo() 関数]（https://github.com/WICG/turtledove/blob/main/Proposed_First_FLEDGE_OT_Details.md#reporting）です。この関数はバイヤーおよびセラーのレポートワークレットで使用でき、ブラウザは広告レンダリングの開始時に指定された URL 文字列に対して GET リクエストを行います。ワークレットで使用可能な任意のシグナルを URL のクエリ パラメーターとしてエンコードできます。

たとえば、買い手は請求目的で、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 オークションのシグナルに関連付けられたインプレッション データやクリックデータなど、広告クリエイティブからのイベントレベルのデータが含まれます。広告はオークション終了後に表示されるため、広告を表示するフレーム内ではオークション シグナルを利用できません。異なる期間のこれらのデータを関連付けるために、エンゲージメント レポートを生成するための移行メカニズムが 2 つ提供されています。

上で説明した sendReportTo() 関数を使用すると、オークション データを iframe からのイベントレベル データに関連付けることができますが、Fenced Frame では機能しません。これは、エンベッダーと Fenced Frame 間の通信が制約されているため、エンベッダーから一意の ID を渡すことができないためです。オークション データを Fenced Frame の広告からのイベントレベル データに関連付けるには、Ads Reporting API を使用できます。

# Ads Reporting API for fenced frames and iframes

Fenced Frame と iframe 用の Ads Reporting API は、広告フレームからのユーザーイベントレベル データを、Protected Audience オークション内のシグナルに関連付けるメカニズムを提供します。

Protected Audience API レポート ワークレットでは、registerAdBeacon() 関数を使用して広告ビーコンを登録し、シグナルをクエリ パラメーターとして設定します。次に、ユーザーレベル データペイロードで window.fence.reportEvent() 関数を呼び出すことで、Fenced Frame からイベントをトリガーします。

In the following example, a campaign ID is associated with an event-level payload that the click coordinates:

// Protected Audience API worklet
function generateBid(interestGroup) {
  const { campaignId } = interestGroup.ads.metadata;
  registerAdBeacon({
    click: `https://your-server.example/report/click?campaignId=${campaignId}`
  })
}

// Ad frame
window.fence.reportEvent({
  'eventType': 'click',
  'eventData': JSON.stringify({'clickX': '123', 'clickY': '456'}),
  'destination':['buyer', 'seller']
});

The Fenced Frames Ads Reporting API will also be available until at least 2026 for the same reasons as win reporting.

For a deeper dive, see the explainer.

# 制約のないネットワークアクセス

Fenced Frame を使用すると、iframe と同じ方法でネットワーク リソースを読み込むことができ、Fenced Frame 内のイベントレベル データをサーバーに送信できます。Fenced Frame からのイベントレベル データを、上記のオークション イベントレベルのレポートメカニズムのセクションで説明した sendReportTo() で送信されたオークションデータに関連付けることにより、後でサーバー側でイベントレベル レポートを生成できます。

Network access will be constrained sometime after third-party cookie deprecation.

現在、Protected Audience API に存在するイベントレベル レポートのメカニズムは移行メカニズムであり、既存のユースケースをより適切にサポートするための代替ソリューションが設計される予定です。

# アトリビューション レポート

アトリビューション レポートでは、ウェブサイト上のコンバージョンを Protected Audience API オークションから選択された広告に関連付けることができます。たとえば、配信した商品広告をユーザーがクリックすると広告主のサイトにリダイレクトされますが、そこで購入が発生した場合に、その購入が表示された広告に起因するものであるかどうかを知りたいことがあります。Attribution Reporting API は Protected Audience API と統合されて、サイト運営者サイトからのオークション データと広告主サイトからのコンバージョン データが組み合わされるようになります。

より永続的なソリューションを設計してはいますが、アトリビューション レポートを使用してイベント レベルの集計可能なレポートを生成するための移行メカニズムとして、Fenced Frame の Ads Reporting API を使用できます。これらのレポートはコンバージョンを測定するためのものであり、オークションや広告フレームから生成されるイベントレベルの集計可能なエンゲージメント レポートとは異なることに注意してください。より永続的なソリューションの準備ができ次第、Explainer を公開します。

# 移行メカニズム

広告ビーコンを登録する際に、キーワード reserved.top_navigation を使用できます。これにより、ビーコンの Attribution-Reporting-Eligible ヘッダーが自動的に追加され、アトリビューション ソースとして登録できるようになります。

registerAdBeacon({
 'reserved.top_navigation': 'https://adtech.example/click?buyer_event_id=123',
});

登録したビーコンにイベントレベルのデータを接続するには、イベント ペイロードで Fenced Frame から setReportEventDataForAutomaticBeacons() を呼び出します。

window.fence.setReportEventDataForAutomaticBeacons({
  eventType: 'reserved.top_navigation',
  eventData: 'data from the frame',
  destination:['seller', 'buyer']
})

See the Attribution Reporting section of the Ads Reporting API explainer to learn more.

# エンゲージメントおよびコンバージョン レポートの例

この例では、オークション、広告フレーム、コンバージョンサイトのデータを関連付けることに関心がある買い手の視点から見てみましょう。

このワークフローでは、買い手が売り手と調整して、一意の ID をオークションに送信します。オークション中に、買い手はこの一意の ID をオークションデータとともに送信します。レンダリング時とコンバージョン時には、Fenced Frame または iframe からのデータも同じ一意の ID で送信されます。後で、その一意の ID を使用してこれらのレポートを関連付けることができます。

ワークフロー:

1. オークションが開始される前に、買い手はプログラムによるリアルタイム入札（RTB」）入札レスポンスの一部として、一意の ID を売り手に送信します。この ID は、auctionId のような変数として設定できます。ID は auctionConfig の perBuyerSignals として渡され、買い手のワークレットで使用できるようになります。
2. オークション時間中、買い手は広告レンダリング時間とコンバージョン時間中にトリガーされる広告ビーコンを登録できます（registerAdBeacon()）。
   1. 広告フレームイベントのオークションシグナルを関連付けるには、auctionId をビーコン URL のクエリ パラメーターとして設定します。
   2. コンバージョン イベントのオークション シグナルを関連付けるには、ビーコン URL に auctionId を設定します。
3. 広告レンダリング時間中、オークション時間中に登録したビーコンをトリガーしたりイベントレベルのデータで強化したりできます。
   3. reportEvent() でフレームイベントをトリガーし、イベントレベル データを渡します。4. setReportEventDataForAutomaticBeacons() を使用して、イベントレベルのペイロードをアトリビューション ビーコンに追加します。5. Attribution-Reporting-Register-Source ヘッダーを使用して広告ビーコン リクエストに応答することで、Attribution Reporting API で広告を登録します。
4. During conversion time, you can trigger the source you registered during auction time.

上記のプロセスが終わると、買い手はオークション レポート、エンゲージメント レポート、コンバージョン レポートを取得します。これらはすべて、相互に関連付けるために使用できる単一の一意のキーによって結び付けられています。

アトリビューション データにアクセスする必要がある場合、同様のワークフローが売り手に適用され、売り手も一意の ID を使用して registerAdBeacon() で送信することができます。フレームからの reportEvent() 呼び出しには、買い手と売り手の両方にレポートを送信するために使用できる宛先プロパティが含まれています。トリガーがソースに関連付けられるには、ランディング ページにも SSP が存在する必要があることに注意してください。

# Aggregating Protected Audience data

The Private Aggregation API is the mechanism used to report Protected Audience data to generate a summary report, which is a noisy, aggregated report of data collected in buckets. A bucket is represented by an aggregation key, and some information can be encoded into the key.

たとえば、ある広告インプレッション イベントは、それぞれに異なる広告キャンペーンを表す様々なバケットにカウントすることができます。イベントレベル レポートと異なるのは、要約レポートが個々のイベントに関する情報を明らかにしないという点です。イベントレベル レポートを使用すると、ユーザー A、B、C がキャンペーン 123 を閲覧したことを確認できますが、要約レポートの場合は、キャンペーン 123 を閲覧したユーザーの数を測定でき、ノイズの追加によって、ユーザーのプライバシーが保護されています。

See the Private Aggregation article for more on the API.

# Aggregating auction signals

プライベート集計を使用して、ワークレット内で使用可能なシグナルをサーバーに集計できます。シグナル集約の場合、買い手の入札ワークレット、売り手のスコアリング ワークレット、および買い手/売り手レポート ワークレットで使用できる privateAggregation.contributeToHistogram() メソッドを使用できます。

この例では、落札入札はインタレスト グループ オーナーのバケットに集計されます。

function convertBuyerToBucket(igOwner) {}
function convertWinningBidToValue(winningBid) {}

function reportResult(auctionConfig, browserSignals) {
  privateAggregation.contributeToHistogram({
    bucket: convertBuyerToBucket(browserSignals.interestGroupOwner),
    value: convertWinningBidToValue(browserSignals.bid)
  });
}

これは、集計するシグナルがイベントレベル データに関連付けられておらず、オークション外のイベントによってトリガーされない場合に使用する一般的なメカニズムです。オークション シグナルのレポートの詳細については、Explainer をご覧ください。

# Aggregating auction signals with event data

You can aggregate auction signals with limited information about an event that occurs in an ad frame. For example, you can aggregately measure how many clicks an ad for a campaign has received by creating a bucket that represents that campaign and the click event. Note that, from the ad frame, you can specify what event has occurred, but you cannot attach an event-level payload.

To aggregate auction signals by events, you can use privateAggregation.contributeToHistogramOnEvent(eventType, contribution) that takes a string that specifies the event type and the contribution to be reported when that event is triggered. You can call the method with a custom event type, then, call window.fence.reportEvent(eventType) from the ad frame to trigger the report to be submitted.

Let’s say you want to measure how many clicks an ad for a campaign has received.

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

In the bid generation function, you can define a bucket as the combination of the campaign ID and the click event, then increase the value for that bucket by 1 every time the event is triggered.

// Ad frame
window.fence.reportEvent('click');

Then, at a later time, from the ad frame, you can trigger the report submission by calling reportEvent(eventType):

Learn more about triggering Private Aggregation contributions from a frame from the explainer.

# オークション結果とパフォーマンスのレポート

You can also aggregate auction results when triggered by an auction win or loss event with contributeToHistogramOnEvent(eventType, contribution) when you pass in a reserved event type keywords (reserved.win, reserved.loss, and reserved.always).

Private Aggregation provides a list of base values you can calculate the bucket and value of your contribution from. The available base values for auction results are the bid value of the winning ad, the bid value that was scored as second highest, and the reason a bid was rejected from the auction.

When some base value is provided, like the winning bid amount, you can set how much to add or subtract from that value, then report the final value. For example, if the winning bid of $5 is provided as the base value, you can subtract your bid of $2 to calculate the actual value of $3 of how much you lost your auction by.

# オークション結果レポート

Let’s look at an example where you have lost an auction, and you want to learn how far off your bid was from the auction clearing price.

To learn how much you lost the auction by, you can subtract your bid price from the winning bid price:

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
    }
  });
}

When the report is submitted, the actual reported value will be the scaled baseValue shifted by the offset value. To learn more, see the explainer.

# パフォーマンスレポート

買い手と売り手は、スクリプトの実行にかかった時間と、信頼できるシグナルを取得するのににかかった時間をレポートできます。売り手は、買い手の許可を得て、各買い手の入札生成時間と信頼できる入札シグナル時間を収集できます。

See the explainer to learn more.

# 共有ストレージでのオークション シグナルの保存

Shared storage is an unpartitioned and cross-origin storage that you can write freely into, but is guarded with gates when reading and processing the stored values. One of the available gates for the Shared Storage API is Private Aggregation. You can only read the values in shared storage from inside a worklet, and you can report those values using Private Aggregation from the worklet.

You can also write to shared storage from Protected Audience API bidding, scoring, and reporting worklets. At a later point in time, you can report those values in shared storage to your server using Private Aggregation . You can also use the stored values for the URL Selection operation.

Protected Audience API ワークレットから、任意のキーと値を共有ストレージに書き込むことができます。

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

At a later time, you can load a shared storage worklet to read and send that value out with 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);

To learn more about Shared Storage, see the shared storage section of the Protected Audience API reporting developer guide, explainer, live demo, and the demo code on GitHub.

# 今後の予定

すべての人にとって機能する API を確実に構築できるように、皆さんとの対話を持ちたいと考えています。

# この API に関するディスカッション

他のプライバシーサンドボックス提案と同様に、この API は文書化され、公に議論されています。

# API の実験

Protected Audience API を試して会話に参加できます。