search

Esri / cordova-plugin-advanced-geolocation

Highly configurable native Android interface to both GPS and NETWORK on-device location providers.
Apache License 2.0
77 stars 38 forks source link
geolocation native-development

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="https://github.com/Esri/cordova-plugin-advanced-geolocation/raw/master/sample-map.html" /> or <content src="https://github.com/Esri/cordova-plugin-advanced-geolocation/raw/master/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:

Geolocation Data Description

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

FAQ

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="https://github.com/Esri/cordova-plugin-advanced-geolocation/raw/master/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)