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

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

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

立即試用

歡迎體驗現場示範！請按照示範操作說明中的步驟啟用 Privacy Sandbox API。開啟 Chrome 開發人員工具，可協助您將不同用途的結果視覺化。用途 操作示範：

• 私人匯總資料
  • Unique Reach 評估
  • 客層評估
  • 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。

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

Shared Storage API

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

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

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

叫用共用儲存空間

廣告技術人員可以使用 JavaScript 或回應標頭寫入共用儲存空間。只能在獨立的 JavaScript 中讀取共用儲存空間的資料 稱為 Worklet

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

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

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

  您可以在「建議的 API 途徑 - 在 worklet 中」一節中，查看在作業期間在 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";
    

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

寫入共用儲存空間

如要寫入 Shared Storage，請從 JavaScript 工作區內或外呼叫 sharedStorage.set()。如果從工作程式外部呼叫，系統會將資料寫入 發出呼叫的瀏覽環境來源。如果不是透過 將資料寫入瀏覽背景的原始碼 載入了小程式所設定的金鑰到期日為 30 距離上次更新的天數。

ignoreIfPresent 為選填欄位。如果鍵已存在且已設為 true，則系統不會更新該鍵。金鑰到期日為 30 天，自 set() 呼叫。

如果在同一個網頁載入中使用相同的鍵多次存取共用儲存空間，系統會覆寫該鍵的值。建議你使用 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。方法是使用 回應標頭中的 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'}
  

  在 Worklet 中附加以下內容：

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

• 使用回應標頭

  與在 Shared Storage 中設定值類似，您可以在回應標頭中使用 Shared-Storage-Write 傳入鍵/值組合。

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

從共用儲存空間讀取

您只能在工作區中讀取共用儲存空間。

await sharedStorage.get('mykey');

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

從共用儲存空間刪除

您可以使用 JavaScript 從共用儲存空間中刪除 或在 Worklet 之外使用回應標頭搭配 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()，則會將資料寫入嵌入器的 Shared 儲存空間：當您在 iframe 中載入第三方程式碼時，程式碼會收到新的瀏覽內容，其來源為 iframe 的來源。因此，從 iframe 發出的 sharedStorage.set() 呼叫會將資料儲存至 iframe 來源的 Shared Storage。

第一方情境

如果第一方網頁嵌入了會呼叫的第三方 JavaScript 程式碼， sharedStorage.set() 或 sharedStorage.delete()，系統會儲存鍵/值組合 都一樣

第三方情境

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

私密匯總 API

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

如要建立報表，請在工作程式中呼叫 contributeToHistogram()，並加上 值區和值這個區塊會以不帶正負號的 128 位元整數表示，且必須以 BigInt 的形式傳遞至函式。值為正整數。

為保護隱私，報表酬載，其中包含值區和值； 且只有在傳輸過程中加密及匯總時，才能使用 匯總服務。

瀏覽器也會限制網站可對輸出查詢做出的貢獻。具體而言，使用者接受度 預算 限制某個瀏覽器在特定瀏覽器中從單一網站產生的所有報表總數 所有值區的指定時間範圍如果超出目前的預算， 不會產生報表

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

執行共用儲存空間和私密匯總

您必須建立工作物件，才能存取共用儲存空間中的資料。方法是呼叫 createWorklet() 為工作程式的網址。在預設情況下，當您使用共用項目時 儲存空間為 createWorklet()，資料分區來源會是叫用 瀏覽情境 而不是 Worklet 指令碼本身的來源

如要變更預設行為，請在呼叫 createWorklet 時設定 dataOrigin 屬性。

• dataOrigin: "context-origin"：(預設) 資料會儲存在叫用瀏覽內容的來源共用儲存空間中。
• dataOrigin: "script-origin"：資料會儲存在 Worklet 指令碼的來源。請注意，您必須選擇採用才能啟用這個模式。

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。在這些變更發布至穩定版之前，您可以透過指令列啟動 Canary M130 以上版本，並搭配 --enable-privacy-sandbox-ads-apis --disable-features=EnforcePrivacySandboxAttestations --enable-features=SharedStorageCrossOriginScript,SharedStorageCreateWorkletUseContextOriginByDefault 標記進行測試。如果您已使用 createWorklet()，並將指令碼來源設為 worklet 的資料分割區來源，則可以在發布前將 dataOrigin 設為「script-origin」，以確保與穩定版 M130 以上的相容性。

使用跨來源 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()。您必須設定資料分區來源 也就是建立 Worklet 時指令碼來源的樣子

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

偵錯

如要啟用偵錯功能，請在使用共用儲存空間和私人匯總功能的相同情境中呼叫 enableDebugMode() JavaScript 方法。這將是 以及用於日後的報表

privateAggregation.enableDebugMode();

如要將報表與觸發事件的情境建立關聯，您可以設定 64 位元無正負號整數偵錯金鑰，並傳遞至 JavaScript 呼叫。debugKey 是 BigInt。

privateAggregation.enableDebugMode({debugKey: 1234});

共用儲存空間偵錯

Shared Storage 會傳回一般錯誤訊息：

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_origin": "https://publickeyservice.msmt.gcp.privacysandboxservices.com",
   "aggregation_service_payloads": [ {
      "debug_cleartext_payload": "omRkYXRhlKJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAB1vNFaJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAKJldmFsdWVEAAAAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAAAGlvcGVyYXRpb25paGlzdG9ncmFt",
      "key_id": "1569ab37-da44-4a26-80d9-5ed6524ab2a7",
      "payload": "/9nHrWn1MnJWRxFvanbubciWE9mPyIij6uYLi5k351eQCd3/TZpe2knaatUNcniq4a4e61tmKebv50OmMRZFnnCfcAwIdIgLHu1a3en97PojqWJBfO52RiVMIcP7KQTLzMxq2LhvPSdV4zjXo1Teu/JuIK3LIyis3vUMpS+tUAX0QV+I6X5SVmZFiNW9aMb8DwLOtqrBy5JJ/EkOIY0G+1Fi1/3R7UtKsqM1o71A/OzdmlNkwO7EV/VUNinGvWnd19FvDHe/kqkNdTHKbhAnMmbZzHW9bsEQS81leElCla6BTdbdbeeFU/jbTj0AOaoNOIe5r7FU5NG6nW4ULXTCbLLjTQ1mtl3id3IP41Zin1JvABCDC/HUSgLFz8EUqkmbMIOlMfNYA79aURq6FqE0GO0HtICYf0GPNdVv7p4jY3FNn6+JS4l5F3t+3lP9ceo4IpCE+31jzMtYJ+19xFh6C5ufteBR/iknZFcc1w3caQBhgRl5jt8DbaOzYcW4690H8Ul4Oh2wRO+6/njifk+pExLay/O5swLi2lUUph5OUEaaztwwzh2mnhwIBxMkPnfsGihiF+5KDEajVfMZ3NLsIDoZO+l4RTZrkqE+jVkAqaZGBiCIx42Edp/JV0DXfrryypCdQBZr8iEbSzCM9hKsMfLN7S/VkPe5rDwOZbhKCn5XXgfGz5tSx/KbZgsQf4OCEhwAyNPHAh3MHU7xmkQ3pKg4EIUC/WOtKAlVDOtDMmPPoQY1eAwJhw9SxZaYF1kHjUkTm3EnGhgXgOwCRWqeboNenSFaCyp6DbFNI3+ImONMi2oswrrZO+54Tyhca5mnLIiInI+C3SlP4Sv1jFECIUdf/mifJRM5hMj6OChzHf4sEifjqtD4A30c4OzGexWarie2xakdQej9Go4Lm0GZEDBfcAdWLT9HwmpeI2u4HDAblXDvLN8jYFDOOtzOl90oU7AwdhkumUCFLRadXAccXW9SvLfDswRkXMffMJLFqkRKVE1GPonFFtlzaRqp7IgE8L6AOtz6NDcxAjHnEuzDPPMcWMl1AFH0gq7h"
   } ],
   "debug_key": "1234",
   "shared_info": "{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"80d93c0a-a94e-4ab7-aeb5-a4ecd4bfc598\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1717784740\",\"version\":\"0.1\"}"
}

偵錯明文酬載

debug_cleartext_payload 採用 CBOR 和 Base64 編碼。您可以查看值區 透過解碼器指定值 「共用儲存空間」中的 JavaScript 程式碼 解碼器

後續步驟

以下頁面說明「共用儲存空間」與「私人」的重要事項 匯總 API。

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

當您熟悉 API 後，即可開始收集報表 並以 POST 要求的形式傳送至下列端點 要求主體

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

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

提供意見

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

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