共享儲存 API

可用性有限

此特性不是基線特性，因為它在一些最廣泛使用的瀏覽器中不起作用。

實驗性： 這是一項實驗性技術
在生產中使用此技術之前，請仔細檢查瀏覽器相容性表格。

警告： 此功能目前遭到一家瀏覽器廠商的反對。詳見下方的標準立場部分。

共享儲存 API 是一種客戶端儲存機制，它支援未分割槽、跨站的資料訪問，同時保護隱私（即不依賴跟蹤 Cookie）。

概念與用法

Web 上隱私和安全問題的一個主要來源是使用在網站中嵌入的第三方內容上設定的 Cookie（例如透過<iframe>元素）。這些 Cookie 可用於跟蹤和分析使用者，並在網站之間共享資訊。

為了防止跨站跟蹤，瀏覽器正在努力分割槽所有儲存型別，包括Cookie、Web 儲存、IndexedDB和Cache API。然而，實現這一目標的一個主要障礙是存在一些合法的用例，它們依賴於跨站資訊共享。此類用例的示例包括廣告商希望衡量其廣告在網站上的覆蓋範圍並生成報告，以及網站所有者希望根據使用者所屬的群組或其之前的網站互動來定製使用者體驗。

共享儲存 API 為此類用例提供了靈活的解決方案。它旨在提供所需的資料儲存、處理和共享功能，同時不具備跟蹤和分析使用者的功能。

與其他儲存 API 一樣，您可以隨時寫入共享儲存。但是，您只能在 worklet 中讀取共享儲存資料。Worklet 提供了一個安全的環境，您可以在其中處理共享儲存資料並返回有用的結果，但您無法將資料直接共享給關聯的瀏覽上下文。

要從共享儲存 worklet 中提取有用的結果，您需要使用輸出門。這些門具有特定的用途，例如根據共享儲存資料從提供的列表中選擇一個 URL 顯示給使用者。面向使用者的結果會安全地顯示在圍欄框架中，並且無法從嵌入頁面訪問。

輸出門

共享儲存 API 當前可用的輸出門將在以下部分中討論。在每個部分中，我們列出了每個門的典型用例，並提供了包含更多資訊和程式碼示例的指南連結。

注意： 未來可能會新增更多輸出門以支援其他用例。

URL 選擇

URL 選擇輸出門透過selectURL()方法訪問，用於根據共享儲存資料，從提供的列表中選擇一個 URL 顯示給使用者。此門可用於以下目的：

創意輪播：使用儲存的資料（例如創意 ID、檢視次數和使用者互動）來確定使用者在不同網站上看到哪些創意內容。這種方法有助於平衡檢視次數並防止某些內容過度曝光，從而避免負面使用者體驗。
A/B 測試：將使用者分配到一個實驗組，然後將組詳細資訊儲存在共享儲存中以供跨站訪問。
定製使用者體驗：根據使用者的註冊狀態或其他使用者狀態共享定製內容和行動號召。

執行

執行輸出門，透過run()方法訪問，旨在以通用方式處理某些共享儲存資料。

私有聚合 API 可以使用 Run 輸出門來處理共享儲存資料並生成聚合報告。這些報告可用於以下用例：

獨立覆蓋率報告：內容生產者和廣告商通常希望瞭解其內容的獨立觀看者數量。您可以使用共享儲存來報告使用者首次看到您的廣告或嵌入式出版物的時間，並防止在不同網站上對同一使用者進行重複計數，從而為您提供一個近似獨立覆蓋率的聚合噪音報告。
使用者人口統計報告：內容生產者通常希望瞭解其受眾的人口統計資料。您可以使用共享儲存在您的主站點上記錄使用者人口統計資料，並使用聚合報告在嵌入式上下文中報告其他站點上的資料。
K+ 頻率測量：有時被稱為“有效頻率”，K+ 頻率是指使用者識別或回憶某些內容所需的最小檢視次數（通常用於廣告檢視的上下文中）。您可以使用共享儲存來構建至少看過 K 次內容的獨立使用者報告。

瞭解共享儲存的工作原理

使用共享儲存 API 分為兩個部分——向儲存寫入資料和讀取/處理資料。為了讓您瞭解這些部分是如何處理的，我們將透過 developer.chrome.com 上基本的A/B 測試示例來引導您。在這個示例中，使用者被分配到一個實驗組，並且組詳細資訊儲存在共享儲存中。其他網站在選擇要在圍欄框架中顯示的 URL 時能夠使用這些資料。

寫入共享儲存

寫入共享儲存很簡單——您可以使用SharedStorage介面上定義的方法來設定、追加或刪除/清除資料。

此功能在兩種不同的上下文中可用：

在執行您的網站或應用程式的主瀏覽上下文中，在WindowSharedStorage上。這可以透過window.sharedStorage獲得。
在您的共享儲存工作執行緒的上下文中，在WorkletSharedStorage上。這可以透過this.sharedStorage獲得。

在我們的 A/B 測試示例中，我們在應用程式上下文中定義了一個函式，它生成一個隨機數——0 或 1——來表示一個實驗組。然後我們執行window.sharedStorage.set()函式將使用者分配到一個組並將結果儲存在共享儲存中：

// Randomly assigns a user to a group 0 or 1
function getExperimentGroup() {
  return Math.round(Math.random());
}

async function injectContent() {
  // Assign user to a random group (0 or 1) and store it in shared storage
  window.sharedStorage.set("ab-testing-group", getExperimentGroup(), {
    ignoreIfPresent: true,
  });
}

注意： ignoreIfPresent: true選項導致如果共享儲存中已經包含具有指定鍵的資料項，則set()函式中止。

從共享儲存讀取和處理資料

如上所述，要從共享儲存 worklet 中提取有用的結果，您需要使用輸出門。在此示例中，我們將使用URL 選擇輸出門讀取使用者的實驗組，然後根據其組在圍欄框架中顯示一個 URL。

要使用輸出門，您需要：

在 worklet 模組指令碼中定義並註冊一個操作來處理 URL 選擇。
將模組新增到您的共享儲存 worklet。
使用 worklet 操作選擇 URL，並將其載入到圍欄框架中。

下面我們將逐一檢視這些步驟。

在工作執行緒模組中定義一個操作

URL 選擇是基於儲存在共享儲存中的實驗組。為了檢索該值並根據它選擇一個 URL，我們需要在SharedStorageWorklet上下文中定義一個操作。這確保了原始資料對其他上下文隱藏，從而保護了隱私。

URL 選擇操作是一個 JavaScript 類，它必須遵循以下規則（這些規則因每個輸出門而異，具體取決於其預期用例）：

實際功能必須包含在一個非同步的run()方法中，該方法將一個包含 URL 的物件陣列作為其第一個引數，並將一個數據物件作為其第二個引數（呼叫時，資料引數是可選的）。
run()方法必須返回一個數字，該數字將等於所選 URL 的序號。

注意： 每個輸出門都有一個對應的介面，定義其類和run()方法所需的結構。對於 URL 選擇，請參閱SharedStorageSelectURLOperation。

一旦操作被定義，就需要使用SharedStorageWorkletGlobalScope.register()進行註冊。

// ab-testing-worklet.js
class SelectURLOperation {
  async run(urls, data) {
    // Read the user's experiment group from shared storage
    const experimentGroup = await this.sharedStorage.get("ab-testing-group");

    // Return the group number
    return experimentGroup;
  }
}

register("ab-testing", SelectURLOperation);

請注意，我們主應用程式上下文中設定的值是如何使用WorkletSharedStorage.get()檢索的。重申一下，為了保護隱私和減少資料洩露，您只能在工作執行緒中從共享儲存中讀取值。

注意： 可以在同一個共享儲存工作執行緒模組指令碼中定義和註冊多個具有不同名稱的操作；有關示例，請參閱SharedStorageOperation。

將模組新增到共享儲存工作執行緒

要使用工作執行緒模組中定義的操作，需要使用window.sharedStorage.worklet.addModule()將其新增到共享儲存工作執行緒中。在我們的主應用程式上下文中，這在設定實驗組值之前完成，以便在需要時隨時可用：

async function injectContent() {
  // Add the module to the shared storage worklet
  await window.sharedStorage.worklet.addModule("ab-testing-worklet.js");

  // Assign user to a random group (0 or 1) and store it in shared storage
  window.sharedStorage.set("ab-testing-group", getExperimentGroup(), {
    ignoreIfPresent: true,
  });
}

選擇 URL 並將其載入到圍欄框架中

為了執行在工作執行緒中定義的操作，我們呼叫WindowSharedStorage.selectURL()。此方法充當我們工作執行緒操作的代理，安全地訪問它並返回結果，而不會洩露任何資料。selectURL()是呼叫我們使用者定義的工作執行緒操作的正確方法，因為它使用適用於 URL 選擇操作的適當類結構定義，如上所述。

selectURL()需要一個包含要選擇的 URL 的物件陣列、一個可選的 options 物件，並且底層操作需要返回一個整數，它可以用來選擇一個 URL。

// Run the URL selection operation
const fencedFrameConfig = await window.sharedStorage.selectURL(
  "ab-testing",
  [
    { url: `https://your-server.example/content/default-content.html` },
    { url: `https://your-server.example/content/experiment-content-a.html` },
  ],
  {
    resolveToConfig: true,
  },
);

由於 options 物件包含resolveToConfig: true，返回的Promise將解析為FencedFrameConfig物件。此物件可以設定為HTMLFencedFrameElement.config屬性的值，從而導致所選 URL 的內容顯示在相應的<fencedframe>元素中：

document.getElementById("content-slot").config = fencedFrameConfig;

完整的應用程式指令碼如下所示：

// Randomly assigns a user to a group 0 or 1
function getExperimentGroup() {
  return Math.round(Math.random());
}

async function injectContent() {
  // Add the module to the shared storage worklet
  await window.sharedStorage.worklet.addModule("ab-testing-worklet.js");

  // Assign user to a random group (0 or 1) and store it in shared storage
  window.sharedStorage.set("ab-testing-group", getExperimentGroup(), {
    ignoreIfPresent: true,
  });

  // Run the URL selection operation
  const fencedFrameConfig = await window.sharedStorage.selectURL(
    "ab-testing",
    [
      { url: `https://your-server.example/content/default-content.html` },
      { url: `https://your-server.example/content/experiment-content-a.html` },
    ],
    {
      resolveToConfig: true,
    },
  );

  // Render the chosen URL into a fenced frame
  document.getElementById("content-slot").config = fencedFrameConfig;
}

injectContent();

共享儲存與 Web 儲存的區別

關鍵區別在於，共享儲存旨在用於儲存分割槽後的跨域資料。

如果您是釋出者，並且希望儲存只有您自己可以訪問的第一方資料，請使用Web 儲存的localStorage版本。
如果您希望資料僅在瀏覽器會話期間持久化，請使用sessionStorage。
如果您在另一個網站上作為第三方運營，並且希望記錄該網站的資料以便稍後在另一個網站上訪問，請使用共享儲存。

共享儲存和 Web 儲存之間的另一個重要區別是，從共享儲存讀取資料是受保護的（寫入儲存的行為類似）。使用localStorage和sessionStorage，您可以自由讀取。使用共享儲存，只能在共享儲存工作執行緒中進行讀取，並且工作執行緒中用於讀取的源與建立它的瀏覽上下文相同。

此外，作為一種跟蹤保護措施，您無法在共享儲存工作執行緒之外提取共享儲存資料。您必須使用其中一個輸出門來處理共享儲存中的資料。

最後，localStorage中的資料會一直保留，直到手動清除。sessionStorage在瀏覽會話結束時清除，而共享儲存資料在最後一次寫入呼叫後 30 天清除。

介面

SharedStorage: 表示特定源的共享儲存。它定義了向共享儲存寫入資料的方法。
WindowSharedStorage: 表示暴露給標準瀏覽上下文的特定源的共享儲存。除其他外，它定義了使用可用輸出門的方法，這些門充當在工作執行緒中定義的操作的代理。
WorkletSharedStorage: 表示工作執行緒上下文內特定源的共享儲存。除其他外，它定義了讀取共享儲存資料的方法。
SharedStorageWorklet: 表示當前源的共享儲存工作執行緒。它包含用於新增模組的addModule()方法。與常規Worklet不同，出於隱私原因，SharedStorageWorklet只能新增一個模組。
SharedStorageWorkletGlobalScope: 表示SharedStorageWorklet模組的全域性範圍。它包含註冊已定義操作和訪問共享儲存的功能。