Network Stats API

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 represent wifi or mobile. If null, data measurement from both origins are merged. To know in advance which kind of origin is available, the MozNetworkStatsManager.getAvailableNetworks() method returns an Array of MozNetworkStats objects representing each supported interface.
• start: A Date object representing the beginning of data measurement.
• end: A Date object representing the end of data measurement.
• options Optional: A NetworkStatsGetOptions dictionary. It consists of three keys, two of which are DOMString objects — appManifestURL and serviceType — 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 that serviceType and appManifestURL cannot currently be specified at the same time for now. This results in an NS_ERROR_NOT_IMPLMENTED exception being thrown.
  • browsingTrafficOnly controls what kind of traffic is returned in the network stats. If it is set to true, only the browsing traffic generated from the mozbrowser <iframe> element within an app is returned in result. If it is set as false (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.

See also

• Navigator.mozNetworkStats
• MozNetworkStats
• MozNetworkStatsData
• MozNetworkStatsManager
• NetworkStats API 2.0 proposal