# Network Information Plugin Tested Version: [2.0.1](https://github.com/apache/cordova-plugin-network-information/releases/tag/2.0.1) {% hint style="info" %} This document is based on the original Cordova docs available at [Cordova Docs](https://github.com/apache/cordova-plugin-network-information). {% endhint %} This plugin provides an implementation of an old version of the [Network Information API](http://www.w3.org/TR/2011/WD-netinfo-api-20110607/). It provides information about the device's cellular and wifi connection, and whether the device has an internet connection. ## Plugin ID ```javascript cordova-plugin-network-information ``` ## Adding the Plugin in Monaca In order to use this plugin, please [enable](https://en.docs.monaca.io/products_guide/monaca_ide/dependencies/cordova_plugin#importing-cordova-plugins) `Network Information` plugin in Monaca Cloud IDE. ## Supported Platforms * Android * iOS ## Reference ### 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** ```javascript 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. ## Network-related Events ### offline The event fires when an application goes offline, and the device is not connected to the Internet. ```javascript 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 ```javascript 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. ### online This event fires when an application goes online, and the device becomes connected to the Internet. ```javascript 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 ```javascript 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`. ## 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. {% hint style="info" %} This code example requires the File plugin. {% endhint %} ```javascript 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. ```javascript 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.NON`E. If you have a connection, you try to upload a file. ```javascript 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. {% hint style="info" %} This example requires the FileTransfer plugin. {% endhint %} ```javascript 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 element in index.html. ft.upload(fileURL, encodeURI(SERVER), success, fail, options); }; ``` Here is the code for the `offlineWrite` function. {% hint style="info" %} This code examples requires the File plugin. {% endhint %} ```javascript 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). ```javascript function onOffline() { // Handle the offline event console.log("lost connection"); } ``` See Also: * [Third-party Cordova Plugins](https://en.docs.monaca.io/reference/third_party_phonegap) * [Core Cordova Plugins](https://en.docs.monaca.io/reference/core-cordova-plugins)