Document: 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.
Die requestStorageAccess()
-Methode des Document
-Interfaces ermöglicht es Inhalten, die in einem Drittanbieter-Kontext geladen sind (d. h. eingebettet in einem <iframe>
), Zugriff auf Drittanbieter-Cookies und nicht partitionierten Zustand anzufordern. Dies ist relevant für User Agents, die standardmäßig den Zugriff auf Drittanbieter- und 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 Berechtigung zum Zugriff auf Drittanbieter-Cookies bereits gewährt wurde, können Sie Permissions.query()
aufrufen und den Funktionsnamen "storage-access"
angeben.
Hinweis: Die Nutzung dieser Funktion kann durch eine auf Ihrem Server gesetzte storage-access
Berechtigungsrichtlinie blockiert werden. Darüber hinaus muss das Dokument zusätzliche browserspezifische Überprüfungen bestehen, wie z. B. Positivlisten, Negativlisten, ON-Device-Klassifizierungen, Benutzereinstellungen, Anti-Clickjacking-Heuristiken oder das Anfordern einer expliziten Erlaubnis vom Benutzer.
Syntax
requestStorageAccess()
requestStorageAccess(types)
Parameter
types
Optional-
Ein Objekt, das Eigenschaften enthält, die steuern, welcher nicht partitionierte Zustand zugänglich gemacht wird. Wenn nicht angegeben, ist der Standardwert der Eigenschaft
false
. Verfügbare Eigenschaften sind:all
-
Ein Boolean, der angibt, dass alle möglichen nicht partitionierten Zustände zugänglich gemacht werden sollten.
-
Ein Boolean, der angibt, dass Drittanbieter-Cookies zugänglich gemacht werden sollten.
sessionStorage
-
Ein Boolean, der angibt, dass
StorageAccessHandle.sessionStorage
zugänglich gemacht werden sollte. localStorage
-
Ein Boolean, der angibt, dass
StorageAccessHandle.localStorage
zugänglich gemacht werden sollte. indexedDB
-
Ein Boolean, der angibt, dass
StorageAccessHandle.indexedDB
zugänglich gemacht werden sollte. locks
-
Ein Boolean, der angibt, dass
StorageAccessHandle.locks
zugänglich gemacht werden sollte. caches
-
Ein Boolean, der angibt, dass
StorageAccessHandle.caches
zugänglich gemacht werden sollte. getDirectory
-
Ein Boolean, der angibt, dass
StorageAccessHandle.getDirectory()
zugänglich gemacht werden sollte. estimate
-
Ein Boolean, der angibt, dass
StorageAccessHandle.estimate()
zugänglich gemacht werden sollte. createObjectURL
-
Ein Boolean, der angibt, dass
StorageAccessHandle.createObjectURL()
zugänglich gemacht werden sollte. revokeObjectURL
-
Ein Boolean, der angibt, dass
StorageAccessHandle.revokeObjectURL()
zugänglich gemacht werden sollte. BroadcastChannel
-
Ein Boolean, der angibt, dass
StorageAccessHandle.BroadcastChannel()
zugänglich gemacht werden sollte. -
Ein Boolean, 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, oder mit StorageAccessHandle
erfüllt wird, wenn der Zugriff auf nicht partitionierten Zustand, der durch den types
-Parameter angefordert wurde, gewährt wurde, und das verworfen wird, wenn der Zugriff abgelehnt wurde.
requestStorageAccess()
-Anfragen werden automatisch abgelehnt, es sei denn, der eingebettete Inhalt verarbeitet aktuell eine Benutzeraktion wie ein Tippen oder Klicken (transiente Aktivierung), oder die Erlaubnis wurde bereits zuvor gewährt. Wenn die Erlaubnis nicht zuvor gewährt wurde, müssen sie innerhalb eines benutzergestengestützten Ereignis-Handlers ausgeführt werden. Das Verhalten der Benutzeraktion hängt vom Status des Promises ab:
- Wenn das Promise aufgelöst wird (d. h. wenn die Erlaubnis erteilt wurde), wird die Benutzeraktion nicht verbraucht, sodass das Skript anschließend APIs aufrufen kann, die eine Benutzeraktion erfordern.
- Wenn das Promise abgelehnt wird (d. h. die Erlaubnis wurde nicht erteilt), wird die Benutzeraktion verbraucht, sodass das Skript nichts machen kann, was eine Aktion erfordert. Dies ist ein beabsichtigter 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 oberste Dokument einen
null
-Ursprung hat. - Das einbettende
<iframe>
im Sandbox-Modus ist und dasallow-storage-access-by-user-activation
-Token nicht gesetzt ist. - Die Nutzung durch die Erlaubnisanforderung des Benutzeragents zur Nutzung der API abgelehnt 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 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