實作共用儲存空間和私密匯總的快速入門導覽課程

本文件為快速入門指南，說明如何使用共用儲存空間和私人匯總功能。您必須瞭解這兩種 API，因為共用儲存空間會儲存值，而私人匯總會建立可匯總報表。

目標對象：廣告技術和評估服務供應商。

立即試用

體驗現場示範。請按照示範操作說明中的步驟啟用 Privacy Sandbox API。開啟 Chrome 開發人員工具，能夠以視覺化方式呈現不同用途的結果。示範中提供的用途：

• 私人匯總
  • 不重複觸及評估
  • 客層評估
  • K+ 頻率評估
• 一般用法
  • 測量圍欄頁框中的懸停事件
  • 頂層導覽
  • 控管第三方可撰寫內容的位置

如何查看共用儲存空間

如要查看共用儲存空間中儲存的內容，請使用 Chrome 開發人員工具。儲存的資料可在 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。

如要啟用偵錯功能，請按照偵錯一節中的指示操作。

共用儲存空間 API

為避免跨網站追蹤，瀏覽器已開始分割所有形式的儲存空間，包括本機儲存空間和 Cookie 等。但也在某些情況下需要使用未分區儲存空間。Shared Storage API 提供橫跨不同頂層網站的寫入權限，並具有隱私權保護的讀取權限。

共用儲存空間僅限背景資訊來源 (sharedStorage 的呼叫端)。

「共用儲存空間」有每個來源的容量限制，每個項目設有字元數上限。如果達到限制，系統就不會儲存其他輸入內容。如要瞭解資料儲存空間上限，請參閱共用儲存空間說明。

叫用共用儲存空間

廣告技術可以使用 JavaScript 或回應標頭，將資料寫入共用儲存空間。從共用儲存空間讀取資料只會在獨立的 JavaScript 環境 (稱為 Worklet) 內進行。

工作可讓您執行特定的 JavaScript 函式，並將資訊傳回要求者。在 Worklet 中，您可以執行 JavaScript，但無法與外部網頁互動或通訊。

工作程式可用來儲存及擷取 Shared Storage API 的資料。

• 使用 JavaScript 廣告技術可以執行特定的共用儲存空間函式，例如在 JavaScript 工作程式外設定、附加及刪除值。不過，讀取共用儲存空間和執行私人匯總等功能都必須透過 JavaScript 小程式完成。如要在 JavaScript Worklet 外使用的方法，請參閱「Proposed API Surface - Outside the tasklet」。

  想瞭解在作業期間於 Worklet 中使用的方法，請參閱「Proposed API Surface - In the worklet」。

• 使用回應標頭

  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 Worklet 內部或外部呼叫 sharedStorage.set()。如果從 Worklet 外部呼叫，資料會寫入發出呼叫的瀏覽結構定義的來源。如果從 Worklet 內部呼叫，資料就會寫入載入 Work 小程式的瀏覽結構定義來源。設定的金鑰到期日為上次更新後 30 天。

ignoreIfPresent 為選填欄位。如果金鑰存在且設為 true，則如果索引鍵已存在，則不會更新。即使金鑰尚未更新，金鑰到期日也會從 set() 呼叫起續約 30 天。

如果以相同鍵在相同網頁載入中多次存取 Shared Storage，該鍵的值會遭到覆寫。如果鍵需要保留先前的值，建議您使用 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'}
  

  同樣地，在 Worklet 中：

  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() 會建立鍵並設定值。您可以使用 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 傳入鍵/值組合。

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

從共用儲存空間讀取

您只能透過工作小程式從「共用儲存空間」讀取資料。

await sharedStorage.get('mykey');

載入 Worklet 模組的瀏覽情境來源會決定其共用儲存空間。

從共用儲存空間中刪除

您可以透過工作小程式內部或外部的 JavaScript 從共用儲存空間執行刪除作業，也可以使用回應標頭搭配 delete() 執行。如要一次刪除所有鍵，請在任一索引鍵中使用 clear()。

• 使用 JavaScript

  如何從工作小程式以外的共用儲存空間刪除：

  window.sharedStorage.delete('myKey');
  

  如何從工作小程式內刪除共用儲存空間：

  sharedStorage.delete('myKey');
  

  如何一次從 Worklet 外部刪除所有按鍵：

  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 程式碼，該鍵/值組合會儲存在第一方情境中。

第三方內容

建立 iframe 並從 iframe 內呼叫 JavaScript 程式碼中的 set() 或 delete()，即可將鍵/值組合儲存在廣告技術或第三方內容中。

私密匯總 API

如要測量儲存在共用儲存空間中的可匯總資料，您可以使用 Private Aggregation API。

如要建立報表，請在設定值區和值的小程式中呼叫 contributeToHistogram()。值區是以無正負號的 128 位元整數表示，該整數必須以 BigInt 的形式傳入函式。這個值是正整數。

為保護隱私權，報表的酬載 (含有值區和值) 在傳輸過程中會經過加密，而且只能使用匯總服務解密及匯總。

瀏覽器也會限制網站可對輸出查詢貢獻的內容。具體而言，貢獻預算會限制指定時間範圍內，單一網站在所有值區中產生的所有報表總數。如果超出目前預算，系統就不會產生報表。

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

執行共用儲存空間與私人匯總

在廣告的 iframe 中呼叫 addModule()，載入 Worklet 模組。如要執行在 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' },
});

在 Worklet 指令碼中，您需要使用非同步 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();

如要將報表與觸發報表的結構定義建立關聯，您可以設定 64 位元無正負號整數偵錯金鑰，再傳送至 JavaScript 呼叫。debugKey 為 BigInt。

privateAggregation.enableDebugMode({debugKey: 1234});

對共用儲存空間進行偵錯

共用儲存空間會傳回一般錯誤訊息：

Promise is rejected without and explicit error message

您可以利用 try-catch 區塊納入呼叫，藉此對 Shared Storage 進行偵錯。

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 程式碼。

後續步驟

以下頁面說明共用儲存空間和私人匯總 API 的重要層面。

• 共用儲存空間 (開發人員 Chrome) 簡介
• 共用儲存空間用途 (開發人員 Chrome)
• 私密匯總簡介 (開發人員 Chrome)
• 共用儲存空間說明 (GitHub)
• 私密匯總說明 (GitHub)
• 共用儲存空間與私人匯總示範

熟悉 API 後，即可開始收集報表，這些報表會以 POST 要求的形式，在要求主體中以 JSON 格式傳送至下列端點。

• 偵錯報表 - context-origin/.well-known/private-aggregation/debug/report-shared-storage
• 報表 - context-origin/.well-known/private-aggregation/report-shared-storage

收集報表後，您可以使用本機測試工具進行測試，或設定匯總服務的受信任執行環境取得匯總報表。

提供意見

我們可以針對 GitHub 的 API 和說明文件提供意見。

• 共用儲存空間
• 私人匯總