Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

cordova-plugin-advanced-geolocation

esri103Apache-2.01.6.2

Android geolocation plugin for both GPS and NETWORK-based location providers. Also can return satellite info, cellular info and cellular network signal strength.

gps, location, geolocation, satellite, network, cellular, triangulation, signal-strength, ecosystem:cordova, cordova-android, cordova, phonegap

readme

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 android@5.0.0 [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 android@5.0.0.
  • 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" />

Sample Mapping App

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)

changelog

cordova-plugin-advanced-geolocation - Changelog

Version 1.6.2 - May 15, 2018

No breaking changes.

Enhancements

  • Fixes NullPointerException errors when stopping listeners on the TelephonyManager.

Version 1.6.1 - October 2, 2017

No breaking changes.

Enhancements

  • Minor documentation clarification on Android SDK support

Version 1.6 - June 28, 2017

No breaking changes.

Enhancements

  • Adds accuracy info to the console when running samples.
  • Adds location data output to the screen when running samples.
  • Fixed a minor CSP bug in Esri-leaflet sample

Version 1.5 - December 9, 2016

No breaking changes.

Bug Fixes

  • Closes #43 - Plugin fails to build on Ionic. Include StopLocation Class in plugin.xml

Version 1.4 - November 22, 2016

Possible breaking changes.

Enhancements

  • Closes #40 - provide success callback(s) for stop() and kill().

Bug Fixes

  • Closes #41 - removes memory leaks created by improper method modifiers
  • Implements a cancelable Future that is returned from the ExecutureService.submit() method. The submit() method replaced the old execute(Runnable) method.

Version 1.3.2 - October 12, 2016

No breaking changes.

Enhancements

  • Closes #33 - removed old code comment.
  • Closes #37 - missing reference in plugin.xml.

Version 1.3.1 - September 15, 2016

No breaking changes.

Enhancements

  • Closes #34 - Change JSONHelper.signalStrengthJSON provider property to signal_strength.
  • Minor documentation updates.

Version 1.3.0 - September 13, 2016

Has breaking changes. An additional configuration option is now required.

Enhancements

  • Closes #31 - adds signal strength support via configuration options. Supported types include Lte, GSM, WCDMA and CDMA devices.

Version 1.2.0 - September 11, 2016

No breaking changes.

Enhancements

  • This release focused on improving the robustness of the startup and shutdown processes.
  • The plugin now explicitly checks for a thread interrupt on all location providers before sending location updates. Previous versions lazily assume that the thread would be terminated.

Bug Fixes

  • Closes #26 - Android OS NullPointerException on initialization
  • Closes #28 - LocationManager error on shutdown

Version 1.1.1 - September 8, 2016

No breaking changes.

Enhancements

  • Added a Leaflet mapping sample.

Version 1.1.0 - August 24, 2016

No breaking changes.

Bug Fixes

  • Closes #22 - Fix accidental thread interrupt clearing

Version 1.0.0 - August 17, 2016

Has breaking changes. This is a v1 implementation so any improvements and suggestions are welcome!

Enhancements

  • Handles Android 6 permissions with native system prompts. Continues to handle previous Android versions exactly the same as before.
  • Improved incompatible version protection. If using this library on an unsupported platform it should protect against incompatibility errors where functionality is not available on a specific Android version. If you come across something that fails please open an issue.
  • Significantly improved error handling. Errors are now reported as JSON Objects that include an error number and message. Errors messages are now pervasively collected where possible.
  • Improved sample app and fixed various bugs.

Known Issues

  • Does not provide a rationale message explaining why the library requires location information. There is a GPSPermsDeniedDialogFragment in the project and other stubs reserved for either custom implementation or as inclusion for future functionality.

Version 0.5.1 - July 13, 2016

No breaking changes.

Enhancements

  • Changed cell data configuration option verification from API 17 to 18 as per the Android SDK docs. CellIdentityWcdma was added at API 18 so that's now the least common denominator.

Version 0.5.0 - July 13, 2016

No breaking changes.

Enhancements

  • Disable cellular data configuration option if Android API Level is less than v17. This functionality is not available on those phones and could cause app to crash.
  • Updates docs. Added notices that Android N will have breaking changes in terms of how GPS is implemented.

Version 0.4.0 - May 6, 2016

No breaking changes.

Enhancements

  • Updated API docs to correctly reflect what data is returns by GPS and Network.

Bug Fixes

  • GPSController no longer returns a fake location if parsedLocation is null.
  • NetworkController also no longer returns a fake location if parsedLocation is null.

Version 0.3.1 - May 4, 2016

No breaking changes.

Bug Fixes

  • Adds missing CellLocationController to plugin.xml

Version 0.3.0 - April 22, 2016

No breaking changes.

Enhancements

  • Closes #2 - Added ability to access cell tower meta-data
  • Various doc improvements

Version 0.2.0 - April 19, 2016

No breaking changes.

Enhancements

  • Various doc improvements

Bug Fixes

  • Closes #3 - Bug in map.js throwing null values.