flutter_background_geolocation

Merge branch 'insertLocation'

• [Fixed] insertLocation() now works — the supplied record is inserted as-given (import-as-is) and the returned Future resolves with the inserted record's uuid. It was previously unimplemented on iOS (the call never resolved) and on Android stored a record with an empty uuid (so destroyLocation() couldn't remove it) and an unvalidated timestamp. Timestamps are now normalized (ISO-8601 or epoch), and a uuid is generated when you don't provide one.
• [Fixed][iOS] A location arriving with a future timestamp (device clock skew) could poison the internal last-location comparator, causing every subsequent location to be rejected until the app was restarted (stalled odometer, no location updates). Future-stamped fixes are now tolerated and the comparator self-heals. Android is unaffected.

• [Fixed][Android] Headless events permanently dropped after the app is relaunched and terminated a second time (FlutterJNI was detached from native C++ — regression introduced in 5.1.2). HeadlessTask.destroyBackgroundIsolate() destroyed the background FlutterEngine but left the headless registration state pointing at the dead engine, blocking a replacement isolate from ever booting. The registration state is now reset along with the engine, so the next headless event boots a fresh background isolate; events arriving during the teardown window remain queued and flush once it's ready.

🛡️ Reduced Foreground-Service Usage (Android)

Geofencing and activity recognition (motion detection) no longer require a foreground service. These modes now run without a persistent notification — ahead of Google Play's August 2026 policy that removes geofencing as an approved foreground-service location use-case.

• Run without foreground-service permissions. You can remove FOREGROUND_SERVICE / FOREGROUND_SERVICE_LOCATION from your manifest. When absent, continuous location degrades gracefully to the OS significant-changes path (best-effort) instead of failing to start.
• Quieter by default. Geofence-only and motion-only apps no longer show an ongoing notification.
• Opt back in via config for apps that still need classic foreground-service delivery.

Continuous high-frequency tracking (trackingMode: LOCATION) still uses a foreground service where permitted.

• [Added] New getLocations([LocationQuery query]) method — page through the location database, eg getLocations(LocationQuery(limit: 500, page: 0, order: LocationQuery.ORDER_DESC)). The .locations getter is retained as an alias for the unbounded read. Fixes out-of-memory crashes when reading a database holding thousands of records.
• [iOS] Pin TSLocationManager ~> 4.3.0
• [Android] Pin tslocationmanager 4.3.+

Merge branch 'onLocationFilter'

• [Added] New event onLocationFilter — fires when the tracking location-filter rejects a location (eg: horizontal accuracy worse than LocationFilter.trackingAccuracyThreshold, or a GPS spike under the Conservative policy: implausible implied-speed / statistical outlier). Rejected locations are not delivered to onLocation, so this is the only way to observe and adapt to them. The event provides the rejected location, a normalized reason ("low-accuracy" | "implied-speed" | "outlier-capped"), accuracy, and trackingAccuracyThreshold.
• [iOS] Pin TSLocationManager ~> 4.2.0
• [Android] Pin tslocationmanager 4.2.+

• [iOS] Pin TSLocationManager 4.1.10 — delivers the native fixes below.
• [Android] Pin tslocationmanager 4.1.9 — delivers the native fixes below.
• [Added] New config option LocationFilter.odometerPolicy — selects the filtering policy applied to odometer-relevant samples, independent of LocationFilter.policy. Defaults to adjust (existing behavior: anomalous samples are capped but still accumulated); use conservative to reject GPS teleports outright, eliminating phantom odometer distance on devices that emit corrupted location bursts.
• [Fixed] Odometer under-counted the first motionchange location after exiting the stationary geofence: the Kalman filter restarted from a zero estimate, crediting only ~20% (Android) / ~1% (iOS) of the genuine exit distance (200–1000m). The filter now seeds from its first post-reset measurement, crediting the full gap distance.
• [Fixed][iOS] LocationFilterPolicy.conservative rejected the first motionchange fix after a stationary-geofence exit as an outlier — the outlier bound was time-independent. Android parity: the bound now scales with elapsed time via the kinematic cap, so genuine post-gap fixes are accepted while teleports (dt ≈ 0) are still rejected.
• [Fixed][iOS] Declare FlutterFramework dependency in the plugin's Package.swift, required by Flutter's Swift Package Manager integration (Flutter ≥ 3.38). Silences the missing-dependency warning at build time; CocoaPods consumers are unaffected.
• [Changed][Android] geolocation.filter options now apply at runtime via setConfig without restarting tracking (parity with iOS).
• [Changed] Example app — migrated the iOS Runner to the UIScene lifecycle (UIApplicationSceneManifest + FlutterImplicitEngineDelegate plugin registration), ahead of Apple's upcoming requirement.
• [Changed] Minimum Flutter SDK raised to >=3.38.0 (aligned with background_fetch; required by the Swift Package Manager FlutterFramework integration).

• [Fixed][Android] watchPosition crashes — Integer→Long / Integer→Double ClassCastException from Flutter MethodChannel type mapping, and incorrect Map response shape where Dart expected an int watchId.
• [Fixed][Android] watchPosition @UiThread RuntimeException — EventSink.success() called from background thread pool; now posted to main thread via Handler(Looper.getMainLooper()).
• [Added] New Subscription class — watchPosition and all on* event-listener methods now return a Subscription instance with a .remove() method for convenient listener teardown.
• [Changed] Example app — added "Watch position" toggle to SpeedDial FAB menu.

• [Fixed][Android] App stuck on splash / logo after relaunch when the foreground service kept the process alive past Activity termination. Root cause: HeadlessTask's static background FlutterEngine was never destroyed, so on main Activity reattach the stale engine conflicted with the freshly attaching main engine's plugin channels. HeadlessTask.destroyBackgroundIsolate() now runs when BackgroundGeolocationModule.setActivity(activity) receives a non-null Activity, clearing the background engine before the main engine attaches.
• [Changed] Example main.dart — added boot-trace print() milestones to make stuck-splash reproductions immediately identify the Dart boot stage that hangs.
• [Changed] Example bumps background_fetch to ^1.6.2 for the sibling fix that surfaced once the background engine started being properly destroyed (MissingPluginException on com.transistorsoft/flutter_background_fetch/methods).

Merge branch 'timestampFormat'

• [Added] New config option PersistenceConfig.timestampFormat — set to "epoch" to receive timestamp and recorded_at as epoch milliseconds (number) instead of the default ISO-8601 UTC strings.
• [Fixed][Android] getCurrentPosition timeout (408) with approximate (COARSE-only) location permission. With only approximate location granted, the SDK now resolves immediately with the first available location instead of waiting for samples that won't arrive.

[Example] pin tslocationmanager 4.1.+

🚀 Zero Third-Party Native Logging Dependencies

The native TSLocationManager SDK no longer depends on any third-party logging frameworks on either platform:

• [iOS] Removed CocoaLumberjack — replaced with a custom, zero-dependency SQLite-backed logger using os_log for console output.
• [Android] Removed slf4j / logback-android — replaced with a custom SQLite-backed logger using the native Android Log API.

This eliminates a long-standing source of dependency conflicts for apps that use these popular logging libraries at different versions. The SDK's logging behavior, output format, and emailLog / uploadLog functionality remain identical.

• [iOS] Pin TSLocationManager ~> 4.1.0
• [Android] Pin tslocationmanager 4.1.+

Merge branch 'release-5.0.7'

• Fix Package.swift: bump ios min .v12

Merge branch 'release-5.0.6'

• Fix Package.swift for SPM users. The package name is renamed BackgroundGeolocation

Merge branch 'location-filter-sparse-update'

• Support sparse updates on LocationFilter

Merge branch 'release-5.0.4'

• Fix bug in State parsing.

Merge branch 'release-5.0.3'

• Add guards in dart Location model to handle receiving dummy location-data provided by setOdometer when the SDK is !state.enabled or location auth is denied. In this state, the SDK will simply zero the odometer, not caring about the location where that occured.

• [iOS] Fix bug in iOS License Validation Failure modal dialog interfering with React Native app launching. Change to less intrusive alert mechanism.
• [iOS] Fix bug returning wrong data-structure to watchPosition callback.
• [iOS] Fix first-launch issue with initial call to .start()..
• [iOS] Fix config.authorization bug (refreshPayload and refreshHeaders being ignored).
• [Android] Re-factor Android activity life-cycle management. It's all done internally within SDK now. No need for react-native plugin code to manually listen to Activity lifecycle and poke the SDK when interesting events happen.
• Fix bug not respecting PersistenceConfig.geofenceTemplate
• [iOS] Fix bug in setOdometer not resolving its Promise

• [iOS] Fix syntax error in Package.swift

• [Release] 5.0.0.
• See 5.0.0 Migration Guide
• See 5.0.0 Discussion

• Fix type-cast bug in GeofenceEvent while in headless-mode.

• [Android] Add proguard rules to preserve flutter plugin classnames (eg: HeadlessTask) in release with minifyEnabled.

• Bug fixes.
• [Android] Add guards against spurious geofence exit events reported with certain devices.

• Initial introduction of v5 beta. See the Migration Guide

• [Android] Backport spurious stationary geofence exit detection from v5. Google Play Services seems to have a bug where geofence exit events fire even while the device is still inside the geofence, causing the SDK to constantly enter the m oving state, draining the battery

• [Android] Rebuild with Android ELF Alignment

• [Android] pin tslocationmanager at 3.+ in preparation for next release..

• [Android] Remove Huawei HMS support for failure to provide their SDKs with Android 16KB Page Size compatibility.

• Fix example/pubspec.yaml enable-swift-package-manager: true

• [iOS] Implement Swift Package Manager support
• [example] Re-factor /example app's location marker images.

• [Android] Rebuild tslocationmanager with AGP >= 8.5.1
• [example] Update example's flutter_map to latest 8.1.1
• [Android] Implement behaviour for locationAuthorizationRequest: "Any" to not continue showing backgroundPermissionRationale after user clicks [CANCEL] button.

• [Android] Fix issue with polygon geofencing where identifier consists of long strings, such as aaaa-bbbb-cccccccc-dddd-eeeee eeeeeee.
• [Android] Fix edge-case where polygons can fail to fire after the containing geofence is exited. This could happen if the containing geofence was exited without trigger an onMotionChange event.
• [iOS] Fix edge-case where polygon could fail to fire EXIT event after launching from terminated state when the containing geofence is exit causes background app restart.

• [Android] Support 16KB pages sizes.
• [iOS] Fix ProviderChangeEvent.enabled not showing the result of global Privacy -> Location Services -> Enabled switch
• [Android] Fix java.util.ConcurrentModificationException at com.transistorsoft.locationmanager.location.SingleLocationRequest.getBestLocation.

• [Android] Re-compile library with jdk 17

• [Android] Re-compile library with jdk 17 instead of 22

• [Android] Fix ConcurrentModificationException in StopTimeoutEvaluator.

• [Android] Address phenonenon of "UI Freezing".

• [Android] Remove Android Setup Step for proguard-rules.pro in your android/app/build.gradle. The SDK is now able to automatically apply its required proguard-rules.pro.

• [Android] Remove enforcement of minimum Geofence radius 150
• [Android] Fix issue with TSLocationManagerActivity (responsible for showing location permission / authorization dialogs). Minimizing the app with an active permission dialog would cause the app's MainActivity to terminate on some devices.

• [Android] Fix reported "screen flickering" issue on some devices when SDK requests permissions.
• [Android] Address Android synchronization issue with TSLocation.toMap.
• [iOS] Address crash in TSConfig due to "uncaught exception NSInvalidArgumentException"
• [Android] Change foregroundServiceType on LocationRequestService from shortService -> location.
• [iOS] Address inconsistent location-tracking performance on iOS.

• [iOS] Fix bug with triggerActivites preventing motion-triggering in iOS simulator with simulated location.

• [Android] Implement Service.onTimeout to handle foregroundServiceType="shortService" timeouts.
• [iOS] Add new Config.activityType ACTIVITY_TYPE_AIRBORNE.
• [iOS] Implement Config.triggerActivities for iOS.
• [Android] Guard against NullPointerException receiving a null location in PolygonGeofenceService event.
• [Android] Remove unused imports related to Flutter V1 Embedding.
• [Android] Address possible leak of Activity reference when terminating the app. Ensure internal reference to Activity is nullified when app is terminated.
• [Android] Add improvements to Android geofencing-only mode with goefenceModeHighAccuracy: true where motion-activity updates disabled.
• [Android] Add error-checking in polygon-geofencing to handle a possible NullPointerException.
• [iOS] Fix broken linking to Settings screen in locationAuthorizationAlert on iOS 18.

• [iOS] Fix bug in iOS Polygon Geofencing when running in geofences-only mode (.startGeofences). iOS would mistakenly turn off location updates exactly 3 samples into the containing circular geofence of a polygon.
• Implement notifyOnDwell for polygon-geofences.

• [Android] Remove permission FOREGROUND_SERVICE_HEALTH. It turns out that this permission is no longer required when the ActivityRecognitionServivce is defined with a foregroundServiceType="shortservice", which allows a background-launched foreground-service to stay active for up to 3 minutes, which is sufficient for the ActivityRecognitionService, which typically stays activated only for a few milliseconds.

• [Android] Fix issues #1298 "Multiple geofence events triggered for a single geofence registration when registered individually".

• [Android] Fix bug in .getCurrentPosition not returning or throwing an error in a condition where Network OFF and GPS ON.
• Fix bug in .changePace exception-handling, throwing a FormatException instead of PlatformException.

• [iOS] Code-sign TSLocationManager.xcframework with new Apple Organization (9224-2932 Quebec Inc) certificate.

• [iOS] Add PrivacyInfo -> TSLocationManager.xcframework
• [iOS] codesign TSLocationManager.xcframework
• [iOS] Update CocoaLumberjack version -> 3.8.5 (version which includes its own PrivacyInfo) .

• [iOS] Implement new iOS Privacy Manifest
• Add property AuthorizationEvent.status, provding the HTTP status code from the refreshUrl.

• [iOS] Fix bug in iOS scheduler, triggering ON incorrectly. For example, given a schedule: ['1 00:00-23:59'], the plugin was trigging on for DAY 2`.

• [iOS] Fix bug in polygon-geofencing: monitoredIdentifiers not being cleared when .removeGeofences() is called, can result in null-pointer exception.

• [Android] Change foregroundServiceType of the SDK's GeofencingService definition in its AndroidManifest from shortService -> location.

• [iOS] Modify behaviour of stop-detection system to NOT turn off location-services but merely adjust desiredAccuracy as high as possible. There were problems reported using locationAuthorizationRequest: 'WhenInUse' with recent versions of iOS where the stop-detection system could put the app to sleep during tracking if the motion API reported the device became momentarily stationary.

• Fix minor static analysis issues reported in dart code referencing part-of directive.

• [Android] Add multi FlutterEngine support to Android

• [Android] Fix problem with polygon-geofencing license-validation not working in DEBUG builds when configured with product flavors.

• [Android] HMS geolocation event does not provide a timestamp for the triggering location!! Use System current time.
• [Android] Remove deprecated flutter V1 plugin architecture code (registerWith).
• [Android] Guard against Geofence SQLite query returning null in GeofencingService.
• [Android] Fix ConcurrentModificationException in SingleLocationRequest.getBestLocation

• [Android] Fix IllegalStateException calling addGeofences when number of geofences exceeds platform maximum (100).

• [Android] Fix error Unhandled Exception: type 'Null' is not a subtype of type 'List<Object?>' in BackgroundGeolocation.geofences / getGeofence(uuid).
• [iOS] Rename iOS Obj-c classes, prefixing with TS.

• [iOS] Fix "Duplicate symbol error DummyPods_TSLocationManager".

• Polygon Geofencing: The Background Geolocation SDK now supports Polygon Geofences (Geofences of any shape). For more information, see API docs Geofence.vertices. ℹ️ Polygon Geofencing is sold as a separate add-on (fully functional in DEBUG builds).

• Remove backup_rules.xml from AndroidManifest.xml — it's causing conflicts with other plugins.
• [Android] Add proguard-rule for compilation of the android library to prevent from obfuscating the BuildConfig class to a.a.class, conflicting with other libraries.

• [Android] Performance enhancements and error-checking.

• [Android] Fix memory-leak in .startBackgroundTask: If a Task timed-out and is "FORCE KILLED", it was never removed from a List<Task>.
• [Android] Fix Exception NullPointerException:at com.transistorsoft.locationmanager.util.BackgroundTaskWorker.onStopped

• [iOS] Fix build failure "Use of '@import' when C++ modules are disabled"
• [Android] Modify Foreground-service management to use stopSelfResult(startId) instead of stopSelf(). This could improve reports of Android ANR Context.startForeground.
• [Android] Add sanity-check for invalid Geofence arguments (eg: invalid latitude/longitude).
• [Android] Add safety-checks in ForegroundService stop-handling. There was a report of a reproducible crash while aggressively calling .getCurrentPosition in a Timer (eg: every second).
• [Android] Demote HeartbeatService from a Foreground Service to AlarmManager ONESHOT. :warning: In your onHeartbeat event, if you intend to perform any kind of asynchronous function, you should wrap it inside BackgroundGeolocation.startBackgroundTask in order to prevents the OS from suspending your app before your task is complete:

BacckgroundGeolocation.onHeartbeat((event) async {
  print("[onHeartbeat] $event");
  // First register a background-task.
  var taskId = await BackgroundGeolocation.startBackgroundTask();
  try {
    // Now you're free to perform long-running tasks, such as getCurrentPosition()
    var location = await BackgroundGeolocation.getCurrentPosition(
      samples: 3,
      timeout: 30,
      extras: {
        "event": "heartbeat"
      }
    );
    print("[onHeartbeat] location: $location");
  } catch(error) {
    print("[getCurrentPosition] ERROR: $error");
  }
  // Be sure to singal completion of your background-task:
  BackgroundGeolocation.stopBackgroundTask(taskId);
});

• [Android] Fix NPE iterating a List in AbstractService.
• [Android] If a SingleLocationRequest error occurs and at least one sample exits, prefer to resolve the request successfully rather than firing the error (eg: getCurrentPosition, motionchange, providerchange requests).