cordova-plugin-advanced-geolocation (Android-only)

Highly configurable native interface to GPS and NETWORK on-device location providers. It will return and identify any location data registered by the on-device providers including real-time satellite info.

It also offers direct access to CellInfo, CellLocation and CellSignalStrength data.

In comparison to the W3C HTML Geolocation API, this plugin provides you with significantly greater control and more information to make better decisions with geolocation data.

If you are experiencing annoying jumping around of your geolocation coordinates then this plugin will help. It seperates GPS from NETWORK coordinates and allows you smooth out the user experience.

This plugin is available via npm.

Supported Platforms

Android-only. This plugin is designed for Android versions between Android 5.0.0 (Lollipop / API Level 21) and Android 6.x (Marshmallow / API Level 23).

IMPORTANT This library currently doesn't implement any Android N+ GPS capabilities. All capabilities in the current plugin should be compatible with Android 5+. See the issues list for the most current information.

Cordova supports the following android releases.

Quick Start!

Here are the cliff notes for getting started. More details on the Cordova CLI can be found here.

cordova create cordova-advanced-geolocation com.esri.geo GeoTest

cd cordova-advanced-geolocation

cordova platform add android

If you are running the latest version of Cordova you don't need to run update:

cordova platform update [email protected] [choose 5.0.0 or higher]

cordova plugin add https://github.com/esri/cordova-plugin-advanced-geolocation.git

In config.xml modify the src to either <content src="sample-map.html" /> or <content src="sample-leaflet-map.html" />

cordova build

Plug in your phone and run: cordova run android, or in Android Studio select ^D.

IMPORTANT!

This API does NOT conform to the coding patterns described in the W3C Geolocation API Specification.

Use this plugin to gain significantly greater control and insight into which location provider submitted geolocation data.

This plugin won't increase device accuracy. Accuracy is heavily dependent on the quality of the GPS antenna and the GPS processor. Most smartphones and tablets use consumer-priced GPS chipsets and micro-strip antennas which under perfect conditions typically return between 3 - 10 meters accuracy, at best. For more information check out this series of blog posts.

External consumer GPS devices may help provide better accuracy, faster location acquisition and less location fluctuation. Here's a good article on Why Buy an External GPS Antenna?.

If your requirements specifically call for less than 3 meter accuracy then consider using a commercial, external high-accuracy GPS such as the Trimble R1 and slave it to your device via Bluetooth.

PRIVACY WARNING Keep in mind the W3C security and privacy considerations. This plugin uses native geolocation functionality only. Users will not automatically see a W3C Geolocation prompt, they will only get native Android prompts. The plugin requires the following Android User Permissions: ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION, ACCESS_NETWORK_STATE, ACCESS_WIFI_STATE and INTERNET.

API Reference

Click here to read all about it.

Example Usage

    
    // Implement this in `deviceready` event callback
    AdvancedGeolocation.start(function(success){

        try{
            var jsonObject = JSON.parse(success);

            switch(jsonObject.provider){
                case "gps":
					 //TODO
                    break;

                case "network":
					 //TODO
                    break;

                case "satellite":
					 //TODO
                    break;
                    
                case "cell_info":
                	//TODO
                	break;
                	
                case "cell_location":
                	//TODO
                	break;  
                
                case "signal_strength":
                	//TODO
                	break;              	
            }
        }
        catch(exc){
            console.log("Invalid JSON: " + exc);
        }
    },
    function(error){
        console.log("ERROR! " + JSON.stringify(error));
    },
    ////////////////////////////////////////////
    //
    // REQUIRED:
    // These are required Configuration options!
    // See API Reference for additional details.
    //
    ////////////////////////////////////////////
    {
        "minTime":500,         // Min time interval between updates (ms)
        "minDistance":1,       // Min distance between updates (meters)
        "noWarn":true,         // Native location provider warnings
        "providers":"all",     // Return GPS, NETWORK and CELL locations
        "useCache":true,       // Return GPS and NETWORK cached locations
        "satelliteData":false, // Return of GPS satellite info
        "buffer":false,        // Buffer location data
        "bufferSize":0,        // Max elements in buffer
        "signalStrength":false // Return cell signal strength data
    });

Use Cases

Here are example use cases for the different ways location providers can be set in the configuration options via the providers attribute:

• "gps" Activates only the GPS provider. Best accuracy where device has an unobstructed view of the sky.
• "network" Activates only the Network provider. Best accuracy indoors and urban/downtown areas with tall buildings where device does not have an unobstructed view of the sky and cellular service is available and/or WiFi.
• "cell" Access only cell network information.
• "all" Activates GPS, Network and Cellular providers. Allows you to take advantage of network providers to establish initial location and then use GPS to finalize a more accurate location. Typically the device will provide the network location first before the GPS warms up. After the GPS warms up, and if the accuracy is good enough for your requirements, then you would switch to using the GPS locations. The Cellular provider gives you access to cell tower location information.
• "some" Activates only GPS and Network providers. Allows you to take advantage of network providers to establish initial location and then use GPS to finalize a more accurate location. Typically the device will provide the network location first before the GPS warms up. After the GPS warms up, and if the accuracy is good enough for your requirements, then you would switch to using the GPS locations.

Geolocation Data Description

The following geolocation data may be exposed and accessible by this API if the on-device provider is available and enabled:

• Real-time GPS location
• Cached GPS location
• GPS satellites meta data
• Real-time Network location triangulation
• Cached Network location
• Cell tower information (type of information varies by device, OS version and cell service provider)
• Cellular network signal strength

FAQ

• Which location providers does this plugin use? The plugin can be configured to use both GPS and NETWORK location providers. NETWORK location providers require access to the internet whether it's via cellular or WiFi connection. The plugin does not use PASSIVE location providers because you have no direct control over those.
• What is the difference between CellInfo and CellLocation data? It can be confusing because they have a lot of overlapping capabilities and may provide slightly different data, as well. They are both focused on providing cell tower information. CellLocation is only triggered during an PhoneStateListener.LISTEN_CELL_LOCATION event and has two types: CdmaCellLocation and GsmCellLocation. CellInfo contains a sub-set of information focused on the cell tower's id and its signal strength and is derived by querying TelephonyManager.getAllCellInfo(), and there are four different types that are device and provider dependent: CellInfoCdma, CellInfoWcmda, CellInfoGsm and CellInfoLte.
• How is cell signal strength information provided? There are two ways that signal strength information is derived. The first is when the signal strength changes and the second is when CellInfo changes. There are differences in the data that is returned between SignalStrength and CellSignalStrength. You will get access to both sets of information depending on what event triggered the change.
• Will this library work as a background process? No. This library is not designed to be used while minimized. Because of its potential to consume large amounts of memory and CPU cycles it will only provide locations, by default, while the application is in the foreground and active.
• I got a plugin not supported error, what do I do? If you get the following error Plugin doesn't support this project's cordova-android version. cordova-android: 4.1.1, failed version requirement: >=5.0.0 Skipping 'cordova-plugin-advanced-geolocation' for android, then you most likely need to upgrade your version of cordova-android. You can explicitly upgrade by running the following command in your cordova project directory cordova platform update [email protected].
• How come this plug-in does not support iOS? iOS does not give you the same granular-level control over the location manager as does Android.
• Does the plugin store location data? No. The only information it stores intentionally is the action setting in the Configuration options. The reason that is stored is so the application can automatically restart after being paused or placed in the background.

Sample Mapping App

Included with the plugin are two sample mapping apps called sample-map.html and sample-leaflet-map.html. To use it simply change the following line in your config.xml to point to the app's location, for example:

   <content src="sample-map.html" />

Licensing

Copyright 2017 Esri

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.

A copy of the license is available in the repository's license.txt file.

[](Esri Tags: JavaScript HTML5 GPS Geolocation ArcGIS Location Tools Cordova PhoneGap) [](Esri Language: JavaScript)