Protected Audience API のオークション データと結果を測定する
この記事では、Protected Audience API のオークション データをサーバーに報告する際に利用できるさまざまなメカニズムの概要と、代替ソリューションが準備できるまで、移行中にすぐに使用できる移行メカニズムについて説明します。
広告オークションから収集した重要な指標に関するレポートを作成するために、Protected Audience API は次のものと連携します。
- プライベート アグリゲーション: オークションのシグナルと結果を収集して概要レポートを生成します。
- フェンス付きフレームと iframe 用の Ads Reporting API(Protected Audience API ワークレットと通信するためのフレーム内のチャネル)この API を使用すると、イベント単位のデータとオークション シグナルを関連付けることができます。Ads Reporting API のイベントレベルのレポートは、よりプライバシーに配慮したレポート メカニズムが設計されるまでの暫定的なメカニズムです。
- アトリビューション レポート: コンバージョン データとオークション シグナルを関連付けることができます。
- 共有ストレージ: オークション シグナルをクロスオリジン ストレージに書き込み、プライベート アグリゲーションを使用して後でそのデータを報告できます。
Protected Audience API レポートの概要
<ph type="x-smartling-placeholder">![Protected Audience の全体的なワークフロー](https://developers.google.cn/static/privacy-sandbox/assets/images/protected-audience-overal-cd55be71ecfa2.png?hl=ja)
Protected Audience API オークション フローからのデータがサーバーにレポートされる主な期間は 3 つに分けられます。パブリッシャー サイトからオークションが実施されたときのオークション時間、パブリッシャー サイトのフェンス付きフレームまたは iframe に広告がレンダリングされるレンダリング時間、ユーザーが別のサイトでオークションに起因する可能性のあるなんらかのアクションをユーザーが実行したときのコンバージョンの時間です。
オークション期間中に、レポート ワークレットを使用してオークション データのレポートを作成できます。レンダリング時に、iframe またはフェンス付きフレームからエンゲージメント データをレポートできます。コンバージョンの期間中に、Attribution Reporting API を使ってリンク先ページからアトリビューション データのレポートを取得できます。
レポートの場所
オークションでは、購入者は generateBid()
ワークレットと reportWin()
ワークレットで利用可能なシグナルを報告でき、販売者は scoreAd()
と reportResult()
で利用可能なシグナルを報告できます。オークション以外では、購入者と販売者は、広告を表示したフレームのデータと、コンバージョンの発生元サイトのデータをレポートできます。
期間 | 目的地 | 場所 | データがあります | 使用可能な Reporting 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 |
示された各期間中、購入者と販売者は、オークション シグナル、イベント単位のデータ、コンバージョン データなどのデータのレポート作成に使用できるさまざまな Reporting API にアクセスできます。
Protected Audience API オークション内で利用可能なデータ
オークション中に、Protected Audience API ワークレットから次のデータをレポートできます。
シグナル
シグナルとは、オークションのコンテキスト データ、ユーザーデータ、リアルタイム データ、ブラウザデータのことです。購入者と販売者は、ワークレット内で入札単価の生成、広告のスコアリング、オークション結果の報告に使用できます。
シグナル | 説明 | 場所を設定 | ユーザー | 利用可能な国と地域 |
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 | 広告のスコアリングのために販売者に提供されるリアルタイムのシグナル。 | この URL は、販売者がオークション設定でパブリッシャー サイトから設定します。 | 販売者 | ScoreAd reportResult |
perBuyerSignals | 特定の購入者に提供されるオークションのコンテキスト データ。販売者は、オークションの開始前に購入者のために値を取得できます。広告配信予想数に関する購入者の情報。 | オークション設定で販売者がパブリッシャー サイトから設定します。 | 購入者 | generateBid scoreAd reportWin reportResult |
trustedBiddingSignals | 広告の入札のために購入者に提供されるリアルタイムのシグナル。 | この URL は、インタレスト グループの設定時に購入者が広告主のサイトで設定したものです。 | 購入者 | generateBid |
userBiddingSignals | 購入者から提供されたユーザーデータ。 | インタレスト グループの設定時に、購入者が広告主のサイトで設定します。 | 購入者 | generateBid |
オークション構成オブジェクトは、ワークレットでシグナルとして使用できるようになるために提供されるデータの主要なソースです。パブリッシャーと販売者は、オークション設定でコンテキスト データとファーストパーティ データを提供できます。これらのシグナルは、購入者からのインタレスト グループ データ、広告レンダリング フレームのイベントレベルのデータ、クリックスルー ページのアトリビューション データで拡充できます。報告されたデータは、購入者/販売者のレポート、請求、予算編成、ML モデルのトレーニングなどに使用できます。
その他の利用可能なデータ
- 落札単価や入札拒否の理由など、オークションの勝敗データに関連する結果データ。
- パフォーマンス データ。入札ワークレットを取得して実行するのにかかった時間などのレイテンシ情報が含まれます。
Protected Audience API オークション外でデータが利用可能
Protected Audience API オークション以外では、レポートの対象となるデータが 2 つの期間に分けられます。
レンダリング時、パブリッシャー サイトで広告がレンダリングされる際に、iframe またはフェンス付きフレーム内のイベントレベルのデータを Protected Audience API のオークション データと関連付けて、サーバーにレポートできます。イベント単位のデータの例としては、広告のインプレッション、クリックスルー、カーソルを合わせたイベントなど、フレーム内で発生するイベントが挙げられます。
コンバージョンの期間中に、ユーザーがクリックスルー ページでオークションに起因するなんらかのアクションを行うと、コンバージョン ページのイベントレベルのデータが Protected Audience API のオークション データと関連付けられ、サーバーにレポートされます。
イベントレベルのレポート
イベントレベル レポートでは、1 つ以上のイベントの詳細情報を確認できます。イベントとは、オークションでの勝利、広告のインプレッション、コンバージョンのいずれかを指します。遅くとも 2026 年までは、イベントレベルのオークション落札レポートが維持されます。Protected Audience 広告のレンダリングにフェンス付きフレームは必要ありません。また、ネットワーク アクセスが制限されていない iframe をイベントレベルのレポートに使用できます。また、フェンス付きフレームと iframe では、Ads Reporting API を使用して、オークション データとコンバージョン データをフレームのイベントレベルのデータに関連付けることができます。これは、システムを 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 と統合され、パブリッシャー サイトのオークション データと広告主サイトのコンバージョン データが統合されます。
Google ではより永続的なソリューションを設計していますが、Attribution Reporting でイベントレベル レポートと集計レポートを生成する移行メカニズムとして、フェンス付きフレーム用の 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 を使用してこれらのレポートを関連付けることができます。
ワークフロー:
- オークションの開始前に、購入者はプログラマティックリアルタイム ビッダー(RTB)の入札レスポンスの一環として、販売者に一意の ID を送信します。ID は、
auctionId
などの変数として設定できます。ID はauctionConfig
でperBuyerSignals
として渡され、購入者のワークレットで使用可能になります。 - オークションの期間中、購入者は広告のレンダリング時間およびコンバージョンの時間(
registerAdBeacon()
)にトリガーされる広告ビーコンを登録できます。 <ph type="x-smartling-placeholder">- </ph>
- 広告フレーム イベントのオークション シグナルを関連付けるには、
auctionId
をビーコン URL のクエリ パラメータとして設定します。 - コンバージョン イベントのオークション シグナルを関連付けるには、ビーコン URL に
auctionId
を設定します。
- 広告フレーム イベントのオークション シグナルを関連付けるには、
- 広告のレンダリング時に、オークション時に登録したビーコンをイベント単位のデータでトリガーまたは拡張できます。
reportEvent()
でフレーム イベントをトリガーし、イベントレベルのデータを渡します。setReportEventDataForAutomaticBeacons()
を使用してイベントレベルのペイロードをアトリビューション ビーコンに追加するAttribution-Reporting-Register-Source
ヘッダーで広告ビーコン リクエストに応答して、Attribution Reporting API に広告を登録します。
- コンバージョンの期間中に、オークション時に登録した参照元を表示できます。
上記の手順を終えると、購入者はオークション レポート、エンゲージメント レポート、コンバージョン レポートを取得できるようになります。これらのレポートはすべて、互いに関連付け可能な 1 つの一意のキーで結び付けられます。
販売者がアトリビューション データにアクセスする必要がある場合、同様のワークフローが販売者に適用されます。販売者は一意の 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)
を含むオークションの勝敗イベントによってトリガーされると、オークション結果を集計することもできます。
Private Aggregation は、寄付のバケットと価値を計算できるベース値のリストを提供します。オークション結果に使用できる基本値は、落札した広告の入札単価、2 番目に高いスコアの入札単価、入札がオークションで拒否された理由です。
落札単価などの基本値を指定すると、その値に加算または減算する値を設定し、最終的な値をレポートできます。たとえば、落札単価が 500 円の場合、入札単価の 200 円を差し引くと、落札できなかった額として実際に 300 円となります。
オークション結果レポート
オークションで負けた例を見てみましょう。入札価格とオークション決済価格の差額を把握したいとします。
オークションで落札できなかった金額を確認するには、落札単価から入札単価を差し引きます。
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 があります。共有ストレージの値は、ワークレット内からのみ読み取ることができます。また、ワークレットからプライベート集計を使用して、それらの値をレポートできます。
Protected Audience API の入札、スコアリング、レポートのワークレットから共有ストレージに書き込むこともできます。後で、プライベート アグリゲーションを使用して、共有ストレージ内のこれらの値をサーバーに報告できます。保存された値は、URL の選択操作でも使用できます。
Protected Audience API ワークレットから、任意のキーと値を共有ストレージに書き込むことができます。
// 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 を構築するために、Google は皆様との対話を通じてしたいと考えています。
API についてディスカッションする
他のプライバシー サンドボックス API と同様に、この API はドキュメント化され、一般公開されているです。
API を試す
Protected Audience API に関する会話をテストして参加できます。