Document.hasStorageAccess() — Methode · JavaScript-Referenz

Signatur

Document.prototype.hasStorageAccess()

Beschreibung

hasStorageAccess() gehört zur Storage Access API. Mit der Methode prüft Code, der in einem eingebetteten Drittanbieter-Kontext läuft (typischerweise ein <iframe>), ob er gerade Zugriff auf seine nicht partitionierten Cookies hat. Das sind die Cookies, die der Drittanbieter auch als Hauptseite (First-Party) sieht. Moderne Browser blockieren oder partitionieren Drittanbieter-Cookies standardmäßig, zum Beispiel über Safari ITP, Firefox Total Cookie Protection oder Chromes Einschränkungen für Drittanbieter-Cookies.

Typischer Einsatz: Ein eingebettetes Widget, etwa ein Kommentarsystem, ein SSO-Login oder ein Bezahl-Button, prüft beim Laden mit hasStorageAccess(), ob der Nutzer schon angemeldet erkannt werden kann. Liefert die Methode false, zeigt das Widget einen Button an. Dessen Klick-Handler ruft dann document.requestStorageAccess() auf, denn dafür ist eine Nutzeraktion (transiente Aktivierung) nötig.

Die Methode selbst fragt den Nutzer nicht um Erlaubnis und zeigt keinen Dialog. Sie liest nur den aktuellen Zustand aus. Im Top-Level-Dokument (First-Party) wird das Promise immer mit true erfüllt. Ist das Dokument nicht „vollständig aktiv“ (z. B. ein abgelöstes iframe), wird das Promise mit einem InvalidStateError abgelehnt.

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Ein Promise, das mit true erfüllt wird, wenn das Dokument Zugriff auf nicht partitionierte Cookies hat, sonst mit false. Es wird mit InvalidStateError (DOMException) abgelehnt, wenn das Dokument nicht vollständig aktiv ist.

Beispiele

Zugriffsstatus im eingebetteten iframe prüfen

// Läuft im Drittanbieter-iframe, z. B. https://widget.example
const checkAccess = async () => {
  if (!document.hasStorageAccess) {
    console.log('Storage Access API nicht unterstützt');
    return;
  }
  const hasAccess = await document.hasStorageAccess();
  console.log(hasAccess ? 'Cookies verfügbar' : 'Kein Cookie-Zugriff');
};

checkAccess();

Kein Cookie-Zugriff

Nur bei Bedarf per Klick Zugriff anfordern

const loginButton = document.querySelector('#login');

const init = async () => {
  if (await document.hasStorageAccess()) {
    loadUserSession(); // Cookies sind bereits nutzbar
    return;
  }
  loginButton.hidden = false;
};

// requestStorageAccess() braucht eine Nutzeraktion
loginButton.addEventListener('click', async () => {
  try {
    await document.requestStorageAccess();
    loginButton.hidden = true;
    loadUserSession();
  } catch (err) {
    console.warn('Zugriff verweigert:', err.name);
  }
});

function loadUserSession() {
  fetch('/api/me', { credentials: 'include' })
    .then((res) => res.json())
    .then((user) => console.log('Angemeldet als', user.name));
}

init();

Angemeldet als Anna

Mit bestehender Berechtigung automatisch Zugriff holen

// Wurde die Berechtigung schon einmal erteilt, klappt
// requestStorageAccess() in Chrome/Firefox ohne Nutzeraktion
const ensureAccess = async () => {
  if (await document.hasStorageAccess()) return true;

  const status = await navigator.permissions.query({ name: 'storage-access' });
  if (status.state === 'granted') {
    await document.requestStorageAccess();
    return true;
  }
  return false; // Button anzeigen und auf Klick warten
};

ensureAccess().then((ok) => console.log('Zugriff:', ok));

Zugriff: true

// Wichtig · Fallstricke

Nur Statusabfrage: hasStorageAccess() gewährt selbst keinen Zugriff. Dafür ist requestStorageAccess() zuständig, und das in der Regel nur innerhalb einer Nutzeraktion wie einem Klick.
Pro Dokument: Ein gewährter Zugriff gilt für das aktuelle Dokument. Nach einem Neuladen oder einer Navigation im iframe kann hasStorageAccess() wieder false liefern. Prüfe den Status deshalb bei jedem Laden neu.
Sandbox-iframes: In einem <iframe sandbox> muss das Token allow-storage-access-by-user-activation gesetzt sein, sonst lässt sich kein Zugriff erlangen. Außerdem kann eine Permissions-Policy (storage-access) die Funktion sperren.
Browserunterschiede: Safari, Firefox und Chrome setzen die Regeln unterschiedlich um, etwa bei automatischer Gewährung, Prompts und Heuristiken. Frühere Firefox-Versionen haben die Methode nur bei aktivem Tracking-Schutz sinnvoll ausgewertet. Vor dem Aufruf per Feature-Detection prüfen: 'hasStorageAccess' in document.
Nur Cookies: Die Methode bezieht sich auf nicht partitionierte Cookies. Für localStorage, IndexedDB usw. gibt es in Chrome die Erweiterung requestStorageAccess({ all: true }), die nicht in allen Browsern verfügbar ist.
Fehler: Ist das Dokument nicht vollständig aktiv, wird das Promise mit InvalidStateError abgelehnt. Aufrufe daher bei Bedarf in try/catch einschließen.

Siehe auch

Permissions.query() Document.cookie Document Document.hasUnpartitionedCookieAccess() StorageEvent.initStorageEvent()