Dokument: requestStorageAccessFor() Methode

Syntax

requestStorageAccessFor(requestedOrigin)

Parameter

requestedOrigin

Ein String, der die URL des Ursprungs repräsentiert, für die 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 oberste Inhalt verarbeitet gerade eine Benutzeraktion wie einen Tap oder Klick (transiente Aktivierung), oder die Erlaubnis wurde bereits zuvor erteilt. Falls die Erlaubnis nicht zuvor erteilt wurde, müssen sie innerhalb eines benutzeraktionsbasierten Event-Handlers ausgeführt werden. Das Benutzeraktionsverhalten hängt vom Status des Versprechens ab:

• Wenn das Versprechen erfüllt wird (d.h. die Erlaubnis wurde erteilt), wurde die Benutzeraktion nicht verbraucht, und das Skript kann anschließend APIs aufrufen, die eine Benutzeraktion erfordern.
• Wenn das Versprechen abgelehnt wird (d.h. die Erlaubnis wurde nicht erteilt), wurde die Benutzeraktion verbraucht, und das Skript kann nichts ausführen, was eine Aktion 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 oberste Dokument ist.
• Das Dokument einen null Ursprung hat.
• Der angegebene requestedOrigin opak ist.
• Die oberste und eingebetteten Websites nicht im selben zusammenhängenden Website-Set sind.
• Das eingebettete <iframe> gesandboxt ist, und das allow-storage-access-by-user-activation Token nicht gesetzt ist.
• Die Nutzung durch eine storage-access Berechtigungsrichtlinie blockiert ist.
• Die Nutzung durch die Berechtigungsanfrage 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 obersten Websites, die plattformü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 (zum Beispiel, um Tracking zu verhindern) und ist eine vorgeschlagene Erweiterung der Storage Access API.

requestStorageAccessFor() kann den Zugriff auf Drittanbieter-Cookies für plattformübergreifende Ressourcen direkt ermöglichen, die in eine oberste Website eingebettet sind und selbst keinen Speicherzugriff anfordern können, beispielsweise <img> Elemente. Plattformübergreifende Inhalte, die in <iframe>s eingebettet sind, 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 bereits die Erlaubnis zum Zugriff auf Drittanbieter-Cookies über requestStorageAccessFor() erteilt wurde, können Sie Permissions.query() aufrufen und den Funktionsnamen "top-level-storage-access" spezifizieren. Dies unterscheidet sich von dem Funktionsnamen, der für die reguläre Document.requestStorageAccess() Methode verwendet wird, der "storage-access" ist.

Der Permissions.query() Aufruf muss den eingebetteten Ursprung 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 requestStorageAccessFor() Aufruf werden plattformübergreifende Anforderungen Cookies enthalten, wenn sie CORS / crossorigin umfassen, sodass Websites eventuell warten möchten, bevor sie eine Anforderung 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()
• Die Verwendung der Storage Access API
• Einführung der Storage Access API (WebKit Blog)