@josuelmm/cordova-background-geolocation 3.1.1 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [3.2.0](https://github.com/josuelmm/cordova-background-geolocation/tree/3.2.0) (2026-02-28)
+
+### Added
+
+- **Session API for route/recording** — Lets the app keep a full copy of all locations for the *current recording session* in the plugin, independent of the sync queue. When the user reopens the app without internet, the app can restore the entire route from the plugin (no need to rely on `localStorage` for points).
+  - **`startSession(success?, fail?)`** — Call when the user starts a route (e.g. "Start" button). Clears the session table and from then on every new location is also stored in the session table. Session data is **not** removed when locations are synced to the server.
+  - **`getSessionLocations(success?, fail?)`** — Returns all locations currently in the session table, ordered by time. Same format as `Location` (latitude, longitude, time, speed, altitude, bearing, accuracy, etc.). Use when reopening without internet to rebuild the track.
+  - **`clearSession(success?, fail?)`** — Call when the route is finished and sync has succeeded. Clears the session table so the next `startSession()` starts clean.
+  - **`getSessionLocationsCount(success?, fail?)`** — Returns the number of locations in the session (e.g. to show "X points" without loading all).
+- **Android:** New table `location_session` (DB version 20), `SessionLocationDAO`, and persistence from `PostLocationTask` when session is active. Session state stored in `SharedPreferences`.
+- **iOS:** New table `location_session` (DB version 5), `MAURSessionLocationDAO` (singleton), and persistence from `MAURPostLocationTask` when session is active. Session state stored in `NSUserDefaults`.
+- **JS / TypeScript:** The four session methods are available on the global plugin and in the `.d.ts`. **Angular:** `BackgroundGeolocationService` exposes `startSession`, `getSessionLocations`, `clearSession`, `getSessionLocationsCount`.
+
+### Documentation
+
+- **README.md** — New section *"New in 3.2.0"* describing the session API and typical flow (start route → startSession; reopen without internet → getSessionLocations; finish route → clearSession).
+- **docs/api.md** — Quick reference and full sections for `startSession`, `getSessionLocations`, `clearSession`, `getSessionLocationsCount`.
+- **docs/angular.md** — Session methods added to the methods table.
+- **docs/index.md** — Mention of session/route restore without internet.
+- **CHANGELOG.md** — This entry. **HISTORY.md** — 3.2.0 session methods. **RELEASE.MD** — Version example updated.
+
+### Changed
+
+- Version bump to 3.2.0.
+
+[Full Changelog](https://github.com/josuelmm/cordova-background-geolocation/compare/3.1.1...3.2.0)
+
+---
+
 ## [3.1.1](https://github.com/josuelmm/cordova-background-geolocation/tree/3.1.1) (2026-02-27)
 
 ### Added

package/HISTORY.md

@@ -2,6 +2,12 @@
 
 **for cordova-plugin-background-geolocation**
 
+## [3.2.0] - 2026-02-28
+
+### Added
+
+- **Session API (route/recording):** `startSession()`, `getSessionLocations()`, `clearSession()`, `getSessionLocationsCount()`. Separate session table (Android DB v20, iOS DB v5) so the app can restore the full route when reopening without internet. Session is cleared on `startSession()` and `clearSession()`; not cleared when sync succeeds.
+
 ## [3.1.0] - 2019-09-24
 
 ### Fixed

package/README.md

@@ -316,11 +316,15 @@ More on sync (headers, retries, postTemplate): [HTTP posting](docs/http_posting.
 | `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"). |
+| `getPluginVersion(success, fail)` | Plugin version string (e.g. "3.2.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. |
+| `startSession(success, fail)` | Start session: clear session table and store all new locations until `clearSession()`. |
+| `getSessionLocations(success, fail)` | All locations in current session (restore route when reopening without internet). |
+| `clearSession(success, fail)` | Clear session table (call when route finished and sync OK). |
+| `getSessionLocationsCount(success, fail)` | Number of locations in current session. |
 
 All methods return a **Promise** if you omit the `success` / `fail` callbacks.
 
@@ -343,6 +347,15 @@ Subscribe with `BackgroundGeolocation.on(eventName, callback)`. Unsubscribe with
 
 Full event payloads and options: [Events](docs/events.md). Full API (all options, all methods): [API](docs/api.md).
 
+### New in 3.2.0
+
+- **Session API for route/recording** — Store all locations for the *current route* in the plugin, independent of sync. When the user reopens the app without internet, you can restore the full track from the plugin (no need for `localStorage` for points).
+  - **`startSession()`** — Call when the user starts a route. Clears the session table; from then on every location is also saved in the session table (and not removed when synced).
+  - **`getSessionLocations()`** — Returns all session locations (same format as `Location`: latitude, longitude, time, speed, altitude, bearing, accuracy). Use to rebuild the track after reopening without internet.
+  - **`clearSession()`** — Call when the route is finished and sync succeeded. Clears the session table.
+  - **`getSessionLocationsCount()`** — Returns how many points are in the session (e.g. to show "X points" in the UI).
+- Typical flow: **Start route** → `startSession()` then `start()`. **Reopen without internet** → `getSessionLocations()` and redraw the route. **Finish route and sync OK** → `clearSession()`.
+
 ### 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).
@@ -435,7 +448,7 @@ This README is the main entry point. For more detail, edge cases and examples us
 
 | 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. |
+| **[API reference](docs/api.md)** | Every `configure` option, every method (`configure`, `start`, `stop`, `getPendingSyncCount`, `forceSync`, `clearSync`, `startSession`, `getSessionLocations`, `clearSession`, `getSessionLocationsCount`, `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. |

package/RELEASE.MD

@@ -1,7 +1,7 @@
 In order to release a version the following actions are needed:
 
 1. **Version and docs**
-   - Set the new version (e.g. `3.1.1`) in:
+   - Set the new version (e.g. `3.2.0`) in:
      - `package.json` (`version` field)
      - `plugin.xml` (root `<plugin>` attribute `version`)
    - Add a release entry in `CHANGELOG.md` (date, Added/Fixed/Changed/Documentation).
@@ -12,5 +12,5 @@ In order to release a version the following actions are needed:
 
 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`).
+   - Create a tag with the version name (e.g. `v3.2.0`).
    - Publish the release. GitHub Actions will publish the package to npm.

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

@@ -73,10 +73,14 @@ public class BackgroundGeolocationPlugin extends CordovaPlugin implements Plugin
     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_START_SESSION = "startSession";
+    public static final String ACTION_GET_SESSION_LOCATIONS = "getSessionLocations";
+    public static final String ACTION_CLEAR_SESSION = "clearSession";
+    public static final String ACTION_GET_SESSION_LOCATIONS_COUNT = "getSessionLocationsCount";
     public static final String ACTION_GET_PLUGIN_VERSION = "getPluginVersion";
 
     /** Plugin version; keep in sync with plugin.xml. */
-    public static final String PLUGIN_VERSION = "3.1.0";
+    public static final String PLUGIN_VERSION = "3.2.0";
 
     private BackgroundGeolocationFacade facade;
 
@@ -399,6 +403,49 @@ public class BackgroundGeolocationPlugin extends CordovaPlugin implements Plugin
                 }
             });
             return true;
+        } else if (ACTION_START_SESSION.equals(action)) {
+            runOnWebViewThread(new Runnable() {
+                @Override
+                public void run() {
+                    facade.startSession();
+                    callbackContext.success();
+                }
+            });
+            return true;
+        } else if (ACTION_GET_SESSION_LOCATIONS.equals(action)) {
+            runOnWebViewThread(new Runnable() {
+                @Override
+                public void run() {
+                    try {
+                        callbackContext.success(getSessionLocations());
+                    } catch (JSONException e) {
+                        callbackContext.sendPluginResult(ErrorPluginResult.from("getSessionLocations failed", e, PluginException.JSON_ERROR));
+                    }
+                }
+            });
+            return true;
+        } else if (ACTION_CLEAR_SESSION.equals(action)) {
+            runOnWebViewThread(new Runnable() {
+                @Override
+                public void run() {
+                    facade.clearSession();
+                    callbackContext.success();
+                }
+            });
+            return true;
+        } else if (ACTION_GET_SESSION_LOCATIONS_COUNT.equals(action)) {
+            runOnWebViewThread(new Runnable() {
+                @Override
+                public void run() {
+                    try {
+                        int count = facade.getSessionLocationsCount();
+                        callbackContext.success(count);
+                    } catch (Exception e) {
+                        callbackContext.sendPluginResult(ErrorPluginResult.from("getSessionLocationsCount failed", e, PluginException.SERVICE_ERROR));
+                    }
+                }
+            });
+            return true;
         } else if (ACTION_GET_PLUGIN_VERSION.equals(action)) {
             callbackContext.success(PLUGIN_VERSION);
             return true;
@@ -557,6 +604,15 @@ public class BackgroundGeolocationPlugin extends CordovaPlugin implements Plugin
         return jsonLocationsArray;
     }
 
+    private JSONArray getSessionLocations() throws JSONException {
+        JSONArray jsonLocationsArray = new JSONArray();
+        Collection<BackgroundLocation> locations = facade.getSessionLocations();
+        for (BackgroundLocation location : locations) {
+            jsonLocationsArray.put(location.toJSONObjectWithId());
+        }
+        return jsonLocationsArray;
+    }
+
     private JSONArray getLogs(Integer limit, int offset, String minLevel) throws Exception {
         JSONArray jsonLogsArray = new JSONArray();
         Collection<LogEntry> logEntries = facade.getLogEntries(limit, offset, minLevel);

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

@@ -26,11 +26,13 @@ import com.marianhello.bgloc.data.BackgroundLocation;
 import com.marianhello.bgloc.data.ConfigurationDAO;
 import com.marianhello.bgloc.data.DAOFactory;
 import com.marianhello.bgloc.data.LocationDAO;
+import com.marianhello.bgloc.data.SessionLocationDAO;
 import com.marianhello.bgloc.provider.LocationProvider;
 import com.marianhello.bgloc.service.LocationService;
 import com.marianhello.bgloc.service.LocationServiceImpl;
 import com.marianhello.bgloc.service.LocationServiceProxy;
 import com.marianhello.bgloc.data.LocationTransform;
+import com.marianhello.bgloc.data.sqlite.SQLiteSessionLocationDAO;
 import com.marianhello.bgloc.sync.AccountHelper;
 import com.marianhello.bgloc.sync.NotificationHelper;
 import com.marianhello.bgloc.sync.SyncService;
@@ -294,6 +296,30 @@ public class BackgroundGeolocationFacade {
         return dao.getValidLocationsAndDelete();
     }
 
+    /** Clear session table and start storing all new locations in session. Call when user starts a route. */
+    public void startSession() {
+        SessionLocationDAO dao = new SQLiteSessionLocationDAO(getContext());
+        dao.startSession();
+    }
+
+    /** Return all locations stored in the current session (ordered by time). */
+    public Collection<BackgroundLocation> getSessionLocations() {
+        SessionLocationDAO dao = new SQLiteSessionLocationDAO(getContext());
+        return dao.getSessionLocations();
+    }
+
+    /** Clear session table and stop storing. Call when route is finished and sync OK. */
+    public void clearSession() {
+        SessionLocationDAO dao = new SQLiteSessionLocationDAO(getContext());
+        dao.clearSession();
+    }
+
+    /** Number of locations in the current session. */
+    public int getSessionLocationsCount() {
+        SessionLocationDAO dao = new SQLiteSessionLocationDAO(getContext());
+        return dao.getSessionLocationsCount();
+    }
+
     public BackgroundLocation getStationaryLocation() {
         return mStationaryLocation;
     }

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

@@ -2,6 +2,7 @@ package com.marianhello.bgloc;
 
 import com.marianhello.bgloc.data.BackgroundLocation;
 import com.marianhello.bgloc.data.LocationDAO;
+import com.marianhello.bgloc.data.SessionLocationDAO;
 import com.marianhello.logging.LoggerManager;
 
 import org.json.JSONArray;
@@ -29,6 +30,7 @@ import java.util.concurrent.TimeUnit;
  */
 public class PostLocationTask {
     private final LocationDAO mLocationDAO;
+    private final SessionLocationDAO mSessionDAO;
     private final PostLocationTaskListener mTaskListener;
     private final ConnectivityListener mConnectivityListener;
 
@@ -48,10 +50,17 @@ public class PostLocationTask {
 
     public PostLocationTask(LocationDAO dao, PostLocationTaskListener taskListener,
                             ConnectivityListener connectivityListener) {
+        this(dao, null, taskListener, connectivityListener);
+    }
+
+    public PostLocationTask(LocationDAO dao, SessionLocationDAO sessionDAO,
+                            PostLocationTaskListener taskListener,
+                            ConnectivityListener connectivityListener) {
         logger = LoggerManager.getLogger(PostLocationTask.class);
         logger.info("Creating PostLocationTask");
 
         mLocationDAO = dao;
+        mSessionDAO = sessionDAO;
         mTaskListener = taskListener;
         mConnectivityListener = connectivityListener;
 
@@ -84,6 +93,10 @@ public class PostLocationTask {
         long locationId = mLocationDAO.persistLocation(location);
         location.setLocationId(locationId);
 
+        if (mSessionDAO != null && mSessionDAO.isSessionActive()) {
+            mSessionDAO.persistSessionLocation(location);
+        }
+
         try {
             mExecutor.execute(new Runnable() {
                 @Override

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

@@ -0,0 +1,18 @@
+package com.marianhello.bgloc.data;
+
+import java.util.Collection;
+
+/**
+ * DAO for the current recording session locations.
+ * Session is independent of sync: locations are kept until startSession() or clearSession().
+ */
+public interface SessionLocationDAO {
+    /** Clear session table and set session active. Call when user starts a route. */
+    void startSession();
+    /** Clear session table and set session inactive. Call when route is finished and sync OK. */
+    void clearSession();
+    boolean isSessionActive();
+    void persistSessionLocation(BackgroundLocation location);
+    Collection<BackgroundLocation> getSessionLocations();
+    int getSessionLocationsCount();
+}

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

@@ -8,6 +8,7 @@ import android.util.Log;
 
 import com.marianhello.bgloc.data.sqlite.SQLiteLocationContract.LocationEntry;
 import com.marianhello.bgloc.data.sqlite.SQLiteConfigurationContract.ConfigurationEntry;
+import com.marianhello.bgloc.data.sqlite.SQLiteSessionContract.SessionEntry;
 
 import java.util.ArrayList;
 
@@ -21,7 +22,7 @@ import static com.marianhello.bgloc.data.sqlite.SQLiteLocationContract.LocationE
 public class SQLiteOpenHelper extends android.database.sqlite.SQLiteOpenHelper {
     private static final String TAG = SQLiteOpenHelper.class.getName();
     public static final String SQLITE_DATABASE_NAME = "cordova_bg_geolocation.db";
-    public static final int DATABASE_VERSION = 19;
+    public static final int DATABASE_VERSION = 20;
 
     public static final String TEXT_TYPE = " TEXT";
     public static final String INTEGER_TYPE = " INTEGER";
@@ -66,6 +67,8 @@ public class SQLiteOpenHelper extends android.database.sqlite.SQLiteOpenHelper {
         execAndLogSql(db, SQL_CREATE_CONFIG_TABLE);
         execAndLogSql(db, SQL_CREATE_LOCATION_TABLE_TIME_IDX);
         execAndLogSql(db, SQL_CREATE_LOCATION_TABLE_BATCH_ID_IDX);
+        execAndLogSql(db, SessionEntry.SQL_CREATE_SESSION_TABLE);
+        execAndLogSql(db, SessionEntry.SQL_CREATE_SESSION_TABLE_TIME_IDX);
     }
 
     @Override
@@ -137,6 +140,9 @@ public class SQLiteOpenHelper extends android.database.sqlite.SQLiteOpenHelper {
                         " ADD COLUMN " + ConfigurationEntry.COLUMN_NAME_SHOW_TIME + INTEGER_TYPE);
                 alterSql.add("ALTER TABLE " + ConfigurationEntry.TABLE_NAME +
                         " ADD COLUMN " + ConfigurationEntry.COLUMN_NAME_SHOW_DISTANCE + INTEGER_TYPE);
+            case 19:
+                alterSql.add(SessionEntry.SQL_CREATE_SESSION_TABLE);
+                alterSql.add(SessionEntry.SQL_CREATE_SESSION_TABLE_TIME_IDX);
 
                 break; // DO NOT FORGET TO MOVE DOWN BREAK ON DB UPGRADE!!!
             default:
@@ -154,6 +160,7 @@ public class SQLiteOpenHelper extends android.database.sqlite.SQLiteOpenHelper {
         // we don't support db downgrade yet, instead we drop table and start over
         execAndLogSql(db, SQL_DROP_LOCATION_TABLE);
         execAndLogSql(db, SQL_DROP_CONFIG_TABLE);
+        execAndLogSql(db, SessionEntry.SQL_DROP_SESSION_TABLE);
         onCreate(db);
     }
 

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

@@ -0,0 +1,74 @@
+package com.marianhello.bgloc.data.sqlite;
+
+import android.provider.BaseColumns;
+
+import static com.marianhello.bgloc.data.sqlite.SQLiteOpenHelper.COMMA_SEP;
+import static com.marianhello.bgloc.data.sqlite.SQLiteOpenHelper.INTEGER_TYPE;
+import static com.marianhello.bgloc.data.sqlite.SQLiteOpenHelper.REAL_TYPE;
+import static com.marianhello.bgloc.data.sqlite.SQLiteOpenHelper.TEXT_TYPE;
+
+/**
+ * Contract for the "session" location table.
+ * Stores all locations for the current recording session (route).
+ * Cleared on startSession() and clearSession(); not cleared when sync succeeds.
+ */
+public final class SQLiteSessionContract {
+
+    public SQLiteSessionContract() {}
+
+    public static abstract class SessionEntry implements BaseColumns {
+        public static final String TABLE_NAME = "location_session";
+        public static final String COLUMN_NAME_NULLABLE = "NULLHACK";
+        public static final String COLUMN_NAME_TIME = "time";
+        public static final String COLUMN_NAME_ACCURACY = "accuracy";
+        public static final String COLUMN_NAME_VERTICAL_ACCURACY = "vertical_accuracy";
+        public static final String COLUMN_NAME_SPEED = "speed";
+        public static final String COLUMN_NAME_BEARING = "bearing";
+        public static final String COLUMN_NAME_ALTITUDE = "altitude";
+        public static final String COLUMN_NAME_LATITUDE = "latitude";
+        public static final String COLUMN_NAME_LONGITUDE = "longitude";
+        public static final String COLUMN_NAME_RADIUS = "radius";
+        public static final String COLUMN_NAME_HAS_ACCURACY = "has_accuracy";
+        public static final String COLUMN_NAME_HAS_VERTICAL_ACCURACY = "has_vertical_accuracy";
+        public static final String COLUMN_NAME_HAS_SPEED = "has_speed";
+        public static final String COLUMN_NAME_HAS_BEARING = "has_bearing";
+        public static final String COLUMN_NAME_HAS_ALTITUDE = "has_altitude";
+        public static final String COLUMN_NAME_HAS_RADIUS = "has_radius";
+        public static final String COLUMN_NAME_PROVIDER = "provider";
+        public static final String COLUMN_NAME_LOCATION_PROVIDER = "service_provider";
+        public static final String COLUMN_NAME_STATUS = "valid";
+        public static final String COLUMN_NAME_BATCH_START_MILLIS = "batch_start";
+        public static final String COLUMN_NAME_MOCK_FLAGS = "mock_flags";
+
+        public static final String SQL_CREATE_SESSION_TABLE =
+                "CREATE TABLE " + SessionEntry.TABLE_NAME + " (" +
+                        SessionEntry._ID + " INTEGER PRIMARY KEY AUTOINCREMENT," +
+                        SessionEntry.COLUMN_NAME_TIME + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_ACCURACY + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_VERTICAL_ACCURACY + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_SPEED + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_BEARING + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_ALTITUDE + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_LATITUDE + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_LONGITUDE + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_RADIUS + REAL_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_ACCURACY + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_VERTICAL_ACCURACY + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_SPEED + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_BEARING + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_ALTITUDE + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_HAS_RADIUS + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_PROVIDER + TEXT_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_LOCATION_PROVIDER + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_STATUS + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_BATCH_START_MILLIS + INTEGER_TYPE + COMMA_SEP +
+                        SessionEntry.COLUMN_NAME_MOCK_FLAGS + INTEGER_TYPE +
+                        " )";
+
+        public static final String SQL_DROP_SESSION_TABLE =
+                "DROP TABLE IF EXISTS " + SessionEntry.TABLE_NAME;
+
+        public static final String SQL_CREATE_SESSION_TABLE_TIME_IDX =
+                "CREATE INDEX session_time_idx ON " + SessionEntry.TABLE_NAME + " (" + SessionEntry.COLUMN_NAME_TIME + ")";
+    }
+}

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

@@ -0,0 +1,169 @@
+package com.marianhello.bgloc.data.sqlite;
+
+import android.content.ContentValues;
+import android.content.Context;
+import android.database.Cursor;
+import android.database.sqlite.SQLiteDatabase;
+import com.marianhello.bgloc.data.BackgroundLocation;
+import com.marianhello.bgloc.data.SessionLocationDAO;
+
+import java.util.ArrayList;
+import java.util.Collection;
+
+public class SQLiteSessionLocationDAO implements SessionLocationDAO {
+
+    private static final String PREFS_NAME = "bgloc_session";
+    private static final String KEY_SESSION_ACTIVE = "session_active";
+
+    private final SQLiteDatabase db;
+    private final Context context;
+
+    public SQLiteSessionLocationDAO(Context context) {
+        this.context = context.getApplicationContext();
+        SQLiteOpenHelper helper = SQLiteOpenHelper.getHelper(this.context);
+        this.db = helper.getWritableDatabase();
+    }
+
+    @Override
+    public void startSession() {
+        db.delete(SQLiteSessionContract.SessionEntry.TABLE_NAME, null, null);
+        setSessionActive(true);
+    }
+
+    @Override
+    public void clearSession() {
+        db.delete(SQLiteSessionContract.SessionEntry.TABLE_NAME, null, null);
+        setSessionActive(false);
+    }
+
+    @Override
+    public boolean isSessionActive() {
+        return context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .getBoolean(KEY_SESSION_ACTIVE, false);
+    }
+
+    private void setSessionActive(boolean active) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .edit()
+                .putBoolean(KEY_SESSION_ACTIVE, active)
+                .apply();
+    }
+
+    @Override
+    public void persistSessionLocation(BackgroundLocation location) {
+        if (!isSessionActive() || location == null) return;
+        ContentValues values = getContentValues(location);
+        db.insertOrThrow(SQLiteSessionContract.SessionEntry.TABLE_NAME,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_NULLABLE, values);
+    }
+
+    @Override
+    public Collection<BackgroundLocation> getSessionLocations() {
+        Collection<BackgroundLocation> locations = new ArrayList<>();
+        String orderBy = SQLiteSessionContract.SessionEntry.COLUMN_NAME_TIME + " ASC";
+        Cursor cursor = null;
+        try {
+            cursor = db.query(
+                    SQLiteSessionContract.SessionEntry.TABLE_NAME,
+                    queryColumns(),
+                    null, null, null, null, orderBy);
+            while (cursor.moveToNext()) {
+                locations.add(hydrate(cursor));
+            }
+        } finally {
+            if (cursor != null) cursor.close();
+        }
+        return locations;
+    }
+
+    @Override
+    public int getSessionLocationsCount() {
+        Cursor cursor = null;
+        try {
+            cursor = db.rawQuery("SELECT COUNT(*) FROM " + SQLiteSessionContract.SessionEntry.TABLE_NAME, null);
+            return cursor.moveToFirst() ? cursor.getInt(0) : 0;
+        } finally {
+            if (cursor != null) cursor.close();
+        }
+    }
+
+    private BackgroundLocation hydrate(Cursor c) {
+        BackgroundLocation l = new BackgroundLocation(c.getString(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_PROVIDER)));
+        l.setTime(c.getLong(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_TIME)));
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ACCURACY)) == 1) {
+            l.setAccuracy(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_ACCURACY)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_VERTICAL_ACCURACY)) == 1) {
+            l.setVerticalAccuracy(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_VERTICAL_ACCURACY)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_SPEED)) == 1) {
+            l.setSpeed(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_SPEED)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_BEARING)) == 1) {
+            l.setBearing(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_BEARING)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ALTITUDE)) == 1) {
+            l.setAltitude(c.getDouble(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_ALTITUDE)));
+        }
+        if (c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_RADIUS)) == 1) {
+            l.setRadius(c.getFloat(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_RADIUS)));
+        }
+        l.setLatitude(c.getDouble(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LATITUDE)));
+        l.setLongitude(c.getDouble(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LONGITUDE)));
+        l.setLocationProvider(c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LOCATION_PROVIDER)));
+        l.setLocationId(c.getLong(c.getColumnIndex(SQLiteSessionContract.SessionEntry._ID)));
+        l.setMockFlags(c.getInt(c.getColumnIndex(SQLiteSessionContract.SessionEntry.COLUMN_NAME_MOCK_FLAGS)));
+        return l;
+    }
+
+    private ContentValues getContentValues(BackgroundLocation l) {
+        ContentValues values = new ContentValues();
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_PROVIDER, l.getProvider());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_TIME, l.getTime());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_ACCURACY, l.getAccuracy());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_VERTICAL_ACCURACY, l.getVerticalAccuracy());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_SPEED, l.getSpeed());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_BEARING, l.getBearing());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_ALTITUDE, l.getAltitude());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_RADIUS, l.getRadius());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LATITUDE, l.getLatitude());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LONGITUDE, l.getLongitude());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ACCURACY, l.hasAccuracy() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_VERTICAL_ACCURACY, l.hasVerticalAccuracy() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_SPEED, l.hasSpeed() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_BEARING, l.hasBearing() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ALTITUDE, l.hasAltitude() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_RADIUS, l.hasRadius() ? 1 : 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_LOCATION_PROVIDER, l.getLocationProvider());
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_STATUS, 0);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_BATCH_START_MILLIS, 0L);
+        values.put(SQLiteSessionContract.SessionEntry.COLUMN_NAME_MOCK_FLAGS, l.getMockFlags());
+        return values;
+    }
+
+    private String[] queryColumns() {
+        return new String[]{
+                SQLiteSessionContract.SessionEntry._ID,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_PROVIDER,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_TIME,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_ACCURACY,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_VERTICAL_ACCURACY,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_SPEED,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_BEARING,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_ALTITUDE,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_RADIUS,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_LATITUDE,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_LONGITUDE,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ACCURACY,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_VERTICAL_ACCURACY,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_SPEED,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_BEARING,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_ALTITUDE,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_HAS_RADIUS,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_LOCATION_PROVIDER,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_STATUS,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_BATCH_START_MILLIS,
+                SQLiteSessionContract.SessionEntry.COLUMN_NAME_MOCK_FLAGS
+        };
+    }
+}

package/android/common/src/main/java/com/marianhello/bgloc/service/LocationServiceImpl.java

@@ -49,7 +49,9 @@ import com.marianhello.bgloc.data.BackgroundLocation;
 import com.marianhello.bgloc.data.ConfigurationDAO;
 import com.marianhello.bgloc.data.DAOFactory;
 import com.marianhello.bgloc.data.LocationDAO;
+import com.marianhello.bgloc.data.SessionLocationDAO;
 import com.marianhello.bgloc.data.LocationTransform;
+import com.marianhello.bgloc.data.sqlite.SQLiteSessionLocationDAO;
 import com.marianhello.bgloc.headless.AbstractTaskRunner;
 import com.marianhello.bgloc.headless.ActivityTask;
 import com.marianhello.bgloc.headless.LocationTask;
@@ -125,6 +127,7 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
     private HandlerThread mHandlerThread;
     private ServiceHandler mServiceHandler;
     private LocationDAO mLocationDAO;
+    private SessionLocationDAO mSessionDAO;
     private PostLocationTask mPostLocationTask;
     private String mHeadlessTaskRunnerClass;
     private TaskRunner mHeadlessTaskRunner;
@@ -255,8 +258,9 @@ public class LocationServiceImpl extends Service implements ProviderDelegate, Lo
         ContentResolver.setSyncAutomatically(mSyncAccount, authority, true);
 
         mLocationDAO = DAOFactory.createLocationDAO(this);
+        mSessionDAO = new SQLiteSessionLocationDAO(this);
 
-        mPostLocationTask = new PostLocationTask(mLocationDAO,
+        mPostLocationTask = new PostLocationTask(mLocationDAO, mSessionDAO,
                 new PostLocationTask.PostLocationTaskListener() {
                     @Override
                     public void onRequestedAbortUpdates() {

package/angular/background-geolocation.service.ts

@@ -168,6 +168,34 @@ export class BackgroundGeolocationService {
     return this.ensurePlugin().getPendingSyncCount(success, fail);
   }
 
+  startSession(
+    success?: () => void,
+    fail?: (error: any) => void
+  ): Promise<void> {
+    return this.ensurePlugin().startSession(success, fail);
+  }
+
+  getSessionLocations(
+    success?: (locations: any[]) => void,
+    fail?: (error: any) => void
+  ): Promise<any[]> {
+    return this.ensurePlugin().getSessionLocations(success, fail);
+  }
+
+  clearSession(
+    success?: () => void,
+    fail?: (error: any) => void
+  ): Promise<void> {
+    return this.ensurePlugin().clearSession(success, fail);
+  }
+
+  getSessionLocationsCount(
+    success?: (count: number) => void,
+    fail?: (error: any) => void
+  ): Promise<number> {
+    return this.ensurePlugin().getSessionLocationsCount(success, fail);
+  }
+
   getConfig(
     success?: (config: any) => void,
     fail?: (error: any) => void