react-native-background-geolocation 4.4.0 → 4.4.4

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Change Log
 
+## 4.4.4 — 2021-11-11
+* [Fixed][iOS] More issues with iOS plugin 'invalidate' method.  Get rid of this method.  Implement startObserving, stopObserving.
+
+## 4.4.3 — 2021-11-10
+* [Fixed][iOS] Backwards compatibility issue:  react-native@0.66 does have this method.  `No visible @interface for 'RCTEventEmitter' declares the selector 'invalidate' in RNBackgroundGeolocation.m`.  
+
+## 4.4.2 — 2021-10-29
+* [Fixed][Android] Android 12 behaviour changes mean that foreground-services remain running.  When an Android app is terminated, the app process does not terminate (since the foreground-service is active) and `RNBackgroundGeolocationModule` remains in memory.  Given that, the plugin cannot rely on registering its event-listeners in the `RNBackgroundGeolocationModule` constructor, but must perform that task when `.ready()` is called.  This also requires resetting `mReady = false` when the `MainActivity` is destroyed, so that the next time `.ready()` is called, the event-listeners are re-registered.
+* [Fixed][Android] When `.ready()` is called __`reset: false`__, the `success` callback was not invoked with the current `State`.  This bug was introduced in previous `v4.4.1`.
+
+## 4.4.1 — 2021-10-29
+* [Added] Added a `Subscription` interface to Typescript API.  Added helpful docs to Subscription for new event-handler subscriptions.
+
+```typescript
+import BackgroundGeolocation, {
+  Subscription
+} from "...";
+.
+.
+.
+const subscription:Subscription = BacckgroundGeolocation.onLocation(myHandler);
+```
+
 ## 4.4.0 — 2021-10-25
 * [Added] New `Authorization.strategy "SAS"` (alternative to default `JWT`).
 * [Fixed] Fixed __`RCTEventEmitter`__ warning "addListener", "removeListeners".  A corresponding fix has also been released for [react-native-background-fetch](https://github.com/transistorsoft/react-native-background-fetch/blob/master/CHANGELOG.md#404--2021-10-22) so be sure to update to `background-fetch >= 4.0.4`.

package/README.md

@@ -29,6 +29,7 @@ The **[Android module](http://www.transistorsoft.com/shop/products/react-native-
 ![Settings](https://dl.dropboxusercontent.com/s/8oad228siog49kt/settings-framed-350.png?dl=1)
 
 # Contents
+- ### 😫 [Help!](../../wiki/Help)
 - ### :books: [API Documentation](https://transistorsoft.github.io/react-native-background-geolocation)
 - ### [Installing the Plugin](#large_blue_diamond-installing-the-plugin)
 - ### [Setup Guides](#large_blue_diamond-setup-guides)
@@ -136,40 +137,77 @@ For more information, see [this blog post](https://medium.com/@transistorsoft/ne
 
 There are three main steps to using `BackgroundGeolocation`
 1. Wire up event-listeners.
-2. `#ready` the plugin.
-3. `#start` the plugin.
+2. `.ready(config)` the plugin.
+3. `.start()` the plugin.
+
+:warning: Do not execute *any* API method which will require accessing location-services until the **`.ready(config)`** method resolves (eg: `#getCurrentPosition`, `#watchPosition`, `#start`).
 
 ```javascript
-// Import BackgroundGeolocation + any optional interfaces
-import BackgroundGeolocation from "react-native-background-geolocation";
+// NO!  .ready() has not resolved.
+BackgroundGeolocation.getCurrentPosition(options);
+BackgroundGeolocation.start();
+
+BackgroundGeolocation.ready(config).then((state) => {
+  // YES -- .ready() has now resolved.
+  BackgroundGeolocation.getCurrentPosition(options);
+  BackgroundGeolocation.start();  
+});
+
+// NO!  .ready() has not resolved.
+BackgroundGeolocation.getCurrentPosition(options);
+BackgroundGeolocation.start();
+```
 
-export default class App extends Component {
-  componentWillMount() {
-    ////
-    // 1.  Wire up event-listeners
-    //
 
-    // This handler fires whenever bgGeo receives a location update.
-    BackgroundGeolocation.onLocation(this.onLocation, this.onError);
+### Example 1. — React *Functional Component*
 
-    // This handler fires when movement states changes (stationary->moving; moving->stationary)
-    BackgroundGeolocation.onMotionChange(this.onMotionChange);
+<details>
+  <summary>Show Source</summary>
 
-    // This event fires when a change in motion activity is detected
-    BackgroundGeolocation.onActivityChange(this.onActivityChange);
+```javascript
+
+import React from 'react';
+import {
+  Switch,
+  Text,
+  View,
+} from 'react-native';
 
-    // This event fires when the user toggles location-services authorization
-    BackgroundGeolocation.onProviderChange(this.onProviderChange);
+import BackgroundGeolocation, {
+  Location,
+  Subscription
+} from "react-native-background-geolocation";
 
-    ////
-    // 2.  Execute #ready method (required)
-    //
+const HelloWorld = () => {
+  const [enabled, setEnabled] = React.useState(false);
+  const [location, setLocation] = React.useState('');
+
+  React.useEffect(() => {
+    /// 1.  Subscribe to events.
+    const onLocation:Subscription = BackgroundGeolocation.onLocation((location) => {
+      console.log('[onLocation]', location);
+      setLocation(JSON.stringify(location, null, 2));
+    })
+
+    const onMotionChange:Subscription = BackgroundGeolocation.onMotionChange((event) => {
+      console.log('[onMotionChange]', event);
+    });
+
+    const onActivityChange:Subscription = BackgroundGeolocation.onActivityChange((event) => {
+      console.log('[onMotionChange]', event);
+    })
+
+    const onProviderChange:Subscription = BackgroundGeolocation.onProviderChange((event) => {
+      console.log('[onProviderChange]', event);
+    })
+
+    /// 2. ready the plugin.
     BackgroundGeolocation.ready({
       // Geolocation Config
       desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
       distanceFilter: 10,
       // Activity Recognition
-      stopTimeout: 1,
+      stopTimeout: 5,
       // Application config
       debug: true, // <-- enable this hear sounds for background-geolocation life-cycle.
       logLevel: BackgroundGeolocation.LOG_LEVEL_VERBOSE,
@@ -185,68 +223,178 @@ export default class App extends Component {
       params: {               // <-- Optional HTTP params
         "auth_token": "maybe_your_server_authenticates_via_token_YES?"
       }
-    }, (state) => {
+    }).then((state) => {
+      setEnabled(state.enabled)
       console.log("- BackgroundGeolocation is configured and ready: ", state.enabled);
+    });
+
+    return () => {
+      // Remove BackgroundGeolocation event-subscribers when the View is removed or refreshed
+      // during development live-reload.  Without this, event-listeners will accumulate with
+      // each refresh during live-reload.
+      onLocation.remove();
+      onMotionChange.remove();
+      onActivityChange.remove();
+      onProviderChange.remove();
+    }
+  }, []);
+
+  /// 3. start / stop BackgroundGeolocation
+  React.useEffect(() => {
+    if (enabled) {
+      BackgroundGeolocation.start();
+    } else {
+      BackgroundGeolocation.stop();
+      setLocation('');
+    }
+  }, [enabled]);
+
+  return (
+    <View style={{alignItems:'center'}}>
+      <Text>Click to enable BackgroundGeolocation</Text>
+      <Switch value={enabled} onValueChange={setEnabled} />
+      <Text style={{fontFamily:'monospace', fontSize:12}}>{location}</Text>
+    </View>
+  )
+}
 
-      if (!state.enabled) {
-        ////
-        // 3. Start tracking!
-        //
-        BackgroundGeolocation.start(function() {
-          console.log("- Start success");
-        });
+export default HelloWorld;
+```
+
+</details>
+
+### Example 2. &mdash; React *Class Component*
+
+<details>
+  <summary>Show Source</summary>
+
+```javascript
+import React from 'react';
+import {
+  Switch,
+  Text,
+  View,
+} from 'react-native';
+
+import BackgroundGeolocation, {
+  Location,
+  Subscription
+} from "react-native-background-geolocation";
+
+export default class HelloWorld extends React.Component {
+  subscriptions:Subscription[] = [];
+  state:any = {};
+  constructor(props:any) {
+    super(props);
+    this.state = {
+      enabled: false,
+      location: ''
+    }
+  }
+
+  componentDidMount() {
+    /// 1.  Subscribe to BackgroundGeolocation events.
+    this.subscriptions.push(BackgroundGeolocation.onLocation((location) => {
+      console.log('[onLocation]', location);
+      this.setState({location: JSON.stringify(location, null, 2)})
+    }, (error) => {
+      console.log('[onLocation] ERROR:', error);
+    }))
+
+    this.subscriptions.push(BackgroundGeolocation.onMotionChange((event) => {
+      console.log('[onMotionChange]', event);
+    }))
+
+    this.subscriptions.push(BackgroundGeolocation.onActivityChange((event) => {
+      console.log('[onActivityChange]', event);
+    }))
+
+    this.subscriptions.push(BackgroundGeolocation.onProviderChange((event) => {
+      console.log('[onProviderChange]', event);
+    }))
+
+    /// 2. ready the plugin.
+    BackgroundGeolocation.ready({
+      // Geolocation Config
+      desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
+      distanceFilter: 10,
+      // Activity Recognition
+      stopTimeout: 5,
+      // Application config
+      debug: true, // <-- enable this hear sounds for background-geolocation life-cycle.
+      logLevel: BackgroundGeolocation.LOG_LEVEL_VERBOSE,
+      stopOnTerminate: false,   // <-- Allow the background-service to continue tracking when user closes the app.
+      startOnBoot: true,        // <-- Auto start tracking when device is powered-up.
+      // HTTP / SQLite config
+      url: 'http://yourserver.com/locations',
+      batchSync: false,       // <-- [Default: false] Set true to sync locations to server in a single HTTP request.
+      autoSync: true,         // <-- [Default: true] Set true to sync each location to server as it arrives.
+      headers: {              // <-- Optional HTTP headers
+        "X-FOO": "bar"
+      },
+      params: {               // <-- Optional HTTP params
+        "auth_token": "maybe_your_server_authenticates_via_token_YES?"
       }
-    });
+    }).then((state) => {
+      this.setState({enabled: state.enabled});
+      console.log("- BackgroundGeolocation is configured and ready: ", state.enabled);
+    })
   }
 
-  // You must remove listeners when your component unmounts
+  /// When view is destroyed (or refreshed during development live-reload),
+  /// remove BackgroundGeolocation event subscriptions.
   componentWillUnmount() {
-    BackgroundGeolocation.removeListeners();
-  }
-  onLocation(location) {
-    console.log('[location] -', location);
-  }
-  onError(error) {
-    console.warn('[location] ERROR -', error);
-  }
-  onActivityChange(event) {
-    console.log('[activitychange] -', event);  // eg: 'on_foot', 'still', 'in_vehicle'
+    this.subscriptions.forEach((subscription) => subscription.remove());
   }
-  onProviderChange(provider) {
-    console.log('[providerchange] -', provider.enabled, provider.status);
+
+  onToggleEnabled(value:boolean) {
+    console.log('[onToggleEnabled]', value);
+    this.setState({enabled: value})
+    if (value) {
+      BackgroundGeolocation.start();
+    } else {
+      this.setState({location: ''});
+      BackgroundGeolocation.stop();
+    }
   }
-  onMotionChange(event) {
-    console.log('[motionchange] -', event.isMoving, event.location);
+
+  render() {
+    return (
+      <View style={{alignItems:'center'}}>
+        <Text>Click to enable BackgroundGeolocation</Text>
+        <Switch value={this.state.enabled} onValueChange={this.onToggleEnabled.bind(this)} />
+        <Text style={{fontFamily:'monospace', fontSize:12}}>{this.state.location}</Text>
+      </View>
+    )
   }
 }
-
-```
-
-```javascript
-BackgroundGeolocation.ready({
-  reset: true,  // <-- true to always apply the supplied config
-  distanceFilter: 10
-}, (state) => {
-  console.log('- BackgroundGeolocation is ready: ', state);
-});
 ```
-
-:warning: Do not execute *any* API method which will require accessing location-services until the callback to **`#ready`** executes (eg: `#getCurrentPosition`, `#watchPosition`, `#start`).
+</details>
 
 ### Promise API
 
-The `BackgroundGeolocation` Javascript API supports [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) for *nearly* every method (the exceptions are **`#watchPosition`** and adding event-listeners via **`#on`** method.  For more information, see the [API Documentation](https://transistorsoft.github.io/react-native-background-geolocation)
+The `BackgroundGeolocation` Javascript API supports [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) for *nearly* every method (the exceptions are **`#watchPosition`** and adding event-listeners via **`#onXXX`** method (eg: `onLocation`).  For more information, see the [API Documentation](https://transistorsoft.github.io/react-native-background-geolocation-android)
 
 ```javascript
-// Traditional API still works:
 BackgroundGeolocation.ready({
-  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
+  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH, 
   distanceFilter: 50
 }).then(state => {
   console.log('- BackgroundGeolocation is ready: ', state);
 }).catch(error => {
-  console.log('- BackgroundGeolocation error: ', error);
+  console.warn('- BackgroundGeolocation error: ', error);
 });
+
+// Or use await in an async function
+try {
+  const state = await BackgroundGeolocation.ready({
+    desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH, 
+    distanceFilter: 50
+  })
+  console.log('- BackgroundGeolocation is ready: ', state);
+} catch (error) {
+  console.warn('- BackgroundGeolocation error: ', error);
+}
 ```
 
 ## :large_blue_diamond: [Demo Application](https://github.com/transistorsoft/rn-background-geolocation-demo)

package/android/libs/com/transistorsoft/tslocationmanager/3.1.35/tslocationmanager-3.1.35.aar.md5

@@ -0,0 +1 @@
+3a9143ce4479579c135bbf7f1ca80e9c

package/android/libs/com/transistorsoft/tslocationmanager/3.1.35/tslocationmanager-3.1.35.aar.sha1

@@ -0,0 +1 @@
+c16850b24271032c3ccb10349ba0774069a67819

package/android/libs/com/transistorsoft/tslocationmanager/3.1.35/tslocationmanager-3.1.35.aar.sha256

@@ -0,0 +1 @@
+e18fc8dd9d37cd2ee00c64e8e1a78ebc0839cf8515cf52463cfdd0761aa580f9

package/android/libs/com/transistorsoft/tslocationmanager/3.1.35/tslocationmanager-3.1.35.aar.sha512

@@ -0,0 +1 @@
+566d4327d7b1b9ab3b271dc61d6d661ac1f4c8c89557de1d11c52928a4af5682c702a315e76f2cf46dc882d405fe3c4d6a958c7f0a885a228b3d0b2a735d8305

package/android/libs/com/transistorsoft/tslocationmanager/3.1.35/tslocationmanager-3.1.35.pom

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.transistorsoft</groupId>
+  <artifactId>tslocationmanager</artifactId>
+  <version>3.1.35</version>
+  <packaging>aar</packaging>
+</project>

package/android/libs/com/transistorsoft/tslocationmanager/3.1.35/tslocationmanager-3.1.35.pom.md5

@@ -0,0 +1 @@
+007e6f97f3eef0a29312b614881094d5

package/android/libs/com/transistorsoft/tslocationmanager/3.1.35/tslocationmanager-3.1.35.pom.sha1

@@ -0,0 +1 @@
+a558cd1eb103134e207932ea7af8c6cf48cc97d7

package/android/libs/com/transistorsoft/tslocationmanager/3.1.35/tslocationmanager-3.1.35.pom.sha256

@@ -0,0 +1 @@
+f11bf76c75d7d586ceef2978d3bb789deceee30b6c06032edf57647333f98efe

package/android/libs/com/transistorsoft/tslocationmanager/3.1.35/tslocationmanager-3.1.35.pom.sha512

@@ -0,0 +1 @@
+d7d2120c48292dc74e273daacad40b19ebfa0617aed7f8fa3b9a8eeb4a10b0ab85e2cc702394f9d1aaf0619b3fdcef728db223c76ffca66288033eb867787acb

package/android/libs/com/transistorsoft/tslocationmanager/maven-metadata.xml

@@ -3,13 +3,11 @@
   <groupId>com.transistorsoft</groupId>
   <artifactId>tslocationmanager</artifactId>
   <versioning>
-    <latest>3.1.34</latest>
-    <release>3.1.34</release>
+    <latest>3.1.35</latest>
+    <release>3.1.35</release>
     <versions>
-      <version>3.1.32</version>
-      <version>3.1.33</version>
-      <version>3.1.34</version>
+      <version>3.1.35</version>
     </versions>
-    <lastUpdated>20211013180057</lastUpdated>
+    <lastUpdated>20211110133724</lastUpdated>
   </versioning>
 </metadata>

package/android/libs/com/transistorsoft/tslocationmanager-reverse/3.1.35/tslocationmanager-reverse-3.1.35.aar.md5

@@ -0,0 +1 @@
+2f0a4b4aca18ec71d130eb7042ba8334

package/android/libs/com/transistorsoft/tslocationmanager-reverse/3.1.35/tslocationmanager-reverse-3.1.35.aar.sha1

@@ -0,0 +1 @@
+e7828269f47ca87dd74c5a6952ed1fc464ec074e

package/android/libs/com/transistorsoft/tslocationmanager-reverse/3.1.35/tslocationmanager-reverse-3.1.35.aar.sha256

@@ -0,0 +1 @@
+1230b611eb4b11c8a65f878e8253cea9f510fac5979f250014c37dc800645054

package/android/libs/com/transistorsoft/tslocationmanager-reverse/3.1.35/tslocationmanager-reverse-3.1.35.aar.sha512

@@ -0,0 +1 @@
+650b7213bc570d2a8697550f5a03ca42657c190a37c490a82fc762d88d6fe5f1170cba23f68530d90180c19ac795c69142b9d39290495a119314163d1ff9577f

package/android/libs/com/transistorsoft/tslocationmanager-reverse/3.1.35/tslocationmanager-reverse-3.1.35.pom

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.transistorsoft</groupId>
+  <artifactId>tslocationmanager-reverse</artifactId>
+  <version>3.1.35</version>
+  <packaging>aar</packaging>
+</project>

package/android/libs/com/transistorsoft/tslocationmanager-reverse/3.1.35/tslocationmanager-reverse-3.1.35.pom.md5

@@ -0,0 +1 @@
+00b43ef20d3f14d733a05d82c4435aaf

package/android/libs/com/transistorsoft/tslocationmanager-reverse/3.1.35/tslocationmanager-reverse-3.1.35.pom.sha1

@@ -0,0 +1 @@
+28d26ba8a4044945fd457d033dbdd457dde4144d

package/android/libs/com/transistorsoft/tslocationmanager-reverse/3.1.35/tslocationmanager-reverse-3.1.35.pom.sha256

@@ -0,0 +1 @@
+5ee1b9a1bf97d7ea8e005f108f18ec78e2410dfdc45a6e29755a28e5df15daf1

package/android/libs/com/transistorsoft/tslocationmanager-reverse/3.1.35/tslocationmanager-reverse-3.1.35.pom.sha512

@@ -0,0 +1 @@
+db1bf3fe2779d75145bcf1929692b5a87e24f9d4046d783a40d903eb7ef0a780f26062c03be017b2a9bb759778b9969eebda9b952abde90ac9e0dd37912d728f

package/android/libs/com/transistorsoft/tslocationmanager-reverse/maven-metadata.xml

@@ -3,13 +3,11 @@
   <groupId>com.transistorsoft</groupId>
   <artifactId>tslocationmanager-reverse</artifactId>
   <versioning>
-    <latest>3.1.34</latest>
-    <release>3.1.34</release>
+    <latest>3.1.35</latest>
+    <release>3.1.35</release>
     <versions>
-      <version>3.1.32</version>
-      <version>3.1.33</version>
-      <version>3.1.34</version>
+      <version>3.1.35</version>
     </versions>
-    <lastUpdated>20211013180057</lastUpdated>
+    <lastUpdated>20211110133724</lastUpdated>
   </versioning>
 </metadata>

package/android/src/main/java/com/transistorsoft/rnbackgroundgeolocation/RNBackgroundGeolocationModule.java

@@ -90,13 +90,14 @@ public class RNBackgroundGeolocationModule extends ReactContextBaseJavaModule im
 
     public RNBackgroundGeolocationModule(ReactApplicationContext reactContext) {
         super(reactContext);
+        reactContext.addLifecycleEventListener(this);
 
         TSConfig config = TSConfig.getInstance(getReactApplicationContext());
         config.useCLLocationAccuracy(true);
 
         config.updateWithBuilder()
-            .setHeadlessJobService(getClass().getPackage().getName() + "." + JOB_SERVICE_CLASS)
-            .commit();
+                .setHeadlessJobService(getClass().getPackage().getName() + "." + JOB_SERVICE_CLASS)
+                .commit();
 
         // These are the only events which can be subscribed to.
         mEvents.add(BackgroundGeolocation.EVENT_LOCATION);
@@ -113,9 +114,18 @@ public class RNBackgroundGeolocationModule extends ReactContextBaseJavaModule im
         mEvents.add(BackgroundGeolocation.EVENT_ENABLEDCHANGE);
         mEvents.add(BackgroundGeolocation.EVENT_NOTIFICATIONACTION);
         mEvents.add(TSAuthorization.NAME);
+    }
 
-        reactContext.addLifecycleEventListener(this);
+    @Override
+    public void initialize() {
+        // do nothing
+    }
+    @Override
+    public String getName() {
+        return "RNBackgroundGeolocation";
+    }
 
+    private void registerEvents() {
         BackgroundGeolocation adapter = getAdapter();
         adapter.onLocation(new LocationCallback());
         adapter.onMotionChange(new MotionChangeCallback());
@@ -133,16 +143,6 @@ public class RNBackgroundGeolocationModule extends ReactContextBaseJavaModule im
         HttpService.getInstance(getReactApplicationContext()).onAuthorization(new AuthorizationCallback());
     }
 
-    @Override
-    public void initialize() {
-        // do nothing
-    }
-    @Override
-    public String getName() {
-        return "RNBackgroundGeolocation";
-    }
-
-
     /**
      * location event callback
      */
@@ -340,6 +340,7 @@ public class RNBackgroundGeolocationModule extends ReactContextBaseJavaModule im
     @Override
     public void onHostDestroy() {
         mInitialized = false;
+        mReady = false;
         removeAllListeners();
         getAdapter().onActivityDestroy();
     }
@@ -374,10 +375,13 @@ public class RNBackgroundGeolocationModule extends ReactContextBaseJavaModule im
                 setConfig(params, success, failure);
             } else {
                 TSLog.logger.warn(TSLog.warn("#ready already called.  Ignored config since reset: false"));
+                success.invoke(getState());
             }
             return;
         }
         mReady = true;
+        registerEvents();
+
         if (config.isFirstBoot()) {
             config.updateWithJSONObject(mapToJson(setHeadlessJobService(params)));
         } else {

package/ios/RNBackgroundGeolocation/RNBackgroundGeolocation.m

@@ -659,13 +659,13 @@ RCT_EXPORT_METHOD(playSound:(int)soundId)
     [self sendEventWithName:event body:body];
 }
 
-- (void)invalidate
-{
-    [super invalidate];
-    [locationManager removeListeners];
-    dispatch_async(dispatch_get_main_queue(), ^{
-        [self.locationManager stopWatchPosition];
-    });
+- (void) startObserving {
+    // TODO Could possibly execute [self registerEventListeners] here.
+    [locationManager log:@"info" message:@"[RNBackgroundGeolocation startObserving]"];
+}
+- (void) stopObserving {
+    // TODO Could possibly execute [locationManager removeListeners] here.
+    [locationManager log:@"info" message:@"[RNBackgroundGeolocation stopObserving]"];
 }
 
 - (void)dealloc

package/ios/RNBackgroundGeolocation/TSLocationManager.xcframework/Info.plist

@@ -6,47 +6,47 @@
 	<array>
 		<dict>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_i386_x86_64-simulator</string>
+			<string>ios-arm64_x86_64-maccatalyst</string>
 			<key>LibraryPath</key>
 			<string>TSLocationManager.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>i386</string>
 				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
 			<key>SupportedPlatformVariant</key>
-			<string>simulator</string>
+			<string>maccatalyst</string>
 		</dict>
 		<dict>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_armv7</string>
+			<string>ios-arm64_i386_x86_64-simulator</string>
 			<key>LibraryPath</key>
 			<string>TSLocationManager.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>armv7</string>
+				<string>i386</string>
+				<string>x86_64</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
+			<key>SupportedPlatformVariant</key>
+			<string>simulator</string>
 		</dict>
 		<dict>
 			<key>LibraryIdentifier</key>
-			<string>ios-arm64_x86_64-maccatalyst</string>
+			<string>ios-arm64_armv7</string>
 			<key>LibraryPath</key>
 			<string>TSLocationManager.framework</string>
 			<key>SupportedArchitectures</key>
 			<array>
 				<string>arm64</string>
-				<string>x86_64</string>
+				<string>armv7</string>
 			</array>
 			<key>SupportedPlatform</key>
 			<string>ios</string>
-			<key>SupportedPlatformVariant</key>
-			<string>maccatalyst</string>
 		</dict>
 	</array>
 	<key>CFBundlePackageType</key>

package/ios/RNBackgroundGeolocation/TSLocationManager.xcframework/ios-arm64_i386_x86_64-simulator/TSLocationManager.framework/_CodeSignature/CodeResources

@@ -138,7 +138,7 @@
 		</data>
 		<key>Info.plist</key>
 		<data>
-		lCvkm6gOxhn5NxMHGiCuBZPRf6w=
+		Wmf3yVcUbx+t9XH4ju46ia3KxCE=
 		</data>
 		<key>Modules/module.modulemap</key>
 		<data>

package/ios/RNBackgroundGeolocation/TSLocationManager.xcframework/ios-arm64_x86_64-maccatalyst/TSLocationManager.framework/Resources/Info.plist

@@ -3,7 +3,7 @@
 <plist version="1.0">
 <dict>
 	<key>BuildMachineOSBuild</key>
-	<string>20G165</string>
+	<string>21A559</string>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleExecutable</key>
@@ -17,29 +17,29 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>4.0.7</string>
+	<string>4.1.0</string>
 	<key>CFBundleSupportedPlatforms</key>
 	<array>
 		<string>MacOSX</string>
 	</array>
 	<key>CFBundleVersion</key>
-	<string>381</string>
+	<string>382</string>
 	<key>DTCompiler</key>
 	<string>com.apple.compilers.llvm.clang.1_0</string>
 	<key>DTPlatformBuild</key>
-	<string>12D4e</string>
+	<string>13A1030d</string>
 	<key>DTPlatformName</key>
 	<string>macosx</string>
 	<key>DTPlatformVersion</key>
-	<string>11.1</string>
+	<string>12.0</string>
 	<key>DTSDKBuild</key>
-	<string>20C63</string>
+	<string>21A344</string>
 	<key>DTSDKName</key>
-	<string>macosx11.1</string>
+	<string>macosx12.0</string>
 	<key>DTXcode</key>
-	<string>1240</string>
+	<string>1310</string>
 	<key>DTXcodeBuild</key>
-	<string>12D4e</string>
+	<string>13A1030d</string>
 	<key>LSMinimumSystemVersion</key>
 	<string>10.15</string>
 	<key>UIDeviceFamily</key>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-background-geolocation",
-  "version": "4.4.0",
+  "version": "4.4.4",
   "description": "The most sophisticated cross-platform background location-tracking & geofencing module with battery-conscious motion-detection intelligence",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -46,7 +46,7 @@
     "react-native-background-fetch": "~4.0.4"
   },
   "devDependencies": {
-    "@transistorsoft/typedoc-theme": "^2.0.7",
+    "@transistorsoft/typedoc-theme": "^2.0.8",
     "chalk": "^4.1.0",
     "fs-extra": "^9.1.0",
     "rimraf": "^3.0.2"

package/src/declarations/BackgroundGeolocation.d.ts

@@ -23,7 +23,7 @@
 /// <reference path="interfaces/Authorization.d.ts" />
 /// <reference path="interfaces/AuthorizationEvent.d.ts" />
 /// <reference path="interfaces/TransistorAuthorizationToken.d.ts" />
-///
+/// <reference path="interfaces/Subscription.d.ts" />
 declare module "react-native-background-geolocation" {
   /**
   * Primary API of the SDK.
@@ -253,6 +253,23 @@ declare module "react-native-background-geolocation" {
     */
     static on(event: string, success:Function, failure?:Function):void;
     /**
+    * @deprecated.  Use [[Subscription]] returned from __`BackgroundGeolocation.onXXX`__ to remove listeners.
+    *
+    * @example
+    * ```typescript
+    * const subscription = BackgroundGeolocation.onLocation((location) => {
+    *   console.log('[onLocation]', location);
+    * });
+    * .
+    * .
+    * .
+    * // Remove listener
+    * subscription.remove();
+    * ```
+    *
+    * ---------------------------------------------------------------------
+    * ### ⚠️ [Deprecated]
+    *
     * Removes an event listener.  You must supply the *type* of event to remove in addition to a reference to the *exact* function you
     * used to subscribe to the event.
     *
@@ -274,7 +291,7 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * let locationHandler = (location) => {
+    * const locationHandler = (location) => {
     *   console.log("[location] - ", location)
     * }
     * BackgroundGeolocation.onLocation(locationHandler)
@@ -293,7 +310,9 @@ declare module "react-native-background-geolocation" {
     static un(event: string, handler: Function, success?:Function, failure?:Function): void;
 
     /**
-    * Removes all event-listeners
+    * Removes all event-listeners.
+    *
+    * Calls [[Subscription.remove]] on all subscriptions.
     *
     * @example
     * ```typescript
@@ -314,7 +333,7 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onLocation((location) => {
+    * const subscription = BackgroundGeolocation.onLocation((location) => {
     *   console.log("[onLocation] success: ", location);
     * }, (error) => {
     *   console.log("[onLocation] ERROR: ", error);
@@ -333,7 +352,7 @@ declare module "react-native-background-geolocation" {
     *
     * @event location
     */
-    static onLocation(success: (location:Location)=>void, failure?:(errorCode: LocationError) => void):void;
+    static onLocation(success: (location:Location)=>void, failure?:(errorCode: LocationError) => void):Subscription;
 
     /**
     * Subscribe to Geofence transition events.
@@ -342,7 +361,7 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onGeofence((event) => {
+    * const subscription = BackgroundGeolocation.onGeofence((event) => {
     *   console.log("[onGeofence] ", event);
     * });
     * ```
@@ -352,7 +371,7 @@ declare module "react-native-background-geolocation" {
     *
     * @event geofence
     */
-    static onGeofence(callback: (event: GeofenceEvent) => void):void;
+    static onGeofence(callback: (event: GeofenceEvent) => void):Subscription;
 
     /**
     * Subscribe to __`motionchange`__ events.
@@ -362,7 +381,7 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onMotionChange((event) => {
+    * const subscription = BackgroundGeolocation.onMotionChange((event) => {
     *   if (event.isMoving) {
     *      console.log("[onMotionChange] Device has just started MOVING ", event.location);
     *   } else {
@@ -385,14 +404,14 @@ declare module "react-native-background-geolocation" {
     *
     * @event motionchange
     */
-    static onMotionChange(callback: (event:MotionChangeEvent) => void): void;
+    static onMotionChange(callback: (event:MotionChangeEvent) => void): Subscription;
 
     /**
     * Subscribe to HTTP responses from your server [[Config.url]].
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onHttp((response) => {
+    * const subscription = BackgroundGeolocation.onHttp((response) => {
     *   let status = response.status;
     *   let success = response.success;
     *   let responseText = response.responseText;
@@ -404,7 +423,7 @@ declare module "react-native-background-geolocation" {
     *
     * @event http
     */
-    static onHttp(callback: (response:HttpEvent) => void): void;
+    static onHttp(callback: (response:HttpEvent) => void): Subscription;
 
     /**
     * Subscribe to changes in motion activity.
@@ -416,13 +435,13 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onActivityChange((event) => {
+    * const subscription = BackgroundGeolocation.onActivityChange((event) => {
     *   console.log("[onActivityChange] ", event);
     * });
     * ```
     * @event activitychange
     */
-    static onActivityChange(callback: (event: MotionActivityEvent) => void): void;
+    static onActivityChange(callback: (event: MotionActivityEvent) => void): Subscription;
 
     /**
     * Subscribe to changes in device's location-services configuration / authorization.
@@ -431,7 +450,7 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onProviderChange((event) => {
+    * const subscription = BackgroundGeolocation.onProviderChange((event) => {
     *   console.log("[onProviderChange: ", event);
     *
     *   switch(event.status) {
@@ -459,7 +478,7 @@ declare module "react-native-background-geolocation" {
     *
     * @event providerchange
     */
-    static onProviderChange(callback: (event:ProviderChangeEvent) => void): void;
+    static onProviderChange(callback: (event:ProviderChangeEvent) => void): Subscription;
 
     /**
     * Subscribe to periodic heartbeat events.
@@ -469,10 +488,11 @@ declare module "react-native-background-geolocation" {
     * @example
     * ```typescript
     * BackgroundGeolocation.ready({
-    *   heartbeatInterval: 60
+    *   heartbeatInterval: 60,
+    *   preventSuspend: true // <-- Required for iOS
     * });
     *
-    * BackgroundGeolocation.onHeartbeat((event) => {
+    * const subscription = BackgroundGeolocation.onHeartbeat((event) => {
     *   console.log("[onHeartbeat] ", event);
     *
     *   // You could request a new location if you wish.
@@ -489,7 +509,7 @@ declare module "react-native-background-geolocation" {
     * -  The [[Location]] provided by the [[HeartbeatEvent]] is only the last-known location.  The *heartbeat* event does not actively engage location-services.  If you wish to get the current location in your `callback`, use [[getCurrentPosition]].
     * @event heartbeat
     */
-    static onHeartbeat(callback: (event: HeartbeatEvent) => void): void;
+    static onHeartbeat(callback: (event: HeartbeatEvent) => void): Subscription;
 
     /**
     * Subscribe to changes in actively monitored geofences.
@@ -508,7 +528,7 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onGeofencesChange((event) => {
+    * const subscription = BackgroundGeolocation.onGeofencesChange((event) => {
     *   let on = event.on;     //<-- new geofences activated.
     *   let off = event.off; //<-- geofences that were just de-activated.
     *
@@ -528,7 +548,7 @@ declare module "react-native-background-geolocation" {
     * - 📘 [[Geofence | Geofencing Guide]]
     * @event geofenceschange
     */
-    static onGeofencesChange(callback: (event: GeofencesChangeEvent) => void): void;
+    static onGeofencesChange(callback: (event: GeofencesChangeEvent) => void): Subscription;
 
     /**
     * Subscribe to [[schedule]] events.
@@ -538,7 +558,7 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onSchedule((state) => {
+    * const subscription = BackgroundGeolocation.onSchedule((state) => {
     *   if (state.enabled) {
     *     console.log("[onSchedule] scheduled start tracking");
     *   } else {
@@ -548,7 +568,7 @@ declare module "react-native-background-geolocation" {
     * ```
     * @event schedule
     */
-    static onSchedule(callback: (state:State) => void): void;
+    static onSchedule(callback: (state:State) => void): Subscription;
 
     /**
     * Subscribe to changes in network connectivity.
@@ -561,13 +581,13 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onConnectivityChange((event) => {
+    * const subscription = BackgroundGeolocation.onConnectivityChange((event) => {
     *   console.log("[onConnectivityChange] ", event);
     * });
     * ```
     * @event connectivitychange
     */
-    static onConnectivityChange(callback: (event:ConnectivityChangeEvent) => void): void;
+    static onConnectivityChange(callback: (event:ConnectivityChangeEvent) => void): Subscription;
 
     /**
     * Subscribe to state changes in OS power-saving system.
@@ -592,13 +612,13 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onPowerSaveChange((isPowerSaveMode) => {
+    * const subscription = BackgroundGeolocation.onPowerSaveChange((isPowerSaveMode) => {
     *   console.log("[onPowerSaveChange: ", isPowerSaveMode);
     * });
     * ```
     * @event powersavechange
     */
-    static onPowerSaveChange(callback: (enabled:boolean) => void): void;
+    static onPowerSaveChange(callback: (enabled:boolean) => void): Subscription;
 
     /**
     * Subscribe to changes in plugin [[State.enabled]].
@@ -609,18 +629,18 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onEnabledChange(isEnabled => {
+    * const subscription = BackgroundGeolocation.onEnabledChange(isEnabled => {
     *   console.log("[onEnabledChanged] isEnabled? ", isEnabled);
     * });
     * ```
     * @event enabledchange
     */
-    static onEnabledChange(callback: (enabled:boolean) => void): void;
+    static onEnabledChange(callback: (enabled:boolean) => void): Subscription;
 
     /**
     * [__Android-only__] Subscribe to button-clicks of a custom [[Notification.layout]] on the Android foreground-service notification.
     */
-    static onNotificationAction(callback: (buttonId:string) => void): void;
+    static onNotificationAction(callback: (buttonId:string) => void): Subscription;
 
     /**
     * Subscribe to [[Authorization]] events.
@@ -632,7 +652,7 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * BackgroundGeolocation.onAuthorization((event) => {
+    * const subscription = BackgroundGeolocation.onAuthorization((event) => {
     *   if (event.success) {
     *     console.log("[authorization] ERROR: ", event.error);
     *   } else {
@@ -642,7 +662,7 @@ declare module "react-native-background-geolocation" {
     * ```
     *
     */
-    static onAuthorization(callback: (event:AuthorizationEvent) => void): void;
+    static onAuthorization(callback: (event:AuthorizationEvent) => void): Subscription;
 
     /**
     * Registers a Javascript callback to execute in the Android "Headless" state, where the app has been terminated configured with
@@ -656,7 +676,7 @@ declare module "react-native-background-geolocation" {
     *
     * @example
     * ```typescript
-    * let BackgroundGeolocationHeadlessTask = async (event) => {
+    * const BackgroundGeolocationHeadlessTask = async (event) => {
     *   let params = event.params;
     *    console.log("[BackgroundGeolocation HeadlessTask] -", event.name, params);
     *

package/src/declarations/interfaces/Subscription.d.ts

@@ -0,0 +1,104 @@
+declare module "react-native-background-geolocation" {
+  /**
+  * Object returned by BackgroundGeolocation event-listeners.  `Subscription` contains just a single method [[remove]], used for removing an event-listener.
+  *
+  * - [[BackgroundGeolocation.onLocation]]
+  * - [[BackgroundGeolocation.onMotionChange]]
+  * - [[BackgroundGeolocation.onHttp]]
+  * - [[BackgroundGeolocation.onHeartbeat]]
+  * - [[BackgroundGeolocation.onProviderChange]]
+  * - [[BackgroundGeolocation.onActivityChange]]
+  * - [[BackgroundGeolocation.onGeofence]]
+  * - [[BackgroundGeolocation.onGeofencesChange]]
+  * - [[BackgroundGeolocation.onEnabledChange]]
+  * - [[BackgroundGeolocation.onConnectivityChange]]
+  * - [[BackgroundGeolocation.onSchedule]]
+  * - [[BackgroundGeolocation.onPowerSaveChange]]
+  * - [[BackgroundGeolocation.onNotificationAction]]
+  * - [[BackgroundGeolocation.onAuthorization]]
+  *
+  * In the past, one would remove event-listeners using the __now-deprectated__ [[BackgroundGeolocation.removeListener]].
+  *
+  * ## Removing an event-listener:
+  *
+  * @example
+  * ```typescript
+  * // Event-listeners return a Subscription instance, containing a .remove() method.
+  * const subscription = BackgroundGeolocation.onLocation(location => {
+  *   console.log("[onLocation] ", location);
+  * });
+  * .
+  * .
+  * .
+  * // Later, to remove the event-listener:
+  * subscription.remove();
+  * ```
+  *
+  * One might typically manage a collection of `Subscription` instances
+  *
+  * @example
+  * ```typescript
+  * import BackgroundGeolocation, {
+  *   Location,
+  *   Subscription
+  * } from ...
+  *
+  * // Your custom Collection of Subscription instances.
+  * const SUBSCRIPTIONS = [];
+  *
+  * // Your custom method to push a Subscription instance.
+  * const subscribe = (subscription:Subscription) => {
+  *   SUBSCRIPTIONS.push(subscription);
+  * }
+  *
+  * // Your custom method to interate your SUBSCRIPTIONS and .remove each.
+  * const unsubscribe = () => {
+  *   SUBSCRIPTIONS.forEach((subscription:Subscription) => subscription.remove());
+  * }
+  *
+  * const initBackgroundGeolocation = () {
+  *   // Create event-listeners as usual, feeding the returned Subscription into
+  *   // your custom  subscribe() method.
+  *   subscribe(BackgroundGeolocation.onLocation((location:Location) => {
+  *     console.log('[onLocation]', location);
+  *   });
+  *
+  *   subscribe(BackgroundGeolocation.onMotionChange((location:Location) => {
+  *     console.log('[onMotionChange]', location);
+  *   });
+  *
+  *   subscribe(BackgroundGeolocation.onEnabledChange((enabled:boolean) => {
+  *     console.log('[onEnabledChange]', enabled);
+  *   });
+  * }
+  *
+  * const onDestroyView = () => {
+  *   // Call your custom unsubscribe method
+  *   unsubscribe();
+  * }
+  *
+  * ```
+  */
+  interface Subscription {
+    /**
+     * Removes a `BackgroundGeolocation` event-listener.
+     * @example
+     * ```typescript
+     * // Event-listeners return a Subscription instance, containing a .remove() method.
+     * const onLocationSubscription = BackgroundGeolocation.onLocation(location => {
+     *   console.log("[onLocation] ", location);
+     * });
+     *
+     * const onGeofenceSubscription = BackgroundGeolocation.onGeofence(event => {
+     *   console.log("[onGeofence] ", event);
+     * });
+     * .
+     * .
+     * .
+     * // Later, removing event-listeners.
+     * onLocationSubscription.remove();
+     * onGeofenceSubscription.remove();
+     */
+    remove():void;
+  }
+}