Setup

Installation

Add the dependency to pubspec.yaml:

dependencies:
  flutter_background_geolocation: '^5.8.0'

Then fetch:

flutter pub get

Configure your license

Purchase a license

The SDK requires a license for release builds. Debug builds work without one. Need to test a release build? Generate a free 30-day trial license — or purchase a license.

iOS — Info.plist

<key>TSLocationManagerLicense</key>
<string>YOUR_LICENSE_KEY_JWT</string>

Android — AndroidManifest.xml

<application>
    <meta-data
        android:name="com.transistorsoft.locationmanager.license"
        android:value="YOUR_LICENSE_KEY_JWT" />
</application>

iOS Setup

Dependency manager

Swift Package ManagerCocoaPods

The plugin ships a Package.swift, so Flutter can resolve it through Swift Package Manager instead of CocoaPods — no Podfile, no pod install.

Swift Package Manager is a machine-wide Flutter setting, not per-project. Enable it and confirm:

flutter config --enable-swift-package-manager
flutter config --list | grep swift-package-manager

Because the setting is machine-wide it affects your other Flutter projects too; undo it with flutter config --no-enable-swift-package-manager.

With SPM active, Flutter generates no ios/Podfile and the :linkage => :static step does not apply. Do not hand-write a Podfile.

Xcode resolves two Swift packages at build time. Allowlist these hosts if you build behind a proxy or firewall:

Package	Minimum
transistorsoft/native-background-geolocation	4.4.0
transistorsoft/transistor-background-fetch	4.0.5

Both managers can be active at once: an existing project keeps using CocoaPods for any plugin that does not ship a Package.swift.

Add :linkage => :static to your target in ios/Podfile:

target 'Runner' do
  use_frameworks! :linkage => :static
  # ...
end

Then run:

cd ios && pod install

Background Modes

In Xcode, select your target → Signing & Capabilities → + Capability → Background Modes. Enable:

• [x] Location updates
• [x] Background fetch
• [x] Audio (optional — enables debug sound FX)

Info.plist

<!-- License key -->
<key>TSLocationManagerLicense</key>
<string>YOUR_LICENSE_KEY_JWT</string>

<!-- Background modes -->
<key>UIBackgroundModes</key>
<array>
    <string>location</string>
    <string>fetch</string>
    <string>processing</string>
    <string>audio</string>
</array>

<!-- Background task identifier -->
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.transistorsoft.fetch</string>
</array>

<!-- Location usage descriptions -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>App requires location access at all times for background tracking.</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>App requires location access while in use.</string>

<key>NSMotionUsageDescription</key>
<string>Motion detection helps determine when the device is stationary.</string>

Android Setup

Gradle ext vars (optional)

Optional — most apps should skip this

The plugin already depends on tested, compatible versions of these libraries. Leave them unset and the defaults apply — the right choice for almost everyone. Override only for a specific reason (a version conflict with another plugin, or pinning an exact release).

If you do need to override, set the ext var in your root build.gradle:

build.gradle.ktsbuild.gradle

// Only if overriding — otherwise omit and use the plugin default.
ext["playServicesLocationVersion"] = "21.3.0"
ext["tslocationmanagerVersion"]    = "4.6.+"

// Only if overriding — otherwise omit and use the plugin default.
ext {
    playServicesLocationVersion = "21.3.0"
    tslocationmanagerVersion    = "4.6.+"
}

Variable	Description
playServicesLocationVersion	Pins com.google.android.gms:play-services-location. Versions ≥ 21 use tslocationmanager; < 21 use tslocationmanager-gms20. Defaults to 21.3.0. Browse: maven.google.com
tslocationmanagerVersion	Pins the Transistor Android SDK (com.transistorsoft:tslocationmanager). Defaults to 4.6.+ — omit unless you need a specific release. Browse: central.sonatype.com

android/app/build.gradle

build.gradle.ktsbuild.gradle

val backgroundGeolocation = project(":flutter_background_geolocation")
apply { from("${backgroundGeolocation.projectDir}/background_geolocation.gradle") }

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = false   // required
        }
    }
}

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

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources false   // required
        }
    }
}

AndroidManifest.xml

<application>
    <meta-data
        android:name="com.transistorsoft.locationmanager.license"
        android:value="YOUR_LICENSE_KEY_JWT" />
</application>

Example

import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;

// Use the 'bg' namespace to avoid conflicts with Flutter's own Location/State types.
bg.BackgroundGeolocation.ready(bg.Config(
  geolocation: bg.GeoConfig(
    desiredAccuracy: bg.DesiredAccuracy.high,
    distanceFilter: 10.0,
  ),
  app: bg.AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
  ),
  logger: bg.LoggerConfig(
    debug: true,
    logLevel: bg.LogLevel.verbose,
  ),
)).then((bg.State state) {
  if (!state.enabled) {
    bg.BackgroundGeolocation.start();
  }
});