Verwendung der Storage Access API

Nutzungshinweise

Die Storage Access API wurde entwickelt, um eingebetteten Inhalten zu ermglichen, Zugriff auf Third-party Cookies und unpartitionierten Zustand anzufordern die meisten modernen Browser blockieren standardmig solchen Zugriff, um die Privatsphre der Nutzer zu schtzen. Da eingebettete Inhalte nicht wissen, wie sich ein Browser in dieser Hinsicht verhalten wird, ist es am besten, stets zu berprfen, ob das eingebettete <iframe> Speicherkapazitt hat, bevor versucht wird, ein Cookie zu lesen oder zu schreiben. Dies gilt insbesondere fr den Zugriff auf Document.cookie, da Browser oft ein leeres Cookie-Glas zurckgeben, wenn der Zugriff auf Third-party Cookies blockiert wird.

Im folgenden Beispiel zeigen wir, wie ein eingebettetes cross-site <iframe> auf Third-party Cookies und unpartitionierten Zustand zugreifen kann, unter einer Browser-Speicherzugriffspolitik, die den Zugriff ansonsten blockieren wrde.

Zulassen eines sandboxed <iframe> zur Nutzung der API

Zunchst einmal muss, wenn das <iframe> sandboxed ist, die einbettende Website das allow-storage-access-by-user-activation Sandbox-Token hinzufgen, um Storage Access API-Anfragen erfolgreich zu machen, zusammen mit allow-scripts und allow-same-origin, um zu ermglichen, dass ein Skript ausgefhrt wird, um die API aufzurufen, und es in einem Ursprung ausgefhrt wird, der Cookies und Zustand haben kann:

<iframe
  sandbox="allow-storage-access-by-user-activation
                 allow-scripts
                 allow-same-origin">
  
</iframe>

berprfen und Anfordern des Speicherzugriffs

Nun zum Code, der innerhalb des eingebetteten Dokuments ausgefhrt wird. In diesem Code:

1. Zuerst verwenden wir Feature-Erkennung (if (document.hasStorageAccess) {}), um zu berprfen, ob die API untersttzt wird. Falls nicht, fhren wir unseren Code, der auf Cookies zugreift, trotzdem aus und hoffen, dass er funktioniert. Er sollte in jedem Fall defensiv kodiert werden, um mit solchen Eventualitten umzugehen.
2. Wenn die API untersttzt wird, rufen wir document.hasStorageAccess() auf.
3. Wenn dieser Aufruf true zurckgibt, bedeutet das, dass dieses <iframe> bereits Zugriff erhalten hat, und wir knnen unseren Code, der auf Cookies und Zustand zugreift, sofort ausfhren.
4. Wenn dieser Aufruf false zurckgibt, rufen wir dann Permissions.query() auf, um zu berprfen, ob die Erlaubnis zum Zugriff auf Third-party Cookies und unpartitionierten Zustand bereits erteilt wurde (d.h. zu einem anderen Same-site-Embedding). Wir umschlieen diesen gesamten Abschnitt mit einem try...catch Block, da einige Browser die "storage-access" Berechtigung nicht untersttzen, was den Aufruf von query() zum Werfen bringen kann. Wenn er wirft, geben wir das an die Konsole aus und versuchen den Cookie-Code trotzdem auszufhren.
5. Wenn der Berechtigungszustand "granted" ist, rufen wir sofort document.requestStorageAccess() auf. Dieser Aufruf wird automatisch aufgelst, was dem Benutzer etwas Zeit spart, dann knnen wir unseren Code, der auf Cookies und Zustand zugreift, ausfhren.
6. Wenn der Berechtigungszustand "prompt" ist, rufen wir document.requestStorageAccess() nach einer Benutzerinteraktion auf. Dieser Aufruf kann eine Eingabeaufforderung beim Benutzer auslsen. Wenn dieser Aufruf aufgelst wird, knnen wir unseren Code, der auf Cookies und Zustand zugreift, ausfhren.
7. Wenn der Berechtigungszustand "denied" ist, hat der Benutzer unsere Anfragen zum Zugriff auf Third-party Cookies oder unpartitionierten Zustand abgelehnt und unser Code kann sie nicht nutzen.

function doThingsWithCookies() {
  document.cookie = "foo=bar"; // set a cookie
}

function doThingsWithLocalStorage(handle) {
  handle.localStorage.setItem("foo", "bar"); // set a local storage key
}

async function handleCookieAccess() {
  if (!document.hasStorageAccess) {
    // This browser doesn't support the Storage Access API
    // so let's just hope we have access!
    doThingsWithCookies();
  } else {
    const hasAccess = await document.hasStorageAccess();
    if (hasAccess) {
      // We have access to third-party cookies, so let's go
      doThingsWithCookies();
      // If we want to modify unpartitioned state, we need to request a handle.
      const handle = await document.requestStorageAccess({
        localStorage: true,
      });
      doThingsWithLocalStorage(handle);
    } else {
      // Check whether third-party cookie access has been granted
      // to another same-site embed
      try {
        const permission = await navigator.permissions.query({
          name: "storage-access",
        });

        if (permission.state === "granted") {
          // If so, you can just call requestStorageAccess() without a user interaction,
          // and it will resolve automatically.
          const handle = await document.requestStorageAccess({
            cookies: true,
            localStorage: true,
          });
          doThingsWithLocalStorage(handle);
          doThingsWithCookies();
        } else if (permission.state === "prompt") {
          // Need to call requestStorageAccess() after a user interaction
          btn.addEventListener("click", async () => {
            try {
              const handle = await document.requestStorageAccess({
                cookies: true,
                localStorage: true,
              });
              doThingsWithLocalStorage(handle);
              doThingsWithCookies();
            } catch (err) {
              // If there is an error obtaining storage access.
              console.error(`Error obtaining storage access: ${err}.
                            Please sign in.`);
            }
          });
        } else if (permission.state === "denied") {
          // User has denied third-party cookie access, so we'll
          // need to do something else
        }
      } catch (error) {
        console.log(`Could not access permission state. Error: ${error}`);
        doThingsWithCookies(); // Again, we'll have to hope we have access!
      }
    }
  }
}

Verwandte Website-Sets

Das Chrome-only Verwandte Website-Sets Feature kann als progressiver Verbesserungsmechanismus betrachtet werden, der zusammen mit der Storage Access API funktioniert untersttzende Browser gewhren standardmig Third-party Cookie- und unpartitionierten Zustand-Zugriff zwischen Websites im selben Set. Das bedeutet, dass der bliche Workflow der Benutzergenehmigungsaufforderung, der oben beschrieben ist, nicht durchlaufen werden muss, was eine benutzerfreundlichere Erfahrung fr die Benutzer der Websites im Set ergibt.

Anfordern des Speicherzugriffs von der obersten Website im Namen eingebetteter Ressourcen

Die oben genannten Funktionen der Storage Access API ermglichen es einem eingebetteten Dokument, seinen eigenen Third-party Cookie-Zugriff anzufordern. Es gibt eine zustzliche experimentelle Methode, Document.requestStorageAccessFor(), eine vorgeschlagene Erweiterung der Storage Access API, die es obersten Websites ermglicht, Speicherzugriff im Namen spezifischer verwandter Ursprnge anzufordern.

Die Methode requestStorageAccessFor() spricht Herausforderungen bei der Einfhrung der Storage Access API auf obersten Websites an, die cross-site Bilder oder Skripte verwenden, die Cookies erfordern. Sie kann den Zugriff auf Third-party Cookies fr cross-site Ressourcen, die direkt in die obere Website eingebettet sind und nicht in der Lage sind, ihren eigenen Speicherzugriff anzufordern, ermglichen, zum Beispiel ber <img> oder <script> Elemente.

Damit requestStorageAccessFor() funktioniert, mssen sowohl die aufrufende oberste Seite als auch die eingebettete Ressource, fr die der Speicherzugriff angefordert wird, Teil desselben verwandten Website-Sets sein.

Die typische Nutzung von requestStorageAccessFor() sieht folgendermaen aus (diesmal im regulren Promise-Stil statt async/await geschrieben):

navigator.permissions
  .query({
    name: "top-level-storage-access",
    requestedOrigin: "https://example.com",
  })
  .then((permission) => {
    if (permission.state === "granted") {
      // Permission has already been granted
      // No need to call requestStorageAccessFor() again, just start using cookies
      doThingsWithCookies();
    } else if (permission.state === "prompt") {
      // Need to call requestStorageAccessFor() after a user interaction
      btn.addEventListener("click", () => {
        // Request storage access
        rSAFor();
      });
    } else if (permission.state === "denied") {
      // User has denied third-party cookie access, so we'll
      // need to do something else
    }
  });

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

Beim Abfragen des Berechtigungsstatus fr Speicherzugriffsanfragen, die im Namen eines anderen Ursprungs gestellt werden, wird ein anderer Berechtigungsname als beim Rest der Storage Access API verwendet: "top-level-storage-access" statt "storage-access". Im obigen Code verwenden wir den folgenden Aufruf:

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

um herauszufinden, ob dem Ursprung zuvor die Berechtigung erteilt wurde oder ob der Cookie-Zugriff noch angefordert werden muss.

• Wenn der Berechtigungsstatus "granted" ist, knnen wir mit der Nutzung von Cookies beginnen; requestStorageAccessFor() wurde bereits aufgerufen, also besteht keine Notwendigkeit, es noch einmal aufzurufen.
• Wenn der Berechtigungsstatus "prompt" ist, mssen wir document.requestStorageAccessFor("https://example.com") innerhalb einer Benutzeraktion, wie einem Klick auf einen Button, aufrufen.

Nachdem die Berechtigung "top-level-storage-access" erteilt wurde, schlieen cross-site Anfragen Cookies ein, wenn sie CORS / crossorigin einbeziehen, daher mchten Websites vielleicht warten, bevor sie eine Anfrage auslsen. Solche Anfragen mssen die Option credentials: "include" verwenden und Ressourcen mssen 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
    });
}