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

本文件是使用共用儲存空間與私人匯總功能的快速入門指南。您必須瞭解這兩個 API，因為 Shared Storage 會儲存值，而 Private Aggregation 會建立可匯總的報表。

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

Shared Storage API

為了防止跨網站追蹤，瀏覽器已開始分割所有形式的儲存空間，包括本機儲存空間、Cookie 等。但有些用途需要使用未分割的儲存空間。Shared Storage API 可在不同頂層網站之間提供無限的寫入存取權，並保留隱私權保護的讀取存取權。

共用儲存空間僅限於內容來源 (sharedStorage 的呼叫端)。

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

叫用共用儲存空間

廣告技術人員可以使用 JavaScript 或回應標頭寫入共用儲存空間。只有在名為 worklet 的隔離 JavaScript 環境中，才會讀取共用儲存空間。

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

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

• 使用 JavaScript 廣告技術可執行特定的共用儲存空間函式，例如在 JavaScript 工作區外設定、附加及刪除值。不過，讀取共用儲存空間和執行私人匯總等函式必須透過 JavaScript 工作區完成。如要瞭解可在 JavaScript 工作區外使用的各項方法，請參閱「建議的 API 途徑 - 工作區外」。

  您可在「Proposed API Surface - In theworklet」中找到作業期間用於 Worklet 的方法。

• 使用回應標頭

  與 JavaScript 類似，只有特定函式 (例如在 Shared Storage 中設定、附加和刪除值) 才能使用回應標頭執行。如要在回應標頭中使用 Shared Storage，您必須在要求標頭中加入 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>
    

  • 使用 IDL 屬性搭配 iframe 或 img 標記

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

詳情請參閱「共用儲存空間：回應標頭」。

寫入共用儲存空間

如要寫入 Shared Storage，請從 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() 會建立鍵並設定值。這可以使用 JavaScript 或回應標頭完成。

• 使用 JavaScript

  如要更新現有鍵的值，請使用 Worklet 內部或外部的 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');

載入工作模組的瀏覽內容來源會決定要讀取哪個共用儲存空間。

從共用儲存空間刪除

您可以使用 JavaScript 從工作單元內部或外部，或使用含有 delete() 的回應標頭，從 Shared Storage 執行刪除作業。如要一次刪除所有鍵，請使用任一鍵的 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() 時，系統會將資料寫入嵌入者的 Shared Storage。在 iframe 中載入第三方程式碼時，程式碼會收到新的瀏覽內容，而其來源是 iframe 的來源。因此，從 iframe 發出的 sharedStorage.set() 呼叫會將資料儲存至 iframe 來源的 Shared Storage。

第一方情境

如果第一方頁面嵌入了呼叫 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)
});

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

您必須建立工作物件，才能存取共用儲存空間中的資料。方法是使用 Worklet 的網址呼叫 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()` 建立跨原點 Worklet。

使用跨來源 iframe

您需要使用 iframe 才能叫用共用儲存空間小程式。

在廣告的 iframe 中，呼叫 addModule() 以載入 worklet 模組。如要在同一個廣告 iframe JavaScript 中，執行 sharedStorageWorklet.js 工作區塊檔案中註冊的方法，請呼叫 sharedStorage.run()。

const sharedStorageWorklet = await window.sharedStorage.createWorklet(
  'https://any-origin.example/modules/sharedStorageWorklet.js'
);
await sharedStorageWorklet.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,
      value
    });
  }
}
register('shared-storage-report', SharedStorageReportOperation);

使用跨來源要求

共用儲存空間與私人匯總功能可讓您建立跨來源 Worklet，而不需要跨來源 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() 可用於建立跨來源的 worklet。不過，建議您使用 createWorklet()，因為這樣就能建立跨來源資料分區，並且建立多個和 addModule() 不同的工作程式。

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 後，就可以開始收集報表。報表會以 POST 要求的形式，在要求主體中以 JSON 格式傳送至下列端點。

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

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

提供意見

歡迎在 GitHub 上分享您對 API 和說明文件的意見。

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