cordova-plugin-geolocation-plus

Advanced Cordova geolocation plugin for Android and iOS. This plugin exposes the native APIs more explicitly than the standard browser geolocation API. This is done to give better control over accuracy, frequency of updates and battery management to the programmer. The plugin relies on LocationManager in Android (which works also AOSP, instead of FusedLocationProviderClient) and CLLocationManager in iOS.

This is has been developed with lots of help from Claude, but has been reviewed and commented manually line-by-line and corrected/steered when neecessary.

Install

cordova plugin add cordova-plugin-geolocation-plus

JS API

The plugin is exposed at:

cordova.plugins.geolocationPlus;

isLocationServiceEnabled(options?)

Returns a promise that resolves with the current location service state.

cordova.plugins.geolocationPlus
  .isLocationServiceEnabled()
  .then(function (result) {
    console.log(result);
  });

Current native return value: true if the location service is running and false otherwise.

If the native check throws an exception, the promise is rejected and the rejection reason contains the native exception message.

Supported options:

• provider - Android-only check against a specific provider name. See below for possible values.

requestPermissions(options?)

Requests OS location permission and resolves with the permission state after the request completes.

cordova.plugins.geolocationPlus
  .requestPermissions({ authorization: "whenInUse" })
  .then(function (result) {
    console.log(result);
  });

Supported options:

• authorization - preferred permission scope, it can be whenInUse (default) or always
• scope - alias for authorization

Return values: { granted : true, status: 'denied' }

The status on Android is either granted or denied. On iOS it can be notDetermined (user has not chosen whether the app can use location services), restricted (app is not authorized to use location services), denied (user denied the use of location services), authorizedAlways (app can start location services at any time), authorizedWhenInUse (app can start location services while it is in use).

Android adds 2 boolean properties: fineGranted and coarseGranted that indicate which accuracy the app is allowed to use.

hasPermissions(options?)

Queries whether location permission has already been granted.

cordova.plugins.geolocationPlus.hasPermissions().then(function (result) {
  console.log(result);
});

See requestPermissions for returned values.

getCurrentPosition(options?)

Gets one location fix and resolves once with the position. This does not start a continuous watch.

cordova.plugins.geolocationPlus
  .getCurrentPosition({
    provider: "best",
    desiredAccuracy: 10,
  })
  .then(function (position) {
    console.log(position);
  });

Supported options:

• provider: Android-only gets the location from a specific provider. See below for possible values.
• desiredAccuracy: iOS-only is the desired accuracy of the location. See below for possible values.

The position object returned is explained below.

startPositionUpdates(positionCallback, options?)

Starts continuous location updates. Only one upate callback can be started by the app at any time.

cordova.plugins.geolocationPlus
  .startPositionUpdates(
    function (position) {
      console.log(position);
    },
    {
      distanceFilter: 5,
      provider: "best",
      minTime: 2000,
      desiredAccuracy: 10,
    },
  )
  .then(function () {
    console.log("watch started");
  });

Returns a Promise that resolves when updates are started. Only one active callback can exist at a time. If startPositionUpdates is called again before stopPositionUpdates, the Promise is rejected.

Supported options:

• distanceFilter: minimum distance between location updates in meters.
• provider: Android-only gets the location from a specific provider. See below for possible values.
• desiredAccuracy: iOS-only is the desired accuracy of the location. See below for possible values.
• minTimeMs: Android-only minimum time interval between location updates in milliseconds.

stopPositionUpdates()

Stops continuous location updates.

cordova.plugins.geolocationPlus.stopPositionUpdates();

Position object

The plugin returns location data in this shape:

{
  provider: 'gps',
  timestamp: 1710000000000,
  coords: {
    latitude: 0,
    longitude: 0,
    accuracy: 10,
    altitude: 0,
    altitudeAccuracy: 5,
    heading: 0,
    speed: 0
  }
}

Some fields may be null when the platform cannot provide them. timestamp is in milliseconds since epoch.

Android-only provider parameter

This indicates the location provider name to use (string), common values include best, gps, network, passive and fused. See LocationManager for details. Default: best enabled provider, falling back to network, then gps, then passive.

iOS-only desiredAccuracy parameters

It specifies the accuracy in meters, and can also be mapped to categories, see CLLocationAccuracy for details. Default: kCLLocationAccuracyBest.

Example

document.addEventListener("deviceready", function () {
  var geo = cordova.plugins.geolocationPlus;

  geo
    .hasPermissions()
    .then(function (state) {
      if (!state.granted) {
        return geo.requestPermissions({ authorization: "whenInUse" });
      }
    })
    .then(function () {
      return geo.getCurrentPosition({
        provider: "best",
        desiredAccuracy: 10,
        distanceFilter: 0,
      });
    })
    .then(function (position) {
      console.log(position);
    })
    .catch(function (error) {
      console.error(error);
    });
});