The Network Information API provides an interface for Web Applications to access the underlying connection information of the device.

The functionality described in this specification was initially specified as part of the System Information API but has been extracted in order to be more readily available, more straightforward to implement, and in order to produce a specification that could be implemented on its own merits without interference with other, often unrelated, features.

Introduction

The Network Information API provides an interface enabling Web applications to access the underlying connection information of the device.

The following example shows how an image viewer can select a low definition or a high definition image based on the current connection bandwidth:

        <!DOCTYPE>
        <html>
          <head>
            <title>Poney viewer</title>
          </head>
          <body>
            <img id='poney' alt="An image showing a poney" title="My precious!"></img>
            <script>
              var i = document.getElementById('poney');

              if (navigator.connection.bandwidth > 2) {
                i.src = "http://example.com/poney_hd.png";
              } else {
                i.src = "http://example.com/poney_ld.png";
              }
            </script>
          </body>
        </html>
      

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to expose the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]].

Terminology

The Function interface represents a function in the scripting language being used as defined in [[!HTML5]].

The concepts queue a task and fires a simple event are defined in [[!HTML5]].

The terms event handlers and event handler event types are defined in [[!HTML5]].

Security and privacy considerations

The API defined in this specification is used to determine the connection information of the hosting device. The information disclosed has minimal impact on privacy or fingerprinting, and therefore is exposed without permission grants. For example, authors cannot directly know what kind of connection is actually in use by the hosting device.

The NetworkInformation interface

The NetworkInformation interface is exposed on the Navigator object.

readonly attribute Connection connection
The object from which connection information is accessed.

The Connection interface

The Connection interface provides a handle to the device's connection information.

readonly attribute double bandwidth
The attribute SHOULD return an estimation of the current bandwdith in MB/s (Megabytes per seconds) the user agent has with the Document's subdomain. It MUST return Infinity if the bandwidth is unknown and it MUST return 0 if the user is currently offline.
readonly attribute boolean metered

A connection is metered when the user's connection is subject to a limitation from his Internet Service Provider strong enough to request web applications to be gentle with the bandwidth usage.

What is a metered connection is voluntarily left to the user agent. It would not be possible to give an exhaustive way of all limitations considered strong enough to flag the connection has metered and even if doable, some limitations can be considered strong or weak depending on the context.
Examples of metered connections are mobile connection with a small bandwidth quota or a connection with a pay-per use.

The attribute SHOULD return true if the connection with the Document's subdomain is metered and false otherwise. If the implementation is not able to know the status of the connection or if the user is offline, it MUST return false.

If not able to know if a connection is metered, a user agent could ask the user about the status of his current connection. For example, a preference letting the user say if the mobile connection used on the device is metered.
[TreatNonCallableAsNull] attribute Function? onchange

When the Connection changes, the user agent MUST queue a task which updates the Connection properties and fires a simple event named change at the Connection object.

When the user goes online or offline, in addition of the change event fired on the Connection object, the user agent has to fire a simple event named either online or offline depending on the applicable value, as defined in [[!HTML5]].

Event handlers

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the Connection object:

event handler event handler event type
onchange change

Examples

This trivial example writes the connection bandwidth to the console and shows it again each time it is changing:

          function show() {
            console.log(navigator.connection.bandwidth);
          }

          navigator.connection.addEventListener('change', show, false);

          show();
        

This example shows how an application can prevent automatic polling using the metered attribute:

          <!DOCTYPE html>
          <html>
            <head>
              <title>Conditional polling</title>
              <script>
                var gPreviousMetered = navigator.connection.metered;
                var gIntervalId;

                function poll() {
                  // poll stuff
                }

                navigator.connection.addEventListener('change', function() {
                  if (gPreviousMetered == navigator.connection.metered) {
                    return;
                  }

                  gPreviousMetered = navigator.connection.metered;
                  if (navigator.connection.metered) {
                    gIntervalId = setInterval(poll, 1000);
                  } else {
                    clearInterval(gIntervalId);
                  }
                }, false);

                // At load time.
                if (navigator.connection.metered) {
                  gIntervalId = setInterval(poll, 1000);
                }
              </script>
            </head>
            <body>
              <button onclick="poll();">Poll</button>
            </body>
          </html>
        

Acknowledgements