Navigator: sendBeacon() Methode

Syntax

sendBeacon(url)
sendBeacon(url, data)

Parameter

url

Die URL, die die Daten empfangen wird. Kann relativ oder absolut sein.

data Optional

Ein ArrayBuffer, ein TypedArray, ein DataView, ein Blob, ein Zeichenkettenliteral oder Objekt, ein FormData- oder ein URLSearchParams-Objekt, das die zu sendenden Daten enthält. Die Gesamtgröße der aufgereihten Daten ist auf 64 KiB (65.536 Bytes) begrenzt.

Rückgabewert

Gibt true zurück, wenn der user agent die data erfolgreich zur Übertragung in die Warteschlange gestellt hat. Andernfalls wird false zurückgegeben.

Beschreibung

Diese Methode richtet sich an Analysen und Diagnosecode, um Daten an einen Server zu senden.

Ein Problem beim Senden von Analysedaten ist, dass eine Website oft Analysedaten senden möchte, wenn der Benutzer mit einer Seite fertig ist: zum Beispiel, wenn der Benutzer zu einer anderen Seite navigiert. In dieser Situation könnte der Browser im Begriff sein, die Seite zu entladen, und in diesem Fall könnte der Browser sich entscheiden, keine asynchronen XMLHttpRequest-Anfragen zu senden.

In der Vergangenheit haben Webseiten versucht, das Entladen der Seite lange genug zu verzögern, um Daten zu senden. Dazu haben sie Workarounds verwendet wie:

• Das Einreichen der Daten mit einem blockierenden synchronen XMLHttpRequest-Aufruf.
• Erstellen eines <img>-Elements und Festlegen seines src. Die meisten Benutzeragenten verzögern das Entladen, um das Bild zu laden.
• Erstellen einer No-Op-Schleife für mehrere Sekunden.

Alle diese Methoden blockieren das Entladen des Dokuments, was die Navigation zur nächsten Seite verlangsamt. Die nachfolgende Seite kann nichts dagegen tun, daher scheint die neue Seite langsam zu sein, obwohl es die Schuld der vorherigen Seite ist.

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

• Die Daten werden zuverlässig gesendet
• Sie werden asynchron gesendet
• Sie beeinträchtigen nicht das Laden der nächsten Seite

Die Daten werden als HTTP POST-Anfrage gesendet.

Die Einschränkung besteht jedoch darin, dass die Payload-Größe auf etwa 64 KiB begrenzt ist. Für größere Datenübertragungen sollte fetch() in Betracht gezogen werden.

Analysedaten am Ende einer Sitzung senden

Websites möchten oft Analysen oder Diagnosen an den Server senden, wenn der Benutzer mit der Seite fertig ist. Die zuverlässigste Methode, dies zu tun, besteht darin, die Daten beim visibilitychange-Ereignis zu senden:

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

Vermeiden Sie unload und beforeunload

In der Vergangenheit haben viele Websites die unload- oder beforeunload-Ereignisse verwendet, um Analysedaten am Ende einer Sitzung zu senden. Dies ist jedoch äußerst unzuverlässig. In vielen Situationen, insbesondere auf mobilen Geräten, wird der Browser die unload, beforeunload oder pagehide-Ereignisse nicht auslösen. Zum Beispiel werden diese Ereignisse in der folgenden Situation nicht ausgelöst:

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

Zusätzlich ist das unload-Ereignis mit dem Vorwärts-/Rückwärts-Cache (bfcache) in modernen Browsern unvereinbar. Einige Browser, wie Firefox, behandeln diese Inkompatibilität, indem sie Seiten vom bfcache ausschließen, wenn sie unload-Handler enthalten, was die Leistung beeinträchtigt. Andere, wie Safari und Chrome auf Android, behandeln es, indem sie das unload-Ereignis nicht auslösen, wenn der Benutzer zu einer anderen Seite im selben Tab navigiert.

Firefox schließt Seiten auch vom bfcache aus, wenn sie beforeunload-Handler enthalten.

Verwenden Sie pagehide als Fallback

Um Browser zu unterstützen, die visibilitychange nicht implementieren, verwenden Sie das pagehide-Ereignis. Wie beforeunload und unload wird dieses Ereignis nicht zuverlässig ausgelöst, insbesondere auf mobilen Geräten. Es ist jedoch mit dem bfcache kompatibel.

Beispiele

Das folgende Beispiel spezifiziert einen Handler für das visibilitychange-Ereignis. 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 visibilitychange-Ereignis.
• Beacon API Übersichtsseite.
• Verlieren Sie nicht den Benutzer- und Anwendungszustand, verwenden Sie die Seitensichtbarkeit erklärt ausführlich, warum Sie visibilitychange und nicht beforeunload/unload verwenden sollten.
• Page Lifecycle API bietet Leitlinien für Best Practices im Umgang mit Seitensichtbarkeitsverhalten in Ihren Webanwendungen.
• PageLifecycle.js: eine JavaScript-Bibliothek, die sich mit inkonsistentem Seitensichtbarkeitsverhalten zwischen verschiedenen Browsern befasst.
• Back/forward cache erklärt, was der Vorwärts-/Rückwärts-Cache ist und seine Auswirkungen auf verschiedene Seitensichtbarkeitsereignisse.