react-native-geolocation

GeoLocation module for react-native

The behavior of the default geolocation module included with react-native, navigator.geolocation, is not always obvious and does not meet our use-case for mapeo-mobile. We needed the following features:

• Initial position using non-GPS (cell towers, wifi) so that the app works indoors in cities
• Continued GPS aquisition until the accuracy is below a defined threshold
• Updated GPS positon when the use moves
• Updates to the GPS status when location services are turned on or off whilst the app is open (e.g. airplane mode turned on)

navigator.geolocation will only sometimes throw an error when location serivces are turned off, and will not always get a new location when they are turned on again. This module uses the following strategy:

1. Asks for the necessary permissions for using fine and coarse location
2. Gets an initial position with highAccuracy: false and uses a cached position if a recent one exists
3. In parallel also starts observing the position with highAccuracy: true, with distanceFilter: 0 which will continuously update the location every 1000ms in testing
4. Once the accuracy is below a threshold, turns off the continuous watch and starts a new watch with a distance filter, so the location will stop updating every 1000ms and only update when the user moves beyond the threshold distance

Table of Contents

• Install
• Usage
• API
• Maintainers
• Contribute
• License

Install

You will need to install and link the peer dependecy react-native-gps-state

npm install -S @digidem/react-native-geolocation
npm install -S @digidem/react-native-gps-state
npm link @digidem/react-native-gps-state

Usage

const GeoLocation = require('@digidem/react-native-geolocation')

const loc = new GeoLocation()
loc.startObserving(
  (position) => console.log(position),
  (err) => console.log(err)
)
// call loc.stopObserving() to stop receiving location updates

API

Table of Contents

• GeoLocation
  • Parameters
  • Examples
  • startObserving
    • Parameters
  • stopObserving

GeoLocation

Create a new geolocation instance

Parameters

• options Object [not yet implemented]

Examples

const loc = new GeoLocation()

startObserving

Request permissions and start observing the location.

Position.status is an unsigned short representing the status:

| Value | Associated Constant | Description | | ----- | --------------------------- | --------------------------------------------------------------- | | 1 | GeoLocation.SEARCHING | GPS is searching for a location fix | | 2 | GeoLocation.LOW_ACCURACY | Low accuracy position, continuing to search for better accuracy | | 3 | GeoLocation.HIGH_ACCURACY | High accuracy position, will only update if use moves |

PositionError.code is an unsigned short representing the error:

| Value | Associated Constant | Description | | ----- | ---------------------------------- | ----------------------------------------------------------------------------------- | | 1 | GeoLocation.PERMISSION_DENIED | Location acquisition failed because the app does not have permission | | 2 | GeoLocation.POSITION_UNAVAILABLE | Location acquisition failed because location services are turned off or unavailable | | 3 | GeoLocation.TIMEOUT | Timeout was reached before a location was found | | 4 | GeoLocation.UNKNOWN | Unknown error occured trying to acquire location |

Parameters

• onLocation function Called with every location update, including when searching for a location, but no position is available. Returns a Position object with an additional property status (see above)
• onError function Called every time there is an error (failed to get position) with a PositionError object with an additional PositionError.code (see above)

stopObserving

Stop observing the location

Maintainers

@digidem

Contribute

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2018 Digital Democracy