geolocation property

GeoConfig? geolocation
final

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.

Category Description
Accuracy Controls desired location precision GeoConfig.desiredAccuracy, filtering distance GeoConfig.distanceFilter, and timing intervals GeoConfig.locationUpdateInterval, GeoConfig.fastestLocationUpdateInterval
Elasticity Adjusts responsiveness to motion and idling via GeoConfig.disableElasticity, GeoConfig.elasticityMultiplier, and GeoConfig.stopTimeout.
Permissions Manages platform authorization GeoConfig.locationAuthorizationRequest, alerts GeoConfig.locationAuthorizationAlert / GeoConfig.disableLocationAuthorizationAlert
Geofencing Configures geofence monitoring behavior and entry triggers.
Filtering Provides fine-grained control over the SDK’s noise-reduction filter via GeoConfig.filter.

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

Implementation

final GeoConfig? geolocation;