Version: Smart Feature Phone 2.5Version: Smart Feature Phone 3.0

Network State Changes

In order to build a good offline-capable web application, you need to know when your application is actually offline. You also need to know when your application has returned to an 'online' status again. Effectively, the requirements break down as follows:

  1. You need to know when the user comes back online so that you can re-synchronize with the server.
  2. You need to know when the user is offline so that you can queue your server requests for a later time.

It is this process that online/offline events help to simplify.

navigator.onLine is a property that maintains a true/false value (true for online, false for offline). This property is updated whenever the user switches into "Offline Mode".

Additionally, this property should update whenever a browser is no longer capable of connecting to the network. According to the specification:

The navigator.onLine attribute must return false if the user agent will not contact the network when the user follows links or when a script requests a remote page (or knows that such an attempt would fail)...

online and offline events

You can register listeners for these events in a few familiar ways:

  • Using addEventListener on the window, document, or document.body
  • By setting the .ononline or .onoffline properties on document or document.body to a JavaScript Function object. (Note: using window.ononline or window.onoffline will not work for compatibility reasons.)
  • By specifying ononline="..." or onoffline="..." attributes on the <body> tag in the HTML markup.

Example

window.addEventListener('load', function() {
  let status = document.getElementById("status");
  let log = document.getElementById("log");

  function updateOnlineStatus(event) {
    let condition = navigator.onLine ? "online" : "offline";

    status.className = condition;
    status.innerHTML = condition.toUpperCase();

    log.insertAdjacentHTML("beforeend", "Event: " + event.type + "; Status: " + condition);
  }

  window.addEventListener('online',  updateOnlineStatus);
  window.addEventListener('offline', updateOnlineStatus);
});

Network Information

The Network Information API provides information about the system's connection in terms of general connection type (e.g., 'wifi', 'cellular', etc.). This can be used to select high definition content or low definition content based on the user's connection. The entire API consists of the addition of the NetworkInformation interface and a single property to the Navigator interface: Navigator.connection.

Examples

Detect connection changes

This example watches for changes to the user's connection.

var connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;
var type = connection.type;

function updateConnectionStatus() {
  console.log("Connection type changed from " + type + " to " + connection.type);
}

connection.addEventListener('change', updateConnectionStatus);

Preload large resources

The connection object is useful for deciding whether to preload resources that take large amounts of bandwidth or memory. This example would be called soon after page load to check for a connection type where preloading a video may not be desirable. If a cellular connection is found, then the preloadVideo flag is set to false. For simplicity and clarity, this example only tests for one connection type. A real-world use case would likely use a switch statement or some other method to check all of the possible values of NetworkInformation.type. Regardless of the type value you can get an estimate of connection speed through the NetworkInformation.effectiveType property.

let preloadVideo = true;
var connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;
if (connection) {
  if (connection.type === 'cellular') {
    preloadVideo = false;
  }
}

Interfaces

Provides information about the connection a device is using to communicate with the network and provides a means for scripts to be notified if the connection type changes. The NetworkInformation interfaces cannot be instantiated. It is instead accessed through the Navigator interface.