W3C

The Network Information API

W3C Working Draft 29 November 2012

This version:
http://www.w3.org/TR/2012/WD-netinfo-api-20121129/
Latest published version:
http://www.w3.org/TR/netinfo-api/
Latest editor's draft:
http://dvcs.w3.org/hg/dap/raw-file/tip/network-api/Overview.html
Previous version:
http://www.w3.org/TR/2011/WD-netinfo-api-20110607/
Editor:
Mounir Lamouri, Mozilla

Abstract

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

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

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.

This document was published by the Device APIs and Policy Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

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

1.1 Use Cases

This section is non-normative.

The main use case of the Network Information API is to allow applications to be gentle with the user's bandwidth when they know it is rare or expensive. Even if there are not many applications that do this currently, this specification offers the the tools needed to enable this, allowing it to become more common.

A few hypothetical examples would be:

1.2 Outstanding issues

The specification currently requests the user agent to expose two properties: bandwidth and metered. The working group currently does not have consensus on these.

One concern is that bandwidth may be hard to implement, can be quite power-consuming to keep up-to-date and its value might be unrelated to the actual connection quality that could be affected by the server.
A solution to fix this would be to return non absolute values that couldn't be easily abused and would be more simple to produce for the user agent. For example, having a set of values like very-slow, slow, fast and very-fast. Another solution would be to have only values like very-slow, slow and the empty string."

metered may also be hard to implement as there is currently no standard way for the OS to know if the current connection is metered. The approach of the specification is to leave the implementation details to the user agent. That way, the attribute could return a value based on a heuristic, on knowledge of the current connection status or even by directly asking the user for the information.
It is interesting to point that Android 4.1 and Windows 8 both have a way to check if the current connection is metered. Android is using a boolean (isActiveNetworkMetered()) while Windows 8 allow the developer to ask for different information (NetworkCostType, ApproachingDataLimit, OverDataLimit, Roaming).

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

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].

3. Terminology

The EventHandrer interface represents a callback used for event handlers as defined in [HTML5].

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

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

The concepts of browsing context and active document are defined in [HTML5].

The concept of document domain is defined in [HTML5].

4. 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 currently in use by the hosting device.

5. The NetworkInformation interface

The NetworkInformation interface is exposed on the Navigator object.

Navigator implements NetworkInformation;

All instances of the Navigator type are defined to also implement the NetworkInformation interface.

[NoInterfaceObject]
interface NetworkInformation {
    readonly attribute Connection connection;
};

5.1 Attributes

connection of type Connection, readonly
The object from which connection information is accessed.

6. The Connection interface

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

[NoInterfaceObject]
interface Connection : EventTarget {
    readonly attribute double    bandwidth;
    readonly attribute boolean   metered;
    [TreatNonCallableAsNull]
             attribute EventHandler? onchange;
};

6.1 Attributes

bandwidth of type double, readonly
The user agent must set the value of the bandwidth attribute to:
  • 0 if the user is currently offline;
  • Infinity if the bandwidth is unknown;
  • an estimation of the current bandwidth in MB/s (Megabytes per seconds) available for communication with the browsing context active document's domain.
metered of type boolean, readonly

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 careful with the bandwidth usage.

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

The user agent must set the value of the metered attribute to true if the connection with the browsing context active document's domain is metered and false otherwise. If the implementation is not able to know the status of the connection or if the user is offline, the value must be set to false.

Note
If unable 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 could let the user define if the mobile connection used on the device is metered.
onchange of type EventHandler, nullable

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

When the user goes online or offline, in addition to 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].

6.2 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

7. Examples

This section is non-normative.

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

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

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

show();

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

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

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

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

Example 3
<!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>

A. Acknowledgments

Thanks to Robin Berjon, Frederick Hirsch and Jonas Sicking for their help.

B. References

B.1 Normative references

[HTML5]
Ian Hickson; David Hyatt. HTML5. 29 March 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/