Document: requestStorageAccessFor() Methode

Syntax

requestStorageAccessFor(requestedOrigin)

Parameter

requestedOrigin

Ein String, der die URL des Ursprungs darstellt, für den Sie Zugriff auf Drittanbieter-Cookies 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 Hauptinhalt verarbeitet gerade eine Benutzerinteraktion wie Tippen oder Klicken (flüchtige Aktivierung), oder die Erlaubnis wurde bereits zuvor gewährt. Wenn die Erlaubnis nicht zuvor erteilt wurde, müssen sie innerhalb eines ereignisbasierten Nutzerinteraktions-Handlers ausgeführt werden. Das Verhalten der Benutzerinteraktion hängt vom Zustand des Versprechens ab:

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

Ausnahmen

InvalidStateError DOMException

Wird geworfen, wenn das aktuelle Document noch nicht aktiv ist.

NotAllowedError DOMException

Wird geworfen, wenn:

• Das Fenster des Dokuments kein sicherer Kontext ist.
• Das Dokument nicht das Hauptdokument ist.
• Das Dokument einen null-Ursprung hat.
• Der angegebene requestedOrigin undurchsichtig ist.
• Die Haupt- und eingebetteten Websites nicht im selben verwandten Website-Set sind.
• Das einbettende <iframe> sandkastenfähig ist und das allow-storage-access-by-user-activation-Token nicht gesetzt ist.
• Die Nutzung durch eine storage-access Permissions Policy blockiert wird.
• Die Nutzung durch die Berechtigungsanforderung des Benutzeragenten zur Nutzung der API abgelehnt wird.

TypeError

Wird geworfen, wenn requestedOrigin keine gültige URL ist.

Beschreibung

Die requestStorageAccessFor()-Methode adressiert Herausforderungen bei der Einführung der Storage Access API auf Hauptwebseiten, die standortübergreifende Bilder oder Skripte verwenden, die Cookies benötigen. Sie ist relevant für Benutzeragenten, 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 Zugriff auf Drittanbieter-Cookies für ressourcenübergreifende Inhalte aktivieren, die direkt in eine Hauptwebseite eingebettet sind und selbst keinen Speicherzugriff anfordern können, z.B. <img>-Elemente. Standotverwandte Inhalte, die in <iframe>s eingebettet sind und ihre eigene Logik und Ressourcen haben und Zugriff auf Drittanbieter-Cookies 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, wobei Sie den Funktionsnamen „top-level-storage-access“ angeben. Dies unterscheidet sich vom Funktionsnamen, der für die reguläre Methode Document.requestStorageAccess() verwendet wird, der „storage-access“ lautet.

Der Permissions.query()-Aufruf muss die eingebettete Herkunft spezifizieren; zum Beispiel:

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

Beispiele

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

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

Zum Beispiel:

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

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Document.hasStorageAccess(), Document.hasUnpartitionedCookieAccess(), Document.requestStorageAccess()
• Verwendung der Storage Access API
• Einführung in die Storage Access API (WebKit-Blog)