FetchLaterResult.activated — Eigenschaft · JavaScript-Referenz

Signatur

get FetchLaterResult.activated

Beschreibung

Mit window.fetchLater() merkt man einen Netzwerk-Request vor, den der Browser später abschickt: spätestens, wenn das Dokument entladen wird, oder vorher, sobald die in activateAfter angegebene Zeit abgelaufen ist. Der Aufruf gibt sofort ein FetchLaterResult-Objekt zurück, dessen einzige Eigenschaft activated ist.

activated ist zunächst false und wechselt auf true, sobald der Browser den Request tatsächlich gesendet hat. Der Wert wird bei jedem Zugriff live gelesen, es gibt aber kein Event, das den Wechsel meldet. Wenn du den Zustand beobachten willst, musst du die Eigenschaft also selbst abfragen, zum Beispiel beim Sammeln neuer Daten oder bei visibilitychange.

Typischer Einsatz sind Analyse- und Telemetriedaten, die zuverlässig ankommen sollen: Solange activated noch false ist, kannst du den vorgemerkten Request über ein AbortController-Signal abbrechen und durch einen neuen mit aktuelleren Daten ersetzen. Ist er bereits true, sind die Daten unterwegs und neue Daten gehören in einen neuen Request.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der verzögerte Request gesendet wurde, sonst false. Die Antwort des Servers kann man über diese API grundsätzlich nicht auslesen.

Beispiele

Grundlegende Nutzung mit Funktionsprüfung

if ('fetchLater' in window) {
  const result = fetchLater('/api/log', {
    method: 'POST',
    body: JSON.stringify({ event: 'page_view', ts: Date.now() }),
    headers: { 'Content-Type': 'application/json' }
  });

  console.log(result.activated); // direkt nach dem Vormerken
} else {
  console.log('fetchLater wird nicht unterstützt');
}

false

Senden nach Zeitablauf mit activateAfter

const result = fetchLater('/api/heartbeat', {
  method: 'POST',
  body: 'alive',
  activateAfter: 2000 // spätestens nach 2 Sekunden senden
});

setTimeout(() => {
  console.log('Nach 3 s gesendet?', result.activated);
}, 3000);

Nach 3 s gesendet? true

Vorgemerkten Analyse-Request mit neuen Daten ersetzen

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

const scheduleBeacon = () => {
  // Alten Request abbrechen, solange er noch nicht gesendet wurde
  if (pending && !pending.activated) {
    controller.abort();
  } else if (pending?.activated) {
    events.length = 0; // bereits gesendete Daten verwerfen
  }

  controller = new AbortController();
  pending = fetchLater('/api/analytics', {
    method: 'POST',
    body: JSON.stringify(events),
    signal: controller.signal,
    activateAfter: 60_000
  });
};

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

// Wichtig · Fallstricke

Kompatibilität: fetchLater() gibt es bislang nur in Chromium-basierten Browsern (ab Version 135). Firefox und Safari unterstützen die API nicht. Prüfe deshalb immer mit 'fetchLater' in window und nutze sonst zum Beispiel navigator.sendBeacon() oder fetch() mit keepalive: true.
Die API ist nur in sicheren Kontexten verfügbar (HTTPS).
Für activated gibt es kein Änderungs-Event. Wenn du auf den Wechsel reagieren willst, musst du die Eigenschaft selbst abfragen.
Mit abort() lässt sich ein Request nur abbrechen, solange activated noch false ist. Nach dem Senden hat abort() keine Wirkung mehr.
Die Größe der vorgemerkten Request-Bodies ist begrenzt (Kontingent, etwa 64 KB pro Origin im obersten Dokument). Wird das Kontingent überschritten, wirft fetchLater() einen QuotaExceededError. Ein ReadableStream ist als Body nicht erlaubt.
Ein negativer Wert für activateAfter löst einen RangeError aus.
Auch wenn activated auf true steht, heißt das nur, dass der Request gesendet wurde. Ob der Server ihn erfolgreich verarbeitet hat, lässt sich damit nicht feststellen.

Siehe auch

SpeechSynthesisEvent.utterance FetchEvent.clientId FetchEvent.resultingClientId Sensor.activated FetchEvent.handled