Dokument: requestStorageAccess() Methode

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 der Document-Schnittstelle ermöglicht es Inhalten, die in einem Drittanbieter-Kontext geladen werden (d.h. eingebettet in einem <iframe>), den Zugriff auf Third-Party-Cookies und den unpartitionierten Zustand anzufordern. Dies ist relevant für User Agents, 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 überprüfen, ob die Erlaubnis zum Zugriff auf Drittanbieter-Cookies bereits erteilt wurde, können Sie Permissions.query() aufrufen und den Feature-Namen "storage-access" angeben.

Hinweis: Die Nutzung dieser Funktion kann durch eine vom Server festgelegte Permissions Policy storage-access blockiert werden. Darüber hinaus muss das Dokument zusätzliche, browserspezifische Prüfungen bestehen, wie z. B. Whitelists, Blacklists, On-Device-Klassifizierung, Benutzereinstellungen, Anti-Clickjacking-Heuristiken oder die Aufforderung an den Benutzer zur ausdrücklichen Erlaubnis.

Syntax

requestStorageAccess()
requestStorageAccess(types)

Parameter

types Optional

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

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

Rückgabewert

Ein Promise, der mit undefined erfüllt wird, wenn der Zugriff auf Drittanbieter-Cookies gewährt wurde und kein types-Parameter bereitgestellt wurde, erfüllt mit StorageAccessHandle, wenn der von dem types-Parameter angeforderte unpartitionierte Zustand bereitgestellt wurde, und ablehnt, wenn der Zugang verweigert wurde.

requestStorageAccess()-Anfragen werden automatisch abgelehnt, es sei denn, die eingebetteten Inhalte verarbeiten derzeit eine Benutzerinteraktion wie Tippen oder Klicken (transiente Aktivierung), oder die Erlaubnis wurde bereits zuvor erteilt. Wenn die Erlaubnis nicht zuvor erteilt wurde, müssen sie innerhalb eines benutzerinteraktionsbasierten Ereignishandlers ausgeführt werden. Das Verhalten der Benutzerinteraktion hängt vom Zustand des Versprechens ab:

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

Ausnahmen

InvalidStateError DOMException

Wird ausgelöst, wenn:

Das aktuelle Document noch nicht aktiv ist.
Der types-Parameter bereitgestellt wird 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 oberste Dokument einen null-Ursprung hat.
Das einbettende <iframe> sandboxed ist und das allow-storage-access-by-user-activation Token nicht gesetzt ist.
Die Nutzung durch die Erlaubnisanfrage des User Agents zur Verwendung 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