Dokument: Methode requestStorageAccessFor()

Syntax

requestStorageAccessFor(requestedOrigin)

Parameter

requestedOrigin

Ein String mit der URL des Ursprungs, 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.

Anfragen mit requestStorageAccessFor() werden automatisch abgelehnt, sofern der Top-Level-Inhalt nicht gerade eine Nutzerinteraktion wie ein Tippen oder Klicken verarbeitet (transiente Aktivierung) oder die Berechtigung nicht bereits zuvor erteilt wurde. Wurde die Berechtigung nicht zuvor erteilt, müssen sie innerhalb eines Ereignishandlers ausgeführt werden, der durch eine Nutzerinteraktion ausgelöst wurde. Wie sich die Nutzerinteraktion auswirkt, hängt vom Zustand des Promise ab:

• Wird das Promise erfüllt (d.h. die Berechtigung wurde erteilt), wurde die Nutzerinteraktion nicht verbraucht. Das Skript kann anschließend also APIs aufrufen, die eine Nutzerinteraktion erfordern.
• Wird das Promise abgelehnt (d.h. die Berechtigung wurde nicht erteilt), wurde die Nutzerinteraktion verbraucht. Das Skript kann daher nichts mehr ausführen, was eine Nutzerinteraktion erfordert. Dies verhindert, dass Skripte requestStorageAccessFor() erneut aufrufen, wenn die Berechtigung 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 Top-Level-Dokument ist.
• das Dokument einen null-Ursprung hat.
• der angegebene requestedOrigin opak ist.
• die Top-Level-Website und die eingebettete Website nicht zum selben Verbund zusammengehöriger Websites gehören.
• das einbettende <iframe> durch eine Sandbox eingeschränkt ist und das Token allow-storage-access-by-user-activation nicht gesetzt ist.
• die Verwendung durch eine storage-access-Permissions Policy blockiert wird.
• die Verwendung durch die Berechtigungsabfrage des User Agents für die API verweigert wird.

TypeError

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

Beschreibung

Die Methode requestStorageAccessFor() hilft bei Herausforderungen, die sich bei der Einführung der Storage Access API auf Top-Level-Websites ergeben, die websiteübergreifende Bilder oder Skripte verwenden, für die Cookies erforderlich sind. Sie ist für User Agents relevant, die den Zugriff auf Drittanbieter-Cookies, die nicht partitioniert sind, standardmäßig blockieren, um den Datenschutz zu verbessern (z. B. um Tracking zu verhindern). Sie ist eine vorgeschlagene Erweiterung der Storage Access API.

requestStorageAccessFor() kann den Zugriff auf Drittanbieter-Cookies für websiteübergreifende Ressourcen ermöglichen, die direkt in eine Top-Level-Website eingebettet sind und selbst keinen Speicherzugriff anfordern können, beispielsweise <img>-Elemente. Websiteübergreifende Inhalte, die in <iframe>-Elemente eingebettet sind, über eigene Logik und Ressourcen verfügen und Zugriff auf Drittanbieter-Cookies benötigen, sollten den Speicherzugriff über Document.requestStorageAccess() anfordern.

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

Beim Aufruf von Permissions.query() muss der eingebettete Ursprung angegeben werden, 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() enthalten websiteübergreifende Anfragen Cookies, wenn sie CORS / crossorigin verwenden. Websites sollten daher gegebenenfalls warten, bevor sie eine Anfrage auslösen. Solche Anfragen müssen die Option credentials: "include" verwenden, und Ressourcen müssen das Attribut crossorigin="use-credentials" 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)