Document.requestStorageAccessFor() — Methode · JavaScript-Referenz

Signatur

Document.prototype.requestStorageAccessFor(requestedOrigin)

Beschreibung

document.requestStorageAccessFor() ist das Gegenstück zu document.requestStorageAccess(), arbeitet aber aus Sicht der obersten Seite (Top-Level-Dokument). Die Top-Level-Seite fragt im Namen einer anderen Origin (requestedOrigin) an, damit deren eingebettete Ressourcen, etwa Bilder, Skripte oder fetch()-Anfragen, trotz blockierter Drittanbieter-Cookies ihre ungeteilten Cookies mitsenden dürfen.

Gedacht ist die Methode für Websites, die zu einem gemeinsamen Related Website Set (früher „First-Party Sets“) gehören, zum Beispiel shop.example und cdn-example.com desselben Betreibers. Der Browser gewährt den Zugriff nur, wenn beide Sites im selben Set eingetragen sind. In der Regel ist außerdem eine vorübergehende Benutzeraktivierung nötig, die Methode muss also in einem Handler für eine Nutzeraktion wie click aufgerufen werden. Anders als bei requestStorageAccess() wird dabei kein Dialog angezeigt: Der Browser entscheidet allein anhand der Set-Zugehörigkeit.

Nach einer Erlaubnis gilt der Zugriff nur für CORS-Anfragen an die angefragte Origin. Dazu gehören fetch() mit credentials: "include" und <img>- oder <script>-Elemente mit dem Attribut crossorigin="use-credentials". Ob die Berechtigung schon erteilt wurde, lässt sich mit navigator.permissions.query({ name: "top-level-storage-access", requestedOrigin }) prüfen.

Parameter

Name	Typ	Default	Beschreibung
$requestedOrigin Pflicht	string		URL bzw. Origin der eingebetteten Website, für die der Cookie-Zugriff angefragt wird, z. B. `"https://cdn-example.com"`. Sie muss zum selben Related Website Set gehören wie die Top-Level-Seite.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, wenn der Zugriff gewährt wurde. Es wird abgelehnt mit InvalidStateError (Dokument ist nicht aktiv oder nicht das Top-Level-Dokument), NotAllowedError (Zugriff verweigert, z. B. fehlende Benutzeraktivierung oder kein gemeinsames Set), NotAllowedError/SecurityError bei opaken Origins oder mit TypeError bei einer ungültigen URL.

Beispiele

Zugriff per Klick anfordern

const CDN_ORIGIN = "https://cdn-example.com";

document.querySelector("#login-sync").addEventListener("click", async () => {
  if (!("requestStorageAccessFor" in document)) {
    console.log("requestStorageAccessFor wird nicht unterstützt");
    return;
  }
  try {
    await document.requestStorageAccessFor(CDN_ORIGIN);
    console.log("Zugriff gewährt");
  } catch (err) {
    console.log(`Zugriff verweigert: ${err.name}`);
  }
});

Zugriff gewährt

Berechtigung vorab prüfen und danach Daten mit Cookies laden

const origin = "https://cdn-example.com";

const loadProfile = async () => {
  const res = await fetch(`${origin}/api/profile`, {
    credentials: "include", // CORS-Anfrage mit Cookies
    mode: "cors"
  });
  return res.json();
};

const init = async () => {
  const status = await navigator.permissions.query({
    name: "top-level-storage-access",
    requestedOrigin: origin
  });

  if (status.state === "granted") {
    // Bereits erlaubt: Aufruf klappt auch ohne Benutzeraktivierung
    await document.requestStorageAccessFor(origin);
    console.log(await loadProfile());
  } else {
    console.log(`Status: ${status.state} – auf Klick warten`);
  }
};

init();

Status: prompt – auf Klick warten

Bild mit Cookies nach der Freigabe einbinden

const origin = "https://cdn-example.com";

document.querySelector("#show-avatar").addEventListener("click", async () => {
  await document.requestStorageAccessFor(origin);

  const img = new Image();
  img.crossOrigin = "use-credentials"; // nötig, damit Cookies gesendet werden
  img.src = `${origin}/user/avatar.png`;
  img.alt = "Profilbild";
  document.body.append(img);
});

// Wichtig · Fallstricke

Browserunterstützung: Die Methode ist experimentell und nicht standardisiert. Sie funktioniert nur in Chromium-Browsern (Chrome/Edge ab 119), nicht in Firefox oder Safari. Weil Google die Related Website Sets im Zuge der Privacy Sandbox zurückfährt, gilt sie als Auslaufmodell. Vor dem Aufruf immer mit "requestStorageAccessFor" in document prüfen, ob sie vorhanden ist, und eine Ausweichlösung bereithalten.
Nur im Top-Level-Dokument: Wird die Methode aus einem <iframe> aufgerufen, wird das Promise mit InvalidStateError abgelehnt. Iframes verwenden stattdessen document.requestStorageAccess().
Benutzeraktivierung: Ohne vorübergehende Benutzeraktivierung, etwa einen Klick, wird die Anfrage abgelehnt. Ausnahme: Die Berechtigung wurde schon früher erteilt.
Nur CORS-Anfragen: Die Freigabe betrifft nur Anfragen mit Anmeldedaten im CORS-Modus. Der Server muss dafür Access-Control-Allow-Origin mit der genauen Origin und Access-Control-Allow-Credentials: true senden. Die Cookies selbst brauchen SameSite=None; Secure.
Sicherheit: Nur Origins aus dem eigenen Related Website Set freigeben. Die Freigabe erlaubt siteübergreifendes Wiedererkennen der Nutzer und sollte deshalb bewusst und gezielt eingesetzt werden.

Siehe auch

Document.requestStorageAccess() Document.hasStorageAccess() Permissions.query() Document new MediaStreamTrackProcessor() PaymentRequestEvent.changePaymentMethod()