mozilla
Your Search Results

    Network Stats

    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.

    Summary

    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 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 DOMStringsappManifestURL 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):

    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);
    };

    MozNetworkStatsManager method overview

    nsIDOMDOMRequest getSamples(in nsISupports network,
                                in jsval start,
                                in jsval end,
                                [optional] in jsval options /* NetworkStatsGetOptions */);
    nsIDOMDOMRequest addAlarm(in nsISupports network,
                              in long threshold,
                              [optional] in jsval options /* NetworkStatsAlarmOptions */);
    nsIDOMDOMRequest getAllAlarms([optional] in nsISupports network);
    nsIDOMDOMRequest removeAlarms([optional] in long alarmId);
    nsIDOMDOMRequest clearStats(in nsISupports network);
    nsIDOMDOMRequest clearAllStats();
    nsIDOMDOMRequest getAvailableNetworks();
    nsIDOMDOMRequest getAvailableServiceTypes();

    Attributes

    Attribute Type Description
    sampleRate long Minimum time in milliseconds between samples stored in the database. Read only.
    maxStorageAge long long Time in milliseconds recorded by the API until present time. All samples older than maxStorageAge from now are deleted. Read only.

    Constants

    Constant Type Description
    WIFI long Constant for WIFI, set to 0
    MOBILE long Constant for MOBILE, set to 1

    Specification

    Not part of any specification.

    See also

    Document Tags and Contributors

    Contributors to this page: SpencerG, zeller, Jeremie, chrisdavidmills, kscarfone, teoli, acperez
    Last updated by: chrisdavidmills,