Dokument: Methode requestStorageAccess()

Baseline 2023 *

Newly available

Since December 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Some parts of this feature may have varying levels of support.

Die requestStorageAccess()-Methode des Document-Interfaces ermöglicht es Inhalten, die in einem Drittanbieter-Kontext geladen sind (z.B. eingebettet in einem <iframe>), den Zugriff auf Drittanbieter-Cookies und unpartitionierten Zustand anzufordern. Dies ist relevant für Benutzeragenten, die standardmäßig den Zugriff auf Drittanbieter-unpartitionierte Cookies blockieren, um die Privatsphäre zu verbessern (z.B. um Tracking zu verhindern), und ist Teil der Storage Access API.

Um zu prüfen, ob die Erlaubnis zum Zugriff auf Drittanbieter-Cookies bereits erteilt wurde, können Sie Permissions.query() aufrufen, wobei der Funktionsname "storage-access" spezifiziert wird.

Hinweis: Die Nutzung dieser Funktion kann von einer auf Ihrem Server gesetzten storage-access Permissions Policy blockiert werden. Zudem muss das Dokument zusätzliche browser-spezifische Überprüfungen bestehen, wie z.B. Whitelists, Blacklists, geräteinterne Klassifikationen, Benutzereinstellungen, Anti-Clickjacking Heuristiken oder das Abfragen der ausdrücklichen Zustimmung des Benutzers.

Syntax

requestStorageAccess()
requestStorageAccess(types)

Parameter

types Optional

Ein Objekt, das Eigenschaften enthält, die steuern, welcher unpartitionierte Zustand zugänglich gemacht wird. Wenn nicht angegeben, ist der Standardwert der Eigenschaft false. Verfügbare Eigenschaften sind wie folgt:

all: Ein Boolean, der spezifiziert, dass alle möglichen unpartitionierten Zustände zugänglich gemacht werden sollen.
cookies: Ein Boolean, der spezifiziert, dass Drittanbieter-Cookies zugänglich gemacht werden sollen.
sessionStorage: Ein Boolean, der spezifiziert, dass StorageAccessHandle.sessionStorage zugänglich gemacht werden soll.
localStorage: Ein Boolean, der spezifiziert, dass StorageAccessHandle.localStorage zugänglich gemacht werden soll.
indexedDB: Ein Boolean, der spezifiziert, dass StorageAccessHandle.indexedDB zugänglich gemacht werden soll.
locks: Ein Boolean, der spezifiziert, dass StorageAccessHandle.locks zugänglich gemacht werden soll.
caches: Ein Boolean, der spezifiziert, dass StorageAccessHandle.caches zugänglich gemacht werden soll.
getDirectory: Ein Boolean, der spezifiziert, dass StorageAccessHandle.getDirectory() zugänglich gemacht werden soll.
estimate: Ein Boolean, der spezifiziert, dass StorageAccessHandle.estimate() zugänglich gemacht werden soll.
createObjectURL: Ein Boolean, der spezifiziert, dass StorageAccessHandle.createObjectURL() zugänglich gemacht werden soll.
revokeObjectURL: Ein Boolean, der spezifiziert, dass StorageAccessHandle.revokeObjectURL() zugänglich gemacht werden soll.
BroadcastChannel: Ein Boolean, der spezifiziert, dass StorageAccessHandle.BroadcastChannel() zugänglich gemacht werden soll.
SharedWorker: Ein Boolean, der spezifiziert, dass StorageAccessHandle.SharedWorker() zugänglich gemacht werden soll.

Rückgabewert

Ein Promise, das mit undefined erfüllt wird, wenn der Zugriff auf Drittanbieter-Cookies gewährt wurde und kein types-Parameter bereitgestellt wurde, erfüllt wird mit StorageAccessHandle, wenn der Zugriff auf den vom types-Parameter angeforderten unpartitionierten Zustand gewährt wurde, und abgewiesen wird, wenn der Zugriff verweigert wurde.

requestStorageAccess()-Anfragen werden automatisch abgelehnt, es sei denn, der eingebettete Inhalt verarbeitet derzeit eine Benutzeraktion wie einen Tipp oder Klick (transient activation), oder die Erlaubnis wurde bereits zuvor erteilt. Wenn die Erlaubnis nicht zuvor erteilt wurde, müssen sie innerhalb eines auf Benutzeraktionen basierenden Ereignishandlers ausgeführt werden. Das Verhalten der Benutzeraktion hängt vom Zustand des Versprechens ab:

Wenn das Versprechen erfüllt wird (d.h. wenn die Erlaubnis erteilt wurde), wurde die Benutzeraktion nicht konsumiert, sodass das Skript anschließend APIs aufrufen kann, die eine Benutzeraktion erfordern.
Wenn das Versprechen abgelehnt wird (d.h. die Erlaubnis wurde nicht erteilt), wurde die Benutzeraktion konsumiert, sodass das Skript nichts tun kann, das eine Aktion erfordert. Dies ist ein beabsichtigter Schutz gegen Missbrauch — es verhindert, dass Skripte requestStorageAccess() in einer Schleife aufrufen, bis der Benutzer das Eingabeaufforderung akzeptiert.

Ausnahmen

InvalidStateError DOMException

Wird ausgelöst, wenn:

Das aktuelle Document noch nicht aktiv ist.
Der types-Parameter angegeben ist und alle seine Eigenschaften false sind.

NotAllowedError DOMException

Wird ausgelöst, wenn:

Das Fenster des Dokuments kein sicherer Kontext ist.
Die Nutzung durch eine storage-access Permissions Policy blockiert wird.
Das Dokument oder das Top-Level-Dokument einen null-Ursprung hat.
Das einbettende <iframe> im Sandbox-Modus ist und das Token allow-storage-access-by-user-activation nicht gesetzt ist.
Die Nutzung durch die Berechtigungsanforderung des Benutzeragenten zur Nutzung der API verweigert wird.

Beispiele

document.requestStorageAccess().then(
  () => {
    console.log("cookie access granted");
  },
  () => {
    console.log("cookie access denied");
  },
);

document.requestStorageAccess({ localStorage: true }).then(
  (handle) => {
    console.log("localStorage access granted");
    handle.localStorage.setItem("foo", "bar");
  },
  () => {
    console.log("localStorage access denied");
  },
);

Hinweis: Siehe Using the Storage Access API für ein vollständigeres Beispiel.

Spezifikationen

Specification
The Storage Access API # dom-document-requeststorageaccess