1. Web
  2. Web-APIs
  3. Navigator
  4. sendBeacon()

Dieser Inhalt wurde automatisch aus dem Englischen übersetzt, und kann Fehler enthalten. Erfahre mehr über dieses Experiment.

View in English Always switch to English

Navigator: sendBeacon() Methode

Baseline Weitgehend verfügbar

Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit April 2018 browserübergreifend verfügbar.

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

Sie ist dafür gedacht, Analysedaten an einen Webserver zu senden, und vermeidet einige der Probleme, die mit älteren Techniken zum Senden von Analysedaten verbunden sind, wie die Verwendung von XMLHttpRequest.

Hinweis: Für Anwendungsfälle, die über die Fähigkeit verfügen müssen, Anfragen mit anderen Methoden als POST zu senden, oder um Anfrageeigenschaften 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, eine DataView, ein Blob, ein String-Literal oder Objekt, ein FormData- oder ein URLSearchParams-Objekt mit den zu sendenden Daten.

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 ist für Analyse- und Diagnosecodes vorgesehen, um Daten an einen Server zu senden.

Ein Problem beim Senden von Analysedaten besteht darin, 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 es sein, dass der Browser die Seite gerade entlädt, und in diesem Fall kann 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. Dabei wurden Umgehungslösungen wie die folgenden verwendet:

  • Übermittlung der Daten mit einem blockierenden synchronen XMLHttpRequest-Aufruf.
  • Erstellung eines <img>-Elements und Setzen von dessen src. Die meisten User-Agents verzögern das Entladen, um das Bild zu laden.
  • Erstellung einer No-Op-Schleife für einige Sekunden.

Alle diese Methoden blockieren das Entladen des Dokuments, was die Navigation zur nächsten Seite verlangsamt. Die neue Seite kann dagegen nichts unternehmen, also erscheint sie langsam, obwohl es die Schuld der vorherigen Seite ist.

Mit der sendBeacon()-Methode werden die Daten asynchron übertragen, wenn 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 beeinträchtigt nicht das Laden der nächsten Seite

Die Daten werden als HTTP POST-Anfrage gesendet.

Hinweis: Die navigator.sendBeacon()-Methode hat ein spezifikationsdefiniertes Payload-Größenlimit von etwa 64 KiB. Wenn dieses Limit überschritten wird, schlägt die Anfrage fehl. Für größere Datenübertragungen sollten Sie fetch() in Betracht ziehen.

Versand von Analysedaten am Ende einer Sitzung

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

js
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 Mobilgeräten, wird der Browser die unload-, beforeunload- oder pagehide-Ereignisse nicht auslösen. Zum Beispiel werden diese Ereignisse in folgender Situation nicht ausgelöst:

  1. Der Benutzer lädt die Seite und interagiert damit.
  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 mit dem App-Manager des Telefons.

Darüber hinaus ist das unload-Ereignis nicht kompatibel mit dem Vor-/Zurück-Cache (bfcache), der in modernen Browsern implementiert ist. Einige Browser, wie Firefox, handhaben 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, handhaben es, indem sie das unload-Ereignis nicht auslösen, wenn der Benutzer zu einer anderen Seite im selben Tab navigiert.

Firefox schließt auch Seiten 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 Mobilgeräten. Es ist jedoch mit dem bfcache kompatibel.

Beispiele

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

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

Spezifikationen

Spezifikation
Beacon
# sendbeacon-method

Browser-Kompatibilität

Siehe auch

Help improve MDN

Erfahren Sie, wie Sie beitragen können Diese Seite wurde automatisch aus dem Englischen übersetzt.
Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden