@josuelmm/cordova-background-geolocation 3.0.2 → 3.1.1

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [3.1.1](https://github.com/josuelmm/cordova-background-geolocation/tree/3.1.1) (2026-02-27)
+
+### Added
+
+- **Browser / `ng serve` support** — The plugin uses `cordova/exec` and `cordova/channel`, which only exist in the Cordova runtime. To allow Angular (and other webpack-based) builds to succeed when running `ng serve` or building for browser, the package now ships:
+  - **Stub modules:** `www/cordova-exec-stub.js` and `www/cordova-channel-stub.js`. When running in the browser they avoid crashes; when running inside Cordova they delegate to the real `cordova.exec` and `cordova/channel`.
+  - **`browser` field in `package.json`** so bundlers (e.g. webpack) resolve `cordova/exec` and `cordova/channel` to these stubs. No app-side webpack config is required in normal setups.
+
+### Fixed
+
+- **Angular types on Windows** — The emitted `.d.ts` in `angular/dist/` used `from '../www/BackgroundGeolocation'`, which resolves (relative to `dist/`) to `angular/www/`, a folder that does not exist in the published package. Some apps worked around this by creating a junction `angular/www` → `www`. The build now runs a post-step (`scripts/fix-angular-dts-paths.js`) that rewrites these paths to `../../www/BackgroundGeolocation` in the emitted declarations, so types resolve to the package root `www/` and the junction is no longer needed.
+
+### Documentation
+
+- **docs/angular.md** — New section *"Build (ng serve / browser)"*: explains why the stubs exist, that webpack uses the `browser` field, and how to add resolve aliases in the app if a bundler does not respect it (e.g. "Can't resolve 'cordova/exec'"). Note that from 3.1.1 the junction workaround for types is unnecessary.
+
+- **README.md** — Angular section and "New in" updated to mention 3.1.1 and browser/ng serve compatibility.
+
+### Changed
+
+- Version bump to 3.1.1.
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/3.1.0...3.1.1)
+
+---
+
+## [3.1.0](https://github.com/josuelmm/cordova-background-geolocation/tree/3.1.0) (2026-02-21)
+
+### Added
+
+- **`getPendingSyncCount(success?, fail?)`** — Returns the number of locations pending to be synced (not yet sent to `syncUrl`). Use with `forceSync()` to show "X locations pending" and let the user trigger sync on demand. (Android, iOS)
+- **`clearSync(success?, fail?)`** — Clears the pending sync queue: discards all locations waiting to be sent to `syncUrl` (they will not be synced). Use when the user wants to discard pending locations (e.g. "Clear queue" button). (Android, iOS)
+- **Config option `sync`** (default `true`) — When `false`, automatic sync and `forceSync()` do not run; locations are still stored and can be synced later by setting `sync: true`. (Android, iOS)
+- **Config options for sync notification texts (Android):** `notificationSyncTitle`, `notificationSyncText`, `notificationSyncCompletedText`, `notificationSyncFailedText` — Customize or localize the notification shown while locations are syncing to the server.
+
+### Fixed
+
+- **Android:** `forceSync()` now correctly calls `callbackContext.success()` so the JS Promise resolves.
+- **Android SyncAdapter:** Use `currentSyncConfig` (not out-of-scope `config`) when building sync notifications.
+- **Android & iOS:** When `sync` was never set in config, DB column `sync_enabled` could be NULL; the plugin now treats NULL as “not set” (sync enabled by default) instead of “sync disabled”, so `forceSync()` and automatic sync work when the user did not pass `sync: false`.
+- **Android sync with `Content-Type: application/x-www-form-urlencoded`:** Batch sync was sending one POST with `locations=<url-encoded-json-array>`, which many servers reject (400). Sync now sends **one POST per location** with the same flat `key=value&key=value` format as real-time posting, so the same endpoint accepts both.
+
+### Changed
+
+- Version bump to 3.1.0.
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/3.0.2...3.1.0)
+
+---
+
 ## [3.0.2](https://github.com/josuelmm/cordova-background-geolocation/tree/3.0.2) (2026-02-21)
 
 ### Fixed

package/README.md

@@ -95,6 +95,22 @@ If your app’s merged manifest ends up with a `foregroundServiceType` other tha
 <string name="plugin_bgloc_content_authority">site.seelight.client.bgloc</string>
 ```
 
+**Notification labels (showTime / showDistance):** If you use `showTime: true` or `showDistance: true`, the notification shows a line for elapsed time and one for distance. **By default the labels are in English** ("Time" and "Distance"). If you want Spanish or another language, add these optional strings in your app so the plugin uses them; if you don’t define them, English is used.
+
+Example — English (default, optional in `res/values/strings.xml`):
+
+```xml
+<string name="plugin_bgloc_notification_time_label">Time</string>
+<string name="plugin_bgloc_notification_distance_label">Distance</string>
+```
+
+Example — Spanish: add in `res/values-es/strings.xml` (or your locale folder):
+
+```xml
+<string name="plugin_bgloc_notification_time_label">Tiempo</string>
+<string name="plugin_bgloc_notification_distance_label">Distancia</string>
+```
+
 This makes your app enforce the correct foreground service type and defines the strings the plugin needs for the sync account.
 
 ---
@@ -161,7 +177,31 @@ BackgroundGeolocation.FOREGROUND_MODE
 
 ### 1. Configure
 
-Set your preferred provider, accuracy, intervals, and optional server URL:
+Set your preferred provider, accuracy, intervals, and optional server URLs. All options are optional; you can reconfigure later with a subset (options are merged).
+
+**Main options:**
+
+| Option | Description |
+|--------|-------------|
+| `locationProvider` | `ACTIVITY_PROVIDER`, `DISTANCE_FILTER_PROVIDER`, or `RAW_PROVIDER` |
+| `desiredAccuracy` | `HIGH_ACCURACY`, `MEDIUM_ACCURACY`, `LOW_ACCURACY`, `PASSIVE_ACCURACY` |
+| `distanceFilter` | Minimum metres the device must move before an update (e.g. 50) |
+| `stationaryRadius` | Metres from “stationary” point before aggressive tracking (e.g. 50) |
+| `interval` / `fastestInterval` / `activitiesInterval` | Android timing (ms) |
+| `notificationTitle` / `notificationText` | Android foreground notification text |
+| `url` | Server URL where **each** location is posted immediately (if post fails, it goes to sync queue) |
+| `syncUrl` | Server URL where **pending** locations are sent in batch (when count reaches `syncThreshold` or on `forceSync()`) |
+| `syncThreshold` | Number of pending locations before automatic batch sync (default 100) |
+| `sync` | When `true` (default), automatic sync and `forceSync()` run. When `false`, sync is disabled (locations are still stored). |
+| `httpHeaders` | Headers for every POST (e.g. `{ 'Content-Type': 'application/json', 'Authorization': 'Bearer TOKEN' }`) |
+| `postTemplate` | Object or array of properties to send (use `@latitude`, `@longitude`, etc.). See [Custom post template](docs/api.md#custom-post-template). |
+| `maxLocations` | Max locations kept in DB (default 10000). Should be &gt; `syncThreshold`. |
+
+**Android-only:** `notificationSyncTitle`, `notificationSyncText`, `notificationSyncCompletedText`, `notificationSyncFailedText` — texts shown in the notification while syncing (defaults in English; set for localization). `startForeground`, `notificationsEnabled`, `startOnBoot`, `stopOnTerminate`, `enableWatchdog`.
+
+**iOS-only:** `activityType`, `pauseLocationUpdates`, `saveBatteryOnBackground`.
+
+Example:
 
 ```js
 BackgroundGeolocation.configure({
@@ -176,15 +216,17 @@ BackgroundGeolocation.configure({
   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).
+  syncUrl: 'https://yourserver.com/location',
+  syncThreshold: 5,
+  sync: true,
   httpHeaders: {
-    'X-FOO': 'bar',
+    'Content-Type': 'application/json',
     'Authorization': 'Bearer YOUR_TOKEN'
   },
   postTemplate: {
     lat: '@latitude',
-    lon: '@longitude'
+    lon: '@longitude',
+    timestamp: '@time'
   }
 });
 ```
@@ -224,7 +266,99 @@ BackgroundGeolocation.on('http_authorization', function () {
 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).
+### 5. Sync queue (syncUrl): pending count, force sync, clear queue
+
+When you use `syncUrl`, locations that fail to post to `url` (or that are only queued for sync) are sent in batch to `syncUrl`.
+
+**How sync sends data (Content-Type):** It depends on the `Content-Type` you set in `httpHeaders`. Many people assume “one request per location”; that is only true for form encoding.
+
+| Content-Type | Sync to `syncUrl` |
+|--------------|-------------------|
+| **`application/json`** (default) | **One POST** with a JSON **array** of all locations in the batch. |
+| **`application/x-www-form-urlencoded`** | **One POST per location** (same flat `key=value&...` as real-time to `url`). Same endpoint can handle both. |
+
+So: with **JSON** you get one request per batch (e.g. 100 locations in one body). With **form-urlencoded** you get one request per location (one record per POST). For headers, retries, `postTemplate` and full behaviour see [HTTP posting](docs/http_posting.md) and [API](docs/api.md).
+
+You can:
+
+- **Get pending count** — `getPendingSyncCount()` returns how many locations are waiting to be synced.
+- **Force sync now** — `forceSync()` sends all pending locations immediately (ignores `syncThreshold`). No-op if `sync: false`.
+- **Clear queue** — `clearSync()` discards all pending locations (they will not be sent). Use for a “Clear queue” or “Discard” button.
+
+```js
+// Show "X locations pending" and let user sync or clear
+BackgroundGeolocation.getPendingSyncCount()
+  .then(function (count) {
+    console.log('Pending to sync:', count);
+    // e.g. show UI: "Sync (5)" or "Clear queue"
+  });
+
+// User taps "Sync now"
+BackgroundGeolocation.forceSync().then(function () {
+  console.log('Sync completed');
+});
+
+// User taps "Clear queue"
+BackgroundGeolocation.clearSync().then(function () {
+  console.log('Queue cleared');
+});
+```
+
+More on sync (headers, retries, postTemplate): [HTTP posting](docs/http_posting.md). Full options and methods: [API](docs/api.md).
+
+### 6. Other methods (summary)
+
+| Method | Description |
+|--------|-------------|
+| `getConfig(success, fail)` | Get current configuration (merged options). |
+| `getLocations(success, fail)` | Get all stored locations. |
+| `getValidLocations(success, fail)` | Get locations not yet posted (valid only). |
+| `deleteLocation(id, success, fail)` | Delete one location by id. |
+| `deleteAllLocations(success, fail)` | Delete all stored locations. |
+| `getCurrentLocation(success, fail, options)` | One-shot location (e.g. timeout, maximumAge). |
+| `getPluginVersion(success, fail)` | Plugin version string (e.g. "3.1.1"). |
+| `checkStatus(success, fail)` | Service status (isRunning, authorization, etc.). |
+| `showAppSettings()` / `openSettings()` | Open app settings. |
+| `showLocationSettings()` | Open system location settings. |
+| `getLogEntries(limit, fromId, minLevel, success, fail)` | Debug log entries. |
+
+All methods return a **Promise** if you omit the `success` / `fail` callbacks.
+
+### 7. Events (summary)
+
+Subscribe with `BackgroundGeolocation.on(eventName, callback)`. Unsubscribe with the returned object’s `remove()` or by calling `removeAllListeners(eventName)`.
+
+| Event | Payload | When |
+|-------|---------|------|
+| `location` | Location object | New location (foreground/background). |
+| `stationary` | Location | Device stopped (activity provider). |
+| `activity` | Activity type | Activity changed (walking, driving, still). |
+| `error` | `{ code, message }` | Error (e.g. permission, timeout). |
+| `start` | — | Tracking started. |
+| `stop` | — | Tracking stopped. |
+| `authorization` | status | Permission status changed. |
+| `background` / `foreground` | — | App entered background/foreground. |
+| `http_authorization` | — | Server returned 401; refresh token and reconfigure headers. |
+| `abort_requested` | — | Server returned 285 (updates not required). |
+
+Full event payloads and options: [Events](docs/events.md). Full API (all options, all methods): [API](docs/api.md).
+
+### New in 3.1.1
+
+- **Browser / `ng serve` builds** — The plugin can now be bundled by webpack without "Can't resolve 'cordova/exec'" or "Can't resolve 'cordova/channel'". The package ships stub modules and a `browser` field so `ng serve` and browser builds succeed; on device/emulator the stubs delegate to the real Cordova API. See [docs/angular.md](docs/angular.md#build-ng-serve--browser).
+
+### New in 3.1.0
+
+- **`getPendingSyncCount()`** — Number of locations pending to be synced. Use with `forceSync()` for “X pending” UI.
+- **`forceSync()`** — Sends all pending locations to `syncUrl` immediately. Promise now resolves correctly on Android.
+- **`clearSync()`** — Clears the pending sync queue (discard without sending).
+- **Config `sync`** (default `true`) — Set `sync: false` to disable automatic sync and `forceSync()`; locations are still stored.
+- **Config `notificationSyncTitle`, `notificationSyncText`, `notificationSyncCompletedText`, `notificationSyncFailedText`** (Android) — Customize or localize the notification shown while syncing.
+- **Sync with `Content-Type: application/x-www-form-urlencoded`** — Batch sync now sends **one POST per location** (same flat format as real-time), so the same server endpoint works for both.
+
+---
+
+More (stationary, activity, headless task, Angular) is in the [documentation](https://josuelmm.github.io/cordova-background-geolocation/). For **Angular** (service, methods, events), see [docs/angular.md](docs/angular.md).
 
 ---
 
@@ -269,6 +403,10 @@ export class MyService {
 
 **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.
 
+**`ng serve` / browser:** From 3.1.1 the plugin includes browser stubs so `ng serve` and web builds complete without "Can't resolve 'cordova/exec'" — see [docs/angular.md](docs/angular.md#build-ng-serve--browser).
+
+**Lazy-loaded pages:** If you see **NG0202** or *"dependency at index N is invalid"* when opening a page that injects this service, use an app-defined token and inject by that token (the plugin token can be undefined in the lazy chunk). See [docs/angular.md](docs/angular.md) (Lazy-loaded modules).
+
 **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
@@ -293,8 +431,16 @@ No extra wrapper (e.g. Awesome Cordova Plugins) is required.
 
 ## Documentation and changelog
 
-- [Documentation](https://josuelmm.github.io/cordova-background-geolocation/) (API, options, examples)
-- [CHANGELOG](CHANGELOG.md) for version history
+This README is the main entry point. For more detail, edge cases and examples use the docs below (and the [online documentation](https://josuelmm.github.io/cordova-background-geolocation/)).
+
+| Doc | What you’ll find |
+|-----|------------------|
+| **[API reference](docs/api.md)** | Every `configure` option, every method (`configure`, `start`, `stop`, `getPendingSyncCount`, `forceSync`, `clearSync`, `getConfig`, `getLocations`, etc.), TypeScript types. |
+| **[HTTP posting](docs/http_posting.md)** | `url` vs `syncUrl`, Content-Type (JSON = one POST with array; form-urlencoded = one POST per location), headers, retries, `postTemplate`, sync behaviour. |
+| **[Events](docs/events.md)** | All events (`location`, `error`, `stationary`, `activity`, `http_authorization`, etc.) and payloads. |
+| **[Angular / Ionic](docs/angular.md)** | Injectable service, module, lazy-loaded modules and token “must be defined”, `ng serve` / browser build. |
+| **[Example](docs/example.md)** | Full example with events and sync. |
+| **[CHANGELOG](CHANGELOG.md)** | Version history. |
 
 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.
 

package/RELEASE.MD

@@ -1,5 +1,16 @@
 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 (e.g. v3.0.2)
-4. Click create. Github actions will publish the package to npm
+
+1. **Version and docs**
+   - Set the new version (e.g. `3.1.1`) in:
+     - `package.json` (`version` field)
+     - `plugin.xml` (root `<plugin>` attribute `version`)
+   - Add a release entry in `CHANGELOG.md` (date, Added/Fixed/Changed/Documentation).
+   - Update `README.md` if needed (e.g. "New in X.Y.Z", example version strings).
+
+2. **Lock file**
+   - Run `npm install` so `package-lock.json` stays in sync with `package.json`.
+
+3. **Git tag and release**
+   - Go to [Releases → Create a new release](https://github.com/josuelmm/cordova-background-geolocation/releases/new).
+   - Create a tag with the version name (e.g. `v3.1.1`).
+   - Publish the release. GitHub Actions will publish the package to npm.

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

@@ -42,6 +42,18 @@ public class ConfigMapper {
         if (jObject.has("notificationText")) {
             config.setNotificationText(!jObject.isNull("notificationText") ? jObject.getString("notificationText") : Config.NullString);
         }
+        if (jObject.has("notificationSyncTitle")) {
+            config.setNotificationSyncTitle(jObject.isNull("notificationSyncTitle") ? null : jObject.getString("notificationSyncTitle"));
+        }
+        if (jObject.has("notificationSyncText")) {
+            config.setNotificationSyncText(jObject.isNull("notificationSyncText") ? null : jObject.getString("notificationSyncText"));
+        }
+        if (jObject.has("notificationSyncCompletedText")) {
+            config.setNotificationSyncCompletedText(jObject.isNull("notificationSyncCompletedText") ? null : jObject.getString("notificationSyncCompletedText"));
+        }
+        if (jObject.has("notificationSyncFailedText")) {
+            config.setNotificationSyncFailedText(jObject.isNull("notificationSyncFailedText") ? null : jObject.getString("notificationSyncFailedText"));
+        }
         if (jObject.has("stopOnTerminate")) {
             config.setStopOnTerminate(jObject.getBoolean("stopOnTerminate"));
         }
@@ -84,6 +96,9 @@ public class ConfigMapper {
         if (jObject.has("syncThreshold")) {
             config.setSyncThreshold(jObject.getInt("syncThreshold"));
         }
+        if (jObject.has("sync")) {
+            config.setSyncEnabled(jObject.getBoolean("sync"));
+        }
         if (jObject.has("httpHeaders")) {
             config.setHttpHeaders(jObject.getJSONObject("httpHeaders"));
         }
@@ -101,6 +116,12 @@ public class ConfigMapper {
         if (jObject.has("enableWatchdog")) {
             config.setEnableWatchdog(jObject.getBoolean("enableWatchdog"));
         }
+        if (jObject.has("showTime")) {
+            config.setShowTime(jObject.getBoolean("showTime"));
+        }
+        if (jObject.has("showDistance")) {
+            config.setShowDistance(jObject.getBoolean("showDistance"));
+        }
 
         return config;
     }
@@ -114,6 +135,10 @@ public class ConfigMapper {
         json.put("notificationsEnabled", config.getNotificationsEnabled());
         json.put("notificationTitle", config.getNotificationTitle() != Config.NullString ? config.getNotificationTitle() : JSONObject.NULL);
         json.put("notificationText", config.getNotificationText() != Config.NullString ? config.getNotificationText() : JSONObject.NULL);
+        json.put("notificationSyncTitle", config.getNotificationSyncTitle());
+        json.put("notificationSyncText", config.getNotificationSyncText());
+        json.put("notificationSyncCompletedText", config.getNotificationSyncCompletedText());
+        json.put("notificationSyncFailedText", config.getNotificationSyncFailedText());
         json.put("notificationIconLarge", config.getLargeNotificationIcon() != Config.NullString ? config.getLargeNotificationIcon() : JSONObject.NULL);
         json.put("notificationIconSmall", config.getSmallNotificationIcon() != Config.NullString ? config.getSmallNotificationIcon() : JSONObject.NULL);
         json.put("notificationIconColor", config.getNotificationIconColor() != Config.NullString ? config.getNotificationIconColor() : JSONObject.NULL);
@@ -128,9 +153,12 @@ public class ConfigMapper {
         json.put("url", config.getUrl() != Config.NullString ? config.getUrl() : JSONObject.NULL);
         json.put("syncUrl", config.getSyncUrl() != Config.NullString  ? config.getSyncUrl() : JSONObject.NULL);
         json.put("syncThreshold", config.getSyncThreshold());
+        json.put("sync", config.getSyncEnabled());
         json.put("httpHeaders", new JSONObject(config.getHttpHeaders()));
         json.put("maxLocations", config.getMaxLocations());
         json.put("enableWatchdog", Boolean.TRUE.equals(config.getEnableWatchdog()));
+        json.put("showTime", Boolean.TRUE.equals(config.getShowTime()));
+        json.put("showDistance", Boolean.TRUE.equals(config.getShowDistance()));
         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,10 +71,12 @@ 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_CLEAR_SYNC = "clearSync";
+    public static final String ACTION_GET_PENDING_SYNC_COUNT = "getPendingSyncCount";
     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";
+    public static final String PLUGIN_VERSION = "3.1.0";
 
     private BackgroundGeolocationFacade facade;
 
@@ -367,7 +369,35 @@ public class BackgroundGeolocationPlugin extends CordovaPlugin implements Plugin
             return true;
         } else if (ACTION_FORCE_SYNC.equals(action)) {
             logger.debug("Forced location sync requested");
-            facade.forceSync();
+            runOnWebViewThread(new Runnable() {
+                @Override
+                public void run() {
+                    facade.forceSync();
+                    callbackContext.success();
+                }
+            });
+            return true;
+        } else if (ACTION_CLEAR_SYNC.equals(action)) {
+            runOnWebViewThread(new Runnable() {
+                @Override
+                public void run() {
+                    facade.clearSync();
+                    callbackContext.success();
+                }
+            });
+            return true;
+        } else if (ACTION_GET_PENDING_SYNC_COUNT.equals(action)) {
+            runOnWebViewThread(new Runnable() {
+                @Override
+                public void run() {
+                    try {
+                        long count = facade.getPendingSyncCount();
+                        callbackContext.success((int) Math.min(count, Integer.MAX_VALUE));
+                    } catch (Exception e) {
+                        callbackContext.sendPluginResult(ErrorPluginResult.from("getPendingSyncCount failed", e, PluginException.SERVICE_ERROR));
+                    }
+                }
+            });
             return true;
         } else if (ACTION_GET_PLUGIN_VERSION.equals(action)) {
             callbackContext.success(PLUGIN_VERSION);

package/android/CDVBackgroundGeolocation/src/test/java/com/marianhello/ConfigMapperTest.java

@@ -34,6 +34,10 @@ public class ConfigMapperTest {
         Assert.assertEquals(config.isDebugging().booleanValue(), jConfig.getBoolean("debug"));
         Assert.assertEquals(config.getNotificationTitle(), jConfig.getString("notificationTitle"));
         Assert.assertEquals(config.getNotificationText(), jConfig.getString("notificationText"));
+        Assert.assertEquals(config.getNotificationSyncTitle(), jConfig.getString("notificationSyncTitle"));
+        Assert.assertEquals(config.getNotificationSyncText(), jConfig.getString("notificationSyncText"));
+        Assert.assertEquals(config.getNotificationSyncCompletedText(), jConfig.getString("notificationSyncCompletedText"));
+        Assert.assertEquals(config.getNotificationSyncFailedText(), jConfig.getString("notificationSyncFailedText"));
         Assert.assertEquals(config.getStopOnTerminate().booleanValue(), jConfig.getBoolean("stopOnTerminate"));
         Assert.assertEquals(config.getStartOnBoot().booleanValue(), jConfig.getBoolean("startOnBoot"));
         Assert.assertEquals(config.getLocationProvider().intValue(), jConfig.getInt("locationProvider"));
@@ -48,6 +52,7 @@ public class ConfigMapperTest {
         Assert.assertEquals(config.getUrl(), jConfig.getString("url"));
         Assert.assertEquals(config.getSyncUrl(), jConfig.getString("syncUrl"));
         Assert.assertEquals(config.getSyncThreshold().intValue(), jConfig.getInt("syncThreshold"));
+        Assert.assertEquals(Boolean.TRUE.equals(config.getSyncEnabled()), jConfig.getBoolean("sync"));
         Assert.assertEquals(new JSONObject(config.getHttpHeaders()).toString(), jConfig.getJSONObject("httpHeaders").toString());
         Assert.assertEquals(config.getMaxLocations().intValue(), jConfig.getInt("maxLocations"));
         Assert.assertEquals(LocationTemplateFactory.getDefault().toString(), jConfig.get("postTemplate").toString());
@@ -90,6 +95,13 @@ public class ConfigMapperTest {
         Assert.assertFalse(config.hasSmallNotificationIcon());
     }
 
+    /** When "sync" is not in JSON, getSyncEnabled() must return true (default). */
+    @Test
+    public void testSyncDefaultWhenNotInJson() throws JSONException {
+        Config config = ConfigMapper.fromJSONObject(new JSONObject());
+        Assert.assertTrue("sync not in JSON should default to true", config.getSyncEnabled());
+    }
+
     @Test
     public void testNullablePropsToJSONObject() throws JSONException {
         Config config = new Config();

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

@@ -407,9 +407,14 @@ public class BackgroundGeolocationFacade {
      * Force location sync
      *
      * Method is ignoring syncThreshold and also user sync settings preference
-     * and sync locations to defined syncUrl
+     * and sync locations to defined syncUrl. No-op if sync is disabled in config (sync: false).
      */
     public void forceSync() {
+        Config config = getConfig();
+        if (!Boolean.TRUE.equals(config.getSyncEnabled())) {
+            logger.debug("Sync disabled in config, skipping forceSync");
+            return;
+        }
         logger.debug("Sync locations forced");
         ResourceResolver resolver = ResourceResolver.newInstance(getContext());
         Account syncAccount = AccountHelper.CreateSyncAccount(getContext(), resolver.getAccountName(),
@@ -417,6 +422,24 @@ public class BackgroundGeolocationFacade {
         SyncService.sync(syncAccount, resolver.getAuthority(), true);
     }
 
+    /**
+     * Returns the number of locations pending to be synced (not yet sent to syncUrl).
+     */
+    public long getPendingSyncCount() {
+        LocationDAO dao = DAOFactory.createLocationDAO(getContext());
+        return dao.getLocationsForSyncCount(Long.MAX_VALUE);
+    }
+
+    /**
+     * Clear the pending sync queue: mark all locations waiting to be synced as deleted.
+     * They will not be sent to syncUrl. Use when the user wants to discard pending locations.
+     */
+    public void clearSync() {
+        LocationDAO dao = DAOFactory.createLocationDAO(getContext());
+        int count = dao.deletePendingSyncLocations();
+        logger.debug("Cleared {} pending sync locations", count);
+    }
+
     public int getAuthorizationStatus() {
         return hasPermissions() ? AUTHORIZATION_AUTHORIZED : AUTHORIZATION_DENIED;
     }