Document: Methode requestStorageAccessFor()

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig, bevor Sie diese produktiv verwenden.

Die requestStorageAccessFor()-Methode des Document-Interfaces ermöglicht es obersten Websites, Drittanbieter-Cookie-Zugriff für eingebettete Inhalte zu beantragen, die von einer anderen Website im selben verwandten Website-Set stammen. Sie gibt ein Promise zurück, das aufgelöst wird, wenn der Zugriff gewährt wurde, und abgelehnt wird, wenn der Zugriff verweigert wurde.

Syntax

js
requestStorageAccessFor(requestedOrigin)

Parameter

requestedOrigin

Ein String, der die URL des Ursprungs darstellt, für den Sie Drittanbieter-Cookie-Zugriff anfordern.

Rückgabewert

Ein Promise, das mit undefined erfüllt wird, wenn der Zugriff auf Drittanbieter-Cookies gewährt wurde, und abgelehnt wird, wenn der Zugriff verweigert wurde.

requestStorageAccessFor()-Anfragen werden automatisch abgelehnt, es sei denn, der oberste Inhalt verarbeitet derzeit eine Benutzeraktion 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 in einem benutzergestengesteuerten Ereignishandler ausgeführt werden. Das Verhalten der Benutzeraktion hängt vom Stand des Versprechens ab:

  • Wenn das Versprechen aufgelöst wird (d.h. die Erlaubnis wurde erteilt), wurde die Benutzeraktion nicht verbraucht, sodass das Skript anschließend APIs aufrufen kann, die eine Benutzeraktion erfordern.
  • Wenn das Versprechen abgelehnt wird (d.h. die Erlaubnis wurde nicht erteilt), wurde die Benutzeraktion verbraucht, sodass das Skript nichts tun kann, was eine Aktion erfordert. Dies verhindert, dass Skripte requestStorageAccessFor() erneut aufrufen, wenn die Erlaubnis verweigert wurde.

Ausnahmen

InvalidStateError DOMException

Wird ausgelöst, wenn das aktuelle Document noch nicht aktiv ist.

NotAllowedError DOMException

Wird ausgelöst, wenn:

  • Das Fenster des Dokuments kein sicherer Kontext ist.
  • Das Dokument nicht das oberste Dokument ist.
  • Das Dokument einen null-Ursprung hat.
  • Der angegebene requestedOrigin opake ist.
  • Die obersten und eingebetteten Websites nicht im selben verwandten Website-Set sind.
  • Das einbettende <iframe> sandboxed ist und das allow-storage-access-by-user-activation-Token nicht gesetzt ist.
  • Die Nutzung durch eine storage-access Berechtigungsrichtlinie blockiert wird.
  • Die Nutzung durch die Berechtigungsanfrage des Benutzeragents zur Nutzung der API verweigert wird.
TypeError

Wird ausgelöst, wenn requestedOrigin keine gültige URL ist.

Beschreibung

Die Methode requestStorageAccessFor() adressiert Herausforderungen bei der Einführung der Storage Access API auf obersten Websites, die plattformübergreifende Bilder oder Skripte verwenden, die Cookies benötigen. Sie ist für Benutzeragenten relevant, die standardmäßig den Zugriff auf Drittanbieter-, unpartitionierte Cookies blockieren, um die Privatsphäre zu verbessern (z.B. um Tracking zu verhindern), und ist eine vorgeschlagene Erweiterung der Storage Access API.

requestStorageAccessFor() kann Drittanbieter-Cookie-Zugriff für plattformübergreifende Ressourcen ermöglichen, die direkt in eine oberste Website eingebettet sind und selbst keinen Speicherzugriff anfordern können, zum Beispiel <img>-Elemente. Plattformübergreifende Inhalte, die in <iframe>s eingebettet sind, eigene Logik und Ressourcen haben und Drittanbieter-Cookie-Zugriff benötigen, sollten den Speicherzugriff über Document.requestStorageAccess() anfordern.

Um zu überprüfen, ob die Erlaubnis zum Zugriff auf Drittanbieter-Cookies bereits über requestStorageAccessFor() erteilt wurde, können Sie Permissions.query() aufrufen und den Funktionsnamen "top-level-storage-access" angeben. Dies unterscheidet sich vom Funktionsnamen, der für die reguläre Document.requestStorageAccess()-Methode verwendet wird, der "storage-access" lautet.

Der Permissions.query()-Aufruf muss den eingebetteten Ursprung angeben; zum Beispiel:

js
navigator.permissions.query({
  name: "top-level-storage-access",
  requestedOrigin: "https://www.example.com",
});

Hinweis: Die Nutzung dieser Funktion kann durch eine storage-access Berechtigungsrichtlinie blockiert werden, die auf Ihrem Server festgelegt ist (die gleiche, die den Rest der Storage Access API steuert). Außerdem muss das Dokument zusätzliche, browserspezifische Prüfungen bestehen, wie z.B. Zulassungslisten, Sperrlisten, Geräteklassifizierung, Benutzereinstellungen oder Anti-Clickjacking-Heuristiken.

Beispiele

js
function rSAFor() {
  if ("requestStorageAccessFor" in document) {
    document.requestStorageAccessFor("https://example.com").then(
      (res) => {
        // Use storage access
        doThingsWithCookies();
      },
      (err) => {
        // Handle errors
      },
    );
  }
}

Nach einem erfolgreichen requestStorageAccessFor()-Aufruf werden plattformübergreifende Anfragen Cookies enthalten, wenn sie CORS / crossorigin beinhalten, sodass Websites möglicherweise warten möchten, bevor sie eine Anfrage auslösen. Solche Anfragen müssen die Option credentials: "include" verwenden und Ressourcen müssen das Attribut crossorigin="use-credentials" beinhalten.

Zum Beispiel:

js
function checkCookie() {
  fetch("https://example.com/getcookies.json", {
    method: "GET",
    credentials: "include",
  })
    .then((response) => response.json())
    .then((json) => {
      // Do something
    });
}

Hinweis: Siehe Verwendung der Storage Access API für ein ausführlicheres Beispiel.

Spezifikationen

Specification
requestStorageAccessFor API
# dom-document-requeststorageaccessfor

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch