The Network Information API enables web applications to access information about the network connection in use by the device.
### What's new? * Introduced the `downlinkMax`. [Discussion on GH](https://github.com/w3c/netinfo/issues/13). * Reintroduce the `type` attribute from the [20110607](http://www.w3.org/TR/2011/WD-netinfo-api-20110607) spec, but with a different set of connection types. * Remove the `bandwidth` and `metered` attributes from the [20121129](http://www.w3.org/TR/2012/WD-netinfo-api-20121129/) spec. * Keep the `onchange` event introduced in the [20121129](http://www.w3.org/TR/2012/WD-netinfo-api-20121129/) spec, but renamed to `ontypechange`. For the rationale for the changes, see the [Discussion](https://github.com/w3c-webmob/netinfo#discussion) section of the [Review of Apps that Use Network Information](https://github.com/w3c-webmob/netinfo).
## Use cases and requirements This document attempts to address the [requirements](https://github.com/w3c-webmob/netinfo/blob/master/README.md) from the [Review of Apps that Use Network Information](https://github.com/w3c-webmob/netinfo) document published by the Web and Mobile Interest Group. Those are: * Provide access to the connection type the system is using to communicate with the network (e.g., cellular, bluetooth, ethernet, wifi, other, or none). This information needs to be available either immediately on page load or as close as possible to it. * Provide a means for scripts to be notified if the connection type changes. This is to allow developers to make dynamic changes to the DOM and/or inform the user that the network connection type has changed (and that it could impact them in some way).
## Examples of usage For examples of the kinds of applications one can build with this API, see the [Review of Apps that Use Network Information](https://github.com/w3c-webmob/netinfo).
// Get the connection type.
var type = navigator.connection.type;

// The maximum downlink speed of the connection
var max = navigator.connection.downlinkMax;

function changeHandler(e) {
  // Handle change to connection here.
}

// Register for event changes.
navigator.connection.onchange = changeHandler;

// Alternatively.
navigator.connection.addEventListener('change', changeHandler);
## Dependencies and definitions The task source used by this specification is the the networking task source [[!HTML]]. The following concepts are defined in [[!DOM]]: * Queue a task. * Fire a simple event. For clarity, a megabit is 1,000,000 bits, and megabits per second is equivalent to transferring: * 1,000,000 bits per second * 1,000 kilobits per second * 125,000 bytes per second * 125 kilobytes per second * and so on...
## Connection types This section defines the connection types:
bluetooth
The user agent is using a Bluetooth connection as the underlying connection technology.
cellular
The user agent is using a cellular connection as the underlying connection technology (e.g., EDGE, HSPA, LTE, etc.).
ethernet
The user agent is using an Ethernet connection as the underlying connection technology.
none
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) - i.e., equivalent to `navigator.onLine === false` in HTML.
wifi
The user agent is using a Wi-Fi connection as the underlying connection technology.
other
The user agent is using a connection type that is not one of enumerated connection types as the underlying connection technology.
unknown
The user agent has established a network connection, but is unable to determine what is the underlying connection technology.
## Extensions to the `Navigator` interface
readonly attribute NetworkInformation connection
### The `connection` attribute The `connection` attribute, when getting, returns an object that implements the `NetworkInformation` interface.
## The `NetworkInformation` interface The `NetworkInformation` interface provides a means to access information about the network connection the user agent is currently using.
readonly attribute ConnectionType type
readonly attribute Megabit downlinkMax
attribute EventHandler onchange
### `type` attribute The `type` attribute, when getting, returns the connection type that the user agent is using. ### `downlinkMax` attribute The `downlinkMax` attribute represents the maximum downlink speed, in megabits per second (Mbps), for underlying connection technology.
##Underlying connection technology The underlying connection technology represents the generation and/or version of the network connection being used by the device. For example, "HSPA" (3.5G) for cellular, or "802.11g" for Wi-Fi. This differs from the connection type exposed by the API, in that it is more fine grained. Each underlying connection technology has an associated maximum downlink speed, which is the standardized, or generally accepted, maximum download data rate in megabits per second. The relationship between an underlying connection technology and its maximum downlink speed is captured in the table of maximum downlink speeds.
The underlying connection technology is not directly exposed to script. Instead, the maximum downlink speed is exposed via the `downlinkMax` attribute.
### Handling changes to the underlying connection If the underlying connection technology changes (in either connection type or maximum downlink speed), the user agent MUST run the steps to update the connection values: 1. Let new-type be the connection type that represents the underlying connection technology. 1. Let max-value be `+Infinity`. 1. If new-type is "none", set max-value to `0`. 1. Otherwise, if new-type is not "unknown": 1. Set max-value to the maximum downlink speed of the underlying connection technology from the table of maximum downlink speeds. 1. If max-value is not equal to the value of `connection.downlinkMax` or if new-type is not equal to the value of `connection.type`: 1. Using the networking task source, queue a task to perform the following: 1. Set `connection.downlinkMax` to max-value. 1. Set `connection.type` to new-type. 1. Fire a simple event named `change` at the `NetworkInformation` object.
## The `ConnectionType` enum
cellular
bluetooth
ethernet
wifi
other
none
unknown
There is only one class of product that can claim conformance to this specification: a user agent.
## Acknowledgments This document reuses text from the [[!HTML]] specification, edited by Ian Hickson, as permitted by the license of that specification.