Skip to content

Setup

Installation

Add the dependency to pubspec.yaml:

dependencies:
  flutter_background_geolocation: '^5.0.7'

Then fetch:

flutter pub get

Configure your license

Purchase a license

The SDK requires a license for release builds. Debug builds work without one. Purchase at transistorsoft.com.

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

Podfile

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

The plugin reads two optional ext vars from your root project. Set them in android/build.gradle to pin specific versions:

ext["playServicesLocationVersion"] = "21.3.0"
ext["tslocationmanagerVersion"]    = "4.0.+"

ext {
    playServicesLocationVersion = "21.3.0"
    tslocationmanagerVersion    = "4.0.+"
}
Variable Default Description
playServicesLocationVersion 21.3.0 com.google.android.gms:play-services-location version. Browse: maven.google.com
tslocationmanagerVersion 4.0.+ Transistor Android SDK version. Browse: central.sonatype.com

android/app/build.gradle / 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
        }
    }
}

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();
  }
});