Using the Beacon API

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

The Beacon interface schedules an asynchronous and non-blocking request to a web server. Beacon requests use HTTP PUT and requests do not require a response. Requests are guaranteed to be initiated before a page is unloaded and they are run to completion without requiring a blocking request (for example XMLHttpRequest).

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

Navigator.sendBeacon()

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 in the request. 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.

In the following example, <body> specifies a handler for the load and beforeunload events and the handler calls sendBeacon() with the value of window.location.

function analytics(state) {
  if (!check_beacon_support) return;

  // Create the data to send
  var URL = "https://example.com/analytics";
  var data = "state=" + state + "&location=" + window.location;
  var status;

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

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

<body onload="analytics('start')" onunload="analytics('end')">

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

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

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

function init() {
  window.onsubmit = send_analytics;
}

<body onload="init()">

WorkerNavigator.sendBeacon()

The Beacon API's WorkerNavigator.sendBeacon() method sends a beacon of data to the the server from the worker global scope. The method takes two arguments, the URL and the data to send in the request. 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.

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(e) {
    // Log worker's send status
    var msg = e.data;
    console.log("Worker reply: sendBeacon() status = " + msg);
  };  
}

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

onmessage = function(ev) {
  // Split the URL and data from the message 
  var msg = ev.data;
  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 === undefined) {
    postMessage("Worker: self.navigator.sendBeacon is NOT supported");
  } else {
    var status = self.navigator.sendBeacon(URL, data);
    postMessage((status == true) ? "success" : "fail");
  }
}

Using the Beacon API

Navigator.sendBeacon()

WorkerNavigator.sendBeacon()

See Also

Document Tags and Contributors