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, in einem Drittanbieter-Kontext geladenen Inhalten (d.h. eingebettet in einem <iframe>) den Zugriff auf Drittanbieter-Cookies und unpartitionierten Zustand zu beantragen. Dies ist relevant für Benutzeragenten, die standardmäßig den Zugriff auf Drittanbieter- und 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 Berechtigung zum Zugriff auf Drittanbieter-Cookies bereits erteilt wurde, können Sie Permissions.query() aufrufen und den Funktionsnamen "storage-access" angeben.

Nachdem ein eingebetteter Inhalt die storage-access Berechtigung über requestStorageAccess() aktiviert hat, sollte er sich selbst neu laden. Der Browser wird die Ressource mit Drittanbieter-unpartitionierten Cookies erneut anfordern und diese dem eingebetteten Inhalt zur Verfügung stellen, sobald er geladen ist.

Drittanbieter-Cookies werden nur mit Anfragen an den genauen Ursprung der eingebetteten Ressource gesendet. Andere Ursprünge innerhalb derselben Seite, die Zugriff auf ihre Drittanbieter-Cookies wünschen, müssen die gewährte Zugriffsberechtigung aktivieren. Die storage access headers sollten zur Aktivierung einer gewährten storage-access Berechtigung verwendet werden. Beachten Sie, dass die Header eine gewährte Berechtigung für jede eingebettete Ressource aktivieren können, z.B. für authentifizierte Bilder, nicht nur für in einem <iframe> eingebetteten Code.

Es ist auch möglich, eine gewährte Berechtigung für einen cross-origin, same-site Endpunkt zu aktivieren, indem requestStorageAccess() aufgerufen wird (diesmal ohne die Anforderung für vorübergehende Aktivierung). Dies funktioniert jedoch nur, um die Berechtigung für eingebetteten Code zu aktivieren. Es ist auch weniger effizient als die Verwendung der Header, da die Ressource geladen werden muss, um die Berechtigung zu aktivieren.

Hinweis: Die Nutzung dieses Features kann durch eine storage-access Berechtigungsrichtlinie, die auf Ihrem Server festgelegt ist, blockiert werden. Zusätzlich muss das Dokument zusätzliche browser-spezifische Prüfungen bestehen, wie z.B. Whitelists, Blacklists, geräteinterne Klassifikation, Benutzereinstellungen, Anti-Clickjacking Heuristiken oder die Aufforderung an den Benutzer, eine explizite Genehmigung zu erteilen.

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 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, das mit undefined erfüllt wird, wenn der Zugriff auf Drittanbieter-Cookies gewährt wurde und kein types Parameter angegeben wurde, mit StorageAccessHandle erfüllt wird, wenn der Zugriff auf den vom types Parameter angeforderten unpartitionierten Zustand gewährt wurde, und abgelehnt wird, wenn der Zugriff verweigert wurde.

requestStorageAccess() Anfragen werden automatisch abgelehnt, es sei denn, der eingebettete Inhalt verarbeitet gerade eine Nutzeraktion wie einen Tap oder Klick (transiente Aktivierung), oder die Berechtigung wurde bereits zuvor erteilt. Wenn die Berechtigung nicht zuvor erteilt wurde, müssen sie innerhalb eines auf Nutzeraktionen basierenden Event-Handlers ausgeführt werden. Das Verhalten der Nutzeraktion hängt vom Zustand des Promises ab:

Wenn das Promise gelöst wird (d.h. wenn die Berechtigung erteilt wurde), dann wurde die Nutzeraktion nicht verbraucht, so dass das Skript anschließend APIs aufrufen kann, die eine Nutzeraktion erfordern.
Wenn das Promise abgelehnt wird (d.h. die Berechtigung wurde nicht erteilt), dann wurde die Nutzeraktion verbraucht, so dass das Skript nichts tun kann, was eine Nutzeraktion erfordert. Dies ist ein beabsichtigter Schutz gegen Missbrauch — es verhindert, dass Skripte requestStorageAccess() in einer Schleife aufrufen, bis der Benutzer die Eingabeaufforderung akzeptiert.

Ausnahmen

InvalidStateError DOMException

Ausgelöst, wenn:

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

NotAllowedError DOMException

Ausgelöst, wenn:

Das Fenster des Dokuments kein sicherer Kontext ist.
Die Nutzung durch eine storage-access Berechtigungsrichtlinie blockiert wird.
Das Dokument oder das oberste Dokument hat einen null Ursprung.
Das eingebettete <iframe> ist sandboxed, und das allow-storage-access-by-user-activation Token ist nicht gesetzt.
Die Nutzung wird durch die Berechtigungsanfrage des Benutzeragenten zur Nutzung der API verweigert.

Beispiele

Grundlegende Verwendung

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 Verwendung der Storage Access API für ein vollständigeres Beispiel.

Spezifikationen

Specification
The Storage Access API # dom-document-requeststorageaccess

Browser-Kompatibilität

Siehe auch

Help improve MDN

Learn how to contribute Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden