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
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.
-
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. -
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 Eigenschaftenfalse
sind.
- Das aktuelle
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 dasallow-storage-access-by-user-activation
Token ist nicht gesetzt. - Die Nutzung wird durch die Berechtigungsanfrage des Benutzeragenten zur Verwendung der API verweigert.
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: 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 GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
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.