Navigator: sendBeacon()-Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2018.

Die navigator.sendBeacon()-Methode sendet asynchron eine HTTP POST-Anfrage mit einer kleinen Datenmenge an einen Webserver.

Sie ist dafür gedacht, Analysedaten an einen Webserver zu senden und vermeidet einige Probleme älterer Techniken zum Senden von Analysedaten, wie z.B. die Verwendung von XMLHttpRequest.

Hinweis: Für Anwendungsfälle, die in der Lage sein müssen, Anfragen mit anderen Methoden als POST zu senden, oder um Anforderungseigenschaften zu ändern, oder die Zugriff auf die Serverantwort benötigen, verwenden Sie stattdessen die fetch()-Methode mit keepalive auf true gesetzt.

Syntax

js
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 Zeichenfolgenliteral oder Objekt, ein FormData- oder ein URLSearchParams-Objekt, das die zu sendenden Daten enthält.

Rückgabewerte

Die sendBeacon()-Methode gibt true zurück, wenn der User Agent die Daten erfolgreich zur Übertragung in die Warteschlange gestellt hat. Andernfalls gibt sie false zurück.

Beschreibung

Diese Methode ist dazu gedacht, Analysen und Diagnosen 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: beispielsweise, wenn der Benutzer zu einer anderen Seite navigiert. In dieser Situation könnte der Browser die Seite entladen wollen, 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:

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

All diese Methoden blockieren das Entladen des Dokuments, was die Navigation zur nächsten Seite verlangsamt. Die nächste Seite kann nichts dagegen tun, sodass die neue Seite langsam erscheint, obwohl es die Schuld der vorherigen Seite ist.

Mit der sendBeacon()-Methode werden die Daten asynchron übertragen, sobald der User Agent 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
  • Es beeinflusst nicht das Laden der nächsten Seite

Die Daten werden als HTTP POST-Anfrage gesendet.

Senden von Analysen am Ende einer Sitzung

Websites möchten häufig Analysen oder Diagnosen an den Server senden, wenn der Benutzer mit der Seite fertig ist. Der zuverlässigste Weg, dies zu tun, ist das Senden der Daten im visibilitychange-Ereignis:

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

Vermeiden Sie unload und beforeunload

In der Vergangenheit haben viele Websites die unload- oder beforeunload-Events verwendet, um Analysen 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 Back/Forward-Cache (bfcache) in modernen Browsern nicht kompatibel. Einige Browser, wie Firefox, umgehen 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, umgehen das Problem, indem sie das unload-Ereignis nicht auslösen, wenn der Benutzer zu einer anderen Seite im selben Tab navigiert.

Firefox wird auch Seiten vom bfcache ausschließen, 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 Analysen zu senden.

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

Spezifikationen

Specification
Beacon
# sendbeacon-method

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch