Dokumentation: 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.

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

Um zu prüfen, ob bereits die Berechtigung zum Zugriff auf Drittanbieter-Cookies gewährt wurde, kann Permissions.query() mit dem Feature-Namen "storage-access" aufgerufen werden.

Hinweis: Die Nutzung dieses Features kann durch eine storage-access Berechtigungsrichtlinie, die auf Ihrem Server festgelegt ist, blockiert werden. Zusätzlich muss das Dokument weitere, browserspezifische Prüfungen bestehen, wie z.B. Whitelists, Blacklists, Klassifikationen auf dem Gerät, Benutzereinstellungen, Anti-Clickjacking-Heuristiken oder die Aufforderung an den Benutzer, eine explizite Berechtigung zu erteilen.

Syntax

js
requestStorageAccess()
requestStorageAccess(types)

Parameter

types Optional

Ein Objekt, das Eigenschaften enthält, die regulieren, welcher unpartitionierte Zustand zugänglich gemacht wird. Wenn nicht angegeben, lautet der Standardwert der Eigenschaft false. Die verfügbaren 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 bereitgestellt wurde, erfüllt mit StorageAccessHandle, wenn der Zugriff auf den durch den 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 derzeit eine Benutzerinteraktion wie einen Tipp oder Klick (transiente Aktivierung), oder die Erlaubnis wurde bereits zuvor erteilt. Falls die Erlaubnis zuvor nicht erteilt wurde, müssen sie innerhalb eines benutzergesteuerten Ereignis-Handlers ausgeführt werden. Das Verhalten des Benutzer-Gesten hängt vom Zustand des Promise ab:

  • Wenn das Promise erfüllt wird (d. h. wenn die Berechtigung erteilt wurde), wurde die Benutzer-Geste nicht verbraucht, sodass das Skript anschließend APIs aufrufen kann, die eine Benutzer-Geste erfordern.
  • Wenn das Promise abgelehnt wird (d. h. die Berechtigung wurde nicht erteilt), wurde die Benutzer-Geste verbraucht, sodass das Skript nichts tun kann, das eine Geste erfordert. Dies ist ein absichtlicher Schutz gegen Missbrauch — es verhindert, dass Skripte requestStorageAccess() in einer Schleife aufrufen, bis der Benutzer das Prompt 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 oberste Dokument einen null-Ursprung hat.
  • Das einbettende <iframe> gesandboxed ist und das allow-storage-access-by-user-activation-Token nicht gesetzt ist.
  • Die Nutzung durch die Erlaubnisanfrage des Benutzeragenten zur Nutzung der API verweigert wird.

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

Spezifikationen

Specification
The Storage Access API
# dom-document-requeststorageaccess

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch