Shared Storage API

Konzepte und Anwendung

Eine Hauptquelle von Privatsphäre- und Sicherheits-problemen im Web ist der Einsatz von Cookies, die auf Drittinhalten gesetzt werden, die auf Websites eingebettet sind (zum Beispiel über <iframe>-Elemente). Diese Cookies können verwendet werden, um Nutzer zu verfolgen und zu profilieren sowie Informationen über Sites hinweg zu teilen.

Um seitenübergreifendes Tracking zu verhindern, arbeiten Browser daran, alle Speicherarten zu partitionieren, einschließlich Cookies, Web Storage, IndexedDB und der Cache-API. Ein großes Hindernis dabei ist jedoch der Bedarf an mehreren legitimen Anwendungsfällen, die auf seitenübergreifenden Informationsaustausch angewiesen sind. Beispiele solcher Anwendungsfälle sind Werbetreibende, die die Reichweite ihrer Anzeigen über Sites hinweg messen und Berichte erzeugen möchten, und Seitenbetreiber, die Nutzererfahrungen anpassen möchten, basierend auf der Gruppe, in der sie sind, oder ihren vorherigen Interaktionen auf der Website.

Die Shared Storage API bietet eine flexible Lösung für solche Anwendungsfälle. Sie zielt darauf ab, die erforderlichen Datenspeicher-, Verarbeitungs- und Freigabefunktionen bereitzustellen, ohne dass die Möglichkeit besteht, Nutzer zu verfolgen und zu profilieren.

Wie bei anderen Speicher-APIs können Sie jederzeit auf den Shared Storage schreiben. Allerdings können Sie Shared Storage-Daten nur aus einem Worklet auslesen. Worklets bieten eine sichere Umgebung, in der Sie Shared Storage-Daten verarbeiten und nützliche Ergebnisse zurückgeben können, ohne dass Sie die Daten direkt mit dem zugehörigen Browsing-Kontext teilen können.

Um nützliche Ergebnisse aus einem Shared-Storage-Worklet zu extrahieren, müssen Sie ein Output Gate verwenden. Diese Tore dienen spezifischen Zwecken, wie z.B. der Auswahl einer URL aus einer bereitgestellten Liste, die basierend auf Shared Storage-Daten dem Nutzer angezeigt wird. Ergebnisse, die für den Nutzer bestimmt sind, werden sicher in einem fenced frame angezeigt, wo sie von der einbettenden Seite nicht abgerufen werden können.

Output Gates

Die derzeit verfügbaren Output Gates für die Shared Storage API werden in den folgenden Abschnitten 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 Codebeispielen.

URL-Auswahl

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

• Creative Rotation: Verwenden Sie gespeicherte Daten wie Creative-IDs, Anzeigemehrheiten und Nutzerinteraktionen, um zu bestimmen, welche kreativen Inhalte Nutzer über verschiedene Sites hinweg sehen. Dieser Ansatz hilft, Anzeigemehrheiten auszugleichen und übermäßige Exposition bestimmter Inhalte zu verhindern, was wiederum eine negative Nutzererfahrung vermeiden kann.
• A/B-Testing: Weisen Sie einen Nutzer einer Experimentgruppe zu und speichern Sie dann die Gruppendetails im Shared Storage für den seitenübergreifenden Zugriff.
• Benutzerdefinierte Nutzererlebnisse: Teilen Sie benutzerdefinierte Inhalte und Handlungsaufforderungen, basierend auf dem Registrierungsstatus eines Nutzers oder anderen Nutzerzuständen.

Run

Das Run-Output Gate, aufgerufen über die Methode run(), ist dazu gedacht, auf generische Weise 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 generieren. Diese Berichte können in den folgenden Anwendungsfällen verwendet werden:

• Unique Reach Reporting: Inhaltsproduzenten und Werbetreibende wollen oft die Anzahl der eindeutigen Zuschauer für ihre Inhalte wissen. Sie können Shared Storage verwenden, um das erste Mal zu berichten, dass ein Nutzer Ihre Anzeige oder Ihre eingebettete Publikation sieht und zu vermeiden, dass derselbe Nutzer auf einer anderen Site doppelt gezählt wird, sodass Sie einen aggregierten, verrauschten Bericht über die ungefähre einzigartige Reichweite erhalten.
• Nutzer-Demografie-Berichterstattung: Inhaltsproduzenten wollen oft die Demografie ihres Publikums verstehen. Sie können Shared Storage verwenden, um demografische Nutzerdaten auf Ihrer Hauptsite zu erfassen und mit aggregierter Berichterstattung darüber über andere Sites in eingebetteten Kontexten zu berichten.
• K+-Frequenzmessung: Manchmal als "effektive Frequenz" bezeichnet, bezieht sich die K+-Frequenz auf die minimale Anzahl von Ansichten, die erforderlich sind, bevor ein Nutzer bestimmte Inhalte erkennt oder erinnert (oft im Kontext von Anzeigenansichten verwendet). Sie können Shared Storage verwenden, um Berichte über eindeutige Nutzer zu erstellen, die ein Inhaltsstück mindestens K-mal gesehen haben.

Verständnis, wie Shared Storage funktioniert

Es gibt zwei Teile bei der Nutzung der Shared Storage API: das Schreiben von Daten in den Speicher und das Lesen/Verarbeiten dieser Daten. 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 Nutzer einer Experimentgruppe zugewiesen, und die Gruppendetails werden im Shared Storage gespeichert. Andere Sites 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 in der Schnittstelle SharedStorage definiert sind, um Daten zu setzen, anzuhängen oder zu löschen/zu leeren.

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

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

In unserem A/B-Testing-Beispiel definieren wir eine Funktion in unserem App-Kontext, die eine Zufallszahl — 0 oder 1 — erzeugt, um eine Experimentgruppe zu repräsentieren. Anschließend führen wir die Funktion window.sharedStorage.set() aus, um den Nutzer 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,
  });
}

Lesen und Verarbeiten von Daten aus dem Shared Storage

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

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

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

Im Folgenden betrachten wir diese Schritte nacheinander.

Definieren einer Operation in einem Worklet-Modul

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

Die URL-Auswahl-Operation ist eine JavaScript-Klasse, die die folgenden Regeln einhalten muss (diese Regeln variieren je nach Output Gate, abhängig von ihrem beabsichtigten Anwendungsfall):

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

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 es zu wiederholen, um die Privatsphäre zu erhalten und Datenlecks zu vermeiden, können Werte aus dem Shared Storage nur innerhalb eines Worklets gelesen werden.

Das Modul zum Shared Storage-Worklet hinzufügen

Um die im Worklet-Modul definierte Operation zu verwenden, muss sie mit window.sharedStorage.worklet.addModule() zum Shared Storage-Worklet hinzugefügt werden. In unserem Haupt-App-Kontext geschieht dies, bevor wir den Experimentgruppenwert setzen, sodass er bereit ist, wenn er 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 für unsere Worklet-Operation, greift sicher darauf zu und gibt das Ergebnis zurück, ohne irgendwelche Daten zu leaken. selectURL() ist die korrekte Methode, um unsere benutzerdefinierte Worklet-Operation aufzurufen, da sie mit der entsprechenden Klassenstruktur für eine URL-Auswahloperation definiert wurde, wie oben erläutert.

selectURL() erwartet ein Array von Objekten, die URLs zur Auswahl enthalten, ein optionales Optionsobjekt, und dass die zugrundeliegende Operation eine Ganzzahl zurückgibt, die sie zur Auswahl einer URL verwenden 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 Eigenschaft HTMLFencedFrameElement.config gesetzt werden, sodass der Inhalt der gewählten URL im entsprechenden <fencedframe>-Element angezeigt wird:

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

Das vollständige App-Script sieht folgendermaßen 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 seitenübergreifenden Daten gedacht ist, nachdem die Speicherung partitioniert wurde.

• Wenn Sie ein Publisher sind und Erstanbieterdaten speichern möchten, die nur Ihnen 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 Drittanbieter auf einer anderen Seite tätig sind und Daten von dieser Seite aufzeichnen möchten, um sie später auf einer anderen Seite zu nutzen, 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 funktioniert ähnlich). Mit localStorage und sessionStorage können Sie frei lesen. Mit Shared Storage kann das Lesen nur innerhalb eines Shared Storage-Worklets geschehen, und der Ursprung, der im Worklet zum Lesen verwendet wird, ist derselbe wie der Browsing-Kontext, der es erstellt hat.

Außerdem können Sie Daten aus dem Shared Storage nicht außerhalb eines Shared Storage-Worklets 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 Browsersitzung 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 zum Schreiben von Daten in den Shared Storage.

WindowSharedStorage

Repräsentiert den Shared Storage für einen bestimmten Ursprung, wie er in einem Standard-Browsing-Kontext bereitgestellt wird. Unter anderem definiert es Methoden zur Nutzung der verfügbaren Output Gates, die als Proxys für die im Worklet definierten Operationen dienen.

WorkletSharedStorage

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

SharedStorageWorklet

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

SharedStorageWorkletGlobalScope

Repräsentiert den globalen Bereich eines SharedStorageWorklet-Moduls. Es enthält die Funktionalität, eine definierte Operation zu registrieren und auf den Shared Storage zuzugreifen.

Output Gate-Operation Signaturdefinitionen

SharedStorageOperation

Repräsentiert die Basisklasse für alle unterschiedlichen Output Gate-Operationstypen.

SharedStorageRunOperation

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

SharedStorageSelectURLOperation

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

Erweiterungen für andere Schnittstellen

Window.sharedStorage

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

Einschreibung und lokale Tests

Um die Shared Storage API in Ihren Sites zu verwenden, müssen Sie sie im Privacy Sandbox-Einschreibungsprozess spezifizieren. Wenn Sie dies nicht tun, werden die Methoden der Shared Storage API nicht erfolgreich ausgeführt.

Sie können Ihren Shared Storage API-Code lokal testen, ohne sich einzuschreiben. Um lokale Tests zu ermöglichen, aktivieren Sie das folgende Chrome-Entwickler-Flag:

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

Beispiele

Für ausführliche Demos siehe die Shared Storage API-Demoseite, die auch einige Beispiele der Private Aggregation API enthält.

Spezifikationen

Standards Positionen

Ein Browser-Anbieter lehnt diese Spezifikation ab. Bekannte Standards Positionen sind wie folgt:

• Mozilla (Firefox): Negativ

Browser-Kompatibilität

Siehe auch

• Shared Storage auf privacysandbox.google.com
• The Privacy Sandbox auf privacysandbox.google.com