Repository files navigation

Npm package is now@mauron85/react-native-background-geolocation!

All new issues should follow instructions inISSUE_TEMPLATE.md.A properly filled issue report will significantly reduce number of follow up questions and decrease issue resolving time.Most issues cannot be resolved without debug logs. Please try to isolate debug lines related to your issue.Instructions for how to prepare debug logs can be found in sectionDebugging.If you're reporting an app crash, debug logs might not contain all the necessary information about the cause of the crash.In that case, also provide relevant parts of output ofadb logcat command.

Fund your issues or feature request to drag attraction of developers. Checkout ourissue hunt page.

There are repeatedly reported issues with some android devices not working in the background. Check if your device model is ondontkillmyapp list before you report new issue. For more information check outdontkillmyapp.com.

Another confusing fact about Android services is concept of foreground services. Foreground service in context of Android OS is different thing than background geolocation service of this plugin (they're related thought).Plugin's background geolocation service actuallybecomes foreground service when app is in the background. Confusing, right? :D

If service wants to continue to run in the background, it must "promote" itself toforeground service. Foreground services must have visible notification, which is the reason, why you can't disable drawer notification.

The notification can only be disabled, when app is running in the foreground, by setting config optionstartForeground: false (this is the default option), but will always be visible in the background (if service was started).

Recommend you to readhttps://developer.android.com/about/versions/oreo/background

React Native fork ofcordova-plugin-background-geolocationwith battery-saving "circular region monitoring" and "stop detection".

This plugin can be used for geolocation when the app is running in the foreground or background.

You can choose from following location providers:

• DISTANCE_FILTER_PROVIDER
• ACTIVITY_PROVIDER
• RAW_PROVIDER

SeeWhich provider should I use? for more information about providers.

Versions of libraries and sdk versions used to compile this plugin can be overriden inandroid/build.gradle with ext declaration.

When ext is not provided then following defaults will be used:

ext {  compileSdkVersion = 28  buildToolsVersion = "28.0.3"  targetSdkVersion = 28  minSdkVersion = 16  supportLibVersion = "28.0.0"  googlePlayServicesVersion = "11+"}

Due to the rapid changes being made in the React Native ecosystem, this module will supportonly the latest version of React Native. Older versions will only be supported if they'recompatible with this module.

If you are using an older version of React Native with this module some features may be buggy.

If you are usingreact-native-maps or another lib that requiresGoogle Play Services such asExponent.js, then in addition to the instalation steps described here, you must setGoogle Play Services library version to match the version used by those libraries. (in this case9.8.0)

Add following toandroid/build.gradle

ext {  googlePlayServicesVersion = "9.8.0"}

The repositoryreact-native-background-geolocation-example hosts an example app for both iOS and Android platform.

importReact,{Component}from'react';import{Alert}from'react-native';importBackgroundGeolocationfrom'@mauron85/react-native-background-geolocation';classBgTrackingextendsComponent{componentDidMount(){BackgroundGeolocation.configure({desiredAccuracy:BackgroundGeolocation.HIGH_ACCURACY,stationaryRadius:50,distanceFilter:50,notificationTitle:'Background tracking',notificationText:'enabled',debug:true,startOnBoot:false,stopOnTerminate:true,locationProvider:BackgroundGeolocation.ACTIVITY_PROVIDER,interval:10000,fastestInterval:5000,activitiesInterval:10000,stopOnStillActivity:false,url:'http://192.168.81.15:3000/location',httpHeaders:{'X-FOO':'bar'},// customize post propertiespostTemplate:{lat:'@latitude',lon:'@longitude',foo:'bar'// you can also add your own properties}});BackgroundGeolocation.on('location',(location)=>{// handle your locations here// to perform long running operation on iOS// you need to create background taskBackgroundGeolocation.startTask(taskKey=>{// execute long running task// eg. ajax post location// IMPORTANT: task has to be ended by endTaskBackgroundGeolocation.endTask(taskKey);});});BackgroundGeolocation.on('stationary',(stationaryLocation)=>{// handle stationary locations hereActions.sendLocation(stationaryLocation);});BackgroundGeolocation.on('error',(error)=>{console.log('[ERROR] BackgroundGeolocation error:',error);});BackgroundGeolocation.on('start',()=>{console.log('[INFO] BackgroundGeolocation service has been started');});BackgroundGeolocation.on('stop',()=>{console.log('[INFO] BackgroundGeolocation service has been stopped');});BackgroundGeolocation.on('authorization',(status)=>{console.log('[INFO] BackgroundGeolocation authorization status: '+status);if(status!==BackgroundGeolocation.AUTHORIZED){// we need to set delay or otherwise alert may not be shownsetTimeout(()=>Alert.alert('App requires location tracking permission','Would you like to open app settings?',[{text:'Yes',onPress:()=>BackgroundGeolocation.showAppSettings()},{text:'No',onPress:()=>console.log('No Pressed'),style:'cancel'}]),1000);}});BackgroundGeolocation.on('background',()=>{console.log('[INFO] App is in background');});BackgroundGeolocation.on('foreground',()=>{console.log('[INFO] App is in foreground');});BackgroundGeolocation.on('abort_requested',()=>{console.log('[INFO] Server responded with 285 Updates Not Required');// Here we can decide whether we want stop the updates or not.// If you've configured the server to return 285, then it means the server does not require further update.// So the normal thing to do here would be to `BackgroundGeolocation.stop()`.// But you might be counting on it to receive location updates in the UI, so you could just reconfigure and set `url` to null.});BackgroundGeolocation.on('http_authorization',()=>{console.log('[INFO] App needs to authorize the http requests');});BackgroundGeolocation.checkStatus(status=>{console.log('[INFO] BackgroundGeolocation service is running',status.isRunning);console.log('[INFO] BackgroundGeolocation services enabled',status.locationServicesEnabled);console.log('[INFO] BackgroundGeolocation auth status: '+status.authorization);// you don't need to check status before start (this is just the example)if(!status.isRunning){BackgroundGeolocation.start();//triggers start on start event}});// you can also just start without checking for status// BackgroundGeolocation.start();}componentWillUnmount(){// unregister all event listenersBackgroundGeolocation.removeAllListeners();}}exportdefaultBgTracking;

Add the package to your project

yarn add @mauron85/react-native-background-geolocation

Since version 0.60 React Native does linking of modulesautomatically. However it does it only for single module.As plugin depends on additional 'common' module, it is required to link it with:

node ./node_modules/@mauron85/react-native-background-geolocation/scripts/postlink.js

Inandroid/settings.gradle

...include':@mauron85_react-native-background-geolocation-common'project(':@mauron85_react-native-background-geolocation-common').projectDir=newFile(rootProject.projectDir,'../node_modules/@mauron85/react-native-background-geolocation/android/common')include':@mauron85_react-native-background-geolocation'project(':@mauron85_react-native-background-geolocation').projectDir=newFile(rootProject.projectDir,'../node_modules/@mauron85/react-native-background-geolocation/android/lib')...

Inandroid/app/build.gradle

dependencies {...    compile project(':@mauron85_react-native-background-geolocation')...}

Register the module (inMainApplication.java)

importcom.marianhello.bgloc.react.BackgroundGeolocationPackage;// <--- Import PackagepublicclassMainApplicationextendsApplicationimplementsReactApplication {  .../**   * A list of packages used by the app. If the app uses additional views   * or modules besides the default ones, add more packages here.   */@OverrideprotectedList<ReactPackage>getPackages() {returnArrays.<ReactPackage>asList(newMainReactPackage(),newBackgroundGeolocationPackage()// <---- Add the Package      );  }  ...}

1. In XCode, in the project navigator, right clickLibraries ➜Add Files to [your project's name]
2. Add./node_modules/@mauron85/react-native-background-geolocation/ios/RCTBackgroundGeolocation.xcodeproj
3. In the XCode project navigator, select your project, select theBuild Phases tab and in theLink Binary With Libraries section addlibRCTBackgroundGeolocation.a
4. AddUIBackgroundModeslocation toInfo.plist
5. AddNSMotionUsageDescriptionApp requires motion tracking toInfo.plist (required by ACTIVITY_PROVIDER)

For iOS before version 11:

6. AddNSLocationAlwaysUsageDescriptionApp requires background tracking toInfo.plist

For iOS 11:

6. AddNSLocationWhenInUseUsageDescriptionApp requires background tracking toInfo.plist
7. AddNSLocationAlwaysAndWhenInUseUsageDescriptionApp requires background tracking toInfo.plist

Configure options:

*DIS = DISTANCE_FILTER_PROVIDERACT = ACTIVITY_PROVIDERRAW = RAW_PROVIDER

Partial reconfiguration is possible by later providing a subset of the configuration options:

BackgroundGeolocation.configure({  debug: true});

In this case new configuration options will be merged with stored configuration options and changes will be applied immediately.

Important: Because configuration options are applied partially, it's not possible to reset option to default value just by omitting it's key name and callingconfigure method. To reset configuration option to the default value, it's key must be set tonull!

// Example: reset postTemplate to defaultBackgroundGeolocation.configure({  postTemplate: null});

Platform: iOS, Android

Get current configuration. Method will return all configuration options and their values in success callback.Becauseconfigure method can be called with subset of the configuration options only,getConfig method can be used to check the actual applied configuration.

BackgroundGeolocation.getConfig(function(config) {  console.log(config);});

Platform: iOS, Android

Start background geolocation.

Platform: iOS, Android

Stop background geolocation.

Platform: iOS, Android

One time location check to get current location of the device.

Error codes:

Check status of the service

Authorization statuses:

• NOT_AUTHORIZED
• AUTHORIZED - authorization to run in background and foreground
• AUTHORIZED_FOREGROUND iOS only authorization to run in foreground only

Note: In the Android concept of authorization, these represent application permissions.

Platform: Android >= 6, iOS >= 8.0

Show app settings to allow change of app location permissions.

Platform: Android

Show system settings to allow configuration of current location sources.

Platform: iOS, Android

Method will return all stored locations.This method is useful for initial rendering of user location on a map just after application launch.

BackgroundGeolocation.getLocations(function(locations){console.log(locations);});

Platform: iOS, Android

Method will return locations which have not yet been posted to server.

Platform: iOS, Android

Delete location with locationId.

Note: You don't need to delete all locations. The plugin manages the number of stored locations automatically and the total count never exceeds the number as defined byoption.maxLocations.

Platform: iOS, Android

Delete all stored locations.

Note: Locations are not actually deleted from database to avoid gaps in locationId numbering.Instead locations are marked as deleted. Locations marked as deleted will not appear in output ofBackgroundGeolocation.getValidLocations.

Platform: iOS

Normally the plugin will handle switching betweenBACKGROUND andFOREGROUND mode itself.Calling switchMode you can override plugin behavior and force it to switch into other mode.

InFOREGROUND mode the plugin uses iOS local manager to receive locations and behavior is affectedbyoption.desiredAccuracy andoption.distanceFilter.

InBACKGROUND mode plugin uses significant changes and region monitoring to receive locationsand usesoption.stationaryRadius only.

// switch to FOREGROUND modeBackgroundGeolocation.switchMode(BackgroundGeolocation.FOREGROUND_MODE);// switch to BACKGROUND modeBackgroundGeolocation.switchMode(BackgroundGeolocation.BACKGROUND_MODE);

Platform: Android, iOS

Force sync of pending locations. OptionsyncThreshold will be ignored andall pending locations will be immediately posted tosyncUrl in single batch.

Platform: Android, iOS

Return all logged events. Useful for plugin debugging.

*Example of infinite log scrolling

Format of log entry:

Unregister all event listeners for given event. If parameterevent is not provided then all event listeners will be removed.

Locations parametersisFromMockProvider andmockLocationsEnabled are not posted tourl orsyncUrl by default.Both can be requested via optionpostTemplate.

Note: Do not use locationid as unique key in your database as ids will be reused whenoption.maxLocations is reached.

Note: Android currently returnstime as type of String (instead of Number)@see issue #9685

Event listeners can registered with:

const eventSubscription = BackgroundGeolocation.on('event', callbackFn);

And unregistered:

eventSubscription.remove();

Note: Components should unregister all event listeners incomponentWillUnmount method,individually, or withremoveAllListeners

All locations updates are recorded in the local db at all times. When the App is in foreground or background, in addition to storing location in local db,the location callback function is triggered. The number of locations stored in db is limited byoption.maxLocations and never exceeds this number.Instead, old locations are replaced by new ones.

Whenoption.url is defined, each location is also immediately posted to url defined byoption.url.If the post is successful, the location is marked as deleted in local db.

Whenoption.syncUrl is defined, all locations that fail to post will be coalesced and sent in some time later in a single batch.Batch sync takes place only when the number of failed-to-post locations reachesoption.syncTreshold.Locations are sent only in single batch when the number of locations reachesoption.syncTreshold. (No individual locations will be sent)

The request body of posted locations is always an array, even when only one location is sent.

Warning:option.maxLocations has to be larger thanoption.syncThreshold. It's recommended to be 2x larger. In any other case the location syncing might not work properly.

Withoption.postTemplate it is possible to specify which location properties should be posted tooption.url oroption.syncUrl. This can be useful to reduce thenumber of bytes sent "over the "wire".

All wanted location properties have to be prefixed with@. For all available properties checkLocation event.

Two forms are supported:

jsonObject

BackgroundGeolocation.configure({  postTemplate: {    lat: '@latitude',    lon: '@longitude',    foo: 'bar' // you can also add your own properties  }});

jsonArray

BackgroundGeolocation.configure({  postTemplate: ['@latitude', '@longitude', 'foo', 'bar']});

Note: Keep in mind that all locations (even a single one) will be sent as an array of object(s), when postTemplate isjsonObject and array of array(s) forjsonArray!

A special task that gets executed when the app is terminated, but the plugin was configured to continue running in the background (optionstopOnTerminate: false). In this scenario theActivitywas killed by the system and all registered event listeners will not be triggered until the app is relaunched.

Note: Prefer configuration optionsurl andsyncUrl over headless task. Use it sparingly!

Keep in mind that the callback function lives in an isolated scope. Variables from a higher scope cannot be referenced!

Following example requiresCORS enabled backend server.

Warning: callback function must byasync!

BackgroundGeolocation.headlessTask(async (event) => {    if (event.name === 'location' ||      event.name === 'stationary') {        var xhr = new XMLHttpRequest();        xhr.open('POST', 'http://192.168.81.14:3000/headless');        xhr.setRequestHeader('Content-Type', 'application/json');        xhr.send(JSON.stringify(event.params));    }});

Important:

After application is launched again (main activity becomes visible), it is important to callstart method to rebind all event listeners.

BackgroundGeolocation.checkStatus(({ isRunning }) => {  if (isRunning) {    BackgroundGeolocation.start(); // service was running -> rebind all listeners  }});

In some cases you might want to modify a location before posting, reject a location, or any other logic around incoming locations - in native code. There's an option of doing so with a headless task, but you may want to preserve battery, or do more complex actions that are not available in React.

In those cases you could register a location transform.

Android example:

When theApplication is initialized (which also happens before services gets started in the background), write some code like this:

BackgroundGeolocationFacade.setLocationTransform(new LocationTransform() {    @Nullable    @Override    public BackgroundLocation transformLocationBeforeCommit(@NonNull Context context, @NonNull BackgroundLocation location) {    // `context` is available too if there's a need to use a value from preferences etc.    // Modify the location    location.setLatitude(location.getLatitude() + 0.018);    // Return modified location    return location;    // You could return null to reject the location,    // or if you did something else with the location and the library should not post or save it.    }});

iOS example:

IndidFinishLaunchingWithOptions delegate method, write some code like this:

BackgroundGeolocationFacade.locationTransform = ^(MAURLocation * location) {  // Modify the location  location.latitude = @(location.latitude.doubleValue + 0.018);    // Return modified location  return location;    // You could return null to reject the location,  // or if you did something else with the location and the library should not post or save it.};

Add string resource "account_name" into "android/app/src/main/res/values/strings.xml"

<string name="account_name">Sync Locations</string>

Background-geolocation-server is a backend server written in nodejs with CORS - Cross-Origin Resource Sharing support.There are instructions how to run it and simulate locations on Android, iOS Simulator and Genymotion.

TODO

NOTE: For iOS in addition, you must manually enable theAudio and Airplay background mode inBackground Capabilities to hear these debugging sounds.

Try usingreact-native-boundary. Let's keep this plugin lightweight as much as possible.

SeeCHANGES.md

See变更（非官方中文版）