Using the Beacon API

This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The Beacon interface schedules an asynchronous and non-blocking request to a web server.

  • Beacon requests use HTTP POST and do not require a response.
  • Beacon requests are guaranteed to be initiated before the page unloads.

This document contains examples of the Beacon interfaces. See Beacon API for an overview.

The Beacon API's Navigator.sendBeacon() method sends a beacon request to the server in the global browsing context. The method takes two arguments: the URL and the data to send. The data argument is optional and its type may be an ArrayBufferView, Blob, DOMString, or FormData.

If the browser successfully queues the request for delivery, the method returns true and returns false otherwise.

The following example specifies a handler for the load and beforeunload events. The handler calls sendBeacon() with the current URL.

window.onload = window.onunload = function analytics(event) {
  if (!navigator.sendBeacon) return;

  var url = "https://example.com/analytics";
  // Create the data to send
  var data = "state=" + event.type + "&location=" + location.href;

  // Send the beacon
  var status = navigator.sendBeacon(url, data);

  // Log the data and result
  console.log("sendBeacon: URL = ", url, "; data = ", data, "; status = ", status);
};

The following example creates a submit handler and when that event is fired, the handler calls sendBeacon().

window.onsubmit = function send_analytics() {
  var data = JSON.stringify({
    location: location.href,
    time: Date()
  });

  navigator.sendBeacon('/analytics', data);
};

WorkerNavigator.sendBeacon()

The Beacon API's WorkerNavigator.sendBeacon() method works identically to the usual method, but is accessible from worker global scope.

In the following example, a Worker sends a beacon using the URL and data from the global context.

This code snippet is for the global context:

function worker_send(url, data) {
  // Create the worker object
  var myWorker = new Worker("worker-using.js");

  // Send the worker the URL and data to beacon
  myWorker.postMessage([url, data]);

  // Set up a message handler to receive the success/fail message from the worker
  myWorker.onmessage = function(event) {
    var msg = event.data;
    // Log worker's send status
    console.log("Worker reply: sendBeacon() status = " + msg);
  };  
}

This code snippet is for the worker (worker-using.js):

onmessage = function(event) {
  var msg = event.data;
  // Split the URL and data from the message 
  var url = msg[0];
  var data = msg[1];

  // If the browser supports worker sendBeacon(), then send the beacon; otherwise
  // return failure message to the global context
  if (self.navigator.sendBeacon) {
    var status = self.navigator.sendBeacon(url, data); 
    postMessage(status ? "success" : "fail");
  } else {
    postMessage("Worker: self.navigator.sendBeacon is unsupported");
  }
}

See Also