@josuelmm/cordova-background-geolocation 2.3.5 → 3.0.0

package/.npmignore

@@ -7,6 +7,15 @@
 !/plugin.xml
 !/package.json
 !/www
+!/angular
+# Only ship ng-packagr output for ./angular, not old tsc .js/.d.ts
+/angular/*.js
+/angular/*.d.ts
+/angular/public-api.ts
+/angular/ng-package.json
+/angular/tsconfig.lib.json
+/angular/package.json
+!/angular/dist
 !/android
 /android/*
 !/android/dependencies.gradle

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [3.0.0](https://github.com/josuelmm/cordova-background-geolocation/tree/3.0.0) (2026-02-20)
+
+### Added
+- Android: Wake lock (PARTIAL_WAKE_LOCK) during tracking
+- Android: Optional location watchdog (`enableWatchdog`) to restart provider if no update in ~60s
+- `openSettings()` — convenience alias for `showAppSettings()`
+- `getPluginVersion()` — returns plugin version from native
+- iOS: `simulated` field in location payload (iOS 15+, from `sourceInformation.isSimulatedBySoftware`)
+- Config option `enableWatchdog` (Android, default `false`)
+- Angular: full documentation in docs/angular.md
+
+### Changed
+- Version bump to 3.0.0
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/2.3.4...3.0.0)
+
 ## [2.3.4](https://github.com/josuelmm/cordova-background-geolocation/tree/2.3.4) (2026-02-20)
 
 [Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/v2.0.4...2.3.4)

package/README.md

@@ -1,4 +1,6 @@
-# Cordova Background Geolocation Plugin
+# Cordova Background Geolocation
+# Capacitor Background Geolocation
+# Background Geolocation
 
 [![npm](https://img.shields.io/npm/v/@josuelmm/cordova-background-geolocation?style=flat-square)](https://www.npmjs.com/package/@josuelmm/cordova-background-geolocation)
 ![npm downloads](https://img.shields.io/npm/dm/@josuelmm/cordova-background-geolocation?style=flat-square)
@@ -7,98 +9,262 @@
 [![GitHub stars](https://img.shields.io/github/stars/josuelmm/cordova-background-geolocation?style=flat-square)](https://github.com/josuelmm/cordova-background-geolocation/stargazers)
 ![GitHub last commit](https://img.shields.io/github/last-commit/josuelmm/cordova-background-geolocation?style=flat-square)
 
-## Introduction
+## What it does
 
-*Cross-platform geolocation for Cordova and Capacitor with battery-saving "circular region monitoring" and "stop detection"*
+This plugin provides **background and foreground geolocation** for **Cordova**, **Capacitor**, and **Ionic** apps. It is tested and works with current versions of Capacitor and Ionic. It is more battery- and data-efficient than the HTML5 Geolocation API and is designed to keep tracking location even when the app is in the background or the screen is off.
 
-This plugin can be used for geolocation when the app is running in the foreground or background. It is more battery and data efficient than html5 geolocation. It can be used side by side with other geolocation providers (eg. html5 navigator.geolocation).
+**Features:**
 
-This project is based on [@mauron85/cordova-plugin-background-geolocation](https://github.com/mauron85/cordova-plugin-background-geolocation), which in turn was based on the original [cordova-background-geolocation plugin](https://github.com/christocracy/cordova-plugin-background-geolocation) by [christocracy](https://github.com/christocracy). This independent fork is maintained at [josuelmm/cordova-background-geolocation](https://github.com/josuelmm/cordova-background-geolocation). If you have any fixes, features or updates that you would like included, please do raise a PR or issue on the GitHub repository.
+- **Circular region monitoring** and **stop detection** to reduce battery use
+- **Activity-based provider** (e.g. walking, driving, still) for smarter updates
+- **Configurable distance/interval** filtering and optional **HTTP posting** of locations to your server
+- **Foreground service** (Android) with a persistent notification so the OS does not kill the tracker
+- Works alongside other geolocation sources (e.g. `navigator.geolocation`)
 
-**ATENTION:** This project changes the package name from it's parents. The words are the same but in a different order, which is easy to miss and can cause some confusion
+**Self-contained:** This plugin works on its own. You install it, call `BackgroundGeolocation.configure()`, `start()`, etc. directly. TypeScript definitions (`.d.ts`) are included. You do **not** need any wrapper or extra package for Capacitor or Cordova.
 
-We are also looking to maintainers to help with this, so that the project does not end up orphaned. If you are interested in helping out with maintaining the project, please open an [issue or discussion](https://github.com/josuelmm/cordova-background-geolocation/issues) on GitHub.
+**Capacitor & Ionic:** Use the plugin in a Capacitor app (with or without Ionic). Install the package, run `npx cap sync`, then use the same JavaScript API. The plugin is compatible with recent Capacitor (e.g. 6.x, 7.x) and Ionic (7.x, 8.x) versions.
 
-The NPM package can be found at [@josuelmm/cordova-background-geolocation](https://www.npmjs.com/package/@josuelmm/cordova-background-geolocation).
+---
 
-**Recent (v2.3.4):** Sync and location providers were hardened for production: null-safe config/manager checks, HTTP timeouts so the sync notification cannot stay stuck, migration of the Android activity provider to `FusedLocationProviderClient` / `ActivityRecognitionClient`, and PendingIntent/requestCode fixes on the distance-filter provider. See [CHANGELOG](CHANGELOG.md) for details.
+## Installation
 
-<font size="4">[Documentation](https://josuelmm.github.io/cordova-background-geolocation/)</font> (original docs; API is compatible)
+### npm (Capacitor or modern Cordova)
 
-### Installing the plugin
-
-Este fork se publica en npm como **`@josuelmm/cordova-background-geolocation`**. Para publicar tú mismo o automatizar desde GitHub, ver [NPM_PUBLISH.md](NPM_PUBLISH.md).
-
-**Note:** for non AndroidX project please use version 1.x of this plugin. Version 2.x and on will support AndroidX.
-
-**Note:** this plugin can be installed on a Capacitor project and it is tested to be working as expected, some configuration may need to be done differently than below according to how Capacitor configuration is implemented.
-
-**Note:** for Android 14+ there's a need to let Google know why the app needs to use the location and have a video link when uploading for the first time to play console. It takes some time to approve and after that there's no need to do it again. This is related to `FOREGROUND_SERVICE_LOCATION` premission.
-
-**Note:** for Android 13+ there's a need for runtime `POST_NOTIFICATION` permission request in order to show the icon.
+```bash
+npm install @josuelmm/cordova-background-geolocation
+```
 
+For Capacitor, sync native projects after installing:
 
 ```bash
-npm install @josuelmm/cordova-background-geolocation
 npx cap sync
 ```
 
+### Cordova CLI
+
 ```bash
 cordova plugin add @josuelmm/cordova-background-geolocation
 ```
 
-You may also want to change default iOS permission prompts and set specific google play version and android support library version for compatibility with other plugins.
-
-**Note:** Always consult documentation of other plugins to figure out compatible versions.
+Optional: set variables for Google Play Services and iOS permission strings:
 
 ```bash
 cordova plugin add @josuelmm/cordova-background-geolocation \
   --variable GOOGLE_PLAY_SERVICES_VERSION=17+ \
-  --variable ALWAYS_USAGE_DESCRIPTION="App requires ..." \
-  --variable MOTION_USAGE_DESCRIPTION="App requires motion detection"
+  --variable ALWAYS_USAGE_DESCRIPTION="Your app needs location for ..." \
+  --variable MOTION_USAGE_DESCRIPTION="Your app uses motion for ..."
+```
+
+**Notes:**
+
+- **AndroidX:** Use plugin version 2.x. For non-AndroidX projects use 1.x.
+- **Android 14+:** You may need to justify foreground location usage (e.g. in Play Console) for `FOREGROUND_SERVICE_LOCATION`.
+- **Android 13+:** Request runtime `POST_NOTIFICATION` permission if you want the tracking notification to show.
+- After changing plugin options, remove and reinstall the plugin for changes to take effect.
+
+---
+
+## Usage (with or without Angular)
+
+You can use the plugin in two ways:
+
+- **Without Angular** — Use the global `BackgroundGeolocation` object (Cordova/Capacitor injects it after `deviceready`). Same in plain JS, React, Vue, or any framework.
+- **With Angular (Ionic Angular)** — Import the Angular service and inject it; same API, better testability and no global. See [Angular (Ionic Angular)](#angular-ionic-angular) below.
+
+The following steps use the global API. If you use Angular, call the same methods on the injected service instead.
+
+### TypeScript imports
+
+You can use either the **native** type names or the **Awesome Cordova Plugins–style** aliases.
+
+**Option A — Named import (same style as @awesome-cordova-plugins):**
+
+```ts
+import {
+  BackgroundGeolocation,
+  BackgroundGeolocationConfig,
+  BackgroundGeolocationEvents,
+  BackgroundGeolocationResponse
+} from '@josuelmm/cordova-background-geolocation';
+
+// After deviceready (use the global object, not injection):
+BackgroundGeolocation.configure({ distanceFilter: 50 } as BackgroundGeolocationConfig);
+BackgroundGeolocation.on('location', (loc: BackgroundGeolocationResponse) => { ... });
+```
+
+**Angular/Ionic:** One import for service and types: use `BackgroundGeolocationService` (and types like `BackgroundGeolocationConfig`, `BackgroundGeolocationResponse`) from `@josuelmm/cordova-background-geolocation/angular`. See [Angular (Ionic Angular)](#angular-ionic-angular).
+
+**Option B — Default export + native type names:**
+
+```ts
+import BackgroundGeolocation from '@josuelmm/cordova-background-geolocation';
+import type {
+  ConfigureOptions,
+  Location,
+  LocationOptions,
+  ServiceStatus,
+  Activity,
+  BackgroundGeolocationError,
+  LogEntry
+} from '@josuelmm/cordova-background-geolocation';
+
+// After deviceready:
+BackgroundGeolocation.configure({ distanceFilter: 50 } as ConfigureOptions);
+BackgroundGeolocation.on('location', (loc: Location) => { ... });
 ```
 
-**Note:** To apply changes, you must remove and reinstall plugin.
+**Type aliases / compatibility:** `BackgroundGeolocationConfig` = `ConfigureOptions`, `BackgroundGeolocationResponse` = `Location`. `BackgroundGeolocationEvents` is an enum (e.g. `BackgroundGeolocationEvents.location`). Enums and types match [@awesome-cordova-plugins/background-geolocation](https://github.com/danielsogl/awesome-cordova-plugins/blob/master/src/%40awesome-cordova-plugins/plugins/background-geolocation/index.ts) where applicable; **accuracy values** in this plugin are `0, 100, 1000, 10000` (use `BackgroundGeolocation.HIGH_ACCURACY` etc. or the `BackgroundGeolocationAccuracy` enum from the types).
+
+**Constants** (accuracy, provider, mode) are on the plugin object:
 
-### Usage
+```ts
+BackgroundGeolocation.HIGH_ACCURACY
+BackgroundGeolocation.ACTIVITY_PROVIDER
+BackgroundGeolocation.BACKGROUND_MODE
+BackgroundGeolocation.FOREGROUND_MODE
+```
+
+### 1. Configure
 
-First, configure the plugin with the settings you require.
+Set your preferred provider, accuracy, intervals, and optional server URL:
 
 ```js
 BackgroundGeolocation.configure({
-    locationProvider: BackgroundGeolocation.ACTIVITY_PROVIDER,
-    desiredAccuracy: BackgroundGeolocation.HIGH_ACCURACY,
-    stationaryRadius: 50,
-    distanceFilter: 50,
-    notificationTitle: 'Background tracking',
-    notificationText: 'enabled',
-    debug: true,
-    interval: 10000,
-    fastestInterval: 5000,
-    activitiesInterval: 10000,
-    url: 'http://192.168.81.15:3000/location',
-    httpHeaders: {
-      'X-FOO': 'bar'
-    },
-    // customize post properties
-    postTemplate: {
-      lat: '@latitude',
-      lon: '@longitude',
-      foo: 'bar' // you can also add your own properties
-    }
+  locationProvider: BackgroundGeolocation.ACTIVITY_PROVIDER,
+  desiredAccuracy: BackgroundGeolocation.HIGH_ACCURACY,
+  stationaryRadius: 50,
+  distanceFilter: 50,
+  notificationTitle: 'Background tracking',
+  notificationText: 'enabled',
+  debug: true,
+  interval: 10000,
+  fastestInterval: 5000,
+  activitiesInterval: 10000,
+  url: 'https://yourserver.com/location',
+  // HTTP headers can be sent in two ways:
+  // 1) Static: set httpHeaders here — same headers on every POST/sync request (e.g. API key, Content-Type).
+  httpHeaders: {
+    'X-FOO': 'bar',
+    'Authorization': 'Bearer YOUR_TOKEN'
+  },
+  postTemplate: {
+    lat: '@latitude',
+    lon: '@longitude'
+  }
+});
+```
+
+### 2. Start tracking
+
+```js
+BackgroundGeolocation.start();
+```
+
+### 3. Listen for events
+
+```js
+BackgroundGeolocation.on('location', function (location) {
+  console.log(location.latitude, location.longitude);
+});
+
+BackgroundGeolocation.on('error', function (error) {
+  console.warn(error.code, error.message);
+});
+```
+
+**HTTP headers (second way — dynamic):** When your server responds with **401 Unauthorized**, the plugin emits the `http_authorization` event. You can then refresh your token and reconfigure headers so the next request uses them (e.g. a new `Authorization` header):
+
+```js
+BackgroundGeolocation.on('http_authorization', function () {
+  // e.g. get a new token from your auth API, then:
+  BackgroundGeolocation.configure({
+    httpHeaders: { 'Authorization': 'Bearer ' + newToken }
   });
+});
+```
+
+### 4. Stop tracking
+
+```js
+BackgroundGeolocation.stop();
+```
+
+More options (stationary, activity, start/stop events, headless task) are in the [documentation](https://josuelmm.github.io/cordova-background-geolocation/). For **Angular** (service, methods, events, example), see [Angular (Ionic Angular)](https://josuelmm.github.io/cordova-background-geolocation/angular).
+
+---
+
+## Angular (Ionic Angular)
+
+The package includes an **Angular integration**: an injectable service and optional NgModule. You can use the plugin **without it** (global `BackgroundGeolocation`) or **with it** (inject the service). Both use the same native plugin.
+
+### Install (same as above)
+
+```bash
+npm install @josuelmm/cordova-background-geolocation
+npx cap sync
+```
+
+### How to import and use
+
+**One import** — Service and the most used types are exported from the `/angular` entry, so you do **not** need a second import from the main package:
+
+```ts
+import {
+  BackgroundGeolocationService,
+  BackgroundGeolocationConfig,
+  BackgroundGeolocationEvents,
+  BackgroundGeolocationResponse
+} from '@josuelmm/cordova-background-geolocation/angular';
+
+@Injectable({ ... })
+export class MyService {
+  constructor(private bg: BackgroundGeolocationService) {}
+
+  startTracking() {
+    this.bg.configure({ distanceFilter: 50, url: 'https://...' } as BackgroundGeolocationConfig)
+      .then(() => this.bg.start());
+  }
+
+  onLocation() {
+    return this.bg.on('location', (loc: BackgroundGeolocationResponse) => console.log(loc));
+    // subscription.unsubscribe() when done
+  }
+}
 ```
 
-Then call `start()` to start location tracking.
+**You must import `BackgroundGeolocationModule`** in your `AppModule` (or feature module) so the service is provided and AOT builds work. Then inject `BackgroundGeolocationService` as in the example above. See [docs/angular.md](docs/angular.md) for the full snippet.
+
+**Migrating from @awesome-cordova-plugins/background-geolocation:** there you inject a class named `BackgroundGeolocation`. In this package, `BackgroundGeolocation` is the **global plugin object**, not an injectable class. Use `BackgroundGeolocationService` instead (same API). See [docs/angular.md](docs/angular.md) for details.
+
+### Summary
+
+| Use case              | What to do |
+|-----------------------|------------|
+| **Without Angular**   | Use global `BackgroundGeolocation` after `deviceready`. Types: main package or Awesome-style aliases (see [TypeScript imports](#typescript-imports) above). |
+| **With Angular**      | Import from `@josuelmm/cordova-background-geolocation/angular`: add `BackgroundGeolocationModule` to your module `imports`, then inject `BackgroundGeolocationService`. Do **not** inject the global `BackgroundGeolocation`. |
+
+No extra wrapper (e.g. Awesome Cordova Plugins) is required.
+
+---
+
+## Compatibility
+
+| Plugin version | Cordova CLI | Cordova Android | Cordova iOS |
+|----------------|-------------|-----------------|-------------|
+| 1.x            | ≥ 8.0.0     | ≥ 8.0.0         | ≥ 6.0.0     |
+| 2.x            | ≥ 10.0.0    | ≥ 10.0.0        | ≥ 6.0.0     |
+
+---
+
+## Documentation and changelog
 
-A more comprehensive example can be found in the [Documentation](https://josuelmm.github.io/cordova-background-geolocation/example) (original docs).
+- [Documentation](https://josuelmm.github.io/cordova-background-geolocation/) (API, options, examples)
+- [CHANGELOG](CHANGELOG.md) for version history
 
-### Compatibility
+This project is based on [@mauron85/cordova-plugin-background-geolocation](https://github.com/mauron85/cordova-plugin-background-geolocation) and the original by [christocracy](https://github.com/christocracy). Maintained at [josuelmm/cordova-background-geolocation](https://github.com/josuelmm/cordova-background-geolocation). Issues and PRs welcome.
 
-| Plugin version   | Cordova CLI       | Cordova Platform Android | Cordova Platform iOS |
-|------------------|-------------------|--------------------------|----------------------|
-| >1.0.0           | 8.0.0             | 8.0.0                    | 6.0.0                |
-| >2.0.0           | 10.0.0            | 10.0.0                   | 6.0.0                |
+---
 
 ## Licence
 

package/RELEASE.MD

@@ -1,5 +1,5 @@
 In order to release a version the following actions are needed:
 1. Update the version in the package.json, lock and plugin.xml files
 2. Go to [releases and create a new release](https://github.com/josuelmm/cordova-background-geolocation/releases/new) in GitHub
-3. Make sure to create a tag too with the version name - v2.3.4
+3. Make sure to create a tag too with the version name (e.g. v3.0.0)
 4. Click create. Github actions will publish the package to npm

package/android/CDVBackgroundGeolocation/src/main/java/com/marianhello/bgloc/cordova/ConfigMapper.java

@@ -98,6 +98,9 @@ public class ConfigMapper {
                 config.setTemplate(LocationTemplateFactory.fromJSON(postTemplate));
             }
         }
+        if (jObject.has("enableWatchdog")) {
+            config.setEnableWatchdog(jObject.getBoolean("enableWatchdog"));
+        }
 
         return config;
     }
@@ -127,6 +130,7 @@ public class ConfigMapper {
         json.put("syncThreshold", config.getSyncThreshold());
         json.put("httpHeaders", new JSONObject(config.getHttpHeaders()));
         json.put("maxLocations", config.getMaxLocations());
+        json.put("enableWatchdog", Boolean.TRUE.equals(config.getEnableWatchdog()));
         LocationTemplate tpl = config.getTemplate();
         Object template = JSONObject.NULL;
         if (tpl instanceof HashMapLocationTemplate) {

package/android/CDVBackgroundGeolocation/src/main/java/com/tenforwardconsulting/bgloc/cordova/BackgroundGeolocationPlugin.java

@@ -71,6 +71,10 @@ public class BackgroundGeolocationPlugin extends CordovaPlugin implements Plugin
     public static final String ACTION_END_TASK = "endTask";
     public static final String ACTION_REGISTER_HEADLESS_TASK = "registerHeadlessTask";
     public static final String ACTION_FORCE_SYNC = "forceSync";
+    public static final String ACTION_GET_PLUGIN_VERSION = "getPluginVersion";
+
+    /** Plugin version; keep in sync with plugin.xml. */
+    public static final String PLUGIN_VERSION = "3.0.0";
 
     private BackgroundGeolocationFacade facade;
 
@@ -365,6 +369,9 @@ public class BackgroundGeolocationPlugin extends CordovaPlugin implements Plugin
             logger.debug("Forced location sync requested");
             facade.forceSync();
             return true;
+        } else if (ACTION_GET_PLUGIN_VERSION.equals(action)) {
+            callbackContext.success(PLUGIN_VERSION);
+            return true;
         }
 
         return false;

package/android/common/src/main/java/com/marianhello/bgloc/BootCompletedReceiver.java

@@ -9,9 +9,11 @@ This is a new class
 
 package com.marianhello.bgloc;
 
+import android.Manifest;
 import android.content.BroadcastReceiver;
 import android.content.Context;
 import android.content.Intent;
+import android.content.pm.PackageManager;
 import android.os.Build;
 import android.util.Log;
 
@@ -44,6 +46,10 @@ public class BootCompletedReceiver extends BroadcastReceiver {
         Log.d(TAG, "Boot completed " + config.toString());
 
         if (config.getStartOnBoot()) {
+            if (!hasLocationPermission(context)) {
+                Log.w(TAG, "Skipping start on boot: ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION not granted");
+                return;
+            }
             Log.i(TAG, "Starting service after boot");
             Intent locationServiceIntent = new Intent(context, LocationServiceImpl.class);
             locationServiceIntent.addFlags(Intent.FLAG_FROM_BACKGROUND);
@@ -56,4 +62,9 @@ public class BootCompletedReceiver extends BroadcastReceiver {
             }
         }
      }
+
+    private static boolean hasLocationPermission(Context context) {
+        return context.checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
+                || context.checkSelfPermission(Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED;
+    }
 }

package/android/common/src/main/java/com/marianhello/bgloc/Config.java

@@ -63,6 +63,7 @@ public class Config implements Parcelable
     private HashMap httpHeaders;
     private Integer maxLocations;
     private LocationTemplate template;
+    private Boolean enableWatchdog;
 
     public Config () {
     }
@@ -92,6 +93,7 @@ public class Config implements Parcelable
         this.syncThreshold = config.syncThreshold;
         this.httpHeaders = CloneHelper.deepCopy(config.httpHeaders);
         this.maxLocations = config.maxLocations;
+        this.enableWatchdog = config.enableWatchdog;
         if (config.template instanceof AbstractLocationTemplate) {
             this.template = ((AbstractLocationTemplate)config.template).clone();
         }
@@ -120,6 +122,7 @@ public class Config implements Parcelable
         setSyncUrl(in.readString());
         setSyncThreshold(in.readInt());
         setMaxLocations(in.readInt());
+        setEnableWatchdog((Boolean) in.readValue(null));
         Bundle bundle = in.readBundle();
         setHttpHeaders((HashMap<String, String>) bundle.getSerializable("httpHeaders"));
         setTemplate((LocationTemplate) bundle.getSerializable(AbstractLocationTemplate.BUNDLE_KEY));
@@ -151,6 +154,7 @@ public class Config implements Parcelable
         config.httpHeaders = null;
         config.maxLocations = 10000;
         config.template = null;
+        config.enableWatchdog = false;
 
         return config;
     }
@@ -183,6 +187,7 @@ public class Config implements Parcelable
         out.writeString(getSyncUrl());
         out.writeInt(getSyncThreshold());
         out.writeInt(getMaxLocations());
+        out.writeValue(getEnableWatchdog());
         Bundle bundle = new Bundle();
         bundle.putSerializable("httpHeaders", getHttpHeaders());
         bundle.putSerializable(AbstractLocationTemplate.BUNDLE_KEY, (AbstractLocationTemplate) getTemplate());
@@ -520,6 +525,19 @@ public class Config implements Parcelable
         this.template = template;
     }
 
+    public boolean hasEnableWatchdog() {
+        return enableWatchdog != null;
+    }
+
+    @Nullable
+    public Boolean getEnableWatchdog() {
+        return enableWatchdog;
+    }
+
+    public void setEnableWatchdog(Boolean enableWatchdog) {
+        this.enableWatchdog = enableWatchdog;
+    }
+
     @Override
     public String toString () {
         return new StringBuffer()