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 überwindow.sharedStorage
verfügbar. - Im Kontext Ihres Shared Storage Worklet, auf
WorkletSharedStorage
. Dies ist überthis.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:
// 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:
- Eine Operation in einem Worklet-Modul-Skript definieren, um die Auswahl der URL zu handhaben, und diese registrieren.
- Das Modul Ihrem Shared Storage-Worklet hinzufügen.
- 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.
// 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:
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.
// 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:
document.getElementById("content-slot").config = fencedFrameConfig;
Das vollständige App-Skript sieht wie folgt aus:
// 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
-
Repräsentiert den Shared Storage für einen bestimmten Ursprung. Es definiert Methoden, um Daten in den Shared Storage zu schreiben.
-
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.
-
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.
-
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ärenWorklet
kann dasSharedStorageWorklet
aus Datenschutzgründen nur ein einzelnes Modul hinzugefügt bekommen. -
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
-
Repräsentiert die Basisklasse für alle verschiedenen Operationstypen des Output-Gates.
-
Repräsentiert eine Run-Output-Gate-Operation.
-
Repräsentiert eine URL Selection-Output-Gate-Operation.
Erweiterungen für andere Schnittstellen
-
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 GitHubLegend
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
- Shared Storage auf developers.google.com
- Die Privacy Sandbox auf developers.google.com