Latest 1.3.0
Homepage https://github.com/apache/cordova-plugin-network-information
License Apache License, Version 2.0 “type”: “Apache License, Version 2.0”,
“text”: ” Licensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Platforms ios 8.0, requires ARC
Dependencies Cordova
Authors

title: Network Information
description: Get information about wireless connectivity.

Android iOS Windows 8.1 Store Windows 8.1 Phone Windows 10 Store Travis CI
Build Status Build Status Build Status Build Status Build Status Build Status

This plugin provides an implementation of an old version of the
Network Information API.
It provides information about the device’s cellular and
wifi connection, and whether the device has an internet connection.

To get a few ideas how to use the plugin, check out the sample at the bottom of this page or go straight to the reference content.

Report issues with this plugin on the Apache Cordova issue tracker.

Reference

Installation

cordova plugin add cordova-plugin-network-information

Supported Platforms

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Browser
  • iOS
  • Windows Phone 7 and 8
  • Tizen
  • Windows
  • Firefox OS

Connection

The connection object, exposed via navigator.connection, provides information about the device’s cellular and wifi connection.

Properties

  • connection.type

Constants

  • Connection.UNKNOWN
  • Connection.ETHERNET
  • Connection.WIFI
  • Connection.CELL_2G
  • Connection.CELL_3G
  • Connection.CELL_4G
  • Connection.CELL
  • Connection.NONE

connection.type

This property offers a fast way to determine the device’s network
connection state, and type of connection.

Quick Example

function checkConnection() {
    var networkState = navigator.connection.type;

    var states = {};
    states[Connection.UNKNOWN]  = 'Unknown connection';
    states[Connection.ETHERNET] = 'Ethernet connection';
    states[Connection.WIFI]     = 'WiFi connection';
    states[Connection.CELL_2G]  = 'Cell 2G connection';
    states[Connection.CELL_3G]  = 'Cell 3G connection';
    states[Connection.CELL_4G]  = 'Cell 4G connection';
    states[Connection.CELL]     = 'Cell generic connection';
    states[Connection.NONE]     = 'No network connection';

    alert('Connection type: ' + states[networkState]);
}

checkConnection();

API Change

Until Cordova 2.3.0, the Connection object was accessed via
navigator.network.connection, after which it was changed to
navigator.connection to match the W3C specification. It’s still
available at its original location, but is deprecated and will
eventually be removed.

iOS Quirks

  • <iOS7 can’t detect the type of cellular network connection.
    • navigator.connection.type is set to Connection.CELL for all cellular data.

Windows Phone Quirks

  • When running in the emulator, always detects navigator.connection.type as Connection.UNKNOWN.

  • Windows Phone can’t detect the type of cellular network connection.
    • navigator.connection.type is set to Connection.CELL for all cellular data.

Windows Quirks

  • When running in the Phone 8.1 emulator, always detects navigator.connection.type as Connection.ETHERNET.

Tizen Quirks

  • Tizen can only detect a WiFi or cellular connection.
    • navigator.connection.type is set to Connection.CELL_2G for all cellular data.

Firefox OS Quirks

  • Firefox OS can’t detect the type of cellular network connection.
    • navigator.connection.type is set to Connection.CELL for all cellular data.

Browser Quirks

  • Browser can’t detect the type of network connection.
    navigator.connection.type is always set to Connection.UNKNOWN when online.

Network-related Events

offline

The event fires when an application goes offline, and the device is
not connected to the Internet.

document.addEventListener("offline", yourCallbackFunction, false);

Details

The offline event fires when a previously connected device loses a
network connection so that an application can no longer access the
Internet. It relies on the same information as the Connection API,
and fires when the value of connection.type becomes NONE.

Applications typically should use document.addEventListener to
attach an event listener once the deviceready event fires.

Quick Example

document.addEventListener("offline", onOffline, false);

function onOffline() {
    // Handle the offline event
}

iOS Quirks

During initial startup, the first offline event (if applicable) takes at least a second to fire.

Windows Phone 7 Quirks

When running in the Emulator, the connection.status is always unknown, so this event does not fire.

Windows Phone 8 Quirks

The Emulator reports the connection type as Cellular, which does not change, so the event does not fire.

online

This event fires when an application goes online, and the device
becomes connected to the Internet.

document.addEventListener("online", yourCallbackFunction, false);

Details

The online event fires when a previously unconnected device receives
a network connection to allow an application access to the Internet.
It relies on the same information as the Connection API,
and fires when the connection.type changes from NONE to any other
value.

Applications typically should use document.addEventListener to
attach an event listener once the deviceready event fires.

Quick Example

document.addEventListener("online", onOnline, false);

function onOnline() {
    // Handle the online event
}

iOS Quirks

During initial startup, the first online event (if applicable) takes
at least a second to fire, prior to which connection.type is
UNKNOWN.

Windows Phone 7 Quirks

When running in the Emulator, the connection.status is always unknown, so this event does not fire.

Windows Phone 8 Quirks

The Emulator reports the connection type as Cellular, which does not change, so events does not fire.

Sample: Upload a File Depending on your Network State

The code examples in this section show examples of changing app behavior using the online and offline events and your network connection status.

To start with, create a new FileEntry object (data.txt) to use for sample data. Call this function from the deviceready handler.

Note This code example requires the File plugin.

var dataFileEntry;

function createSomeData() {

    window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {

        console.log('file system open: ' + fs.name);
        // Creates a new file or returns an existing file.
        fs.root.getFile("data.txt", { create: true, exclusive: false }, function (fileEntry) {

          dataFileEntry = fileEntry;

        }, onErrorCreateFile);

    }, onErrorLoadFs);
}

Next, add listeners for the online and offline events in the deviceready handler.

document.addEventListener("offline", onOffline, false);
document.addEventListener("online", onOnline, false);

The app’s onOnline function handles the online event. In the event handler, check the current network state. In this app, treat any connection type as good except Connection.NONE. If you have a connection, you try to upload a file.

function onOnline() {
    // Handle the online event
    var networkState = navigator.connection.type;

    if (networkState !== Connection.NONE) {
        if (dataFileEntry) {
            tryToUploadFile();
        }
    }
    display('Connection type: ' + networkState);
}

When the online event fires in the preceding code, call the app’s tryToUploadFile function.

If the FileTransfer object’s upload function fails, call the app’s offlineWrite function to save the current data somewhere.

Note This example requires the FileTransfer plugin.

function tryToUploadFile() {
    // !! Assumes variable fileURL contains a valid URL to a text file on the device,
    var fileURL = getDataFileEntry().toURL();

    var success = function (r) {
        console.log("Response = " + r.response);
        display("Uploaded. Response: " + r.response);
    }

    var fail = function (error) {
        console.log("An error has occurred: Code = " + error.code);
        offlineWrite("Failed to upload: some offline data");
    }

    var options = new FileUploadOptions();
    options.fileKey = "file";
    options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
    options.mimeType = "text/plain";

    var ft = new FileTransfer();
    // Make sure you add the domain of your server URL to the
    // Content-Security-Policy <meta> element in index.html.
    ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
};

Here is the code for the offlineWrite function.

Note This code examples requires the File plugin.

function offlineWrite(offlineData) {
    // Create a FileWriter object for our FileEntry.
    dataFileEntry.createWriter(function (fileWriter) {

        fileWriter.onwriteend = function () {
            console.log("Successful file write...");
            display(offlineData);
        };

        fileWriter.onerror = function (e) {
            console.log("Failed file write: " + e.toString());
        };

        fileWriter.write(offlineData);
    });
}

If the offline event occurs, just do something like notify the user (for this example, just log it).

function onOffline() {
    // Handle the offline event
    console.log("lost connection");
}

Latest podspec

{
    "name": "cordova-plugin-network-information",
    "version": "1.3.0",
    "summary": "Cordova Network Information Plugin",
    "description": "This plugin provides an implementation of an old version of the Network Information API. It provides information about the device's cellular and wifi connection, and whether the device has an internet connection.",
    "homepage": "https://github.com/apache/cordova-plugin-network-information",
    "license": {
        "type": "Apache License, Version 2.0",
        "text": "    "type": "Apache License, Version 2.0",n    "text": "      Licensed under the Apache License, Version 2.0 (the "License");n      you may not use this file except in compliance with the License.n      You may obtain a copy of the License atn      n      http://www.apache.org/licenses/LICENSE-2.0n      n      Unless required by applicable law or agreed to in writing, softwaren      distributed under the License is distributed on an "AS IS" BASIS,n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.n      See the License for the specific language governing permissions andn      limitations under the License.n"n"
    },
    "authors": {
        "The Adobe PhoneGap Team": ""
    },
    "platforms": {
        "ios": "8.0"
    },
    "source": {
        "git": "https://github.com/apache/cordova-plugin-network-information.git",
        "tag": "1.3.0"
    },
    "source_files": "src/ios/*.{h,m}",
    "preserve_paths": [
        "*.md",
        "docs/**/*.md",
        "www/*.js",
        "www/ios/*.js"
    ],
    "requires_arc": true,
    "dependencies": {
        "Cordova": [
            ">= 4.3.0"
        ]
    }
}

Pin It on Pinterest

Share This