Background Geolocation for Cordova: tracking that switches itself off

A location SDK for apps that must keep watching

Background Geolocation for Cordova is described as a background location-tracking and geofencing SDK for iOS and Android, built on Cordova. The problem it addresses is specific to mobile applications that need to know where the user has been while the app is not in the foreground. A web view cannot do that on its own, and the platform location APIs are not designed to be left running indefinitely, so a Cordova application that wants continuous tracking has to reach for a native module. That is what this repository is. The audience is Cordova and Ionic developers building delivery, logistics, field service or attendance applications, where the app is closed for most of the working day and the location trace has to continue anyway. The package is published to npm as cordova-background-geolocation-lt, and the repository includes an Ionic and Angular example app under example/ with a hello-world project as well.

Motion detection is the battery strategy

The mechanism that distinguishes this SDK is that it does not simply keep location services running. It uses the motion-detection APIs, that is the accelerometer, the gyroscope and the magnetometer, to decide whether the device is moving or stationary, and it changes its behaviour accordingly. When the device is moving, location recording starts automatically at the configured distanceFilter in metres, so the recording rate follows the configured distance rather than a timer. When the device is stationary, location services turn off automatically to conserve battery. This is the part of the design that makes background tracking viable on a phone, because the naive approach, a permanently active location subscription, drains a battery in hours. The same idea is why the SDK describes itself as motion-detection intelligence rather than a plain geolocation wrapper. The trade-off is that behaviour becomes state dependent: your application has to reason about a tracker that is sometimes off, and a workflow that assumes a fresh fix on demand will need the plugin's ready and provider events rather than a plain call.

Debug builds are free, release builds need a key

This is a commercial SDK, and the licensing model is spelled out in the README. The SDK is fully functional in DEBUG builds, with no license required, so you can try it before you buy anything. A license is required for RELEASE builds on both iOS and Android, and a free 30-day trial license can be generated for testing a release build. The version boundary is the detail to note. This is version 5, and the README states that v4.x license keys do not work with v5, so you have to log in to the customer dashboard to generate a v5 key, and a migration guide is provided in the repository at help/MIGRATION-GUIDE-v5.md for the move from the previous line. The licence files in the repository are also inconsistent about which licence applies. The repository licence field is classified as a custom licence GitHub cannot categorise and points at the LICENSE.md file, the README ends with an MIT copyright line for Transistor Software, and the package manifest declares the licence as Apache-2.0. If you are shipping this in a commercial product, the file and the purchase terms are what govern, not the badge in the README.

The Cordova dependency matrix in the manifest

The manifest is where the compatibility rules live, and it uses the Cordova engines mechanism to express them as a matrix rather than a single minimum version. Three rows are declared, keyed by the Cordova version of the host project. For a project on a Cordova version below 2.9.0, the requirements are cordova at 6.4.0 or newer, cordova-android at 6.0.0 or newer and cordova-ios at 4.3.0 or newer. For 2.9.0, the requirements rise to cordova at 7.1.0, cordova-android at 6.3.0 and cordova-ios at 4.4.0. For 2.12.0 and above, cordova stays at 7.1.0, cordova-android moves to 7.0.0 and cordova-ios stays at 4.4.0:

  "engines": {
    "cordovaDependencies": {
      "<2.9.0": {
        "cordova": ">=6.4.0",
        "cordova-android": ">=6.0.0",
        "cordova-ios": ">=4.3.0"
      },

and the newer rows read:

      "2.9.0": {
        "cordova": ">=7.1.0",
        "cordova-android": ">=6.3.0",
        "cordova-ios": ">=4.4.0"
      },
      "2.12.0": {
        "cordova": ">=7.1.0",
        "cordova-android": ">=7.0.0",
        "cordova-ios": ">=4.4.0"
      }

The manifest also declares the plugin id cordova-background-geolocation-lt with the ios and android platforms, an entry point of ./src/index.js with TypeScript definitions at ./src/index.d.ts, and a single runtime dependency on @transistorsoft/background-geolocation-types at version 5.3.8 or newer. The current package version is 5.5.0.

The plugin ships its own test script

The repository includes a test suite that runs under Node, and the manifest wires it to a single command. The test script runs four test files in sequence, covering the registry, the enums, the transistor token and the removal of geofences:

  "scripts": {
    "test": "node test/registry.test.js && node test/enums.test.js && node test/transistor-token.test.js && node test/remove-geofences.test.js",
    "preflight": "scripts/preflight.sh",
    "release": "scripts/release.sh"
  },

Those four files are visible in the repository layout under test/, alongside a test/ directory in the plugin. The other two scripts are the operational ones, a preflight script that runs before publishing and a release script, both under scripts/ in the shell. The presence of a release script and a RELEASING.md file at the root tells you how a version gets published, which matters because this package is versioned against a commercial product line rather than a public open source release train.

The same native core, six ways to reach it

The SDK availability table shows that this Cordova repository is one front end over a family of products, and that is the clearest way to understand its architecture. Cordova is this repository, the package name cordova-background-geolocation-lt. React Native and Expo are served by react-native-background-geolocation, and Flutter by flutter_background_geolocation, both from separate repositories. Capacitor is a different repository again, with the npm package @transistorsoft/capacitor-background-geolocation. The native packages for Swift on iOS and Kotlin on Android live in native-background-geolocation and are published as background-geolocation. The difference in approach between these options is in the bridge rather than in the behaviour. The native Swift and Kotlin packages give you the underlying implementation without a JavaScript layer, which is what you would want in a native application, while the Cordova, React Native, Flutter and Capacitor packages are the JavaScript facing wrappers with the same feature set described in the README. For an existing Cordova codebase, this repository is the supported path rather than a port of the native SDK.

Documentation, examples and the maintenance trail

The plugin's own documentation lives off the repository, at docs.transistorsoft.com, split into a setup guide, an API reference and an examples section, and the README points to the Cordova pages of each. Inside the repository there is more: the help/ directory holds the migration guide, docs/ holds the package documentation, and example/ holds the Ionic and Angular example application plus a hello-world project. The root also carries a CHANGELOG.md, a RELEASING.md, an ISSUE_TEMPLATE.md and a plugin.xml, the file Cordova reads to install the native pieces, with bin/, src/ and www/ for the plugin code and the web assets. On the maintenance side, the repository publishes no GitHub releases, so the changelog in the tree is the version history, and the npm version badge in the README is the current published version. The default branch is master and the last push to it was on 2026-10-10, so work continues on the branch that carries the current version 5 line.

Editorial conclusion

cordova-background-geolocation-lt fits teams shipping a Cordova or Ionic app that must record location while the screen is off and cannot afford to keep the GPS running all day, and who are prepared to buy a release licence. It is a poor fit for a hobby project or a debug-only build that expects to ship, since release builds require a purchased key and version 4 keys do not work with version 5. Before committing, run the plugin's own test script and the example app in the Ionic directory, and confirm the licence terms in the LICENSE file, because the README's licence line and the package manifest name different licences.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. transistorsoft/cordova-background-geolocation-lt on GitHub