Navigator: sendBeacon()-Methode

Syntax

sendBeacon(url)
sendBeacon(url, data)

Parameter

url

Die URL, an die data gesendet wird. Sie kann relativ oder absolut sein.

data Optional

Ein ArrayBuffer, ein TypedArray, eine DataView, ein Blob, ein String-Literal oder -Objekt, ein FormData- oder ein URLSearchParams-Objekt mit den zu sendenden Daten. Die Gesamtgröße der zur Übertragung eingereihten Daten ist auf 64 KiB (65.536 Byte) begrenzt.

Rückgabewert

Gibt true zurück, wenn der User-Agent data erfolgreich zur Übertragung eingereiht hat. Andernfalls wird false zurückgegeben.

Beschreibung

Diese Methode ist für Analyse- und Diagnosecode vorgesehen, der Daten an einen Server sendet.

Beim Senden von Analysedaten ergibt sich ein Problem: Eine Website möchte solche Daten häufig senden, wenn ein Benutzer die Seite verlässt, beispielsweise beim Navigieren zu einer anderen Seite. Der Browser ist dann möglicherweise bereits dabei, die Seite zu entladen. In diesem Fall kann er entscheiden, asynchrone Anfragen mit XMLHttpRequest nicht mehr zu senden.

Früher haben Webseiten versucht, das Entladen der Seite lange genug zu verzögern, um die Daten zu senden. Dazu nutzten sie Behelfslösungen wie:

• Senden der Daten mit einem blockierenden, synchronen XMLHttpRequest-Aufruf.
• Erstellen eines <img>-Elements und Setzen seiner src. Die meisten User-Agents verzögern das Entladen, um das Bild zu laden.
• Ausführen einer Schleife ohne weitere Funktion für mehrere Sekunden.

All diese Methoden blockieren das Entladen des Dokuments und verlangsamen dadurch die Navigation zur nächsten Seite. Die nächste Seite kann dies nicht verhindern und wirkt deshalb langsam, obwohl die Ursache auf der vorherigen Seite liegt.

Mit der Methode sendBeacon() werden die Daten asynchron übertragen, sobald der User-Agent dazu Gelegenheit hat, ohne das Entladen oder die nächste Navigation zu verzögern. Das bedeutet:

• Die Daten werden zuverlässig gesendet.
• Sie werden asynchron gesendet.
• Das Laden der nächsten Seite wird nicht beeinträchtigt.

Die Daten werden als HTTP-POST-Anfrage gesendet.

Allerdings ist die Größe der Nutzdaten auf etwa 64 KiB begrenzt. Für die Übertragung größerer Datenmengen sollten Sie stattdessen fetch() verwenden.

Analysedaten am Ende einer Sitzung senden

Websites möchten häufig Analyse- oder Diagnosedaten an den Server senden, wenn ein Benutzer die Seite verlässt. Am zuverlässigsten geschieht dies beim Ereignis visibilitychange:

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
});

Frühere Ereignisse

Früher haben viele Websites die Ereignisse unload, beforeunload oder pagehide verwendet, um am Ende einer Sitzung Analysedaten zu senden. Das ist jedoch unzuverlässig. In vielen Situationen, insbesondere auf Mobilgeräten, löst der Browser diese Ereignisse nicht aus. Beispielsweise werden sie in der folgenden Situation nicht ausgelöst:

1. Der Benutzer lädt die Seite und interagiert mit ihr.
2. Danach wechselt er zu einer anderen App, statt den Tab zu schließen.
3. Später schließt er die Browser-App über die App-Verwaltung des Telefons.

Außerdem ist das Ereignis unload nicht mit dem in modernen Browsern implementierten Back/Forward-Cache (bfcache) kompatibel. Einige Browser, etwa Firefox, begegnen dieser Inkompatibilität, indem sie Seiten mit unload-Handlern vom bfcache ausschließen. Das beeinträchtigt die Leistung. Andere, etwa Safari und Chrome unter Android, lösen das Ereignis unload nicht aus, wenn der Benutzer im selben Tab zu einer anderen Seite navigiert.

Das Ereignis pagehide ist weniger problematisch als unload, da es mit dem bfcache kompatibel ist. Allerdings ist es ebenso wenig zuverlässig. Entwickler sollten stattdessen visibilitychange verwenden.

Beispiele

Das folgende Beispiel definiert einen Handler für das Ereignis visibilitychange. Der Handler ruft sendBeacon() auf, um Analysedaten zu senden.

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/log", analyticsData);
  }
});

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Das Ereignis visibilitychange.
• Die Übersichtsseite zur Beacon API.
• Benutzer- und Anwendungszustand nicht verlieren: Page Visibility verwenden erläutert ausführlich, warum Sie visibilitychange statt beforeunload/unload verwenden sollten.
• Die Page Lifecycle API bietet Empfehlungen für den Umgang mit dem Lebenszyklus von Seiten in Ihren Webanwendungen.
• PageLifecycle.js: eine JavaScript-Bibliothek, die Unterschiede zwischen Browsern beim Verhalten im Seitenlebenszyklus berücksichtigt.
• Back/Forward-Cache erklärt, was der Back/Forward-Cache ist und welche Auswirkungen er auf verschiedene Ereignisse im Seitenlebenszyklus hat.