SharedStorage.append() — Methode · JavaScript-Referenz

Signatur

SharedStorage.prototype.append(key, value, options)

Beschreibung

Die Methode append() der Schnittstelle SharedStorage hängt den übergebenen value an den bestehenden Wert des Schlüssels key an. Gibt es den Schlüssel noch nicht, wird er neu angelegt und bekommt value als Wert. Das funktioniert also ähnlich wie set(), nur dass vorhandene Daten erhalten bleiben und nicht überschrieben werden.

Shared Storage ist Teil der Privacy Sandbox von Chrome. Die API bietet einen ursprungsbezogenen Speicher, der auch über Websites hinweg erhalten bleibt (Speicher ohne Partitionierung). Schreiben ist von überall möglich: im Fenster über window.sharedStorage und in Worklets über sharedStorage. Lesen geht dagegen nur in einem SharedStorageWorklet, und die Ergebnisse verlassen das Worklet ausschließlich über datenschutzfreundliche Ausgabewege wie selectURL() oder die Private Aggregation API.

In der Praxis eignet sich append() gut dafür, Ereignisse oder Kennungen zu sammeln, ohne den bisherigen Wert erst lesen zu müssen. Das ist wichtig, weil Lesen im Fensterkontext gar nicht erlaubt ist. Typische Beispiele sind eine Liste bereits gezeigter Werbemittel für die Frequenzbegrenzung oder besuchte Kategorien für A/B-Tests.

Parameter

Name	Typ	Beschreibung
$key Pflicht	string	Schlüssel, an dessen Wert angehängt werden soll. Höchstens 1024 UTF-16-Codeeinheiten, leere Strings sind nicht erlaubt.
$value Pflicht	string	String, der angehängt wird. Der Gesamtwert darf nach dem Anhängen höchstens 1024 UTF-16-Codeeinheiten lang sein.
$options	{ withLock?: string }	Optionales Objekt. Mit `withLock` wird ein Name für eine Sperre der Web Locks API angegeben. Diese Sperre wird vor dem Schreiben angefordert, damit sich gleichzeitige Zugriffe nicht überschneiden. Neuere Ergänzung der API, nicht in allen Chromium-Versionen vorhanden.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Wert angehängt wurde. Es wird mit einem TypeError abgelehnt, wenn Schlüssel oder Wert zu lang sind, die Datenbank nicht verfügbar ist oder Shared Storage deaktiviert ist (etwa durch die Browser-Einstellungen, eine fehlende Registrierung oder die Permissions-Policy).

Beispiele

Einfaches Anhängen im Fensterkontext

// Legt den Schlüssel an, falls er fehlt, sonst wird angehängt
const trackVisit = async (category) => {
  if (!('sharedStorage' in window)) {
    console.log('Shared Storage wird nicht unterstützt');
    return;
  }
  try {
    await window.sharedStorage.append('besuchte-kategorien', `${category};`);
    console.log('Kategorie gespeichert');
  } catch (err) {
    console.error('Schreiben fehlgeschlagen:', err);
  }
};

await trackVisit('sport');
await trackVisit('reisen');
// Wert im Speicher jetzt: "sport;reisen;"

Kategorie gespeichert Kategorie gespeichert

Gezeigte Werbemittel für Frequenzbegrenzung sammeln

// Beim Anzeigen einer Anzeige die Kampagnen-ID anhängen
const recordImpression = async (campaignId) => {
  await window.sharedStorage.append('impressions', `${campaignId},`);
};

document.querySelector('#ad')?.addEventListener('load', () => {
  recordImpression('kampagne-42').catch(console.error);
});

Im Worklet mit Sperre anhängen und auswerten

// worklet.js – wird mit sharedStorage.worklet.addModule() geladen
class LogOperation {
  async run(data) {
    // withLock verhindert, dass sich gleichzeitige Schreibvorgänge überschneiden
    await sharedStorage.append('log', `${data.event}|`, { withLock: 'log-lock' });

    // Lesen ist nur im Worklet erlaubt
    const log = (await sharedStorage.get('log')) ?? '';
    const count = log.split('|').filter(Boolean).length;
    console.log(`Einträge im Log: ${count}`);
  }
}
register('log-operation', LogOperation);

// main.js
await window.sharedStorage.worklet.addModule('/worklet.js');
await window.sharedStorage.run('log-operation', { data: { event: 'klick' } });

Einträge im Log: 1

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell und steht nur in Chromium-Browsern zur Verfügung. Firefox und Safari unterstützen sie nicht. Google hat angekündigt, mehrere Privacy-Sandbox-APIs einzustellen, darunter auch Shared Storage. Verlasse dich in Produktivcode nicht darauf und prüfe die Unterstützung immer mit 'sharedStorage' in window.
Voraussetzungen: Du brauchst einen sicheren Kontext (HTTPS) und eine Privacy-Sandbox-Registrierung mit Attestierung des Ursprungs. Die Permissions-Policy shared-storage darf die Nutzung nicht verbieten. Außerdem kann der Nutzer die Funktion in den Browser-Einstellungen deaktivieren. Bei Verstößen wird das Promise abgelehnt.
Größenlimits: Schlüssel und Gesamtwert dürfen jeweils höchstens 1024 UTF-16-Codeeinheiten lang sein. Wenn du wiederholt anhängst, ist diese Grenze schnell erreicht. Plane deshalb eine Rotation ein oder setze den Wert regelmäßig mit set() bzw. delete() zurück.
Keine Struktur: append() verkettet nur Strings. Trennzeichen (z. B. ;) musst du selbst mitgeben, sonst lassen sich die Einträge später nicht mehr auseinanderhalten.
Alternative ohne JavaScript: Du kannst auch serverseitig über den Antwort-Header Shared-Storage-Write: append;key="k";value="v" schreiben. Voraussetzung ist, dass die Anfrage mit sharedStorageWritable (bei fetch()) oder dem Attribut sharedstoragewritable gestellt wurde.
Einträge verfallen standardmäßig 30 Tage nach dem letzten Schreiben.

Siehe auch

SharedStorageRunOperation.run() SharedStorage.clear() SharedStorage.delete() SharedStorage.set() CacheStorage.open()