Protected Audience API のオークション レポート

Protected Audience API オークションのデータと結果を測定する

この記事では、Protected Audience API のオークション データをサーバーにレポートするために利用できるさまざまなメカニズムの概要と、移行期間中に利用できる移行メカニズムについて説明します。

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

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

Protected Audience API レポートの概要

Protected Audience API オークション フローのデータをサーバーにレポートできる主な期間は 3 つあります。パブリッシャー サイトでオークションが実行されるオークション時間、パブリッシャー サイトのフェンス付きフレームまたは iframe に広告がレンダリングされるレンダリング時間、オークションに起因する別のサイトでユーザーがアクションを実行するコンバージョン時間です。

オークション期間中は、レポート ワークレットを使用してオークション データを報告できます。レンダリング時に、iframe またはフェンス付きフレームからエンゲージメント データをレポートできます。コンバージョン時に、Attribution Reporting API を使用してランディング ページからアトリビューション データをレポートできます。

報告場所

オークション内では、購入者は generateBid() ワークレットと reportWin() ワークレットで利用可能なシグナルをレポートでき、販売者は scoreAd() と reportResult() で利用可能なシグナルをレポートできます。オークション以外では、購入者と販売者は、広告がレンダリングされたフレームと、コンバージョンが行われたサイトのデータをレポートできます。

購入者と販売者は、以下の期間中に、オークション シグナル、イベント単位のデータ、コンバージョン データなどのデータをレポートするために利用できるさまざまなレポート API にアクセスできます。

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

オークション中に Protected Audience API ワークレットからレポートできるデータは次のとおりです。

シグナル

シグナルは、ワークレット内の購入者と販売者が入札の生成、広告のスコアリング、オークションの結果のレポートに使用できるオークションのコンテキスト データ、ユーザーデータ、リアルタイム データ、ブラウザデータです。

オークション構成オブジェクトは、ワークレットでシグナルとして利用可能になるデータを提供する主なソースです。パブリッシャーと販売者はオークション設定でコンテキスト データとファーストパーティ データを指定できます。これらのシグナルは、購入者のインタレスト グループ データ、広告レンダリング フレームのイベントレベル データ、クリックスルー ページの属性データで拡充できます。レポートされるデータは、購入者/販売者のレポート、請求、予算編成、ML モデルのトレーニングなどに使用できます。

その他の利用可能なデータ

• 落札価格や入札拒否の理由など、オークションの落札と入札拒否のデータに関連する結果データ。
• パフォーマンス データ。入札ワークレットの取得と実行にかかった時間など、レイテンシ情報が含まれます。

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

Protected Audience API オークション以外に、レポート可能なデータが利用できる期間が 2 つあります。

レンダリング時に、パブリッシャーのサイトで広告がレンダリングされると、iframe またはフェンス フレーム内のイベントレベル データが Protected Audience API オークション データに関連付けられ、サーバーにレポートされます。イベントレベルのデータには、広告のインプレッション、クリック、ホバー、フレーム内で発生したその他のイベントなどが含まれます。

コンバージョン時に、ユーザーがオークションに帰属するクリック スルー ページでアクションを行うと、コンバージョン ページのイベントレベル データが Protected Audience API オークション データに関連付けられ、サーバーにレポートされます。

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

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

sendReportTo() を使用したイベントレベルのオークション落札レポート

Protected Audience オークション内でイベントレベルのデータをレポートするために利用できるメカニズムは、オークションの落札時の sendReportTo() function です。この関数は購入者と販売者のレポート ワークレットで使用できます。広告のレンダリングが開始されると、ブラウザは指定された 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 のイベントレベルのデータに関連付けるために使用できますが、フェンス付きフレームでは機能しません。これは、エンベッダーとフェンス付きフレーム間の通信が制限されているため、エンベッダーから一意の ID を渡すことができないためです。オークション データをフェンス付きフレーム広告のイベントレベル データに関連付けるには、Ads Reporting API を使用できます。

フェンス付きフレームと iframe の Ads Reporting API

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

Protected Audience API のレポート ワークレットでは、registerAdBeacon() 関数を使用して広告ビーコンを登録し、シグナルがクエリ パラメータとして追加されたレポート URL を渡すことができます。また、レポート用 URL に関連付けるカスタム イベントも指定します。その後、広告がフェンス付きフレームでレンダリングされたときに、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 をフェンス付きフレームで使用して、アトリビューション レポートでイベントレベルのレポートと集計可能レポートを生成するための移行メカニズムとして使用できます。これらのレポートはコンバージョンを測定するためのものであり、オークションと広告フレームから生成されるイベントレベルと集計可能なエンゲージメント レポートとは異なります。より永続的な解決策については、準備が整い次第、説明を公開します。

移行メカニズム

広告ビーコンを登録する際に、キーワード 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. 広告フレーム イベントのオークション シグナルを関連付けるには、ビーコン URL のクエリ パラメータとして auctionId を設定します。
   2. コンバージョン イベントのオークション シグナルを関連付けるには、ビーコン URL で 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 の詳細については、プライベート集計の記事をご覧ください。

オークション シグナルの集計

プライベート アグリゲーションを使用すると、ワークレット内で利用可能なシグナルをサーバーに集約できます。シグナルの集計には、購入者入札ワークレット、販売者スコアリング ワークレット、購入者/販売者レポート ワークレットで使用できる 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) を使用してオークションの落札または落札失敗イベントでトリガーされたオークション結果を集計することもできます。

プライベート アグリゲーションは、貢献度のバケットと値を計算できる基本値のリストを提供します。オークション結果で使用できる基本値は、落札した広告の入札単価、2 番目に高いスコアが得られた入札単価、オークションで入札が不承認となった理由です。

落札単価などの基準値が指定されている場合は、その値に加算または減算する金額を設定し、最終的な値をレポートできます。たとえば、落札額の 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 で利用可能なゲートの 1 つが Private Aggregation です。共有ストレージ内の値を読み取ることができるのはワークレット内のみです。また、ワークレットからプライベート アグリゲーションを使用してこれらの値をレポートできます。

Protected Audience API の入札、スコアリング、レポートのワークレットから共有ストレージに書き込むこともできます。後で、プライベート集計を使用して、共有ストレージ内のこれらの値をサーバーにレポートできます。保存された値は、URL 選択オペレーションでも使用できます。

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

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

後で、共有ストレージ ワークレットを読み込んで、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);

Shared Storage の詳細については、Protected Audience API レポートのデベロッパー ガイドの Shared Storage セクション、説明、ライブデモ、GitHub のデモコードをご覧ください。

次のステップ

誰もが利用できる API を構築するために、Google は皆様との対話を通じてしたいと考えています。

API についてディスカッションする

他のプライバシー サンドボックス API と同様に、この API はドキュメント化され、一般公開されているです。

API を試す

Protected Audience API に関する会話をテストして参加できます。