GeoConfig class

Geolocation Configuration.

The GeoConfig object defines all geolocation-related options for the BackgroundGeolocation SDK. These parameters control how often the SDK acquires locations, how accurately, how long tracking persists when stationary, and how it handles platform-specific permissions, filtering, and elasticity.

Overviewd

GeoConfig is consumed via the Config.geolocation property when calling BackgroundGeolocation.ready or BackgroundGeolocation.setConfig.

Example

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

void main() async {
  bg.Config config = bg.Config(
    geolocation: bg.GeoConfig(
      // High-precision GPS
      desiredAccuracy: bg.DesiredAccuracy.high,

      // Move at least 50 meters before recording next location.
      distanceFilter: 50.0,

      // Consider the device stationary after 5 minutes of no motion.
      stopTimeout: 5,

      // Automatically stop tracking after 120 minutes of continuous operation.
      stopAfterElapsedMinutes: 120,

      // Show the blue location indicator when tracking in the background (iOS).
      showsBackgroundLocationIndicator: true,

      // Customize filtering and denoising of incoming locations.
      filter: bg.LocationFilter(
        policy: bg.LocationFilterPolicy.adjust,
        maxImpliedSpeed: 60,
        odometerAccuracyThreshold: 20,
        trackingAccuracyThreshold: 100
      ),

      // Configure geofence-related behavior.
      geofenceProximityRadius: 1000,
      geofenceInitialTriggerEntry: true,
      geofenceModeHighAccuracy: true,

      // Handle iOS authorization and alerts.
      locationAuthorizationRequest: 'Always',
      disableLocationAuthorizationAlert: false,
      locationAuthorizationAlert: {
        'titleWhenNotEnabled': 'Location Required',
        'message': 'Enable location access for full functionality.',
        'cancelButton': 'Cancel',
        'settingsButton': 'Settings'
      },
    ),///
    // Additional compound config groups may be defined here:
    http: bg.HttpConfig(
      url: 'https://example.com/api/locations',
      autoSync: true,
      batchSync: true,
      maxBatchSize: 10,
      method: 'POST',
      params: {
        'user_id': 1234,
        'trip_id': 5678
      },
      headers: {
        'X-FOO': 'bar',
      },
    ),
    app: bg.AppConfig(
      stopOnTerminate: false,
      startOnBoot: true
    ),
    logging: bg.LoggerConfig(
      debug: true,
      logLevel: bg.LoggerConfig.LOG_LEVEL_VERBOSE
    )
  );

  // Apply configuration
  await bg.BackgroundGeolocation.ready(config);
}

Migration from legacy flat Config

Previously, geolocation options were defined directly in the root Config object:

// Legacy (flat)
Config(
  desiredAccuracy: Config.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10.0,
  stopTimeout: 5,
  stationaryRadius: 150.0,
  locationTimeout: 60,
);

These options are now grouped under the GeoConfig compound object, accessed via Config.geolocation:

// New (compound)
Config(
  geolocation: GeoConfig(
    desiredAccuracy: DesiredAccuracy.high,
    distanceFilter: 10.0,
    stopTimeout: 5,
    stationaryRadius: 150.0,
    locationTimeout: 60,
  ),
);

Legacy flat fields are still supported for backward compatibility, but they are now marked @Deprecated. Going forward, prefer using Config.geolocation for all location-related options to improve organization and clarity.

See also

• LocationFilter for location denoising options.
• AppConfig for lifecycle and startup behavior.