共有ストレージとプライベート集計の実装のクイックスタート

このドキュメントは、共有ストレージとプライベート集約を使用するためのクイックスタート ガイドです。共有ストレージは値を保存し、Private Aggregation は集計可能なレポートを作成するため、両方の API を理解する必要があります。

対象者: 広告テクノロジーと測定プロバイダ。

Shared Storage API

クロスサイト トラッキングを防止するため、ブラウザはローカル ストレージや Cookie など、あらゆる形式のストレージをパーティショニングするようになりました。ただし パーティション分割されていない ストレージが必要なユースケースもありますShared Storage API は、さまざまな最上位サイト間で無制限の書き込みアクセス権を提供し、プライバシーに配慮した読み取りアクセス権を提供します。

共有ストレージは、コンテキスト オリジン（sharedStorage の呼び出し元）に限定されます。

共有ストレージには送信元ごとの容量上限があり、各エントリには上限の文字数があります。上限に達すると、それ以上の入力は保存されません。データ ストレージの上限については、共有ストレージの説明をご覧ください。

共有ストレージの呼び出し

広告テクノロジーは、JavaScript またはレスポンス ヘッダーを使用して共有ストレージに書き込むことができます。共有ストレージからの読み取りは、ワークレットと呼ばれる分離された JavaScript 環境内でのみ行われます。

ワークレットを使用すると、特定の JavaScript 関数を実行し、リクエスト元に情報を返すことができます。ワークレット内では JavaScript は実行できますが、外部ページとのやり取りや通信はできません。

ワークレットは、Shared Storage API でデータを保存、抽出するために使用されます。

• JavaScript を使用: 広告テクノロジーは、JavaScript ワークレットの外部で値の設定、追加、削除など、特定の共有ストレージ機能を実行できます。ただし、共有ストレージの読み取りや非公開集計の実行などの関数は、JavaScript ワークレットで完了する必要があります。JavaScript ワークレットの外部で使用できるメソッドについては、提案されている API サーフェス - ワークレットの外部をご覧ください。

  オペレーション中にワークレットで使用されるメソッドについては、提案されている API サーフェス - ワークレット内をご覧ください。

• レスポンス ヘッダーを使用する

  JavaScript と同様に、レスポンス ヘッダーを使用して実行できるのは、共有ストレージの値の設定、追加、削除など、特定の機能のみです。レスポンス ヘッダーで共有ストレージを操作するには、Shared-Storage-Writable: ?1 をリクエスト ヘッダーに含める必要があります。

  クライアントからリクエストを開始するには、選択した方法に応じて次のコードを実行します。

  • fetch() の使用

    fetch("https://a.example/path/for/updates", {sharedStorageWritable: true});
    

  • iframe タグまたは img タグの使用

    <iframe src="https://a.example/path/for/updates" sharedstoragewritable></iframe>
    

  • iframe タグまたは img タグで IDL 属性を使用する

    let iframe = document.getElementById("my-iframe");
    iframe.sharedStorageWritable = true;
    iframe.src = "https://a.example/path/for/updates";
    

詳細については、共有ストレージ: レスポンス ヘッダーをご覧ください。

共有ストレージへの書き込み

共有ストレージに書き込むには、JavaScript ワークレットの内外から sharedStorage.set() を呼び出します。ワークレットの外部から呼び出された場合は、呼び出し元のブラウジング コンテキストのオリジンにデータが書き込まれます。ワークレット内から呼び出された場合は、ワークレットを読み込んだブラウジング コンテキストのオリジンにデータが書き込まれます。設定された鍵の有効期限は、最後の更新から 30 日です。

ignoreIfPresent フィールドは省略可能です。この鍵が存在し、true に設定されている場合、鍵がすでに存在する場合は更新されません。キーが更新されていなくても、キーの有効期限は set() 呼び出しから 30 日間更新されます。

同じページの読み込みで同じキーを使用して共有ストレージに複数回アクセスすると、キーの値が上書きされます。キーで以前の値を保持する必要がある場合は、sharedStorage.append() を使用することをおすすめします。

• JavaScript を使用している場合

  ワークレットの外部:

  window.sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: true });
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.set('myKey', 'myValue2', { ignoreIfPresent: false });
  // Shared Storage: {'myKey': 'myValue2'}
  

  同様に、ワークレット内では次のようにします。

  sharedStorage.set('myKey', 'myValue1', { ignoreIfPresent: true });
  

• レスポンス ヘッダーの使用

  レスポンス ヘッダーを使用して共有ストレージに書き込むこともできます。これを行うには、レスポンス ヘッダーで、次のコマンドとともに Shared-Storage-Write を使用します。

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present
  

  Shared-Storage-Write : set;key="myKey";value="myValue";ignore_if_present=?0
  

  複数のアイテムをカンマ区切りで指定できます。また、set、append、delete、clear を組み合わせることもできます。

  Shared-Storage-Write :
  set;key="hello";value="world";ignore_if_present, set;key="good";value="bye"
  

値を追加する

既存のキーに値を追加するには、append メソッドを使用します。キーが存在しない場合、append() を呼び出すとキーが作成され、値が設定されます。これは、JavaScript またはレスポンス ヘッダーを使用して実現できます。

• JavaScript を使用している場合

  既存のキーの値を更新するには、ワークレットの内外で sharedStorage.append() を使用します。

  window.sharedStorage.append('myKey', 'myValue1');
  // Shared Storage: {'myKey': 'myValue1'}
  window.sharedStorage.append('myKey', 'myValue2');
  // Shared Storage: {'myKey': 'myValue1myValue2'}
  window.sharedStorage.append('anotherKey', 'hello');
  // Shared Storage: {'myKey': 'myValue1myValue2', 'anotherKey': 'hello'}
  

  ワークレット内に追加するには:

  sharedStorage.append('myKey', 'myValue1');
  

• レスポンス ヘッダーの使用

  共有ストレージで値を設定する方法と同様に、レスポンス ヘッダーの Shared-Storage-Write を使用して Key-Value ペアを渡すことができます。

  Shared-Storage-Write : append;key="myKey";value="myValue2"
  

共有ストレージからの読み取り

共有ストレージから読み取ることができるのは、ワークレット内からのみです。

await sharedStorage.get('mykey');

ワークレット モジュールが読み込まれたブラウジング コンテキストのオリジンによって、どの共有ストレージが読み取られるかが決まります。

共有ストレージからの削除

共有ストレージからの削除は、ワークレットの内外から JavaScript を使用して行うことができます。また、delete() を使用してレスポンス ヘッダーを使用することもできます。すべてのキーを一度に削除するには、どちらかで clear() を使用します。

• JavaScript を使用している場合

  ワークレットの外部から共有ストレージから削除するには:

  window.sharedStorage.delete('myKey');
  

  ワークレット内から共有ストレージから削除するには:

  sharedStorage.delete('myKey');
  

  ワークレットの外部からすべてのキーを一度に削除するには:

  window.sharedStorage.clear();
  

  ワークレット内からすべてのキーを一度に削除するには:

  sharedStorage.clear();
  

• レスポンス ヘッダーの使用

  レスポンス ヘッダーを使用して値を削除するには、レスポンス ヘッダーで Shared-Storage-Write を使用して、削除するキーを渡すこともできます。

  delete;key="myKey"
  

  レスポンス ヘッダーを使用してすべてのキーを削除するには:

  clear;
  

コンテキストの切り替え

共有ストレージのデータは、呼び出しの発信元となったブラウジング コンテキストのオリジン（https://example.adtech.com など）に書き込まれます。

<script> タグを使用してサードパーティのコードを読み込むと、そのコードは埋め込みのブラウジング コンテキストで実行されます。したがって、サードパーティ コードが sharedStorage.set() を呼び出すと、データは埋め込み元の共有ストレージに書き込まれます。iframe 内にサードパーティ コードを読み込むと、コードは新しいブラウジング コンテキストを受け取ります。そのオリジンは iframe のオリジンです。そのため、iframe から sharedStorage.set() 呼び出しが行われると、iframe オリジンの共有ストレージにデータが保存されます。

ファーストパーティ コンテキスト

ファーストパーティ ページに sharedStorage.set() または sharedStorage.delete() を呼び出すサードパーティの JavaScript コードが埋め込まれている場合、Key-Value ペアはファーストパーティ コンテキストに保存されます。

サードパーティのコンテキスト

Key-Value ペアを広告テクノロジーまたはサードパーティのコンテキストに保存するには、iframe を作成し、iframe 内から JavaScript コードで set() または delete() を呼び出します。

Private Aggregation API

共有ストレージに保存されている集計可能なデータを測定するには、Private Aggregation API を使用します。

レポートを作成するには、バケットと値を指定してワークレット内で contributeToHistogram() を呼び出します。バケットは符号なし 128 ビット整数で表され、BigInt として関数に渡す必要があります。値は正の整数です。

プライバシーを保護するため、バケットと値を含むレポートのペイロードは転送中に暗号化されます。このペイロードを復号して集計できるのは、集計サービスを使用する場合のみです。

また、ブラウザは、サイトが出力クエリに提供できる貢献度も制限します。具体的には、コントリビューションの予算により、特定のブラウザで特定の期間にすべてのバケットを対象に行われた、1 つのサイトからのすべてのレポートの合計が制限されます。現在の予算を超えている場合、レポートは生成されません。

privateAggregation.contributeToHistogram({
  bucket: BigInt(myBucket),
  value: parseInt(myBucketValue)
});

共有ストレージとプライベート アグリゲーションの実行

共有ストレージからデータにアクセスするには、ワークレットを作成する必要があります。これを行うには、ワークレットの URL を指定して createWorklet() を呼び出します。デフォルトでは、createWorklet() で共有ストレージを使用する場合、データ パーティションの起点は、ワークレット スクリプト自体の起点ではなく、呼び出し元のブラウジング コンテキストの起点になります。

デフォルトの動作を変更するには、createWorklet を呼び出すときに dataOrigin プロパティを設定します。

• dataOrigin: "context-origin": （デフォルト）データは、呼び出し元のブラウジング コンテキストのオリジンの共有ストレージに保存されます。
• dataOrigin: "script-origin": データは、ワークレット スクリプトの元の共有ストレージに保存されます。このモードを有効にするには、オプトインする必要があります。

sharedStorage.createWorklet(scriptUrl, {dataOrigin: "script-origin"});

オプトインするには、"script-origin" を使用するときに、スクリプト エンドポイントがヘッダー Shared-Storage-Cross-Origin-Worklet-Allowed で応答する必要があります。クロスオリジン リクエストでは CORS を有効にする必要があります。

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

M130 で、createWorklet() で dataOrigin を設定し、addModule() でクロスオリジン ワークレットを作成できるようになりました。

クロスオリジン iframe の使用

共有ストレージ ワークレットを呼び出すには iframe が必要です。

広告の iframe で、addModule() を呼び出してワークレット モジュールを読み込みます。sharedStorageWorklet.js ワークレット ファイルに登録されているメソッドを実行するには、同じ広告 iframe JavaScript で sharedStorage.run() を呼び出します。

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.run('shared-storage-report', {
  data: { campaignId: '1234' },
});

ワークレット スクリプトでは、非同期の run メソッドを持つクラスを作成し、register して広告の iframe で実行する必要があります。sharedStorageWorklet.js 内:

class SharedStorageReportOperation {
  async run(data) {
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

クロスオリジン リクエストの使用

共有ストレージと非公開集計を使用すると、クロスオリジン iframe を使用せずにクロスオリジン ワークレットを作成できます。

ファーストパーティ ページは、クロスオリジン JavaScript エンドポイントへの createWorklet() 呼び出しを呼び出すこともできます。ワークレットを作成するときに、ワークレットのデータ パーティションのオリジンをスクリプト オリジンに設定する必要があります。

async function crossOriginCall() {
  const privateAggregationWorklet = await sharedStorage.createWorklet(
    'https://cross-origin.example/js/worklet.js',
    { dataOrigin: 'script-origin' }
  );
  await privateAggregationWorklet.run('pa-worklet');
}
crossOriginCall();

クロスオリジン JavaScript エンドポイントは、ヘッダー Shared-Storage-Cross-Origin-Worklet-Allowed を返す必要があります。また、リクエストで CORS が有効になっていることに注意してください。

Shared-Storage-Cross-Origin-Worklet-Allowed : ?1

createWorklet() を使用して作成されたワークレットには、selectURL と run() が含まれます。addModule() はこれに使用できません。

注: addModule() を使用して、クロスオリジン ワークレットを作成できます。ただし、クロスオリジンのデータ パーティションを作成でき、addModule() とは異なり、複数のワークレットを作成できるため、createWorklet() を使用することをおすすめします。

class CrossOriginWorklet {
  async run(data){
    // Other code goes here.
    bucket = getBucket(...);
    value = getValue(...);
    privateAggregation.contributeToHistogram({
      bucket,
      value
    });
  }
}

次のステップ

以降のページでは、Shared Storage API と Private Aggregation API の重要な側面について説明します。

• 共有ストレージの概要（デベロッパー向け Chrome）
• 共有ストレージのユースケース（デベロッパー向け Chrome）
• 限定公開集計の概要（デベロッパー向け Chrome）
• 共有ストレージの説明（GitHub）
• 非公開集計の説明（GitHub）
• 共有ストレージと限定公開集計のデモ

API に慣れたら、レポートの収集を開始できます。レポートは、リクエスト本文の JSON として次のエンドポイントに POST リクエストとして送信されます。

• デバッグ レポート - context-origin/.well-known/private-aggregation/debug/report-shared-storage
• レポート - context-origin/.well-known/private-aggregation/report-shared-storage

レポートが収集されたら、ローカルテストツールを使用してテストするか、集計サービス用の高信頼実行環境を設定して集計レポートを取得できます。

フィードバックをお寄せください

GitHub の API やドキュメントに関するフィードバックを送信できます。

• 共有ストレージ
• Private Aggregation