Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.
This API is available on Firefox OS for internal applications only.
The Network Stats API allows you to monitor data usage and expose this information to certified applications.
Data can be accessed through navigator.mozNetworkStats
which returns an instance of the MozNetworkStatsManager
interface.
Accessing data
Information about the volume of data received and sent is automatically stored by the system. Accessing this information is possible by using the MozNetworkStatsManager.getSamples()
method. This method expects three parameters, and a fourth parameter is optional:
network
: The origin of the data, which can representwifi
ormobile
. Ifnull
, data measurement from both origins are merged. To know in advance which kind of origin is available, theMozNetworkStatsManager.getAvailableNetworks()
method returns anArray
ofMozNetworkStats
objects representing each supported interface.start
: ADate
object representing the beginning of data measurement.end
: ADate
object representing the end of data measurement.options
Optional: ANetworkStatsGetOptions
dictionary. It consists of three keys, two of which areDOMString
objects —appManifestURL
andserviceType
— and the one which is a boolean —browsingTrafficOnly
.appManifestURL
is used to filter network stats by app.serviceType
is used to filter stats by system service. Note thatserviceType
andappManifestURL
cannot currently be specified at the same time for now. This results in anNS_ERROR_NOT_IMPLMENTED
exception being thrown.browsingTrafficOnly
controls what kind of traffic is returned in the network stats. If it is set totrue
, only the browsing traffic generated from the mozbrowser<iframe>
element within an app is returned in result. If it is set asfalse
(the default), the total traffic — which is generated from both the mozapp and mozbrowser<iframe>
elements — is returned.
When called, getSamples()
returns a DOMRequest
to handle the success or failure of the information request. In case of success the request's result
is a MozNetworkStats
object.
var networks = navigator.mozNetworkStats.getAvailableNetworks(); networks.onsuccess = function() { var network = this.result[0]; // 0 for Wifi; returns a mozNetworkInterface object var end = new Date(); var start = new Date(); var samples = navigator.mozNetworkStats.getSamples(network, start, end); // returns a mozNetworkStats object samples.onsuccess = function () { console.log("Data received: " + samples.result.data[0].rxBytes + " Bytes"); console.log("Data sent: " + samples.result.data[0].txBytes + " Bytes"); }; samples.onerror = function () { console.log("Something went wrong: ", samples.error); }; }; networks.onerror = function () { console.log("Something went wrong: ", networks.error); };
Sampling over time
To visualise data usage over time, the information about the amount of data is stored in chunks. Each chunk is a value representing the amount of data exchanged since the last chunk was stored.
When requesting the stats, the resulting MozNetworkStats
object contains as many data chunks as possible for the interval defined between the start
and end
date. The total number of chunks depends on two parameters (note that those parameters are read-only):
MozNetworkStatsManager.sampleRate
, which represents the minimum time in milliseconds between samples stored in the database.MozNetworkStatsManager.maxStorageAge
, which represents the time in milliseconds recorded by the API until present time. All samples older than maxStorageAge from now are deleted.
Each data chunk is a MozNetworkStatsData
object, and all the data chunks for a given time frame are available through the MozNetworkStats.data
property, which is an Array
of MozNetworkStatsData
objects.
var networks = navigator.mozNetworkStats.getAvailableNetworks(); networks.onsuccess = function() { var network = this.result[0]; // 0 for Wifi; returns a mozNetworkInterface object var end = new Date(); var oneHour = 3600000; //in milliseconds var start = new Date(end.getTime() - oneHour); var samples = navigator.mozNetworkStats.getSamples(network, start, end); // returns a mozNetworkStats object samples.onsuccess = function () { var total = { receive: 0, send : 0 }; samples.result.data.forEach(function (chunk) { // array of MozNetworkStatsData objects total.receive += chunk.rxBytes; total.send += chunk.txBytes; }); console.log("Since: " + start.toString()); console.log("Data received: " + total.receive + " Bytes"); console.log("Data sent: " + total.send + " Bytes") }; samples.onerror = function () { console.log("Something went wrong: ", samples.error); }; }; networks.onerror = function () { console.log("Something went wrong: ", networks.error); };
Specification
Not part of any specification.