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 des Document Interface ermöglicht es, Inhalten, die in einem Drittanbieter-Kontext geladen sind (d. h. eingebettet in einem <iframe>), Zugriff auf Drittanbieter-Cookies und nicht partitionierten Status anzufordern. Dies ist relevant für Benutzeragenten, die standardmäßig den Zugriff auf Drittanbieter-nicht partitionierte 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 könnte durch eine storage-access Berechtigungsrichtlinie blockiert werden, die auf Ihrem Server gesetzt ist. Außerdem muss das Dokument zusätzliche browserspezifische Prüfungen bestehen, wie Whitelists, Blacklists, Geräteklassifizierungen, Benutzereinstellungen, Anti-Clickjacking Heuristiken oder die Aufforderung an den Benutzer, eine ausdrückliche Erlaubnis zu erteilen.

Syntax

js
requestStorageAccess()
requestStorageAccess(types)

Parameter

types Optional

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

all

Ein boolescher Wert, der angibt, dass alle möglichen nicht partitionierten Zustände zugänglich gemacht werden sollten.

cookies

Ein boolescher Wert, der angibt, dass Drittanbieter-Cookies zugänglich gemacht werden sollten.

sessionStorage

Ein boolescher Wert, der angibt, dass StorageAccessHandle.sessionStorage zugänglich gemacht werden sollte.

localStorage

Ein boolescher Wert, der angibt, dass StorageAccessHandle.localStorage zugänglich gemacht werden sollte.

indexedDB

Ein boolescher Wert, der angibt, dass StorageAccessHandle.indexedDB zugänglich gemacht werden sollte.

locks

Ein boolescher Wert, der angibt, dass StorageAccessHandle.locks zugänglich gemacht werden sollte.

caches

Ein boolescher Wert, der angibt, dass StorageAccessHandle.caches zugänglich gemacht werden sollte.

getDirectory

Ein boolescher Wert, der angibt, dass StorageAccessHandle.getDirectory() zugänglich gemacht werden sollte.

estimate

Ein boolescher Wert, der angibt, dass StorageAccessHandle.estimate() zugänglich gemacht werden sollte.

createObjectURL

Ein boolescher Wert, der angibt, dass StorageAccessHandle.createObjectURL() zugänglich gemacht werden sollte.

revokeObjectURL

Ein boolescher Wert, der angibt, dass StorageAccessHandle.revokeObjectURL() zugänglich gemacht werden sollte.

BroadcastChannel

Ein boolescher Wert, der angibt, dass StorageAccessHandle.BroadcastChannel() zugänglich gemacht werden sollte.

SharedWorker

Ein boolescher Wert, der angibt, dass StorageAccessHandle.SharedWorker() zugänglich gemacht werden sollte.

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, wird mit StorageAccessHandle erfüllt, wenn der Zugriff auf einen nicht partitionierten Status, der durch den types Parameter angefordert wurde, gewährt wurde, und wird abgelehnt, wenn der Zugriff verweigert wurde.

requestStorageAccess() Anfragen werden automatisch verweigert, es sei denn, der eingebettete Inhalt verarbeitet derzeit eine Benutzergeste wie einen Tap oder Klick (transiente Aktivierung), oder die Erlaubnis wurde bereits zuvor gewährt. Wenn die Erlaubnis nicht zuvor gewährt wurde, müssen sie innerhalb eines benutzergesteuerten Ereignishandlers ausgeführt werden. Das Benutzergestenverhalten hängt vom Zustand des Versprechens ab:

  • Wenn das Versprechen eingelöst wird (d. h., wenn die Erlaubnis erteilt wurde), wurde die Benutzergeste nicht verbraucht, sodass das Skript anschließend APIs aufrufen kann, die eine Benutzergeste erfordern.
  • Wenn das Versprechen abgelehnt wird (d. h. die Erlaubnis wurde nicht erteilt), wurde die Benutzergeste verbraucht, sodass das Skript nichts tun kann, was eine Geste 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 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 Berechtigungsrichtlinie blockiert wird.
  • Das Dokument oder das übergeordnete Dokument hat einen null Ursprung.
  • Das einbettende <iframe> ist in einer Sandbox, und das allow-storage-access-by-user-activation Token ist nicht gesetzt.
  • Die Nutzung wird durch die Berechtigungsanfrage des Benutzeragenten zur Verwendung der API verweigert.

Beispiele

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

Spezifikationen

Specification
The Storage Access API
# dom-document-requeststorageaccess

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
requestStorageAccess
types parameter
types.BroadcastChannel parameter
types.SharedWorker parameter
types.all parameter
types.caches parameter
types.cookies parameter
types.createObjectURL parameter
types.estimate parameter
types.getDirectory parameter
types.indexedDB parameter
types.localStorage parameter
types.locks parameter
types.revokeObjectURL parameter
types.sessionStorage parameter

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.

Siehe auch