Background geolocation for Flutter that switches itself off

Motion detection decides when the tracker records at all

The mechanism behind this SDK is a change of state on the device rather than a fixed polling interval. It uses motion-detection APIs, specifically the accelerometer, gyroscope and magnetometer, to detect when the device is moving or stationary, and the two states have different consequences.

When the device is moving, location recording starts automatically at the configured distanceFilter, expressed in metres. When the device is stationary, location services turn off automatically to conserve battery.

That is the whole architecture in two clauses, and it is a good fit for a delivery driver, a field technician or anyone whose phone spends most of the day on a desk. The battery saving is not a background optimisation applied to an always-on service, it is the absence of the service. When the sensors say the phone has not moved, the GPS is not running at all.

The trade-off is a threshold you have to pick. A distanceFilter set too high means a slow walk across a car park produces no points at all, and a filter set too low means the moving state keeps the radio busy. The README does not document a recommended value, so it is a parameter to tune against real movement patterns rather than a default to accept.

v5 invalidated every v4.x licence key

The version notice in the README is the most consequential line for anyone upgrading. This is v5, the previous version lives on the 4.18.3 branch, and v4.x license keys do not work with v5. To use the current release you have to log in to the Customer Dashboard and generate a v5 key, with the Migration Guide at help/MIGRATION-GUIDE-5.0.0.md covering the details.

This is a hard break, not a deprecation window. An existing customer with a working key cannot simply bump the package version, and a key that worked before will not work now. For a product shipping to end users, that means the release build stops validating the moment the version moves, which in practice means key management has to be scheduled alongside the upgrade rather than discovered from a crash report.

The repository is arranged to support that migration. There is a help/ directory holding the migration guide, a CHANGELOG.md at the root, and the older source remains available on its own branch, so a team that is not ready to move can stay on 4.18.3 rather than porting under time pressure.

Debug builds run free, release builds need a purchased key

The licensing section states two separate things and they matter in different contexts. The SDK is fully functional in DEBUG builds and needs no licence, so a developer can try it before buying. A licence is required for RELEASE builds on both iOS and Android, and there is a free 30-day trial licence generator for anyone who needs to test a release build.

In practice that means the evaluation story is unusually good and the production story is a purchase decision. You can write the whole integration, run it on a device, check the geofence callbacks, and only then pay.

It also means the failure mode is late rather than early. A team can go a long way with a free development build and only discover the licensing requirement when the app is ready to ship. The commercial side is run by Transistor Software, with the purchase page on their documentation site and the customer dashboard used for key generation, so the licence key is tied to an account rather than being a file in the repository.

The setup steps live in a separate documentation site

Unlike most Flutter packages, this repository does not carry a copy-paste install command in its README. The documentation links point to a hosted site, with a setup page, an API reference and an examples page under docs.transistorsoft.com, and the repository itself says all information to install and use the SDK can be found there.

The practical consequence is that there is no dependency snippet in the README to copy, and this article does not invent one. The package identity is public though, since the README carries pub.dev badges for flutter_background_geolocation, and the repository contains a pubspec.yaml, an example/ directory with its own pubspec.yaml and a full set of Android and iOS folders, so the project is structured as a normal Flutter plugin with an accompanying sample application.

Two other paths into the codebase exist for teams that need more than the Dart layer. The native repositories for Swift and iOS and for Kotlin and Android are published under the same organisation, and there is a scripts/ directory alongside test/ and lib/. The example README inside the example directory is the closest thing to a local quickstart, and the ISSUE_TEMPLATE.md file at the root indicates the project runs a structured support process.

One engine shipped as Flutter, React Native, Capacitor, Cordova and native

The availability table in the README is really a compatibility map. The Flutter package lives in this repository, and the same background geolocation product is published for React Native as react-native-background-geolocation, for Expo under that same package name, for Capacitor as @transistorsoft/capacitor-background-geolocation, for Cordova as cordova-background-geolocation-lt, and as native Swift and Kotlin packages named background-geolocation.

That breadth says something about the design. The Dart API here is a wrapper over a shared native core rather than a Flutter-specific implementation, which is why an Expo project can use the React Native package and a Cordova project can use the Cordova one while all of them share the same motion-detection behaviour and the same v5 licensing model.

It also gives a team with an existing native or hybrid codebase a way in. The Kotlin and Swift packages carry the same package name on both platforms, background-geolocation, and the documentation site referenced by the README covers the Flutter setup and API in detail.

One caution about the Cordova entry: it is named cordova-background-geolocation-lt, with a different suffix from the others, and the README does not explain the difference, so a Cordova team should confirm what the lt suffix denotes before assuming feature parity with the Flutter package.

An MIT repository wrapping a commercial product

The licence picture here needs two sentences rather than one. The README footer reads MIT © Transistor Software, and a LICENSE file sits at the root of the repository, while the licence field in the repository listing records Apache-2.0. The primary language of the project is Dart, the default branch is master, and the project is not archived.

Whatever the field says, the licence file is the document that governs use, and the repository being open source does not make the SDK free to ship. The README is explicit that a licence is required for release builds on both platforms. The open repository gives you the Dart API, the example application and the native source; the commercial terms govern the compiled artifact you distribute.

That split is the reason the debug-versus-release distinction exists in the first place. Reading the LICENSE file before committing to the product avoids the confusion that the open repository creates, and it lets a legal reviewer see exactly what is being given away and what is being licensed.

Regular commits, no tagged releases to plan against

The maintenance picture is active but not versioned in the way a package consumer would like. The last push was on 2026-10-10, and the repository is not archived, so work is landing. There are no GitHub releases, however, so there is no tag to pin to and no release note feed to diff.

The changelog is in the repository instead, as CHANGELOG.md at the root. That file is the only published account of what changed between versions, and for a package whose updates can change tracking behaviour or require a new key, reading it is part of an upgrade rather than an optional step.

The v5 break is the example worth keeping in mind. A major version with a new key format and a migration guide in help/ is exactly the kind of change that a tag history would have made visible at a glance. Without one, the version key in the project configuration and the CHANGELOG.md file are the two anchors you have, so pin the version in your pubspec.yaml and check the changelog before moving it.

Editorial conclusion

Use flutter_background_geolocation if your Flutter app needs background location with a battery-aware stopping rule, and budget for the commercial licence on release builds rather than treating the repository as free software. Before upgrading, read help/MIGRATION-GUIDE-5.0.0.md and generate a v5 key from the Customer Dashboard, because the v4.x keys do not work with v5. If your requirement is only foreground location, this SDK is more than the job needs.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. transistorsoft/flutter_background_geolocation on GitHub