mozNetworkStats

Summary

The MozNetworkStatsManager interface provides methods and properties to monitor data usage.

Properties

MozNetworkStatsManager.maxStorageAge Read only

A number representing the time in milliseconds recorded by the API until present time for each type of connection. All samples older than maxStorageAge from now are deleted.

MozNetworkStatsManager.sampleRate Read only

A number representing the minimum time in milliseconds between samples stored in the database.

Methods

MozNetworkStatsManager.addAlarm()

Allows to install an alarm on a network. Returns a DOMRequest object to handle the success or failure of the request.

MozNetworkStatsManager.clearAllStats()

Allows to clear all the statistics about the data usage. Returns a DOMRequest object to handle the success or failure of the request.

MozNetworkStatsManager.clearStats()

Allows to clear all the statistics about the data usage on a specific network. Returns a DOMRequest object to handle the success or failure of the request.

MozNetworkStatsManager.getAllAlarms()

Allows to obtain all alarms for those networks returned by MozNetworkStatsManager.getAvailableNetworks. Returns a DOMRequest object to handle the success or failure of the request.

MozNetworkStatsManager.getAvailableNetworks()

Allows to obtain an Array of available networks that used to be saved in the database. Returns a DOMRequest object to handle the success or failure of the request.

MozNetworkStatsManager.getAvailableServiceTypes()

Allows to obtain an Array of available service types that used to be saved in the database. Returns a DOMRequest object to handle the success or failure of the request.

MozNetworkStatsManager.getSamples()

Allows to access the data usage statistics. Returns a DOMRequest object to handle the success or failure of the request.

MozNetworkStatsManager.removeAlarms()

Allows to remove all network alarms, or a specific network alarm, if an alarmId is provided. Returns a DOMRequest object to handle the success or failure of the request.

Constants

MozNetworkStatsManager.WIFI

Returns 0, identifying Wifi

MozNetworkStatsManager.MOBILE

Returns 1, identifying Mobile

Example 1

Information about the volume of data received and sent are automatically stored by the system. Accessing them is possible by using the MozNetworkStatsManager.getSamples() method. This method expects three parameters, and a fourth parameter is optional. Here are those parameters:

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 MozNetworkStatsInterface 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 DOMStrings called appManifestURL and serviceType, and the third is the boolean browsingTrafficOnly. appManifestURL is used to filter network stats by app, while serviceType is used to filter stats by system service. Note that these two options cannot be specified at the same time for now; otherwise, an NS_ERROR_NOT_IMPLMENTED exception will be thrown. As for browsingTrafficOnly, if it is set as true, only the browsing traffic, which is generated from the mozbrowser iframe element within an app, is returned in result. If it is set as false or not set, the total traffic, which is generated from both the mozapp and mozbrowser iframe elements, is returned.

When called, this method 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);
};

Example 2

To get a vision of 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);

Permissions

"type": "certified",
"permissions": {
  "networkstats-manage": {
    "description": "Required for accessing network statistics information on the device."
  }
}

Specification

Not part of any specification.

See also

• Network Stats API
• MozNetworkStats
• MozNetworkStatsData
• MozNetworkStatsManager