このページは Cloud Translation API によって翻訳されました。

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

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

ターゲットオーディエンス: 広告テクノロジーと測定プロバイダ。

デモを試す

ライブデモをお試しください。デモの手順に沿って、プライバシーサンドボックス API を有効にします。Chrome DevTools を開くと、さまざまなユースケースの結果を可視化できます。デモで使用可能なユースケース:

プライベートアグリゲーション
- ユニークリーチ測定
- ユーザー属性の測定
- K+ 周波数測定
一般的な使用方法
- フェンス付きフレーム内でのマウスオーバーイベントを測定する
- トップレベルナビゲーション
- サードパーティが書き込み可能な場所を制御する

共有ストレージを表示する方法

共有ストレージに保存されているデータを表示するには、Chrome DevTools を使用します。保存データは Application -> Shared Storage にあります。

非公開集計のレポートを表示

送信された集計可能レポートを表示するには、chrome://private-aggregation-internals に移動します。デバッグモードを有効にすると、[[YOUR_ORIGIN]]/.well-known/private-aggregation/debug/report-shared-storage に（遅延なく）レポートが送信され、遅延レポートも [[YOUR_ORIGIN]]/.well-known/private-aggregation/report-shared-storage に送信されます。

デバッグを有効にするには、デバッグセクションの手順を行います。

chrome://private-aggregate-internals でレポートを表示する

Shared Storage API

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

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

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

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

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

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

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

この機能は M119 で利用可能になりました。

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 ペアはファーストパーティのコンテキストに保存されます。

サードパーティの JavaScript が埋め込まれたファーストパーティのページに保存されたデータ。

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

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)
});

共有ストレージとプライベート集計の実行

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

await window.sharedStorage.worklet.addModule('modules/sharedStorageWorklet.js');
await window.sharedStorage.worklet.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: bucket,
      value: value
    });
  }
}
register('shared-storage-report',
  SharedStorageReportOperation);

デバッグ

デバッグを有効にするには、共有ストレージとプライベート集計を使用するコンテキストで enableDebugMode() JavaScript メソッドを呼び出します。これは、同じコンテキスト内の今後のレポートに適用されます。

privateAggregation.enableDebugMode();

レポートをトリガーしたコンテキストとレポートを関連付けるには、JavaScript 呼び出しに渡される 64 ビットの符号なし整数デバッグキーを設定します。debugKey が BigInt である。

privateAggregation.enableDebugMode({debugKey: 1234});

共有ストレージのデバッグ

共有ストレージから一般的なエラーメッセージが返されます。

Promise is rejected without and explicit error message

共有ストレージをデバッグするには、呼び出しを try-catch ブロックでラップします。

try {
  privateAggregation.contributeToHistogram({bucket, value});
} catch (e){
  console.log(e);
}

プライベート集計のデバッグ

レポートは /.well-known/private-aggregation/report-shared-storage と /.well-known/private-aggregation/debug/report-shared-storage に送信されます。デバッグレポートは、次の JSON のようなペイロードを受け取ります。このペイロードは、api フィールドを「shared-storage」として定義します。

{
   "aggregation_coordinator_identifier": "aws-cloud",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAEfV32BFWlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "9bc4afa7-2934-4779-99ff-999d91b137ec",
      "payload": "bqOFO/cHCdwefU2W4FjMYRMSLoGHPWwZbgVF4aa/ji2YtwFz+jb6v2XCwQUdmvYcZSRPKosGRpKELJ0xAFv+VBYvCiv3FXP6jjAHQD+XAJUz17A39aXijk6JnEAu86+DfTSbXYn1fWhGzIG9xH/Y"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"93f86829-cdf7-4ecd-b16d-4e415a3ee063\",\"reporting_origin\":\"https://small-free-wealth.glitch.me\",\"scheduled_report_time\":\"1681319668\",\"version\":\"0.1\"}"
}

クリアテキストペイロードをデバッグする

debug_cleartext_payload は Base64 CBOR でエンコードされています。デコーダを使用してバケットと値を表示するか、Shared Storage デコーダにある JavaScript コードを使用できます。

次のステップ

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

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

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

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

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

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