Shared Storage API

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die Shared Storage API ist ein clientseitiger Speichermecanismus, der nicht partitionierten, seitenübergreifenden Datenzugriff ermöglicht, während die Privatsphäre gewahrt bleibt (d.h. ohne auf Tracking-Cookies angewiesen zu sein).

Konzepte und Nutzung

Eine große Quelle für Privatsphäre- und Sicherheitsprobleme im Web ist die Verwendung von Cookies, die auf Dritteinhalte gesetzt werden, die in Websites eingebettet sind (zum Beispiel über <iframe>-Elemente). Diese Cookies können verwendet werden, um Benutzer zu verfolgen und zu profilieren und Informationen über Websites hinweg zu teilen.

Um das seitenübergreifende Tracking zu verhindern, arbeiten Browser daran, alle Speichertypen zu partitionieren, einschließlich Cookies, Web Storage, IndexedDB und die Cache API. Ein großes Hindernis, dies zu erreichen, sind jedoch mehrere legitime Anwendungsfälle, die auf seitenübergreifendes Teilen von Informationen angewiesen sind. Beispiele für solche Anwendungsfälle sind Werbekunden, die die Reichweite ihrer Anzeigen über Websites hinweg messen und Berichte erstellen wollen, sowie Website-Besitzer, die Benutzererfahrungen basierend auf der Gruppe, in der sich ein Benutzer befindet, oder seinen vorherigen Interaktionen mit der Website anpassen möchten.

Die Shared Storage API bietet eine flexible Lösung für solche Anwendungsfälle. Sie soll die notwendige Datenspeicherung, Verarbeitung und -teilung ohne die Möglichkeit bereitstellen, Benutzer zu verfolgen und zu profilieren.

Wie bei anderen Speicher-APIs können Sie jederzeit in den Shared Storage schreiben. Der Lesezugriff auf Shared Storage-Daten ist jedoch nur von innerhalb eines Worklet möglich. Worklets bieten eine sichere Umgebung, in der Sie Shared Storage-Daten verarbeiten und nützliche Ergebnisse zurückgeben können, aber Sie können die Daten nicht direkt mit dem zugehörigen Browsing-Kontext teilen.

Um nützliche Ergebnisse aus einem Shared Storage-Worklet zu extrahieren, müssen Sie ein Output-Gate verwenden. Diese Gates dienen spezifischen Zwecken wie der Auswahl einer URL aus einer bereitgestellten Liste zur Anzeige an den Benutzer basierend auf Shared Storage-Daten. Ergebnisse, die für den Benutzer bestimmt sind, werden sicher in einem fenced frame angezeigt, in dem sie nicht von der eingebetteten Seite aus zugänglich sind.

Output-Gates

Die derzeit verfügbaren Output-Gates für die Shared Storage API werden in den Abschnitten unten erläutert. In jedem Abschnitt listen wir typische Anwendungsfälle für jedes Gate auf und bieten Links zu Leitfäden mit weiteren Informationen und Code-Beispielen.

Hinweis: In Zukunft werden wahrscheinlich weitere Output-Gates hinzugefügt, um zusätzliche Anwendungsfälle zu unterstützen.

URL-Auswahl

Das URL Selection-Output-Gate, aufgerufen über die selectURL()-Methode, wird verwendet, um eine URL aus einer bereitgestellten Liste auszuwählen, die basierend auf Shared Storage-Daten dem Benutzer angezeigt wird. Dieses Gate kann für folgende Zwecke genutzt werden:

  • Creative Rotation: Verwenden Sie gespeicherte Daten wie Creative-IDs, Ansichtenanzahl und Benutzerinteraktionen, um zu bestimmen, welche kreativen Inhalte Benutzer über verschiedene Seiten hinweg zu sehen bekommen. Dieser Ansatz hilft dabei, Ansichten auszugleichen und übermäßige Exposition bestimmter Inhalte zu vermeiden, was wiederum eine negative Benutzererfahrung verhindern kann.
  • A/B-Tests: Weisen Sie einen Benutzer einer Experimentgruppe zu und speichern Sie dann die Gruppendetails im Shared Storage für den seitenübergreifenden Zugriff.
  • Benutzerdefinierte Erlebnisse: Teilen Sie benutzerdefinierte Inhalte und Handlungsaufforderungen basierend auf dem Registrierungsstatus eines Benutzers oder anderen Benutzerzuständen.

Ausführen

Das Run-Output-Gate, aufgerufen über die run()-Methode, soll generisch verwendet werden, um einige Shared Storage-Daten zu verarbeiten.

Die Private Aggregation API kann das Run-Output-Gate verwenden, um Shared Storage-Daten zu verarbeiten und aggregierte Berichte zu erstellen. Diese Berichte können in folgenden Anwendungsfällen verwendet werden:

  • Einzigartige Reichweitenberichte: Inhaltsersteller und Werbetreibende möchten oft die Anzahl der einzigartigen Zuschauer für ihre Inhalte kennen. Sie können Shared Storage verwenden, um das erste Mal, wenn ein Benutzer Ihre Anzeige oder eingebettete Veröffentlichung sieht, zu melden und doppelte Zählungen für denselben Benutzer auf einer anderen Website zu verhindern, was Ihnen einen aggregierten lärmbehafteten Bericht über die ungefähre einzigartige Reichweite liefert.
  • Benutzer-Demografie-Berichte: Inhaltsersteller möchten oft die Demografien ihres Publikums verstehen. Sie können Shared Storage verwenden, um Benutzerdemografiedaten auf Ihrer Hauptseite zu erfassen und mit aggregierter Berichterstattung darüber auf anderen Websites in eingebetteten Kontexten zu berichten.
  • K+ Frequenzmessung: Manchmal als "effektive Frequenz" beschrieben, bezieht sich K+ Frequenz auf die Mindestanzahl von Ansichten, die erforderlich sind, bevor ein Benutzer bestimmte Inhalte erkennen oder sich daran erinnern kann (oft im Kontext von Anzeigenansichten verwendet). Sie können Shared Storage verwenden, um Berichte über einzigartige Benutzer zu erstellen, die ein Stück Inhalt mindestens K Mal gesehen haben.

Verständnis, wie Shared Storage funktioniert

Es gibt zwei Teile bei der Verwendung der Shared Storage API — Daten in den Speicher schreiben und diese lesen/verarbeiten. Um Ihnen eine Vorstellung davon zu geben, wie diese Teile gehandhabt werden, führen wir Sie durch das grundlegende A/B-Testing-Beispiel von developer.chrome.com. In diesem Beispiel wird ein Benutzer einer Experimentgruppe zugewiesen, und die Gruppendetails werden im Shared Storage gespeichert. Andere Websites können diese Daten verwenden, wenn sie eine URL auswählen, die in einem fenced frame angezeigt werden soll.

Schreiben in den Shared Storage

Das Schreiben von Daten in den Shared Storage ist einfach — Sie verwenden Methoden, die auf der SharedStorage-Schnittstelle definiert sind, um Daten zu setzen, anzufügen, oder zu löschen/zu löschen.

Diese Funktionalität ist in zwei verschiedenen Kontexten verfügbar:

  • Im Hauptbrowsing-Kontext, in dem Ihre Website oder App läuft, auf WindowSharedStorage. Dies ist über window.sharedStorage verfügbar.
  • Im Kontext Ihres Shared Storage Worklet, auf WorkletSharedStorage. Dies ist über this.sharedStorage verfügbar.

In unserem A/B-Testbeispiel definieren wir eine Funktion in unserem App-Kontext, die eine zufällige Zahl — 0 oder 1 — generiert, um eine Experimentgruppe darzustellen. Wir führen dann die window.sharedStorage.set()-Funktion aus, um den Benutzer einer Gruppe zuzuweisen und das Ergebnis im Shared Storage zu speichern:

js
// 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,
  });
}

Hinweis: Die Option ignoreIfPresent: true führt dazu, dass die set()-Funktion abbricht, wenn der Shared Storage bereits ein Datenitem mit dem angegebenen Schlüssel enthält.

Lesen und Verarbeiten von Daten aus dem Shared Storage

Wie oben erwähnt, um nützliche Ergebnisse aus einem Shared Storage-Worklet zu extrahieren, müssen Sie ein Output-Gate verwenden. In diesem Beispiel verwenden wir das URL Selection Output-Gate, um die Experimentgruppe des Benutzers zu lesen und dann basierend auf ihrer Gruppe eine URL in einem fenced frame anzuzeigen.

Um das Output-Gate zu verwenden, müssen Sie:

  1. Eine Operation in einem Worklet-Modul-Skript definieren, um die Auswahl der URL zu handhaben, und diese registrieren.
  2. Das Modul Ihrem Shared Storage-Worklet hinzufügen.
  3. Die URL mit der Worklet-Operation auswählen und diese in einem fenced frame laden.

Nachfolgend betrachten wir diese Schritte nacheinander.

Eine Operation in einem Worklet-Modul definieren

Die URL-Auswahl basiert auf der Experimentgruppe, die im Shared Storage gespeichert ist. Um diesen Wert abzurufen und basierend darauf eine URL auszuwählen, müssen wir eine Operation in einem SharedStorageWorklet-Kontext definieren. Dies stellt sicher, dass die rohen Daten vor anderen Kontexten verborgen bleiben und somit die Privatsphäre gewahrt bleibt.

Die URL Selection-Operation ist eine JavaScript-Klasse, die den folgenden Regeln entsprechen muss (diese variieren je nach Output-Gate, je nach beabsichtigtem Anwendungsfall):

  • Die eigentliche Funktionalität muss in einer asynchronen run()-Methode enthalten sein, die als ersten Parameter ein Array von Objekten mit URLs und als zweiten Parameter ein Datenobjekt nimmt (wenn aufgerufen, ist das Datenargument optional).
  • Die run()-Methode muss eine Zahl zurückgeben, die der Anzahl der gewählten URL entspricht.

Hinweis: Jedes Output-Gate hat eine entsprechende Schnittstelle, die die erforderliche Struktur ihrer Klasse und der run()-Methode definiert. Für die URL-Auswahl siehe SharedStorageSelectURLOperation.

Sobald die Operation definiert ist, muss sie mit SharedStorageWorkletGlobalScope.register() registriert werden.

js
// 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);

Beachten Sie, wie der im Haupt-App-Kontext gesetzte Wert mit WorkletSharedStorage.get() abgerufen wird. Um die Privatsphäre zu wahren und Datenlecks zu verhindern, können Sie Werte aus dem Shared Storage nur innerhalb eines Worklets lesen.

Hinweis: Es ist möglich, mehrere Operationen im gleichen Shared Storage-Worklet-Modulskript mit unterschiedlichen Namen zu definieren und zu registrieren; siehe SharedStorageOperation für ein Beispiel.

Das Modul zum Shared Storage-Worklet hinzufügen

Um die im Worklet-Modul definierte Operation zu verwenden, muss sie mithilfe von window.sharedStorage.worklet.addModule() dem Shared Storage-Worklet hinzugefügt werden. In unserem Haupt-App-Kontext wird dies vor dem Setzen des Experimentgruppe-Wertes gemacht, sodass es bereit ist, verwendet zu werden, wenn es benötigt wird:

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

Eine URL auswählen und in einem fenced frame laden

Um die im Worklet definierte Operation auszuführen, rufen wir WindowSharedStorage.selectURL() auf. Diese Methode fungiert als Proxy zu unserer Worklet-Operation, auf die sicher zugegriffen und das Ergebnis zurückgegeben wird, ohne dass Daten durchsickern. selectURL() ist die richtige Methode, um unsere benutzerdefinierte Worklet-Operation aufzurufen, da sie mit der geeigneten Klassenstruktur für eine URL Selection-Operation definiert wurde, wie oben beschrieben.

selectURL() erwartet ein Array von Objekten mit URLs, aus denen gewählt wird, ein optionales Optionsobjekt, und dass die zugrunde liegende Operation eine Ganzzahl zurückgibt, mit der eine URL ausgewählt werden kann.

js
// 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,
  },
);

Da das Optionsobjekt resolveToConfig: true enthält, wird das zurückgegebene Promise mit einem FencedFrameConfig-Objekt aufgelöst. Dieses Objekt kann als Wert der HTMLFencedFrameElement.config-Eigenschaft gesetzt werden, was dazu führt, dass der Inhalt der gewählten URL im entsprechenden <fencedframe>-Element angezeigt wird:

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

Das vollständige App-Skript sieht wie folgt aus:

js
// 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();

Unterschiede zwischen Shared Storage und Web Storage

Der Hauptunterschied besteht darin, dass Shared Storage für die Verwendung mit sektionsübergreifenden Daten nach der Partitionierung des Speichers gedacht ist.

  • Wenn Sie ein Publisher sind und Sie möchten First-Party-Daten speichern, die nur für Sie zugänglich sind, verwenden Sie die localStorage-Version von Web Storage.
  • Wenn Sie möchten, dass Daten nur während einer Browsersitzung bestehen bleiben, verwenden Sie sessionStorage.
  • Wenn Sie als Drittpartei auf einer anderen Website agieren und Daten von dieser Website erfassen möchten, um später auf einer anderen Website darauf zuzugreifen, verwenden Sie Shared Storage.

Ein weiterer wichtiger Unterschied zwischen Shared Storage und Web Storage besteht darin, dass das Lesen aus dem Shared Storage geschützt ist (das Schreiben in den Speicher verhält sich ähnlich). Mit localStorage und sessionStorage können Sie frei lesen. Mit Shared Storage kann das Lesen nur innerhalb eines Shared Storage-Worklets erfolgen, und der für das Lesen im Worklet verwendete Ursprung ist derselbe wie der Browsing-Kontext, der ihn erstellt hat.

Zusätzlich können Sie Shared Storage-Daten außerhalb eines Shared Storage-Worklets nicht extrahieren, als Schutz vor Tracking. Sie müssen eines der Output-Gates verwenden, um mit Ihren Daten im Shared Storage zu arbeiten.

Zuletzt bleiben Daten in localStorage bestehen, bis sie manuell gelöscht werden. sessionStorage wird am Ende einer Browsingsession gelöscht, während Shared Storage-Daten 30 Tage nach dem letzten Schreibaufruf gelöscht werden.

Schnittstellen

SharedStorage

Repräsentiert den Shared Storage für einen bestimmten Ursprung. Es definiert Methoden, um Daten in den Shared Storage zu schreiben.

WindowSharedStorage

Repräsentiert den Shared Storage für einen bestimmten Ursprung, wie er einem Standard-Browsing-Kontext zur Verfügung steht. Unter anderem definiert es Methoden zur Nutzung der verfügbaren Output-Gates, die als Proxy für die im Worklet definierten Operationen fungieren.

WorkletSharedStorage

Repräsentiert den Shared Storage für einen bestimmten Ursprung innerhalb eines Worklet-Kontexts. Unter anderem definieren sie Methoden zum Lesen der Shared Storage-Daten.

SharedStorageWorklet

Repräsentiert den Shared Storage Worklet des aktuellen Ursprungs. Es enthält die addModule()-Methode zum Hinzufügen von Modulen. Im Gegensatz zu einem regulären Worklet kann das SharedStorageWorklet aus Datenschutzgründen nur ein einzelnes Modul hinzugefügt bekommen.

SharedStorageWorkletGlobalScope

Repräsentiert den globalen Bereich eines SharedStorageWorklet-Moduls. Es enthält die Funktionalität zum Registrieren einer definierten Operation und Zugriff auf den Shared Storage.

Signaturdefinitionen für Output-Gate-Betriebsarten

SharedStorageOperation

Repräsentiert die Basisklasse für alle verschiedenen Operationstypen des Output-Gates.

SharedStorageRunOperation

Repräsentiert eine Run-Output-Gate-Operation.

SharedStorageSelectURLOperation

Repräsentiert eine URL Selection-Output-Gate-Operation.

Erweiterungen für andere Schnittstellen

Window.sharedStorage

Gibt das WindowSharedStorage-Objekt für den aktuellen Ursprung zurück.

Anmeldung und lokales Testen

Um die Shared Storage API auf Ihren Websites zu verwenden, müssen Sie sie im Anmeldeprozess für die Privacy Sandbox angeben. Tun Sie dies nicht, werden die Methoden der Shared Storage API nicht erfolgreich ausgeführt.

Sie können Ihren Shared Storage API-Code lokal ohne Anmeldung testen. Um lokales Testen zu ermöglichen, aktivieren Sie das folgende Chrome Developer-Flag:

chrome://flags/#privacy-sandbox-enrollment-overrides

Beispiele

Für umfangreiche Demos siehe die Shared Storage API-Demo-Website, die auch einige Private Aggregation API-Beispiele enthält.

Spezifikationen

Specification
Shared Storage API
# sharedstorage

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
SharedStorage
Experimental
append
Experimental
batchUpdate
Experimental
clear
Experimental
createWorklet
Experimental
delete
Experimental
get
Experimental
run
Experimental
selectURL
Experimental
set
Experimental
worklet
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
Experimental. Expect behavior to change in the future.

Siehe auch