react-native-background-geolocation 4.17.6 → 4.18.0

package/android/build.gradle

@@ -14,7 +14,7 @@ def DEFAULT_TARGET_SDK_VERSION                      = 30
 def DEFAULT_APP_COMPAT_VERSION                      = "1.6.1"
 
 // Plugin dependencies
-def DEFAULT_PLAY_SERVICES_LOCATION_VERSION   	    = "20.0.0"
+def DEFAULT_PLAY_SERVICES_LOCATION_VERSION          = "20.0.0"
 def DEFAULT_HMS_LOCATION_VERSION                    = "6.9.0.300"
 def DEFAULT_OK_HTTP_VERSION                         = "3.12.13"
 def DEFAULT_ANDROID_PERMISSIONS_VERSION             = "2.1.6"
@@ -42,9 +42,14 @@ android {
     defaultConfig {
         minSdkVersion safeExtGet('minSdkVersion', 16)
         targetSdkVersion safeExtGet('targetSdkVersion', DEFAULT_TARGET_SDK_VERSION)
+        consumerProguardFiles 'proguard-rules.pro'
         versionCode 1
         versionName "1.0"
     }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
 }
 
 repositories{
@@ -98,4 +103,5 @@ dependencies {
     def workVersion = safeExtGet('workVersion', DEFAULT_WORK_VERSION)
     def concurrentFuturesVersion = safeExtGet('concurrentFuturesVersion', DEFAULT_CONCURRENT_FUTURES_VERSION)
     implementation "androidx.work:work-runtime:$workVersion"
-    implementation "androidx.concurrent:concurrent-futures:$concurrentFuturesVersion"}
+    implementation "androidx.concurrent:concurrent-futures:$concurrentFuturesVersion"
+}

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

@@ -0,0 +1 @@
+bd49466dd13ba67b82ab2752a1d71318

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

@@ -0,0 +1 @@
+d8523b683cf9d70e53317362389b81bebe6f1d9f

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

@@ -0,0 +1 @@
+328f8a4a248f6d9d5ae95fad7d996eca1470e7e0d56bad5cba04d0fabf8c6632

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

@@ -0,0 +1 @@
+18b6dea8cdb386ac662f7bbeff3a0061fa4855ae63e717db14a6009ed3027090407cc6c0ed97b566a260b57e1f8facbcdeb8b4424c47a27c237d6985878d75dd

package/android/libs/com/transistorsoft/tslocationmanager/{3.6.3/tslocationmanager-3.6.3.pom → 3.6.4/tslocationmanager-3.6.4.pom}

@@ -4,6 +4,6 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.transistorsoft</groupId>
   <artifactId>tslocationmanager</artifactId>
-  <version>3.6.3</version>
+  <version>3.6.4</version>
   <packaging>aar</packaging>
 </project>

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

@@ -0,0 +1 @@
+9a0e698b655e8d6b1de240345eb0bb1e

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

@@ -0,0 +1 @@
+d4c0e936144e9629f09726d231ffb65382d117f8

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

@@ -0,0 +1 @@
+29f18c0813aab1f46f264aae982c92a937c752f9d347371d0504db62885c615a

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

@@ -0,0 +1 @@
+1710cfc5d6b4638db7eca4ba894a346d024f6041c79cbcdd165c3da68939eac4e1e1cb5c5b4ea7d933d6576fab4db08e79301efb42073186349a90bf00b283ed

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

@@ -3,14 +3,15 @@
   <groupId>com.transistorsoft</groupId>
   <artifactId>tslocationmanager</artifactId>
   <versioning>
-    <latest>3.6.3</latest>
-    <release>3.6.3</release>
+    <latest>3.6.4</latest>
+    <release>3.6.4</release>
     <versions>
       <version>3.6.0</version>
       <version>3.6.1</version>
       <version>3.6.2</version>
       <version>3.6.3</version>
+      <version>3.6.4</version>
     </versions>
-    <lastUpdated>20241112183131</lastUpdated>
+    <lastUpdated>20241203042324</lastUpdated>
   </versioning>
 </metadata>

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

@@ -0,0 +1 @@
+74bb14fd07fb16ee170c5ad3d07f817d

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

@@ -0,0 +1 @@
+6c1c89301376ea993978bc06f919edaaa29fb3fb

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

@@ -0,0 +1 @@
+961d0d90ccb09bf5731a3a297c4e7fbacb9f24d20bdaa9dabc79b729d5a109eb

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

@@ -0,0 +1 @@
+01e530f5a7f3db6a9d9d436f345093e5538421d16b663daf9682317829d67bb9a80d4a58de10e485235744793ae039267335c0dc680c54bdc814a7bc31d4f01f

package/android/libs/com/transistorsoft/tslocationmanager-v21/{3.6.3/tslocationmanager-v21-3.6.3.pom → 3.6.4/tslocationmanager-v21-3.6.4.pom}

@@ -4,6 +4,6 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.transistorsoft</groupId>
   <artifactId>tslocationmanager-v21</artifactId>
-  <version>3.6.3</version>
+  <version>3.6.4</version>
   <packaging>aar</packaging>
 </project>

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

@@ -0,0 +1 @@
+95c1c712873b163f6641ce4b071e7af7

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

@@ -0,0 +1 @@
+d003fdeb61221dbe7eccd3eae06a88464f4837ca

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

@@ -0,0 +1 @@
+7e76a8d9ad740486eed08130a444e02a80959b615d0ae87899af8e85a3e0aa8b

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

@@ -0,0 +1 @@
+56a88d4d6a4ca5061f3061bd5bd950a0c6afa271c6bdc5cfa960d77c39092d902736ffc32c53c99c2e55c02ea85f27aeec646e1cc3baceb48160a54dd86fe9b2

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

@@ -3,14 +3,15 @@
   <groupId>com.transistorsoft</groupId>
   <artifactId>tslocationmanager-v21</artifactId>
   <versioning>
-    <latest>3.6.3</latest>
-    <release>3.6.3</release>
+    <latest>3.6.4</latest>
+    <release>3.6.4</release>
     <versions>
       <version>3.6.0</version>
       <version>3.6.1</version>
       <version>3.6.2</version>
       <version>3.6.3</version>
+      <version>3.6.4</version>
     </versions>
-    <lastUpdated>20241112183131</lastUpdated>
+    <lastUpdated>20241203042324</lastUpdated>
   </versioning>
 </metadata>

package/android/proguard-rules.pro

@@ -1,4 +1,20 @@
 -keepnames class com.facebook.react.ReactActivity
+
+# for react-native Headless on new architecture
+-keep class com.facebook.react.defaults.DefaultNewArchitectureEntryPoint {
+  public <methods>;
+}
+-keep class com.facebook.react.ReactApplication {
+  public <methods>;
+}
+-keep class com.facebook.react.ReactHost {
+  public <methods>;
+}
+-keep class * extends com.facebook.react.ReactHost {
+  public <methods>;
+}
+-keep class com.facebook.react.fabric.** { *; }
+
 -keepnames class com.transistorsoft.rnbackgroundgeolocation.RNBackgroundGeolocation
 
 -keep class com.transistorsoft** { *; }

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

@@ -4,19 +4,26 @@ import android.content.Context;
 import android.os.Handler;
 import android.os.Looper;
 
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import com.facebook.infer.annotation.Assertions;
 import com.facebook.react.ReactApplication;
+import com.facebook.react.ReactInstanceEventListener;
 import com.facebook.react.ReactInstanceManager;
+import com.facebook.react.ReactNativeHost;
 import com.facebook.react.bridge.ReactContext;
 import com.facebook.react.bridge.UiThreadUtil;
 import com.facebook.react.bridge.WritableMap;
 import com.facebook.react.bridge.WritableNativeMap;
 import com.facebook.react.jstasks.HeadlessJsTaskConfig;
 import com.facebook.react.jstasks.HeadlessJsTaskContext;
-import com.facebook.react.jstasks.HeadlessJsTaskEventListener;
 
 import org.greenrobot.eventbus.Subscribe;
 
+import com.facebook.react.jstasks.HeadlessJsTaskEventListener;
 import com.transistorsoft.locationmanager.adapter.BackgroundGeolocation;
+import com.transistorsoft.locationmanager.event.FinishHeadlessTaskEvent;
 import com.transistorsoft.locationmanager.event.HeadlessEvent;
 import com.transistorsoft.locationmanager.logger.TSLog;
 
@@ -24,20 +31,70 @@ import org.greenrobot.eventbus.ThreadMode;
 import org.json.JSONException;
 import org.json.JSONObject;
 
+import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.atomic.AtomicInteger;
 
 /**
+ * The BackgroundGeolocation SDK creates a single instance of this class (via reflection upon Config.headlessJobService)
+ * The SDK delivers events to this instance by dropping them onto EventBus (see @Subscribe).  Because this instance is subscribed
+ * into EventBus, it's protected from GC.
+ *
+ * Because there's only one instance of this class, we have to be mindful that we can possibly receive events rapidly,
+ * so we store them in a Queue (#mTaskQueue).
+ *
+ * We also have to be mindful that it's a heavy operation to do the initial launch the ReactNative Host, so several events
+ * might build up in the queue before the Host is finally launched, when we drain the queue (see #drainTaskQueue).
+ *
+ * For finally sending events to the client, we wrap the RN HeadlessJsTaskConfig with our own TaskConfig class.  This class
+ * adds our own auto-incremented "taskId" field to maintain a mapping between our taskId and RN's.  See #invokeStartTask.
+ * This class appends our custom taskId into the the event params sent to Javascript, for the following purpose:
+ *
+ * ```javascript
+ * const BackgroundGeolocationHeadlessTask = async (event) => {
+ *   console.log('[HeadlessTask] taskId: ', event.taskId);  // <-- here's our custom taskId.
+ *
+ *   await doWork();  // <-- perform some arbitrarily long process (eg: http request).
+ *
+ *   BackgroundGeolocation.finishHeadlessTask(event.taskId);  // <-- $$$ Here's the money $$$
+ * }
+ * ```
+ *
+ * See "Here's the $money" above: We want to signal back to this native HeadlessTask instance , that our JS task is now complete.
+ * This is a pretty easy task to do via EventBus -- Just create a new instance of FinishHeadlessTaskEvent(params.taskId);
+ *
+ * The code then looks up a TaskConfig from mEventQueue using the given event.taskId.
+ *
+ * All this extra fussing with taking care to finish our RN HeadlessTasks seems to be more important with RN's "new architecture", where before,
+ * RN seemed to automatically complete its tasks seemingly when the Javascript function stopped executing.  This is why it was always so
+ * important to await one's Promises and do all the work before the the last line of the function executed.
+ *
+ * Now, the Javascript must explicitly call back to the native side to say "I'M DONE" -- BackgroundGeolocation.finishHeadlessTask(taskId)
+ *
  * Created by chris on 2018-01-23.
  */
 
 public class HeadlessTask {
     private static String HEADLESS_TASK_NAME = "BackgroundGeolocation";
-    // Hard-coded time-limit for headless-tasks is 30000 @todo configurable?
-    private static int TASK_TIMEOUT = 30000;
+    // Hard-coded time-limit for headless-tasks is 60000 @todo configurable?
+    private static final int TASK_TIMEOUT = 60000;
+    private static final AtomicInteger sLastTaskId = new AtomicInteger(0);
+
+    synchronized static int getNextTaskId() {
+        return sLastTaskId.incrementAndGet();
+    }
 
-    private final List<Integer> mTasks = new ArrayList<>();
+    private final List<TaskConfig> mTaskQueue = new ArrayList<>();
+    private final AtomicBoolean mIsReactContextInitialized = new AtomicBoolean(false);
+    private final AtomicBoolean mIsInitializingReactContext = new AtomicBoolean(false);
+    private final AtomicBoolean mIsHeadlessJsTaskListenerRegistered = new AtomicBoolean(false);
 
+    /**
+     * EventBus receiver for a HeadlessTask HeadlessEvent
+     * @param event
+     */
     @Subscribe(threadMode = ThreadMode.MAIN)
     public void onHeadlessEvent(HeadlessEvent event) {
         String name = event.getName();
@@ -95,19 +152,55 @@ public class HeadlessTask {
             } catch (JSONException e) {
                 clientEvent.putNull("params");
                 clientEvent.putString("error", e.getMessage());
-                TSLog.logger.error(TSLog.error(e.getMessage()));
+                TSLog.logger.error(TSLog.error(e.getMessage()), e);
                 e.printStackTrace();
             }
         }
 
-        HeadlessJsTaskConfig config = new HeadlessJsTaskConfig(HEADLESS_TASK_NAME, clientEvent, TASK_TIMEOUT);
         try {
-            startTask(event.getContext(), config);
+            startTask(event.getContext(), new TaskConfig(clientEvent));
         } catch (AssertionError e) {
             TSLog.logger.warn(TSLog.warn("Failed invoke HeadlessTask " + name + ".  Task ignored." + e.getMessage()));
         }
     }
 
+    /**
+     * EventBus Receiver.  Called when developer runs BackgroundGeolocation.finishHeadlessTask(taskId) from within their registered HeadlessTask.
+     * Calls RN's HeadlessJsTaskContext.finishTask(taskId);
+     * @param event
+     */
+    @Subscribe(threadMode = ThreadMode.MAIN)
+    public void onFinishHeadlessTask(FinishHeadlessTaskEvent event) {
+        if (!mIsReactContextInitialized.get()) {
+            TSLog.logger.warn(TSLog.warn("BackgroundGeolocation.finishHeadlessTask:" + event.getTaskId() + " found no ReactContext"));
+            return;
+        }
+        ReactContext reactContext = getReactContext(event.getContext());
+        if (reactContext != null) {
+            int taskId = event.getTaskId();
+
+            synchronized (mTaskQueue) {
+                // Locate the TaskConfig instance by our local taskId.
+                TaskConfig taskConfig = null;
+                for (TaskConfig config : mTaskQueue) {
+                    if (config.getTaskId() == taskId) {
+                        taskConfig = config;
+                        break;
+                    }
+                }
+                if (taskConfig != null) {
+                    HeadlessJsTaskContext headlessJsTaskContext = HeadlessJsTaskContext.getInstance(reactContext);
+                    // Tell RN we're done using the mapped getReactTaskId().
+                    headlessJsTaskContext.finishTask(taskConfig.getReactTaskId());
+                } else {
+                    TSLog.logger.warn(TSLog.warn("Failed to find task: " + taskId));
+                }
+            }
+        } else {
+            TSLog.logger.warn(TSLog.warn("Failed to finishHeadlessTask: " + event.getTaskId() + " -- HeadlessTask onFinishHeadlessTask failed to find a ReactContext.  This is unexpected"));
+        }
+    }
+
     /**
      * Start a task. This method handles starting a new React instance if required.
      *
@@ -115,61 +208,202 @@ public class HeadlessTask {
      *
      * @param taskConfig describes what task to start and the parameters to pass to it
      */
-    private void startTask(Context context, final HeadlessJsTaskConfig taskConfig) throws AssertionError {
-        ReactApplication reactApplication = ((ReactApplication) context);
-
+    private void startTask(Context context, final TaskConfig taskConfig) throws AssertionError {
         UiThreadUtil.assertOnUiThread();
-        final ReactInstanceManager reactInstanceManager = reactApplication.getReactNativeHost().getReactInstanceManager();
-
-        ReactContext reactContext = reactInstanceManager.getCurrentReactContext();
-        if (reactContext == null) {
-            reactInstanceManager.addReactInstanceEventListener(new ReactInstanceManager.ReactInstanceEventListener() {
-                @Override public void onReactContextInitialized(final ReactContext reactContext) {
-                    // Hack to fix unknown problem executing asynchronous BackgroundTask when ReactContext is created *first time*.  Fixed by adding short delay before #invokeStartTask
-                    new Handler(Looper.getMainLooper()).postDelayed(new Runnable() {
-                        @Override
-                        public void run() {
-                            invoke(reactContext, taskConfig);
-                        }
-                    }, 500);
-                    reactInstanceManager.removeReactInstanceEventListener(this);
-                }
-            });
-            if (!reactInstanceManager.hasStartedCreatingInitialContext()) {
-                reactInstanceManager.createReactContextInBackground();
-            }
+
+        // push this HeadlessEvent onto the taskQueue, to be drained once the React context is finished initializing,
+        // or executed immediately if Context exists currently.
+        synchronized (mTaskQueue) {
+            mTaskQueue.add(taskConfig);
+        }
+
+        if (!mIsReactContextInitialized.get()) {
+            createReactContextAndScheduleTask(context);
         } else {
-            invoke(reactContext, taskConfig);
+            invokeStartTask(getReactContext(context), taskConfig);
         }
     }
 
-    private void invoke(ReactContext reactContext, final HeadlessJsTaskConfig taskConfig) {
+    synchronized private void invokeStartTask(ReactContext reactContext, final TaskConfig taskConfig) {
         final HeadlessJsTaskContext headlessJsTaskContext = HeadlessJsTaskContext.getInstance(reactContext);
-
-        synchronized(mTasks) {
-            if (mTasks.isEmpty()) {
+        try {
+            if (mIsHeadlessJsTaskListenerRegistered.compareAndSet(false, true)) {
+                // Register the RN HeadlessJSTaskEventListener just once.
+                // This inline-listener is handy here as a closure around the HeadlessJsTaskContext.
+                // Otherwise, we'd have to store this Context to an instance var.
+                // The only purpose of this listener is to clear events from the queue.  The RN task is assumed to have had its .stopTask(taskId) method called, which is why this event has fired.
+                // WARNING:  this listener seems to receive events from ANY OTHER plugin's Headless events.
+                // TODO we might use a LifeCycle event-listener here to remove the listener when the app is launched to foreground.
                 headlessJsTaskContext.addTaskEventListener(new HeadlessJsTaskEventListener() {
-                    @Override public void onHeadlessJsTaskStart(int taskId) {
-                        TSLog.logger.debug("taskId: " + taskId);
-                    }
+                    @Override public void onHeadlessJsTaskStart(int taskId) {}
                     @Override public void onHeadlessJsTaskFinish(int taskId) {
-                        TSLog.logger.debug("taskId: " + taskId);
-                        synchronized (mTasks) {
-                            if (!mTasks.isEmpty()) {
-                                mTasks.remove(0);
+                        synchronized (mTaskQueue) {
+                            if (mTaskQueue.isEmpty()) {
+                                // Nothing in queue?  This events cannot be for us.
+                                return;
+                            }
+                            // Query our queue for this event...
+                            TaskConfig taskConfig = null;
+                            for (TaskConfig config : mTaskQueue) {
+                                if (config.getReactTaskId() == taskId) {
+                                    taskConfig = config;
+                                    break;
+                                }
                             }
-                            if (mTasks.isEmpty()) {
-                                headlessJsTaskContext.removeTaskEventListener(this);
+                            if (taskConfig != null) {
+                                // Clear it from the Queue.
+                                TSLog.logger.debug("taskId: " + taskConfig.getTaskId());
+                                mTaskQueue.remove(taskConfig);
+                            } else {
+                                TSLog.logger.warn(TSLog.warn("Failed to find taskId: " + taskId));
                             }
                         }
                     }
                 });
             }
+            // Finally:  the actual launch of the RN headless-task!
+            int taskId = headlessJsTaskContext.startTask(taskConfig.getTaskConfig());
+            // Provide the RN taskId to our private TaskConfig instance, mapping the RN taskId to our TaskConfig's internal taskId.
+            taskConfig.setReactTaskId(taskId);
+            TSLog.logger.debug("taskId: " + taskId);
+        } catch (IllegalStateException e) {
+            TSLog.logger.error(TSLog.error(e.getMessage()), e);
+        }
+    }
+
+    protected ReactNativeHost getReactNativeHost(Context context) {
+        return ((ReactApplication) context.getApplicationContext()).getReactNativeHost();
+    }
+
+    /**
+     * Get the {ReactHost} used by this app. ure and returns null if not.
+     */
+    private @Nullable Object getReactHost(Context context) {
+        context = context.getApplicationContext();
+        try {
+            Method getReactHost = context.getClass().getMethod("getReactHost");
+            return getReactHost.invoke(context);
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    private ReactContext getReactContext(Context context) {
+        if (isBridglessArchitectureEnabled()) {
+            Object reactHost = getReactHost(context);
+            Assertions.assertNotNull(reactHost, "getReactHost() is null in New Architecture");
             try {
-                mTasks.add(headlessJsTaskContext.startTask(taskConfig));
-            } catch (IllegalStateException e) {
-                TSLog.logger.error(TSLog.error(e.getMessage()));
+                Method getCurrentReactContext = reactHost.getClass().getMethod("getCurrentReactContext");
+                return (ReactContext) getCurrentReactContext.invoke(reactHost);
+            } catch (Exception e) {
+                TSLog.logger.error(TSLog.error("[HeadlessTask] Reflection error getCurrentReactContext: " + e.getMessage()), e);
             }
         }
+        final ReactInstanceManager reactInstanceManager = getReactNativeHost(context).getReactInstanceManager();
+        return reactInstanceManager.getCurrentReactContext();
+    }
+
+    private void createReactContextAndScheduleTask(Context context) {
+
+        // ReactContext could have already been initialized by another plugin (eg: background-fetch).
+        // If we get a non-null ReactContext here, we're good to go!
+        ReactContext reactContext = getReactContext(context);
+        if (reactContext != null && !mIsInitializingReactContext.get()) {
+            mIsReactContextInitialized.set(true);
+            drainTaskQueue(reactContext);
+            return;
+        }
+        if (mIsInitializingReactContext.compareAndSet(false, true)) {
+            TSLog.logger.debug("initialize ReactContext");
+            final Object reactHost = getReactHost(context);
+            if (isBridglessArchitectureEnabled()) { // NEW arch
+                ReactInstanceEventListener callback = new ReactInstanceEventListener() {
+                    @Override
+                    public void onReactContextInitialized(@NonNull ReactContext reactContext) {
+                        mIsReactContextInitialized.set(true);
+                        drainTaskQueue(reactContext);
+                        try {
+                            Method removeReactInstanceEventListener = reactHost.getClass().getMethod("removeReactInstanceEventListener", ReactInstanceEventListener.class);
+                            removeReactInstanceEventListener.invoke(reactHost, this);
+                        } catch (Exception e) {
+                            TSLog.logger.error(TSLog.error("HeadlessTask reflection error A: " + e), e);
+                        }
+                    }
+                };
+                try {
+                    Method addReactInstanceEventListener = reactHost.getClass().getMethod("addReactInstanceEventListener", ReactInstanceEventListener.class);
+                    addReactInstanceEventListener.invoke(reactHost, callback);
+                    Method startReactHost = reactHost.getClass().getMethod("start");
+                    startReactHost.invoke(reactHost);
+                } catch (Exception e) {
+                    TSLog.logger.error(TSLog.error("HeadlessTask reflection error ReactHost start: " + e.getMessage()), e);
+                }
+            } else { // OLD arch
+                final ReactInstanceManager reactInstanceManager = getReactNativeHost(context).getReactInstanceManager();
+                reactInstanceManager.addReactInstanceEventListener(new ReactInstanceEventListener() {
+                    @Override
+                    public void onReactContextInitialized(@NonNull ReactContext reactContext) {
+                        mIsReactContextInitialized.set(true);
+                        drainTaskQueue(reactContext);
+                        reactInstanceManager.removeReactInstanceEventListener(this);
+                    }
+                });
+                reactInstanceManager.createReactContextInBackground();
+            }
+        }
+    }
+
+    /**
+     * Invokes HeadlessEvents queued while waiting for the ReactContext to initialize.
+     * @param reactContext
+     */
+    private void drainTaskQueue(final ReactContext reactContext) {
+        new Handler(Looper.getMainLooper()).postDelayed(() -> {
+            synchronized (mTaskQueue) {
+                for (TaskConfig taskConfig : mTaskQueue) {
+                    invokeStartTask(reactContext, taskConfig);
+                }
+            }
+        }, 500);
+    }
+
+    /**
+     * Return true if this app is running with RN's bridgeless architecture.
+     * Cheers to @mikehardy for this idea.
+     * @return
+     */
+    private boolean isBridglessArchitectureEnabled() {
+        try {
+            Class<?> entryPoint = Class.forName("com.facebook.react.defaults.DefaultNewArchitectureEntryPoint");
+            Method bridgelessEnabled = entryPoint.getMethod("getBridgelessEnabled");
+            Object result = bridgelessEnabled.invoke(null);
+            return (result == Boolean.TRUE);
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    /**
+     * Wrapper for a client event.  Inserts our custom taskId into the RN ClientEvent params.
+     */
+    private static class TaskConfig {
+        private final int mTaskId;
+        private int mReactTaskId;
+        private final WritableMap mParams;
+        public TaskConfig(WritableMap params) {
+            mTaskId = getNextTaskId();
+            // Insert our custom taskId for users to call BackgroundGeolocation.finishHeadlessTask(taskId) with.
+            params.putInt("taskId", mTaskId);
+            mParams = params;
+        }
+        public void setReactTaskId(int taskId) {
+            mReactTaskId = taskId;
+        }
+        public int getTaskId() { return mTaskId; }
+        public int getReactTaskId() { return mReactTaskId; }
+
+        public HeadlessJsTaskConfig getTaskConfig() {
+            return new HeadlessJsTaskConfig(HEADLESS_TASK_NAME, mParams, TASK_TIMEOUT);
+        }
     }
 }

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

@@ -23,10 +23,13 @@ import com.facebook.react.bridge.WritableNativeArray;
 import com.facebook.react.bridge.WritableNativeMap;
 import com.facebook.react.modules.core.RCTNativeAppEventEmitter;
 
+import org.greenrobot.eventbus.EventBus;
 import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 
+import com.transistorsoft.locationmanager.event.FinishHeadlessTaskEvent;
+import com.transistorsoft.locationmanager.event.HeadlessEvent;
 import com.transistorsoft.xms.g.common.ExtensionApiAvailability;
 
 import com.transistorsoft.locationmanager.adapter.BackgroundGeolocation;
@@ -822,6 +825,22 @@ public class RNBackgroundGeolocationModule extends ReactContextBaseJavaModule im
         success.invoke(taskId);
     }
 
+    @ReactMethod
+    public void finishHeadlessTask(int taskId, Callback success, Callback failure) {
+        EventBus eventBus = EventBus.getDefault();
+        if (!eventBus.hasSubscriberForEvent(HeadlessEvent.class)) {
+            // This shouldn't happen.  In order for this method to even be called, it MUST have been executed from within the consumer's
+            // registered HeadlessTask.  In order for that headless-task to have even be called, HeadlessEvent MUST have been registered with EventBus.
+            String message = "finishHeadlessTask failed to find an EventBus subscriber for HeadlessEvent";
+            TSLog.error(TSLog.warn(message));
+            failure.invoke(message);
+            return;
+        }
+        FinishHeadlessTaskEvent event = new FinishHeadlessTaskEvent(getReactApplicationContext(), taskId);
+        eventBus.post(event);
+        success.invoke();
+    }
+
     @ReactMethod
     public void getTransistorToken(String orgname, String username, String url, final Callback success, final Callback failure) {
 

package/expo/plugin/build/androidPlugin.js

@@ -83,14 +83,6 @@ const applyAppGradle = (buildGradle) => {
         offset: 1,
         comment: "//",
     }).contents;
-    buildGradle = (0, generateCode_1.mergeContents)({
-        tag: `${MODULE_NAME}-proguard`,
-        src: buildGradle,
-        newSrc: `\t    proguardFiles "\${background_geolocation.projectDir}/proguard-rules.pro"`,
-        anchor: /\"proguard-rules.pro\"/,
-        offset: 1,
-        comment: "//",
-    }).contents;
     return buildGradle;
 };
 /**

package/expo/plugin/build/androidPlugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"androidPlugin.js","sourceRoot":"","sources":["../src/androidPlugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"androidPlugin.js","sourceRoot":"","sources":["../src/androidPlugin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-background-geolocation",
-  "version": "4.17.6",
+  "version": "4.18.0",
   "description": "The most sophisticated cross-platform background location-tracking & geofencing module with battery-conscious motion-detection intelligence",
   "scripts": {
     "build": "yarn run build:expo",
@@ -30,7 +30,7 @@
   },
   "homepage": "https://www.transistorsoft.com/shop/products/react-native-background-geolocation",
   "dependencies": {
-    "react-native-background-fetch": "~4.2.5"
+    "react-native-background-fetch": "~4.2.6"
   },
   "devDependencies": {
     "@expo/config-plugins": "^4.1.0",

package/src/NativeModule.js

@@ -309,7 +309,6 @@ export default class NativeModule {
     });
   }
 
-  // TODO Rename native methods #finish -> #stopBackgroundTask
   static stopBackgroundTask(taskId) {
     return new Promise((resolve, reject) => {
       if (!taskId) {
@@ -322,6 +321,18 @@ export default class NativeModule {
     });
   }
 
+  static finishHeadlessTask(taskId) {
+    return new Promise((resolve, reject) => {
+      if (!taskId) {
+        reject('INVALID_TASK_ID: ' + taskId);
+        return;
+      }
+      let success = (taskId) => { resolve(taskId) }
+      let failure = (error) =>  { reject(error) }
+      RNBackgroundGeolocation.finishHeadlessTask(taskId, success, failure);
+    });
+  }
+  
   /**
   * Geolocation Methods
   */

package/src/declarations/BackgroundGeolocation.d.ts

@@ -674,30 +674,74 @@ 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`.
     *
     * @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 "heartbeat":
+    *       // Use await for async tasks
+    *       const location = await BackgroundGeolocation.getCurrentPosition({
+    *         samples: 1,
+    *         persist: false
+    *       });
+    *       console.log("[BackgroundGeolocation HeadlessTask] - getCurrentPosition:", location);
+    *       break;
+    *   }
+    *   // Signal completion of our RN HeadlessTask.
+    *   BackgroundGeolocation.finishHeadlessTask(taskId);
     * }
     *
     * 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).
+    * - [[BackgroundGeolocation.finishHeadlessTask]]
+    * - [[Config.enableHeadless]]
     *
     */
     static registerHeadlessTask(callback:(event:Object)=> Promise<void>): void;
@@ -1032,6 +1076,55 @@ declare module "react-native-background-geolocation" {
     */
     static finish(taskId: number, success?: Function, failure?: Function): Promise<number>;
 
+    /**
+     * __[Android-only]__ Signals completion of an Android headless-task (see [[Config.enableHeadless]])
+     * 
+     * @example
+     * ```typescript
+     * const bgGeoHeadlessTask = async (event) => {
+     *   // the name of this event (eg: "location", "motionchange", "http")
+     *   const eventName  = event.name; 
+     *   // our event-data from the BG Geo SDK.
+     *   const params     = event.params;
+     *   // IMPORTANT:  This task's ID
+     *   const taskId     = event.taskId;
+     *   
+     *   console.log('[BGGeoHeadlessTask] ', eventName, taskId, params);
+     *   
+     *   // Fake a long-running task (eg: HTTP request).
+     *   await doWork();
+     *   
+     *   // Signal completion of our RN HeadlessTask.
+     *   BackgroundGeolocation.finishHeadlessTask(taskId);
+     * }
+     *
+     * // Example "work" function where you might perform a long-running task (such as an HTTP request).
+     * // Uses a simple JS setTimeout timer to simulate work.
+     * const doWork = async () => {
+     *   return new Promise(async (resolve, reject) => {
+     *     // Start a BGGeo backgroundTask for performing long-running task (such as HTTP request)     
+     *     const bgTaskId = await BackgroundGeolocation.startBackgroundTask(); 
+     *     console.log('*** [doWork] START');
+     *     setTimeout(() => {
+     *       console.log('*** [doWork] FINISH');
+     *       // Signal completion of our bg-task.
+     *       BackgroundGeolocation.stopBackgroundTask(bgTaskId);
+     *       resolve();
+     *     }, 5000);
+     *   });
+     * }
+     * 
+     * // Register the HeadlessTask with RN.
+     * BackgroundGeolocation.registerHeadlessTask(bgGeoHeadlessTask);
+     * 
+     * ```
+     * ### ℹ️ See also:
+     * - 📘 [Android Headless Mode](github:wiki/Android-Headless-Mode).
+     * - [[BackgroundGeolocation.registerHeadlessTask]]
+     * - [[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,16 @@ 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]]
+    * - [[BackgroundGeolocation.finishHeadlessTask]]
     */
     enableHeadless?: boolean;
 

package/src/index.js

@@ -380,6 +380,16 @@ export default class BackgroundGeolocation {
   static finish(taskId, success, failure) {
     this.stopBackgroundTask.apply(this, arguments);
   }
+  /**
+   * 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