Background Geolocation

Improve this doc

This plugin provides foreground and background geolocation with battery-saving "circular region monitoring" and "stop detection". For more detail, please see https://github.com/mauron85/cordova-plugin-background-geolocation

Repo: https://github.com/mauron85/cordova-plugin-background-geolocation

Installation

1. Install the Cordova and Ionic Native plugins:
   

   $ ionic cordova plugin add cordova-plugin-mauron85-background-geolocation
   $ npm install --save @ionic-native/background-geolocation
   

2. Add this plugin to your app's module

Supported platforms

• Android
• iOS

Usage

BackgroundGeolocation must be called within app.ts and or before Geolocation. Otherwise the platform will not ask you for background tracking permission.

import { BackgroundGeolocation, BackgroundGeolocationConfig } from '@ionic-native/background-geolocation';

constructor(private backgroundGeolocation: BackgroundGeolocation) { }

...

const config: BackgroundGeolocationConfig = {
            desiredAccuracy: 10,
            stationaryRadius: 20,
            distanceFilter: 30,
            debug: true, //  enable this hear sounds for background-geolocation life-cycle.
            stopOnTerminate: false, // enable this to clear background location settings when the app terminates
    };

this.backgroundGeolocation.configure(config)
  .subscribe((location: BackgroundGeolocationResponse) => {

    console.log(location);

    // IMPORTANT:  You must execute the finish method here to inform the native plugin that you're finished,
    // and the background-task may be completed.  You must do this regardless if your HTTP request is successful or not.
    // IF YOU DON'T, ios will CRASH YOUR APP for spending too much time in the background.
    this.backgroundGeolocation.finish(); // FOR IOS ONLY

  });

// start recording location
this.backgroundGeolocation.start();

// If you wish to turn OFF background-tracking, call the #stop method.
this.backgroundGeolocation.stop();

Instance Members

LocationProvider

Set location service provider @see https://github.com/mauron85/cordova-plugin-background-geolocation/wiki/Android-providers


Possible values: ANDROID_DISTANCE_FILTER_PROVIDER: 0,
 ANDROID_ACTIVITY_PROVIDER: 1


Accuracy

Desired accuracy in meters. Possible values [0, 10, 100, 1000].
 The lower the number, the more power devoted to GeoLocation resulting in higher accuracy readings.
 1000 results in lowest power drain and least accurate readings.


Possible values: HIGH: 0
 MEDIUM: 10
 LOW: 100
 PASSIVE: 1000

enum {number}

Mode

Used in the switchMode function


Possible values: BACKGROUND: 0 FOREGROUND: 1


configure(options)

Configure the plugin.

start()

Turn ON the background-geolocation system. The user will be tracked whenever they suspend the app.

stop()

Turn OFF background-tracking

finish()

Platforms:iOS 

Inform the native plugin that you’re finished, the background-task may be completed

changePace(isMoving)

Platforms:iOS 

Force the plugin to enter “moving” or “stationary” state

setConfig(options)

Setup configuration

getStationaryLocation()

Platforms:iOS 

Returns current stationaryLocation if available. null if not

onStationary()

Platforms:iOS 

Add a stationary-region listener. Whenever the devices enters “stationary-mode”, your #success callback will be executed with #location param containing #radius of region

isLocationEnabled()

Platforms:Android 

Check if location is enabled on the device

showAppSettings()

Display app settings to change permissions

showLocationSettings()

Display device location settings

watchLocationMode()

Platforms:Android 

Method can be used to detect user changes in location services settings. If user enable or disable location services then success callback will be executed. In case or error (SettingNotFoundException) fail callback will be executed.

stopWatchingLocationMode()

Platforms:Android 

Stop watching for location mode changes.

getLocations()

Platforms:Android 

Method will return all stored locations. Locations are stored when:

• config.stopOnTerminate is false and main activity was killed by the system or
• option.debug is true

getValidLocations()

Method will return locations, which has not been yet posted to server. NOTE: Locations does contain locationId.


deleteLocation(locationId)

Platforms:Android 

Delete stored location by given locationId.

deleteAllLocations()

Platforms:Android 

Delete all stored locations.

switchMode(modeId)

Platforms:iOS 

Normally plugin will handle switching between BACKGROUND and FOREGROUND mode itself. Calling switchMode you can override plugin behavior and force plugin to switch into other mode.

In FOREGROUND mode plugin uses iOS local manager to receive locations and behavior is affected by option.desiredAccuracy and option.distanceFilter. In BACKGROUND mode plugin uses significant changes and region monitoring to receive locations and uses option.stationaryRadius only.


BackgroundGeolocation.Mode.FOREGROUND BackgroundGeolocation.Mode.BACKGROUND
 *

getLogEntries()

Return all logged events. Useful for plugin debugging. Parameter limit limits number of returned entries.
 @see https://github.com/mauron85/cordova-plugin-background-geolocation/tree/v2.2.1#debugging for more information.


@param limit {number} Limits the number of entries


BackgroundGeolocationResponse

BackgroundGeolocationConfig