|
| 1 | +# react-native-cross-geolocation |
| 2 | + |
| 3 | +[![npm][npm-image]](https://www.npmjs.com/package/react-native-cross-geolocation) |
| 4 | +[![License][license-image]](LICENSE) |
| 5 | + |
| 6 | +React Native Geolocation complatible module that uses the new Google Location API in Android devices. |
| 7 | + |
| 8 | +This module is for React Native 0.50.x using the Google Gradle plugin 3.1.2 or later. |
| 9 | + |
| 10 | +## Setup |
| 11 | + |
| 12 | +```bash |
| 13 | +$ yarn add react-native-cross-geolocation |
| 14 | +$ react-native link react-native-cross-geolocation |
| 15 | +``` |
| 16 | + |
| 17 | +JavaScript import: |
| 18 | +```js |
| 19 | +import Geolocation from 'react-native-cross-geolocation' |
| 20 | +``` |
| 21 | + |
| 22 | +### Configuration and Permissions |
| 23 | + |
| 24 | +This section only applies to projects made with `react-native init` or to those made with Create React Native App which have since ejected. For more information about ejecting, please see the [guide](https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md) on the Create React Native App repository. |
| 25 | + |
| 26 | +#### iOS |
| 27 | +You need to include the NSLocationWhenInUseUsageDescription key in Info.plist to enable geolocation when using the app. Geolocation is enabled by default when you create a project with react-native init. |
| 28 | + |
| 29 | +In order to enable geolocation in the background, you need to include the 'NSLocationAlwaysUsageDescription' key in Info.plist and add location as a background mode in the 'Capabilities' tab in Xcode. |
| 30 | + |
| 31 | +#### Android |
| 32 | +To request access to location, you need to add the following line to your app's AndroidManifest.xml: |
| 33 | + |
| 34 | +```xml |
| 35 | + <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> |
| 36 | + <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> |
| 37 | +``` |
| 38 | + |
| 39 | +Android API >= 18 Positions will also contain a `mocked` boolean to indicate if position was created from a mock provider. |
| 40 | +Android API >= 23 Permissions are handled automatically. |
| 41 | + |
| 42 | +#### Methods |
| 43 | +- [`setRNConfiguration`](#setrnconfiguration) |
| 44 | +- [`requestAuthorization`](#requestauthorization) |
| 45 | +- [`getCurrentPosition`](#getcurrentposition) |
| 46 | +- [`watchPosition`](#watchposition) |
| 47 | +- [`clearWatch`](#clearwatch) |
| 48 | +- [`stopObserving`](#stopobserving) |
| 49 | + |
| 50 | +## Reference |
| 51 | + |
| 52 | +### Methods |
| 53 | + |
| 54 | +#### `setRNConfiguration()` |
| 55 | +```js |
| 56 | +Geolocation.setRNConfiguration(config); |
| 57 | +``` |
| 58 | + |
| 59 | +Sets configuration options that will be used in all location requests. |
| 60 | + |
| 61 | +Parameters: |
| 62 | + |
| 63 | +NAME | TYPE | REQUIRED | DESCRIPTION |
| 64 | +---- | ---- | -------- | ----------- |
| 65 | +config | object | Yes | See below. |
| 66 | + |
| 67 | +Supported options (optionals): |
| 68 | + |
| 69 | +- `skipPermissionRequests` (boolean, iOS-only) - Defaults to `false`. If `true`, you must request permissions before using Geolocation APIs. |
| 70 | +- `lowAccuracyMode` (number, Android-only) - Defaults to LowAccuracyMode.BALANCED. |
| 71 | +- `fastestInterval` (number, Android-only) - Defaults to 10000 (10 secs). |
| 72 | +- `updateInterval` (number, Android-only) - Defaults to 5000 (5 secs). |
| 73 | + |
| 74 | +#### `requestAuthorization()` |
| 75 | +```js |
| 76 | +Geolocation.requestAuthorization(); |
| 77 | +``` |
| 78 | +Request suitable Location permission based on the key configured on pList. If NSLocationAlwaysUsageDescription is set, it will request Always authorization, although if NSLocationWhenInUseUsageDescription is set, it will request InUse authorization. |
| 79 | + |
| 80 | +#### `getCurrentPosition()` |
| 81 | +```js |
| 82 | +Geolocation.getCurrentPosition(geo_success, [geo_error], [geo_options]); |
| 83 | +``` |
| 84 | + |
| 85 | +Invokes the success callback once with the latest location info. |
| 86 | + |
| 87 | +Parameters: |
| 88 | + |
| 89 | +NAME | TYPE | REQUIRED | DESCRIPTION |
| 90 | +---- | ---- | -------- | ----------- |
| 91 | +geo_success | function | Yes | Invoked with latest location info. |
| 92 | +geo_error | function | No | Invoked whenever an error is encountered. |
| 93 | +geo_options | object | No | See below. |
| 94 | + |
| 95 | +Supported options: |
| 96 | + |
| 97 | +- `timeout` (ms) - Defaults to MAX_VALUE |
| 98 | +- `maximumAge` (ms) - Defaults to INFINITY. |
| 99 | +- `enableHighAccuracy` (bool) - On Android, if the location is cached this can return almost immediately, or it will request an update which might take a while. |
| 100 | + |
| 101 | +#### `watchPosition()` |
| 102 | +```js |
| 103 | +Geolocation.watchPosition(success, [error], [options]); |
| 104 | +``` |
| 105 | + |
| 106 | +Invokes the success callback whenever the location changes. Returns a `watchId` (number). |
| 107 | + |
| 108 | +Parameters: |
| 109 | + |
| 110 | +NAME | TYPE | REQUIRED | DESCRIPTION |
| 111 | +---- | ---- | -------- | ----------- |
| 112 | +success | function | Yes | Invoked whenever the location changes. |
| 113 | +error | function | No | Invoked whenever an error is encountered. |
| 114 | +options | object | No | See below. |
| 115 | + |
| 116 | +Supported options: |
| 117 | + |
| 118 | +- `timeout` (ms) - Defaults to MAX_VALUE. |
| 119 | +- `maximumAge` (ms) - Defaults to INFINITY. |
| 120 | +- `enableHighAccuracy` (bool) - Defaults to `false`. |
| 121 | +- `distanceFilter` (m) |
| 122 | +- `useSignificantChanges` (bool) (unused in Android). |
| 123 | + |
| 124 | +#### `clearWatch()` |
| 125 | +```js |
| 126 | +Geolocation.clearWatch(watchID); |
| 127 | +``` |
| 128 | + |
| 129 | +Parameters: |
| 130 | + |
| 131 | +NAME | TYPE | REQUIRED | DESCRIPTION |
| 132 | +---- | ---- | -------- | ----------- |
| 133 | +watchID | number | Yes | Id as returned by `watchPosition()`. |
| 134 | + |
| 135 | +#### `stopObserving()` |
| 136 | +```js |
| 137 | +Geolocation.stopObserving(); |
| 138 | +``` |
| 139 | + |
| 140 | +Stops observing for device location changes. In addition, it removes all listeners previously registered. |
| 141 | + |
| 142 | +Notice that this method has only effect if the `geolocation.watchPosition(successCallback, errorCallback)` method was previously invoked. |
| 143 | + |
| 144 | +## TODO |
| 145 | + |
| 146 | +- [X] Enhanced docs |
| 147 | +- [ ] Tests |
| 148 | + |
| 149 | +[npm-image]: https://img.shields.io/npm/v/react-native-cross-geolocation.svg |
| 150 | +[license-image]: https://img.shields.io/npm/l/express.svg |
0 commit comments