Repository files navigation

Highly configurable native interface toGPS andNETWORK on-devicelocation providers. It will return and identify any location data registered by the on-device providers including real-timesatellite info.

It also offers direct access toCellInfo,CellLocation andCellSignalStrength 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 vianpm.

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 theissues list for the most current information.

Cordova supports the following androidreleases.

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

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 runupdate:

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

Inconfig.xml modify thesrc 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.

This API doesNOT 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 ofblog posts.

External consumer GPS devices may help provide better accuracy, faster location acquisition and less location fluctuation. Here's a good article onWhy 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 theW3C 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 andINTERNET.

Clickhere to read all about it.

// Implement this in `deviceready` event callbackAdvancedGeolocation.start(function(success){try{varjsonObject=JSON.parse(success);switch(jsonObject.provider){case"gps"://TODObreak;case"network"://TODObreak;case"satellite"://TODObreak;case"cell_info"://TODObreak;case"cell_location"://TODObreak;case"signal_strength"://TODObreak;}}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});

Here are example use cases for the different ways location providers can be set in the configuration options via theproviders 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.

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

• Which location providers does this plugin use? The plugin can be configured to use bothGPS andNETWORK location providers. NETWORK location providers require access to the internet whether it's via cellular or WiFi connection. The plugin does not usePASSIVE location providers because you have no direct control over those.
• What is the difference betweenCellInfo andCellLocation 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 anPhoneStateListener.LISTEN_CELL_LOCATION event and has two types:CdmaCellLocation andGsmCellLocation.CellInfo contains a sub-set of information focused on the cell tower's id and its signal strength and is derived by queryingTelephonyManager.getAllCellInfo(), and there are four different types that are device and provider dependent:CellInfoCdma,CellInfoWcmda,CellInfoGsm andCellInfoLte.
• 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 whenCellInfo changes. There are differences in the data that is returned betweenSignalStrength andCellSignalStrength. 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 isnot 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 errorPlugin 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 directorycordova 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 theaction 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.

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

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

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'slicense.txt file.

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