Private Aggregation API の概要

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

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

実装ステータス

Private Aggregation API とは

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

この API の主な機能は、contributeToHistogram() と呼ばれます。ヒストグラム オペレーションを使用すると、 （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 を使用してレポートを送信できます。

マルチタッチ アトリビューション

このガイダンスは、広告テクノロジーが共有ストレージ + プライベート アグリゲーション内に MTA を実装する方法を理解できるように、開発サイトで公開する予定です。

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 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 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.win、reserved.loss、reserved.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 を使用して、共有ストレージ オペレーションからレポートが送信されたことを確認できます。

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

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

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

• GitHub: 解説を読んだり、質問を投稿したり、ディスカッションに参加したりできます。
• デベロッパー サポート: プライバシー サンドボックス デベロッパー サポート リポジトリで、質問したり、ディスカッションに参加したりできます。
• Private Aggregation に関する最新情報を受け取るには、Shared Storage API グループと Protected Audience API グループにご参加ください。