Private Aggregation API の概要

Protected Audience のデータと共有ストレージのクロスサイト データを使用して、集計データ レポートを生成します。

ウェブが依存している重要な機能を提供するために、Private Aggregation は クロスサイト データを集約してレポートするための API が、 保護する方法も学びました。

実装ステータス

建议 状态
通过共享存储空间的报告验证防止无效的 Private Aggregation API 报告
说明者
适用于 Chrome
不公开汇总调试模式的可用性取决于第三方 Cookie 的使用资格
GitHub 问题
适用于 Chrome M119
缩短报告延迟时间
解说
适用于 Chrome M119
支持适用于 Google Cloud 的 Private Aggregation API 和汇总服务
解说
适用于 Chrome M121
可汇总报告载荷的内边距
解说
适用于 Chrome M119
不公开汇总调试模式可用于 AuctionReportBuyers 报告使用
解说
预计会在 Chrome M123 中提供
支持过滤 ID
解说
预计会在 Chrome M128 中提供

Private Aggregation API とは

Private Aggregation API により、デベロッパーは集計データレポートを生成できる Protected Audience API のデータを使用する 共有ストレージからのクロスサイト データ。

この API では現在、contributeToHistogram() という 1 つのオペレーションが提供されていますが、その他のオペレーションが 今後サポートされなくなります。ヒストグラム オペレーションを使用すると、 (API では集計キーと呼ばれます)。 ヒストグラムの呼び出しでは値が累積され、ノイズを加えた集計結果が 概要レポートも作成できます。たとえば、レポートに閲覧された回数が 各ユーザーがコンテンツを見たことがあるサイトや、サードパーティのスクリプトでバグに遭遇したサイトの数。このオペレーションは、別の API のワークレット内で実行されます。

たとえば、これまでに共有ストレージにユーザー属性データと地理データを記録したことがある場合は、Private Aggregation API を使用して、クロスサイトでコンテンツを見たニューヨーク市のおおよそのユーザー数を示すヒストグラムを Private Aggregation API で作成できます。この測定を集計するには、GEOGRAPHY ディメンションを集計キーにエンコードし、集計可能な値でユーザーをカウントします。

主なコンセプト

集計キーと集計可能値を指定して Private Aggregation API を呼び出すと、ブラウザによって集計可能レポートが生成されます。

集計可能レポートは、収集とバッチ処理のためにサーバーに送信されます。一括処理されたレポートは、後で集計サービスによって処理され、概要レポートが生成されます。

Private Aggregation API に関連する主なコンセプトの詳細については、Private Aggregation API の基礎のドキュメントをご覧ください。

Attribution Reporting との違い

Private Aggregation API には、Attribution Reporting API と多くの類似点があります。Attribution Reporting はコンバージョンを測定するために設計されたスタンドアロン API であるのに対し、Private Aggregation は Protected Audience API や Shared Storage などの API と組み合わせてクロスサイト測定向けに構築されています。どちらの API も、集計可能レポートを生成します。集計サービスは、バックエンドが集計レポートを生成する際に使用します。

アトリビューション レポートでは、異なるタイミングで発生するインプレッション イベントとコンバージョン イベントから収集されたデータが関連付けられます。プライベート アグリゲーションでは、単一のクロスサイト イベントを測定します。

この API をテストする

Private Aggregation API をローカルでテストするには、chrome://settings/adPrivacy ですべての Ad privacy API を有効にします。

テストについて詳しくは、テストと参加方法をご覧ください。

デモを使用する

共有ストレージ用の Private Aggregation API のデモは goo.gle/shared-storage-demo からアクセスできます。コードは GitHub で入手できます。このデモでは、クライアントサイドのオペレーションを実装し、サーバーに送信される集計レポートを生成します。

Protected Audience API 向けの Private Aggregation API のデモは今後公開される予定です。

ユースケース

Private Aggregation はクロスサイト測定用の汎用 API で、Shared Storage ワークレットと Protected Audience API ワークレットで使用できます。最初のステップは、収集したい情報を具体的に決定することです。これらのデータポイントが集計キーのベースとなります。

共有ストレージ付き

Shared Storage を使用すると、安全な環境でクロスサイト データの読み取りと書き込みを行い、漏洩を防ぐことができます。また、Private Aggregation API を使用すると、共有ストレージに保存されているクロスサイト データを測定できます。

ユニークリーチ測定

コンテンツを見たユニーク ユーザーの数を測定したい場合もあるでしょう。Private Aggregation API では、「約 317 のユニーク ユーザーが Content ID 861 を視聴しました」といった回答が得られます。

共有ストレージにフラグを設定して、ユーザーがコンテンツをすでに見たかどうかを示すことができます。フラグが存在しない最初のアクセスでは、Private Aggregation が呼び出され、フラグが設定されます。ユーザーによるその後の訪問(クロスサイト訪問を含む)では、[共有ストレージ] をオンにし、フラグが設定されている場合はプライベート アグリゲーションへのレポートの送信をスキップできます。こうした測定を実施する方法について詳しくは、リーチに関するホワイトペーパーをご覧ください。

ユーザー属性の測定

さまざまなサイトでコンテンツを見たユーザーのユーザー属性を測定するとよいでしょう。

プライベート アグリゲーションでは、「約 317 人のユニーク ユーザーが 18 ~ 45 歳のドイツ出身のユーザー」といった答えが得られます。共有ストレージを使用して、サードパーティのコンテキストからユーザー属性データにアクセスします。後で、集計キーで年齢層と国のディメンションをエンコードすることで、非公開集計を含むレポートを生成できます。

K+ 周波数測定

特定のブラウザでコンテンツまたは広告を K 回以上表示したユーザーの数を、事前に選択された値 K で測定することをおすすめします。

非公開集計では、「約 89 人のユーザーが Content ID 581 を 3 回以上見たことがあります」といった回答が得られます。カウンタは、共有ストレージでさまざまなサイトからインクリメントでき、ワークレット内で読み取ることができます。数が K に達すると、Private Aggregation を使用してレポートを送信できます。

Protected Audience API

Protected Audience API では、リターゲティングとカスタム オーディエンスのユースケースが可能で、Private Aggregation では、購入者と販売者のワークレットからのイベントに関するレポートを作成できます。この API は、オークション入札の配分の測定などのタスクに使用できます。

Protected Audience API ワークレットから、contributeToHistogram() を使用してデータを直接集計し、contributeToHistogramOnEvent()(Protected Audience API の特別な拡張機能)を使用するトリガーに基づいてデータを報告できます。

使用可能な関数

共有ストレージと Protected Audience API のワークレットで利用可能な privateAggregation オブジェクトでは、以下の関数を使用できます。

contributeToHistogram()

privateAggregation.contributeToHistogram({ bucket: <bucket>, value: <value> }) を呼び出すことができます。ここで、集計キーは bucket、集計値は value です。bucket パラメータには BigInt が必要です。value パラメータには整数の番号が必要です。

リーチ測定のために共有ストレージで呼び出す方法の例を次に示します。

iframe.js

// Cross-site iframe code

async function measureReach() {
 // Register worklet
 await window.sharedStorage.worklet.addModule('worklet.js');

 // Run reach measurement operation
 await window.sharedStorage.run('reach-measurement', { 
  data: { contentId: '1234' } 
 });
}

measureReach();

worklet.js

// Shared storage worklet code

function convertContentIdToBucket(campaignId){ 
  // Generate aggregation key
}

// The scale factor is multiplied by the aggregatable value to
// maximize the signal-to-noise ratio. See "Noise and scaling" 
// section in the Aggregation Fundamentals document to learn more.
const SCALE_FACTOR = 65536;

class ReachMeasurementOperation {
  async run(data) {
    const key = 'has-reported-content';
    // Read the flag from Shared Storage
    const hasReportedContent = await this.sharedStorage.get(key) === 'true';

    // Do not send report if the flag is set
    if (hasReportedContent) {
      return;
    }

    // Send histogram report
    // Set the aggregation key in `bucket`
    // Bucket examples: 54153254n or BigInt(54153254)
    // Set the scaled aggregatable value in `value`
    privateAggregation.contributeToHistogram({
      bucket: convertContentIdToBucket(data.contentId), 
      value: 1 * SCALE_FACTOR 
    });

    // Set the flag in Shared Storage
    await this.sharedStorage.set(key, true);
  }
}

register('reach-measurement', ReachMeasurementOperation);

上記のコード例では、クロスサイト iframe コンテンツが読み込まれるたびに Private Aggregation を呼び出します。iframe コードがワークレットを読み込み、ワークレットはコンテンツ ID を集計キー(バケット)に変換して Private Aggregation API を呼び出します。

contributeToHistogramOnEvent()

Protected Audience API ワークレット内でのみ、特定のイベントが発生した場合にのみレポートを送信するトリガーベースのメカニズムを提供しています。この機能により、オークションのその時点でまだ利用できないシグナルに基づいてバケットと値を設定することも可能です。

privateAggregation.contributeToHistogramOnEvent(eventType, contribution) メソッドは、トリガーとなるイベントを指定する eventType と、イベントがトリガーされたときに送信される contribution を受け取ります。トリガー イベントは、オークションの落札 / 損失イベントなど、オークション終了後のオークション自体で発生する場合と、広告を表示したフェンス付きフレームから発生する場合があります。 オークション イベントのレポートを送信するには、reserved.winreserved.lossreserved.always の 2 つの予約済みキーワードを使用します。フェンス付きフレームからのイベントによってトリガーされたレポートを送信するには、カスタム イベントタイプを定義します。フェンス付きフレームからイベントをトリガーするには、Fenced Frames Ads Reporting API で利用可能な fence.reportEvent() メソッドを使用します。

次の例では、オークションでの勝利イベントがトリガーされたときにインプレッション レポートを送信し、広告を表示したフェンス付きフレームから click イベントがトリガーされるとクリック レポートを送信します。この 2 つの値を使用して、クリック率を計算できます。

function generateBid(interestGroup, auctionSignals, perBuyerSignals, trustedBiddingSignals, browserSignals) {
  // …
  privateAggregation.contributeToHistogramOnEvent("reserved.win", {
      bucket: getImpressionReportBucket(),
      value: 1
  });
  privateAggregation.contributeToHistogramOnEvent("click", {
      bucket: getClickReportBuckets(), // 128-bit integer as BigInt
      value: 1
  });

詳しくは、拡張プライベート アグリゲーション レポートの説明をご覧ください。

enableDebugMode()

サードパーティ Cookie は引き続き利用できますが、デバッグモードを有効にすることで、デバッグとテストを容易にする一時的なメカニズムが提供されます。デバッグ レポートは、Cookie ベースの測定値とプライベート アグリゲーションの測定値を比較するのに役立ち、API の統合をすばやく検証することもできます。

ワークレットで privateAggregation.enableDebugMode() を呼び出すと、デバッグモードが有効になり、集計可能レポートに暗号化されていない(クリアテキスト)ペイロードが含まれるようになります。これらのペイロードは、集計サービスのローカル テストツールで処理できます。

デバッグモードは、アクセスを許可されている呼び出し元のみが使用できます。 制限します。呼び出し元にサードパーティ Cookie へのアクセス権がない場合は、 enableDebugMode() は通知なく失敗します。つまり第三者が Cookie のサポートが終了すると、デバッグモードは利用できなくなります。

privateAggregation.enableDebugMode({ <debugKey: debugKey> }) を呼び出してデバッグキーを設定することもできます。この場合、BigInt をデバッグキーとして使用できます。デバッグキーを使用して、Cookie ベースの測定のデータとプライベート アグリゲーションの測定のデータを関連付けることができます。

これらはコンテキストごとに 1 回だけ呼び出すことができます。それ以降の呼び出しでは例外がスローされます。

// Enables debug mode
privateAggregation.enableDebugMode();

// Enables debug mode and sets a debug key
privateAggregation.enableDebugMode({ debugKey: BigInt(1234) });

確認を報告

共有ストレージの場合、受信した集計可能レポートが正当であることを確認するには、共有ストレージ オペレーションの呼び出しにコンテキスト ID を追加します。この ID は、送信されたレポートに添付されます。後でその ID を使用して、レポートが共有ストレージ オペレーションから送信されたものであることを確認できます。

この機能は Chrome M114 以降でテストできます。Protected Audience API のレポート検証は、まだテストに利用できません。

詳しくは、報告の検証についての説明をご覧ください。

対応してフィードバックを共有する

Private Aggregation API は現在検討中であり、将来変更される可能性があります。この API をお試しいただき、ご意見やご感想がございましたら、ぜひお聞かせください。