Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
The Network Information API provides an interface for web applications to access the underlying connection information of the device.
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.
This section is non-normative.
The Network Information API provides an interface enabling web applications to access the underlying connection information of the device.
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:
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).
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].
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 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.
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;
};connection of type Connection, readonlyConnection 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;
};bandwidth of type double, readonlybandwidth attribute to:
metered of type boolean, readonlyA 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.
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.
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].
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 |
This section is non-normative.
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 image viewer can select a low definition or a high definition image based on the current connection bandwidth:
<!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:
<!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>
Thanks to Robin Berjon, Frederick Hirsch and Jonas Sicking for their help.