flutter_background_geolocation

In v5, a LocationFilter is enabled by default (geolocation.filter). This filter uses a Kalman filter and accuracy thresholds to smooth/adjust the location stream. If your app uses low/medium accuracy or operates in poor GPS conditions, the default settings might reject locations that were previously delivered in v4.

To replicate the original v4 behavior (delivering all locations without pre-filtering), use LocationFilterPolicy.passThrough and set accuracy thresholds to 0 to disable the accuracy gate.

BackgroundGeolocation.ready(Config(
  geolocation: GeoConfig(
    // ...your existing geolocation config...
    filter: LocationFilterConfig(
      policy: LocationFilterPolicy.passThrough,
      useKalman: false,                 // optional
      trackingAccuracyThreshold: 0,      // optional: disables accuracy gate
      odometerAccuracyThreshold: 0       // optional: disables accuracy gate
    )
  ),
));

Version 5.0.0 introduced a Compound Config format to replace the legacy "flat" configuration structure. While the legacy flat style remains supported for backward compatibility, new features may only be available in the compound structure.

Migration Steps:

1. Update dependency: Ensure you are using flutter_background_geolocation v5.0.0 or later.
2. Android Cleanup: Remove custom maven url entries from android/build.gradle. The local libs repositories for flutter_background_geolocation and background_fetch are no longer required.
3. Group Options: Move related keys into their respective configuration classes (e.g., GeoConfig, HttpConfig, AppConfig).
4. Replace Keys: Pass the new compound config objects into BackgroundGeolocation.ready(Config(...)) instead of passing all options at the top level.

// After (Compound Config)
BackgroundGeolocation.ready(Config(
  geolocation: GeoConfig(
    desiredAccuracy: DesiredAccuracy.high,
    distanceFilter: 50,
  ),
  app: AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
  ),
  http: HttpConfig(
    url: "https://my.server.com/locations",
    headers: { "Authorization": "Bearer TOKEN" },
  ),
  logger: LoggerConfig(
    logLevel: LogLevel.verbose,
    debug: true,
  ),
));

To enable background geolocation on iOS, you must configure both Xcode Background Modes and Info.plist permissions.

1. Enable Background Modes in Xcode

Open ios/Runner/Runner.xcworkspace in Xcode and enable the following under Signing & Capabilities > Background Modes:

• Location updates
• Background fetch
• Audio (Optional: only required if using debug-mode sound FX)

2. Add Permissions to Info.plist

You must add the following keys to your ios/Runner/Info.plist with descriptive strings explaining why your app requires these permissions:

<plist>
<dict>
+    <key>NSMotionUsageDescription</key>
+    <string>Motion usage description</string>
+    <key>NSLocationWhenInUseUsageDescription</key>
+    <string>When in use description</string>
+    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+    <string>Always/When in use description</string>

+    <key>UIBackgroundModes</key>
+    <array>
+        <string>fetch</string>
+        <string>location</string>
+    </array>

+    <key>BGTaskSchedulerPermittedIdentifiers</key>
+    <array>
+        <string>com.transistorsoft.fetch</string>
+    </array>
</dict>
</plist>

To integrate the plugin into your Android application, you must apply the plugin's Gradle script and configure resource shrinking.

Important: You MUST set shrinkResources to false in your release build type to prevent the plugin from being stripped out during the build process.

// In android/app/build.gradle
Project background_geolocation = project(':flutter_background_geolocation')
apply from: "${background_geolocation.projectDir}/background_geolocation.gradle"

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources false   // <-- REQUIRED !!!
        }
    }
}

// In android/app/build.gradle.kts
val backgroundGeolocation = project(":flutter_background_geolocation")
apply { from("${backgroundGeolocation.projectDir}/background_geolocation.gradle") }

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = false   // <-- REQUIRED !!!
        }
    }
}