react-native-background-geolocation 4.17.6 → 4.18.1

package/src/declarations/BackgroundGeolocation.d.ts

@@ -6,6 +6,7 @@
 /// <reference path="interfaces/GeofenceEvent.d.ts" />
 /// <reference path="interfaces/GeofencesChangeEvent.d.ts" />
 /// <reference path="interfaces/HeartbeatEvent.d.ts" />
+/// <reference path="interfaces/HeadlessEvent.d.ts" />
 /// <reference path="interfaces/HttpEvent.d.ts" />
 /// <reference path="interfaces/Location.d.ts" />
 /// <reference path="interfaces/LocationAuthorizationAlert.d.ts" />
@@ -674,33 +675,77 @@ declare module "react-native-background-geolocation" {
     *
     * ### ⚠️ Warning:
     * - You __must__ `registerHeadlessTask` in your application root file (eg: `index.js`).
+    * 
+    * ### ⚠️ Warning:
+    * - Your `function` __must__ be declared as `async`.  You must `await` all work within your task.  Your headless-task will automatically be terminated after executing the last line of your function.
     *
     * @example
     * ```typescript
     * const BackgroundGeolocationHeadlessTask = async (event) => {
-    *   let params = event.params;
-    *    console.log("[BackgroundGeolocation HeadlessTask] -", event.name, params);
-    *
-    *    switch (event.name) {
-    *      case "heartbeat":
-    *        // Use await for async tasks
-    *        let location = await BackgroundGeolocation.getCurrentPosition({
-    *          samples: 1,
-    *          persist: false
-    *        });
-    *        console.log("[BackgroundGeolocation HeadlessTask] - getCurrentPosition:", location);
-    *        break;
-    *    }
+    *   const params = event.params;
+    *   console.log("[BackgroundGeolocation HeadlessTask] -", event.name, params);
+    *
+    *   switch (event.name) {
+    *     case "terminate":
+    *       // Use await for async tasks
+    *       const location = await BackgroundGeolocation.getCurrentPosition({
+    *         samples: 1,
+    *         persist: false
+    *       });
+    *       console.log("[BackgroundGeolocation HeadlessTask] - getCurrentPosition:", location);
+    *       break;
+    *   }
+    *   // You must await all work you do in your task.  
+    *   // Headless-tasks are automatically terminated after executing the last line of your function.
+    *   await doWork();
     * }
     *
     * BackgroundGeolocation.registerHeadlessTask(BackgroundGeolocationHeadlessTask);
     * ```
     *
+    * ### Debugging
+    * 
+    * While implementing your headless-task It's crucial to observe your Android logs in a terminal via 
+    * 
+    * ```bash
+    * $ adb logcat *:S TSLocationManager:V ReactNativeJS:V
+    * 
+    * TSLocationManager: [c.t.r.HeadlessTask onHeadlessEvent] 💀  event: connectivitychange
+    * TSLocationManager: [c.t.r.HeadlessTask createReactContextAndScheduleTask] initialize ReactContext
+    * TSLocationManager: [c.t.r.HeadlessTask onHeadlessEvent] 💀  event: providerchange
+    * TSLocationManager: [c.t.r.HeadlessTask onHeadlessEvent] 💀  event: terminate
+    * ReactNativeJS: '[BGGeoHeadlessTask] ', 'connectivitychange', taskId: 1
+    * TSLocationManager: [c.t.r.HeadlessTask invokeStartTask] taskId: 1
+    * TSLocationManager: [c.t.r.HeadlessTask invokeStartTask] taskId: 2
+    * TSLocationManager: [c.t.r.HeadlessTask invokeStartTask] taskId: 3
+    * ReactNativeJS: '[BGGeoHeadlessTask] ', 'providerchange', taskId: 2
+    * ReactNativeJS: '[BGGeoHeadlessTask] ', 'terminate', taskId: 3
+    * TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task start] ⏳ startBackgroundTask: 1
+    * TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task start] ⏳ startBackgroundTask: 2
+    * ReactNativeJS: *** [doWork] START
+    * ReactNativeJS: *** [doWork] START
+    * TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task start] ⏳ startBackgroundTask: 3
+    * ReactNativeJS: *** [doWork] START
+    * .
+    * .
+    * .
+    * ReactNativeJS: *** [doWork] FINISH
+    * ReactNativeJS: *** [doWork] FINISH
+    * ReactNativeJS: *** [doWork] FINISH
+    * TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task stop] ⏳ stopBackgroundTask: 1
+    * TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task stop] ⏳ stopBackgroundTask: 2
+    * TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task stop] ⏳ stopBackgroundTask: 3
+    * TSLocationManager: [c.t.r.HeadlessTask$1 onHeadlessJsTaskFinish] taskId: 1
+    * TSLocationManager: [c.t.r.HeadlessTask$1 onHeadlessJsTaskFinish] taskId: 2
+    * TSLocationManager: [c.t.r.HeadlessTask$1 onHeadlessJsTaskFinish] taskId: 3
+    * ```
+    * 
     * ### ℹ️ See also:
     * - 📘 [Android Headless Mode](github:wiki/Android-Headless-Mode).
+    * - [[Config.enableHeadless]]
     *
     */
-    static registerHeadlessTask(callback:(event:Object)=> Promise<void>): void;
+    static registerHeadlessTask(callback:(event:HeadlessEvent)=> Promise<void>): void;
 
     /**
     *
@@ -1032,6 +1077,12 @@ declare module "react-native-background-geolocation" {
     */
     static finish(taskId: number, success?: Function, failure?: Function): Promise<number>;
 
+    /**
+     * @private
+     * __[Android-only]__ Signals completion of an Android headless-task (see [[Config.enableHeadless]])
+     */
+    static finishHeadlessTask(taskId: number, success?: Function, failure?: Function): Promise<number>; 
+
     /**
     * Retrieves the current [[Location]].
     *

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

@@ -2250,13 +2250,15 @@ declare module "react-native-background-geolocation" {
     * __`[Android only]`__ Enables "Headless" operation allowing you to respond to events after you app has been terminated with [[stopOnTerminate]] __`false`__.
     * @break
     *
-    * Defaults to __`false`__.  In this Android terminated state, where only the plugin's foreground-service remains running, you can respond to all the plugin's events with your own callback.
+    * Defaults to __`false`__.  In this Android terminated state, where only the plugin's foreground-service remains running, you can respond to all the plugin's events with your own callback.  For more information, see [[BackgroundGeolocation.registerHeadlessTask]].
     *
     * ### ℹ️ Note:
     * - Requires [[stopOnTerminate]] __`false`__.
     * - If you've configured [[stopOnTerminate]] __`false`__, [[BackgroundGeolocation]] will continue to record locations (and post them to your configured [[url]]) *regardless of* __`enabledHeadless: true`__.  You should enable this option *only if* you wish to perform some custom work during the headless state (for example, posting a local notification).
-    * - For more information, see the Wiki [Android Headless Mode](github:wiki/Android-Headless-Mode).
     *
+    * ### ℹ️ See also:
+    * - 📘 [Android Headless Mode](github:wiki/Android-Headless-Mode).
+    * - [[BackgroundGeolocation.registerHeadlessTask]]
     */
     enableHeadless?: boolean;
 

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

@@ -0,0 +1,49 @@
+/// <reference path="../types.d.ts" />
+
+
+declare module "react-native-background-geolocation" {
+  /**
+   * This is the event-object provided to Android headless-tasks registered via [[BackgroundGeolocation.registerHeadlessTask]].
+   * 
+   * @example
+   * ```typescript
+   * const BackgroundGeolocationHeadlessTask = async (event) => {
+   *   const params = event.params;
+   *   console.log("[BackgroundGeolocation HeadlessTask] -", event.name, params);
+   *
+   *   switch (event.name) {
+   *     case "terminate":
+   *       // Use await for async tasks
+   *       const location = await BackgroundGeolocation.getCurrentPosition({
+   *         samples: 1,
+   *         persist: false
+   *       });
+   *       console.log("[BackgroundGeolocation HeadlessTask] - getCurrentPosition:", location);
+   *       break;
+   *   }
+   *   // You must await all work you do in your task.  
+   *   // Headless-tasks are automatically terminated after executing the last line of your function.
+   *   await doWork();
+   * }
+   *
+   * BackgroundGeolocation.registerHeadlessTask(BackgroundGeolocationHeadlessTask);
+   * ```   
+   * 
+   * ### ℹ️ See also:
+   * - 📘 [Android Headless Mode](github:wiki/Android-Headless-Mode).
+   * - [[BackgroundGeolocation.registerHeadlessTask]]
+   * - [[Config.enableHeadless]]
+   * 
+   */
+  interface HeadlessEvent {    
+    /**
+     * BackgroundGeolocation event name (eg: `location`, `motionchange`, `terminate`, `http`, etc).
+     */
+    name: Event;
+    /**
+     * General event params according to the context of the event name.
+     */
+    params: Map;
+  }
+}
+

package/src/declarations/types.d.ts

@@ -157,6 +157,8 @@ declare module "react-native-background-geolocation" {
 
 	type PersistMode = -1 | 0 | 1 | 2;
 
+	type Map = {[key: string]: string|null|number|boolean|Map|string[]|number[]|number[][]|boolean[]|Map[]};
+	
 	type Extras = {[key: string]: string|null|number|boolean|Extras|string[]|number[]|number[][]|boolean[]|Extras[]};
 
 	/**
@@ -185,4 +187,5 @@ declare module "react-native-background-geolocation" {
 	 * - See [[onActivityChange]] and [[Location.activity]].
 	 */
 	type MotionActivityType = "unknown" | "still" | "walking" | "on_foot" | "running" | "on_bicycle" | "in_vehicle";
+
 }

package/src/index.js

@@ -131,13 +131,6 @@ export default class BackgroundGeolocation {
     return _deviceSettingsInstance;
   }
 
-  /**
-  * Register HeadlessTask
-  */
-  static registerHeadlessTask(task) {
-    AppRegistry.registerHeadlessTask(TAG, () => task);
-  }
-
   /**
   * Core Plugin Control Methods
   */
@@ -380,6 +373,42 @@ export default class BackgroundGeolocation {
   static finish(taskId, success, failure) {
     this.stopBackgroundTask.apply(this, arguments);
   }
+
+  /**
+  * Register HeadlessTask
+  * Have to wrap execution to finish our own headless-task because there's an unknown issue with TurboModules in new arch
+  * where RN's HeadlessJsTaskSupport is null.  That module can automatically finish RN headless-tasks.
+  */
+  static registerHeadlessTask(taskProvider) {
+    AppRegistry.registerHeadlessTask(TAG, () => {
+      // return to RN's AppRegistry a Function that returns a Promise.
+      return (event) => {
+        return new Promise((resolve, reject) => {          
+          const taskId = event._transistorHeadlessTaskId;
+          delete(event._transistorHeadlessTaskId);
+          taskProvider(event).then(() => {
+            BackgroundGeolocation.finishHeadlessTask(taskId);
+            resolve();
+          }).catch(reason => {
+            BackgroundGeolocation.finishHeadlessTask(taskId);
+            reject(reason);
+          });  
+        });
+      }
+    });
+  }
+
+  /**
+   * @private 
+   * Signal completion of a react-native headless-task.  This helps RN free-up resources allocated to the headless-task execution.
+   */
+  static finishHeadlessTask(taskId, success, failure) {
+    if (arguments.length == 1) {
+      return NativeModule.finishHeadlessTask(taskId);
+    } else {
+      NativeModule.finishHeadlessTask(taskId).then(success).catch(failure);
+    }
+  }
   /**
   * Toggle motion-state between stationary <-> moving
   */

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

@@ -1 +0,0 @@
-d70cac10dbc1b6a57e634cfa5be354ea

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

@@ -1 +0,0 @@
-5941e344c5f1805782c9ab2b3d8d73a4ab248e4c

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

@@ -1 +0,0 @@
-9ca7098540ac237b9b843c2a365fc9ae4ed1152b7613af9e8a86c1132efb60bc

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

@@ -1 +0,0 @@
-26b7c825a14409d3106c8327826a5e6b52965533686d33801e951f1ba30ca9bc0f4b451d08bdb02e80da102cb8ee96cef4174ffac825ca91f1cc6e044b11b3d3

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

@@ -1 +0,0 @@
-9478219e087d7490355120a6c9ca38ff

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

@@ -1 +0,0 @@
-02cea8fc14a328cdb0ea3ae1bf24531633f0894e

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

@@ -1 +0,0 @@
-84d33712aff68004a83fc684edfbc789e75c9f5dee6e518c5d65a26f2470400a

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

@@ -1 +0,0 @@
-8ac0ece17f7b793e497951b0f3559868b921abf71ec5104f6b03c8cafdd5c8be340a00b3a2c4e4aa7d0aeeeb4b52ffc7c31303a34a8ae9d3b6b18e66893b7ae3

package/android/libs/com/transistorsoft/tslocationmanager-v21/3.6.3/tslocationmanager-v21-3.6.3.aar.md5

@@ -1 +0,0 @@
-f3656398e2e5b566ca160e57dabad005

package/android/libs/com/transistorsoft/tslocationmanager-v21/3.6.3/tslocationmanager-v21-3.6.3.aar.sha1

@@ -1 +0,0 @@
-b1ff74273787634c743e423601d64f165fcf70ec

package/android/libs/com/transistorsoft/tslocationmanager-v21/3.6.3/tslocationmanager-v21-3.6.3.aar.sha256

@@ -1 +0,0 @@
-52d7b676b1632f68b847821a4c298b5e3f5b92c22f043e404fb6b028cb8caf59

package/android/libs/com/transistorsoft/tslocationmanager-v21/3.6.3/tslocationmanager-v21-3.6.3.aar.sha512

@@ -1 +0,0 @@
-ded64b948711582c957b144560e4c5e6d148cbba1b5fdcb5dace23c5c1f5f254190704f194185434dc5c0fd4a5274541e668615a6b5cfc66ed5d8312315acebf

package/android/libs/com/transistorsoft/tslocationmanager-v21/3.6.3/tslocationmanager-v21-3.6.3.pom.md5

@@ -1 +0,0 @@
-3dc20a87947e89a3b7c15a9a7b425e53

package/android/libs/com/transistorsoft/tslocationmanager-v21/3.6.3/tslocationmanager-v21-3.6.3.pom.sha1

@@ -1 +0,0 @@
-7ba36349cd28cfc7ce6a4850fae8428ca2dccae4

package/android/libs/com/transistorsoft/tslocationmanager-v21/3.6.3/tslocationmanager-v21-3.6.3.pom.sha256

@@ -1 +0,0 @@
-87332ef41c56163ba7b7a03be1f0bd3bfa7acdbcf79ec4abc4f0d445165f27ac

package/android/libs/com/transistorsoft/tslocationmanager-v21/3.6.3/tslocationmanager-v21-3.6.3.pom.sha512

@@ -1 +0,0 @@
-bbac4028863c96f7f6dc52e4fbfbe5212b01dee05e0aae5cff08442e907557d8f40c4d04c4c0858fe97f939ee978f38b646c58746addd66f93074ec25257390e