Document.hasUnpartitionedCookieAccess() — Methode · JavaScript-Referenz

Signatur

Document.prototype.hasUnpartitionedCookieAccess()

Beschreibung

hasUnpartitionedCookieAccess() gehört zur Storage Access API. Die Methode prüft, ob das aktuelle Dokument, typischerweise ein eingebetteter <iframe> eines Drittanbieters, auf seine unpartitionierten Cookies zugreifen darf. Gemeint sind die Cookies, die dieselbe Origin auch im Kontext der obersten Ebene (First-Party) sieht. Funktional ist sie ein neuerer, klarerer Name für document.hasStorageAccess().

Browser blockieren oder partitionieren Drittanbieter-Cookies immer häufiger (z. B. CHIPS, Tracking-Schutz). Eingebettete Inhalte wie Login-Widgets, Kommentarsysteme oder Bezahldienste brauchen deshalb einen zuverlässigen Weg, um den aktuellen Status zu erfahren. Die typische Reihenfolge ist: erst mit hasUnpartitionedCookieAccess() prüfen und nur bei false über eine Nutzeraktion document.requestStorageAccess() aufrufen.

Die Methode fragt nur ab. Sie fordert keinen Zugriff an und zeigt niemals einen Berechtigungsdialog. Im Kontext der obersten Ebene wird das Promise normalerweise mit true aufgelöst, bei einer undurchsichtigen Origin (z. B. sandbox-iframe ohne allow-same-origin) mit false.

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Ein Promise, das mit true aufgelöst wird, wenn das Dokument Zugriff auf unpartitionierte Cookies hat, sonst mit false. Ist das Dokument nicht vollständig aktiv, wird das Promise mit einer InvalidStateError-DOMException abgelehnt.

Beispiele

Cookie-Zugriff im eingebetteten iframe prüfen

// Läuft innerhalb eines Drittanbieter-iframes
const pruefeZugriff = async () => {
  if (!('hasUnpartitionedCookieAccess' in document)) {
    console.log('API nicht unterstützt');
    return;
  }
  const hatZugriff = await document.hasUnpartitionedCookieAccess();
  console.log(hatZugriff ? 'Zugriff vorhanden' : 'Kein Zugriff');
};

pruefeZugriff();

Kein Zugriff

Erst prüfen, bei Bedarf per Klick anfordern

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

const initWidget = async () => {
  const hatZugriff = await document.hasUnpartitionedCookieAccess();
  if (hatZugriff) {
    ladeNutzerdaten();
    return;
  }
  // requestStorageAccess() braucht eine Nutzeraktion
  loginButton.hidden = false;
  loginButton.addEventListener('click', async () => {
    try {
      await document.requestStorageAccess();
      loginButton.hidden = true;
      ladeNutzerdaten();
    } catch {
      console.warn('Zugriff wurde verweigert');
    }
  }, { once: true });
};

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

initWidget();

Angemeldet als Anna

Fallback auf hasStorageAccess() für ältere Browser

const hatCookieZugriff = async () => {
  try {
    if (typeof document.hasUnpartitionedCookieAccess === 'function') {
      return await document.hasUnpartitionedCookieAccess();
    }
    if (typeof document.hasStorageAccess === 'function') {
      return await document.hasStorageAccess();
    }
    return true; // Keine Storage Access API: Cookies nicht per API eingeschränkt
  } catch (err) {
    console.error(err.name); // z. B. InvalidStateError
    return false;
  }
};

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

Zugriff: true

// Wichtig · Fallstricke

Browser-Kompatibilität: Bisher nur in Chromium-basierten Browsern (ab Version 125). Firefox und Safari bieten stattdessen document.hasStorageAccess() an. Deshalb immer die Verfügbarkeit prüfen und einen Fallback einbauen.
Die Methode fragt nur den Status ab. Um Zugriff zu bekommen, ist document.requestStorageAccess() nötig, und das nur als Reaktion auf eine Nutzeraktion (transient activation), etwa einen Klick.
false heißt nicht zwingend, dass eine Anfrage scheitert. Es heißt nur, dass gerade kein Zugriff besteht. Eine erteilte Berechtigung kann nach einem Neuladen wieder mit requestStorageAccess() aktiviert werden (in Chrome teils ohne neuen Dialog).
In einem abgekoppelten oder nicht aktiven Dokument (z. B. aus einem entfernten iframe) wird das Promise mit InvalidStateError abgelehnt. Nutze daher try/catch.
In sandbox-iframes muss für Storage Access zusätzlich allow-storage-access-by-user-activation gesetzt sein. Bei einer undurchsichtigen Origin ist das Ergebnis immer false.
Nur in sicheren Kontexten (HTTPS) sinnvoll nutzbar.

Siehe auch

Document.hasStorageAccess() Document.requestStorageAccess() Document.cookie Document CookieStore