FetchLaterResult — Schnittstelle · JavaScript-Referenz

Signatur

interface FetchLaterResult

Beschreibung

FetchLaterResult gehört zur Fetch API. Ein Objekt dieser Schnittstelle bekommst du von window.fetchLater(), sobald eine verzögerte Anfrage (deferred fetch) angelegt ist. Der Browser schickt diese Anfrage spätestens dann ab, wenn das Dokument entladen wird, etwa beim Schließen des Tabs, beim Wegnavigieren oder beim Beenden des Prozesses. Mit der Option activateAfter kann er sie auch schon nach einer festgelegten Zeit abschicken.

Die Schnittstelle hat genau eine Eigenschaft: activated. Sie ist schreibgeschützt und hat den Typ boolean. Sie ist true, sobald der Browser die Anfrage abgeschickt hat. Die Antwort des Servers (Response) bekommst du nicht zu sehen. fetchLater() ist ein reines „Abschicken und vergessen“, gedacht für Statistik, Messdaten, Sitzungsende-Meldungen und Ähnliches.

Typischer Einsatz: Du sammelst über die Lebensdauer einer Seite Daten und ersetzt die geplante Anfrage immer wieder durch eine aktuellere. Dazu brichst du die alte Anfrage über ihr AbortSignal ab und legst eine neue an. Mit activated prüfst du vorher, ob die alte Anfrage schon unterwegs war, damit keine Daten verloren gehen oder doppelt ankommen. Das ist zuverlässiger als navigator.sendBeacon() in einem unload- oder pagehide-Handler, denn diese Ereignisse werden nicht immer ausgelöst.

Rückgabewert

Typ

FetchLaterResult

Beschreibung

Das Objekt hat die schreibgeschützte Eigenschaft activated (boolean). Sie ist true, sobald der Browser die verzögerte Anfrage abgeschickt hat, und sonst false.

Beispiele

Verzögerte Anfrage anlegen und Status prüfen

// Messdaten spätestens beim Verlassen der Seite senden
const result = fetchLater('/api/analytics', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ event: 'page_view', ts: Date.now() })
});

console.log(result instanceof FetchLaterResult);
console.log(result.activated); // noch nicht gesendet

true false

Geplante Anfrage laufend durch aktuellere Daten ersetzen

const events = [];
let controller = null;
let pending = null;

const schedule = () => {
  // Alte Anfrage nur abbrechen, wenn sie noch nicht gesendet wurde
  if (pending && !pending.activated) {
    controller.abort();
  } else if (pending?.activated) {
    events.length = 0; // bereits übertragen, Puffer leeren
  }

  controller = new AbortController();
  pending = fetchLater('/api/events', {
    method: 'POST',
    body: JSON.stringify(events),
    signal: controller.signal,
    activateAfter: 60_000 // spätestens nach 60 s senden
  });
};

document.addEventListener('click', (e) => {
  events.push({ type: 'click', target: e.target.tagName });
  schedule();
});

Feature-Erkennung mit Rückfall auf sendBeacon

const sendOnExit = (url, data) => {
  const body = JSON.stringify(data);
  if (typeof window.fetchLater === 'function') {
    try {
      return fetchLater(url, { method: 'POST', body });
    } catch (err) {
      // z. B. QuotaExceededError, wenn das Kontingent erschöpft ist
      console.warn('fetchLater fehlgeschlagen:', err.name);
    }
  }
  // Rückfall für Browser ohne fetchLater
  addEventListener('pagehide', () => navigator.sendBeacon(url, body), { once: true });
  return null;
};

const r = sendOnExit('/api/session-end', { duration: 1234 });
console.log(r ? `activated: ${r.activated}` : 'Beacon-Fallback aktiv');

activated: false

// Wichtig · Fallstricke

Browser-Unterstützung: Experimentell. Nur Chromium-Browser ab Version 135 kennen fetchLater(). Firefox und Safari unterstützen es derzeit nicht, deshalb immer vorher mit 'fetchLater' in window prüfen.
Keine Antwort: Die Response ist nicht zugänglich. activated sagt nur, dass die Anfrage abgeschickt wurde. Ob sie beim Server angekommen ist, erfährst du nicht.
Kein Ereignis: Es gibt kein Ereignis, das beim Wechsel von activated auf true ausgelöst wird. Du musst den Wert bei Bedarf selbst abfragen.
Nur in sicheren Kontexten: Funktioniert nur über HTTPS. Die Anfrage-URL muss ebenfalls sicher sein, sonst wirft der Aufruf einen TypeError.
Kontingent: Verzögerte Anfragen teilen sich ein Kontingent von standardmäßig 64 KiB pro Ursprung und Dokument. Wird es überschritten, wirft fetchLater() eine QuotaExceededError-DOMException. In eingebetteten Frames kann die Berechtigungsrichtlinie (deferred-fetch, deferred-fetch-minimal) das Kontingent zusätzlich einschränken.
Nicht erlaubt: Ein ReadableStream als body und ein negativer Wert für activateAfter führen zu einem TypeError. Ist das übergebene Signal schon abgebrochen, wirft der Aufruf eine AbortError-DOMException.
Abbrechen: Über AbortController.abort() lässt sich eine Anfrage nur zurückziehen, solange activated noch false ist.

Siehe auch

Window.fetchLater() Navigator.sendBeacon() Request FetchEvent XPathResult