@josuelmm/cordova-background-geolocation 3.0.2 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [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

@@ -161,7 +161,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 > `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 +200,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 +250,82 @@ 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`. 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');
+});
+```
+
+### 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.0"). |
+| `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.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).
 
 ---
 
@@ -293,8 +394,13 @@ 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
+- **[Documentation](https://josuelmm.github.io/cordova-background-geolocation/)** — Full docs (API, options, examples).
+- **[API reference](docs/api.md)** — All `configure` options, every method (`configure`, `start`, `stop`, `getPendingSyncCount`, `forceSync`, `clearSync`, `getConfig`, `getLocations`, etc.), TypeScript types.
+- **[HTTP posting](docs/http_posting.md)** — `url` vs `syncUrl`, headers, Content-Type (JSON vs form-urlencoded), sync batch behaviour, `getPendingSyncCount` / `forceSync` / `clearSync`.
+- **[Events](docs/events.md)** — All events (`location`, `error`, `stationary`, `activity`, `http_authorization`, etc.) and payloads.
+- **[Angular / Ionic](docs/angular.md)** — Injectable service, module, same API.
+- **[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,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 (e.g. v3.0.2)
+3. Make sure to create a tag too with the version name (e.g. v3.1.0)
 4. Click create. 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"));
         }
@@ -114,6 +129,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,6 +147,7 @@ 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()));

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;
     }

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

@@ -45,6 +45,10 @@ public class Config implements Parcelable
     private Boolean debug;
     private String notificationTitle;
     private String notificationText;
+    private String notificationSyncTitle;
+    private String notificationSyncText;
+    private String notificationSyncCompletedText;
+    private String notificationSyncFailedText;
     private String notificationIconLarge;
     private String notificationIconSmall;
     private String notificationIconColor;
@@ -60,6 +64,7 @@ public class Config implements Parcelable
     private String url;
     private String syncUrl;
     private Integer syncThreshold;
+    private Boolean syncEnabled;
     private HashMap httpHeaders;
     private Integer maxLocations;
     private LocationTemplate template;
@@ -76,6 +81,10 @@ public class Config implements Parcelable
         this.debug = config.debug;
         this.notificationTitle = config.notificationTitle;
         this.notificationText = config.notificationText;
+        this.notificationSyncTitle = config.notificationSyncTitle;
+        this.notificationSyncText = config.notificationSyncText;
+        this.notificationSyncCompletedText = config.notificationSyncCompletedText;
+        this.notificationSyncFailedText = config.notificationSyncFailedText;
         this.notificationIconLarge = config.notificationIconLarge;
         this.notificationIconSmall = config.notificationIconSmall;
         this.notificationIconColor = config.notificationIconColor;
@@ -91,6 +100,7 @@ public class Config implements Parcelable
         this.url = config.url;
         this.syncUrl = config.syncUrl;
         this.syncThreshold = config.syncThreshold;
+        this.syncEnabled = config.syncEnabled;
         this.httpHeaders = CloneHelper.deepCopy(config.httpHeaders);
         this.maxLocations = config.maxLocations;
         this.enableWatchdog = config.enableWatchdog;
@@ -106,6 +116,10 @@ public class Config implements Parcelable
         setDebugging((Boolean) in.readValue(null));
         setNotificationTitle(in.readString());
         setNotificationText(in.readString());
+        setNotificationSyncTitle(in.readString());
+        setNotificationSyncText(in.readString());
+        setNotificationSyncCompletedText(in.readString());
+        setNotificationSyncFailedText(in.readString());
         setLargeNotificationIcon(in.readString());
         setSmallNotificationIcon(in.readString());
         setNotificationIconColor(in.readString());
@@ -121,6 +135,7 @@ public class Config implements Parcelable
         setUrl(in.readString());
         setSyncUrl(in.readString());
         setSyncThreshold(in.readInt());
+        setSyncEnabled((Boolean) in.readValue(null));
         setMaxLocations(in.readInt());
         setEnableWatchdog((Boolean) in.readValue(null));
         Bundle bundle = in.readBundle();
@@ -136,6 +151,10 @@ public class Config implements Parcelable
         config.debug = false;
         config.notificationTitle = "Background tracking";
         config.notificationText = "ENABLED";
+        config.notificationSyncTitle = "Syncing locations";
+        config.notificationSyncText = "Sync in progress";
+        config.notificationSyncCompletedText = "Sync completed";
+        config.notificationSyncFailedText = "Sync failed";
         config.notificationIconLarge = "";
         config.notificationIconSmall = "";
         config.notificationIconColor = "";
@@ -151,6 +170,7 @@ public class Config implements Parcelable
         config.url = "";
         config.syncUrl = "";
         config.syncThreshold = 100;
+        config.syncEnabled = true;
         config.httpHeaders = null;
         config.maxLocations = 10000;
         config.template = null;
@@ -171,6 +191,10 @@ public class Config implements Parcelable
         out.writeValue(isDebugging());
         out.writeString(getNotificationTitle());
         out.writeString(getNotificationText());
+        out.writeString(getNotificationSyncTitle());
+        out.writeString(getNotificationSyncText());
+        out.writeString(getNotificationSyncCompletedText());
+        out.writeString(getNotificationSyncFailedText());
         out.writeString(getLargeNotificationIcon());
         out.writeString(getSmallNotificationIcon());
         out.writeString(getNotificationIconColor());
@@ -186,6 +210,7 @@ public class Config implements Parcelable
         out.writeString(getUrl());
         out.writeString(getSyncUrl());
         out.writeInt(getSyncThreshold());
+        out.writeValue(getSyncEnabled());
         out.writeInt(getMaxLocations());
         out.writeValue(getEnableWatchdog());
         Bundle bundle = new Bundle();
@@ -293,6 +318,38 @@ public class Config implements Parcelable
         this.notificationText = notificationText;
     }
 
+    public String getNotificationSyncTitle() {
+        return notificationSyncTitle != null ? notificationSyncTitle : "Syncing locations";
+    }
+
+    public void setNotificationSyncTitle(String notificationSyncTitle) {
+        this.notificationSyncTitle = notificationSyncTitle;
+    }
+
+    public String getNotificationSyncText() {
+        return notificationSyncText != null ? notificationSyncText : "Sync in progress";
+    }
+
+    public void setNotificationSyncText(String notificationSyncText) {
+        this.notificationSyncText = notificationSyncText;
+    }
+
+    public String getNotificationSyncCompletedText() {
+        return notificationSyncCompletedText != null ? notificationSyncCompletedText : "Sync completed";
+    }
+
+    public void setNotificationSyncCompletedText(String notificationSyncCompletedText) {
+        this.notificationSyncCompletedText = notificationSyncCompletedText;
+    }
+
+    public String getNotificationSyncFailedText() {
+        return notificationSyncFailedText != null ? notificationSyncFailedText : "Sync failed";
+    }
+
+    public void setNotificationSyncFailedText(String notificationSyncFailedText) {
+        this.notificationSyncFailedText = notificationSyncFailedText;
+    }
+
     public boolean hasLargeNotificationIcon() {
         return notificationIconLarge != null && !notificationIconLarge.isEmpty();
     }
@@ -468,6 +525,20 @@ public class Config implements Parcelable
         this.syncThreshold = syncThreshold;
     }
 
+    public boolean hasSyncEnabled() {
+        return syncEnabled != null;
+    }
+
+    /** Whether synchronization to syncUrl is enabled. Default true. */
+    @Nullable
+    public Boolean getSyncEnabled() {
+        return syncEnabled != null ? syncEnabled : true;
+    }
+
+    public void setSyncEnabled(@Nullable Boolean syncEnabled) {
+        this.syncEnabled = syncEnabled;
+    }
+
     public boolean hasHttpHeaders() {
         return httpHeaders != null;
     }
@@ -562,6 +633,7 @@ public class Config implements Parcelable
                 .append(" url=").append(getUrl())
                 .append(" syncUrl=").append(getSyncUrl())
                 .append(" syncThreshold=").append(getSyncThreshold())
+                .append(" syncEnabled=").append(getSyncEnabled())
                 .append(" httpHeaders=").append(getHttpHeaders().toString())
                 .append(" maxLocations=").append(getMaxLocations())
                 .append(" postTemplate=").append(hasTemplate() ? getTemplate().toString() : null)
@@ -603,6 +675,18 @@ public class Config implements Parcelable
         if (config2.hasNotificationText()) {
             merger.setNotificationText(config2.getNotificationText());
         }
+        if (config2.notificationSyncTitle != null) {
+            merger.setNotificationSyncTitle(config2.getNotificationSyncTitle());
+        }
+        if (config2.notificationSyncText != null) {
+            merger.setNotificationSyncText(config2.getNotificationSyncText());
+        }
+        if (config2.notificationSyncCompletedText != null) {
+            merger.setNotificationSyncCompletedText(config2.getNotificationSyncCompletedText());
+        }
+        if (config2.notificationSyncFailedText != null) {
+            merger.setNotificationSyncFailedText(config2.getNotificationSyncFailedText());
+        }
         if (config2.hasStopOnTerminate()) {
             merger.setStopOnTerminate(config2.getStopOnTerminate());
         }
@@ -648,6 +732,9 @@ public class Config implements Parcelable
         if (config2.hasSyncThreshold()) {
             merger.setSyncThreshold(config2.getSyncThreshold());
         }
+        if (config2.hasSyncEnabled()) {
+            merger.setSyncEnabled(config2.getSyncEnabled());
+        }
         if (config2.hasHttpHeaders()) {
             merger.setHttpHeaders(config2.getHttpHeaders());
         }

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

@@ -203,11 +203,44 @@ public class HttpPostService {
         }
         stream.close();
         byte[] bodyBytes = baos.toByteArray();
+        String jsonString = new String(bodyBytes, StandardCharsets.UTF_8);
+
+        // When form-urlencoded and body is a JSON array, send one POST per location (same flat
+        // format as real-time posting) so the same server endpoint accepts both.
+        if (isFormUrlEncoded) {
+            try {
+                Object parsed = new JSONTokener(jsonString).nextValue();
+                if (parsed instanceof JSONArray) {
+                    JSONArray arr = (JSONArray) parsed;
+                    int len = arr.length();
+                    if (len == 0) {
+                        if (listener != null) listener.onProgress(100);
+                        return 200;
+                    }
+                    for (int i = 0; i < len; i++) {
+                        JSONObject item = arr.getJSONObject(i);
+                        HttpPostService perRequest = new HttpPostService(mUrl);
+                        int code = perRequest.postJSON(item, headers);
+                        if (listener != null && len > 0) {
+                            listener.onProgress((i + 1) * 100 / len);
+                        }
+                        if (code < 200 || code >= 300) {
+                            return code;
+                        }
+                    }
+                    if (listener != null) {
+                        listener.onProgress(100);
+                    }
+                    return 200;
+                }
+            } catch (Exception e) {
+                // Fall through to single-POST with jsonToUrlEncoded (e.g. array wrap)
+            }
+        }
 
         byte[] outputBytes;
         if (isFormUrlEncoded) {
             try {
-                String jsonString = new String(bodyBytes, StandardCharsets.UTF_8);
                 String formBody = jsonToUrlEncoded(jsonString);
                 outputBytes = formBody.getBytes(StandardCharsets.UTF_8);
             } catch (Exception e) {

package/android/common/src/main/java/com/marianhello/bgloc/data/LocationDAO.java

@@ -19,4 +19,9 @@ public interface LocationDAO {
     BackgroundLocation deleteFirstUnpostedLocation();
     int deleteAllLocations();
     int deleteUnpostedLocations();
+    /**
+     * Delete (mark as deleted) all locations that are pending sync to syncUrl.
+     * Same effect as discarding the pending sync queue without sending to server.
+     */
+    int deletePendingSyncLocations();
 }

package/android/common/src/main/java/com/marianhello/bgloc/data/provider/ContentProviderLocationDAO.java

@@ -392,4 +392,15 @@ public class ContentProviderLocationDAO implements LocationDAO {
 
         return mResolver.update(mContentUri, values, whereClause, whereArgs);
     }
+
+    @Override
+    public int deletePendingSyncLocations() {
+        ContentValues values = new ContentValues();
+        values.put(LocationEntry.COLUMN_NAME_STATUS, BackgroundLocation.DELETED);
+
+        String whereClause = LocationEntry.COLUMN_NAME_STATUS + " = ?";
+        String[] whereArgs = { String.valueOf(BackgroundLocation.SYNC_PENDING) };
+
+        return mResolver.update(mContentUri, values, whereClause, whereArgs);
+    }
 }