Document.requestStorageAccess() — Methode · JavaScript-Referenz

Signatur

Document.prototype.requestStorageAccess(types?)

Beschreibung

requestStorageAccess() gehört zur Storage Access API. Moderne Browser blockieren oder partitionieren Cookies und Speicher von Drittanbietern: Ein eingebettetes <iframe> von widget.example auf news.example sieht also nicht die Cookies, die beim direkten Besuch von widget.example gesetzt wurden. Mit dieser Methode kann das eingebettete Dokument den Zugriff auf seine nicht partitionierten (First-Party-)Cookies anfordern. Typische Fälle sind eingebettete Kommentarfunktionen, Bezahl-Widgets, SSO-Anmeldungen oder Videoplayer mit Login.

Der Aufruf gibt ein Promise zurück. Es wird erfüllt, wenn der Browser den Zugriff gewährt. Das passiert entweder automatisch, weil die Berechtigung schon erteilt ist, oder nachdem die Nutzerin in einem Dialog zugestimmt hat. Lehnt der Browser ab, wird das Promise mit einer DOMException zurückgewiesen. In der Regel ist eine vorübergehende Nutzeraktivierung nötig: Man ruft die Methode also in einem click-Handler auf, nicht beim Laden der Seite.

Ohne Argument betrifft der Zugriff nur Cookies. In Chromium-Browsern kann man zusätzlich ein types-Objekt übergeben. Dann wird das Promise mit einem StorageAccessHandle erfüllt, über den man nicht partitionierten localStorage, indexedDB, caches, BroadcastChannel usw. erreicht.

Vorher sollte man mit document.hasStorageAccess() prüfen, ob schon Zugriff besteht. Mit navigator.permissions.query({ name: "storage-access" }) lässt sich feststellen, ob die Berechtigung bereits erteilt wurde. In diesem Fall darf man requestStorageAccess() in Chromium und Firefox auch ohne Nutzergeste aufrufen.

Parameter

Name	Typ	Default	Beschreibung
$types	object		Nur in Chromium. Objekt mit booleschen Schlüsseln, die festlegen, welche nicht partitionierten Speicher angefordert werden: `all`, `cookies`, `sessionStorage`, `localStorage`, `indexedDB`, `locks`, `caches`, `getDirectory`, `estimate`, `createObjectURL`, `revokeObjectURL`, `BroadcastChannel`, `SharedWorker`. Ohne Angabe werden nur Cookies angefordert.

Rückgabewert

Typ

Promise<undefined> | Promise<StorageAccessHandle>

Beschreibung

Ohne Argument: ein Promise, das mit undefined erfüllt wird, sobald der Zugriff auf Cookies gewährt ist. Mit types: ein Promise<StorageAccessHandle>, dessen Eigenschaften (z. B. handle.localStorage) auf den nicht partitionierten Speicher zeigen. Bei Ablehnung wird es mit einer DOMException zurückgewiesen, z. B. NotAllowedError, InvalidStateError oder SecurityError.

Beispiele

Zugriff per Klick im eingebetteten Widget anfordern

// Läuft im iframe von widget.example
const loginButton = document.querySelector('#login');

const ladeNutzerdaten = async () => {
  const res = await fetch('/api/me', { credentials: 'include' });
  return res.json();
};

loginButton.addEventListener('click', async () => {
  if (await document.hasStorageAccess()) {
    console.log('Zugriff besteht bereits');
  } else {
    try {
      await document.requestStorageAccess();
      console.log('Zugriff gewährt');
    } catch (err) {
      console.warn('Zugriff abgelehnt:', err.name);
      return;
    }
  }
  const user = await ladeNutzerdaten();
  console.log('Angemeldet als', user.name);
});

Zugriff gewährt Angemeldet als Anna

Ohne Nutzergeste anfordern, wenn die Berechtigung schon erteilt ist

const pruefeAutomatisch = async () => {
  if (!document.requestStorageAccess) return false; // Feature-Erkennung
  if (await document.hasStorageAccess()) return true;

  try {
    const status = await navigator.permissions.query({ name: 'storage-access' });
    if (status.state === 'granted') {
      await document.requestStorageAccess(); // keine Geste nötig
      return true;
    }
  } catch {
    // Permissions API kennt 'storage-access' nicht (z. B. Safari)
  }
  return false; // Button anzeigen und auf Klick warten
};

pruefeAutomatisch().then((ok) => console.log('Zugriff:', ok));

Zugriff: true

Nicht partitionierten localStorage anfordern (Chromium)

document.querySelector('#sync').addEventListener('click', async () => {
  try {
    const handle = await document.requestStorageAccess({ localStorage: true });
    // handle.localStorage ist der First-Party-Speicher von widget.example
    const theme = handle.localStorage.getItem('theme') ?? 'hell';
    console.log('Gespeichertes Theme:', theme);
  } catch (err) {
    console.error('Kein Zugriff:', err.name);
  }
});

Gespeichertes Theme: dunkel

Einbettende Seite: sandboxed iframe freigeben

// Auf news.example: iframe mit passender Sandbox-Freigabe erzeugen
const frame = document.createElement('iframe');
frame.src = 'https://widget.example/comments';
frame.sandbox = 'allow-scripts allow-same-origin allow-storage-access-by-user-activation';
document.body.append(frame);

// Wichtig · Fallstricke

Nutzeraktivierung: Ohne vorübergehende Nutzeraktivierung (Klick, Tastendruck) wird das Promise in der Regel mit NotAllowedError zurückgewiesen. Ausnahme in Chromium und Firefox: Die Berechtigung storage-access ist bereits erteilt.
Sandbox: In einem <iframe sandbox> muss das Token allow-storage-access-by-user-activation gesetzt sein. Dokumente mit opakem Ursprung (data:, Sandbox ohne allow-same-origin) erhalten einen SecurityError.
Browserunterschiede: Safari verlangt, dass die Nutzerin die eingebettete Seite zuvor als Hauptseite besucht und dort interagiert hat. Firefox und Chrome gewähren den Zugriff teils automatisch, etwa bei Related Website Sets oder nach wiederholten Interaktionen. Die Dialoge, die Gültigkeitsdauer (in Safari z. B. rund 30 Tage) und die Heuristiken unterscheiden sich je nach Browser.
Der Parameter types und der StorageAccessHandle gibt es nur in Chromium (ab 125). Für andere Browser braucht man eine Feature-Erkennung und einen Fallback.
Bereits geöffnete Verbindungen und schon gelesene Werte werden nach der Freigabe nicht automatisch aktualisiert. Anfragen erst nach dem erfüllten Promise stellen, gegebenenfalls das iframe neu laden.
Nur im sicheren Kontext (HTTPS) verfügbar. Im Top-Level-Dokument wird das Promise sofort erfüllt, denn dort gibt es keine Einschränkung.
Datenschutz: Die API ist kein Ersatz für eine Einwilligung nach DSGVO. Den Zugriff nur für einen klar erkennbaren Nutzen anfordern (z. B. „Mit Konto anmelden“).

Siehe auch

Document.requestStorageAccessFor() Document.hasStorageAccess() Document.createAttributeNS() Document.createAttribute() Document.createCDATASection() Document.hasUnpartitionedCookieAccess() PaymentRequestEvent.changePaymentMethod()