react-native-location
Native GPS location support for React Native.
Installation
Three installation methods are provided here for compatibility and ease of use. All of them require installing the package using NPM. However, you can install the iOS specific bits using one of three methods: RNPM, React-Native Link (only v0.28), or manual linking in XCode.
First step for all three is NPM Install to your project:
npm install --save react-native-location
RNPM Installation
For RNPM, first install RNPM globally and then simply run it with the 'link' command at the root of your project:
npm install rnpm -g
rnpm link
React-Native Link Installation
Since version 0.28 of React Native, rnpm has been merged into the codebase. So, as long as you are using the latest version of the CLI, then you can simply run link:
react-native link
Manual Installation
Finally, you can do a manual installation with XCode. Drag ios/RNLocation.xcodeproj
from the node_modules/react-native-location
folder into your XCode project. Click on the your project in XCode, goto Build Phases then Link Binary With Libraries and add libRNLocation.a
and CoreLocation.framework
.
NOTE: Make sure you don't have the RNLocation
project open separately in XCode otherwise it won't work.
Example application
In the example folder is a React Native sample app which simply allows you to test out whether the library is working for you. You can also use this as a sample implementation to start from. The app requests always on permissions, takes reading every 5 distance and starts immediately. To utilize in the simulator, look on the Debug -> Location
menu for optional sample trips that will show you updating location such as City Bicicle Ride, City Run and Freeway Drive.
PList Permissions
In order to use permissions, your enclosing app needs to grant permissions in the info.plist
file. React Native automatically sets up the PList config key for NSLocationWhenInUseUsageDescription
. However, to use NSLocationAlwaysUsageDescription
you will need to add that in your PList file. The string message in the key will show in the Alert box when your app requests permissions. To start, you can simply add these to your file and edit them (or remove them) later. Remember to only request the permissions you NEED within your app. See the detail on Background Mode later on.
<key>NSLocationWhenInUseUsageDescription</key>
<string>This is the plist item for NSLocationWhenInUseUsageDescription</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This is the plist item for NSLocationAlwaysUsageDescription</string>
Location Usage
var React = require('react-native');
var { DeviceEventEmitter } = React;
var { RNLocation: Location } = require('NativeModules');
Location.requestAlwaysAuthorization();
Location.startUpdatingLocation();
Location.setDistanceFilter(5.0);
var subscription = DeviceEventEmitter.addListener(
'locationUpdated',
(location) => {
/* Example location returned
{
coords: {
speed: -1,
longitude: -0.1337,
latitude: 51.50998,
accuracy: 5,
heading: -1,
altitude: 0,
altitudeAccuracy: -1
},
timestamp: 1446007304457.029
}
*/
}
);
Heading Usage
var React = require('react-native');
var { DeviceEventEmitter } = React;
var { RNLocation: Location } = require('NativeModules');
Location.requestAlwaysAuthorization();
Location.startUpdatingHeading();
DeviceEventEmitter.addListener(
'headingUpdated',
(data) => {
/* Example data returned
{
heading: 57.2839832
}
*/
}
);
It is recommended to set NSWhenInUseUsageDescription
in your Info.plist
file.
Background mode
For background mode to work, a few things need to be configured:
-
In the Xcode project, go to Capabilities, switch on "Background Modes" and check "Location updates".
-
Using
requestAlwaysAuthorization
in place ofrequestWhenInUseAuthorization
, like this:Location.requestAlwaysAuthorization();
-
Set
NSLocationAlwaysUsageDescription
in yourInfo.plist
file. -
For iOS9, set
allowsBackgroundLocationUpdates
to true, like this:Location.setAllowsBackgroundLocationUpdates(true);
Methods
To access the methods, you need import the react-native-location
module. This is done through var Location = require('react-native-location')
.
Location.requestWhenInUseAuthorization
Location.requestWhenInUseAuthorization();
This method should be called before anything else. It requests location updates while the application is open. If the application is in the background, you will not get location updates. Either this method or Location.requestAlwaysAuthorization
(but not both) needs to be called to receive updates.
Location.requestAlwaysAuthorization
Location.requestAlwaysAuthorization();
This method should be called before anything else is called. It requests location updates while the application is open or in the background. Either this method or Location.requestWhenInUseAuthorization
(but not both) needs to be called to receive updates.
Location.getAuthorizationStatus
Location.getAuthorizationStatus(function(authorization) {
// authorization is a string which is either "authorizedAlways",
// "authorizedWhenInUse", "denied", "notDetermined" or "restricted"
});
This methods gets the current authorization status. While this methods provides a callback, it is not executed asynchronously. The values authorizedAlways
and authorizedWhenInUse
correspond to the methods requestWhenInUseAuthorization
and requestAlwaysAuthorization
respectively.
Location.setDesiredAccuracy
Location.setDesiredAccuracy(distanceInMeters);
Set the desired accuracy of location updates in meters. Determines the method used to obtain location updates. Low values will trigger using GPS.
Location.setDistanceFilter
Location.setDistanceFilter(distanceInMeters);
Set the desired minimum distance between location updates in meters.
Location.startMonitoringSignificantLocationChanges
Location.startMonitoringSignificantLocationChanges();
Location.startUpdatingLocation
Location.startUpdatingLocation();
var subscription = DeviceEventEmitter.addListener(
'locationUpdated',
(location) => {
// do something with the location
}
);
Start location updates. Your application will be called back with location updates that meet any mininum distance requirements that you specify via the DeviceEventEmitter event 'locationUpdated'.
Location.startUpdatingHeading
Location.startUpdatingHeading();
var subscription = DeviceEventEmitter.addListener(
'headingUpdated',
(data) => {
// do something with the heading
}
);
Start heading updates. Your application will be called back with heading updates.
Location.stopUpdatingLocation
Location.stopUpdatingLocation();
Stop receiving location events.
Location.stopUpdatingHeading
Location.stopUpdatingHeading();
Stop receiving heading events.
Location.stopMonitoringSignificantLocationChanges
Location.stopMonitoringSignificantLocationChanges();
Stop receiving sigificant location change events.
Events
To listen to events we need to call DeviceEventEmitter.addListener
(var {DeviceEventEmitter} = require('react-native')
) where the first parameter is the event we want to listen to and the second is a callback function that will be called once the event is triggered.
locationUpdated
Received when a location update has been sensed by the system. The event delivers one parameter, location, that is an object with location, elevation, and accuracy data.
headingUpdated
Received when the heading changes. The event delivers one parameter: an object with the current heading in degrees.
License
MIT, for more information see LICENSE