5.0.0 beta #1595

christocracy · 2025-11-26T16:21:54Z

christocracy
Nov 26, 2025
Maintainer

🚀 Migration Guide: Flat Config → Compound Config

Version: 5.0.0
Applies to: flutter_background_geolocation v5.0.0 and above

📢 Overview

Version 5 introduces a new Compound Config format that replaces the legacy "flat" config structure. This guide explains the migration steps, provides before/after examples, and details key differences.

Installation

See the README in 5.0.0-beta branch.

Opt in to the beta by adding this to your pubspec.yaml:

(ℹ️ See pub.dev for latest v5.0.0.beta version (new beta versions are published quite often).

dependencies:
  flutter_background_geolocation: ^5.0.0-beta.3

⚙️ Compatibility

The legacy flat config style remains fully supported for backward compatibility.
You can continue using your existing flat configuration if you prefer, though new features may only appear in the compound structure.

⏩ Why Compound Config?

Clarity: Groups related settings together (e.g., geolocation, HTTP, logging).
Extensibility: Easier to add new config domains without polluting the top-level.
Consistency: Aligns with native SDKs and improves code completion.

🏗️ Old vs. New Config Structure

Before (Flat Config)

BackgroundGeolocation.ready(Config(
  desiredAccuracy: Config.DESIRED_ACCURACY_HIGH,
  distanceFilter: 50,
  stopOnTerminate: false,
  startOnBoot: true,
  url: "https://my.server.com/locations",
  headers: { "Authorization": "Bearer TOKEN" },
  logLevel: Config.LOG_LEVEL_VERBOSE,
  debug: true,
));

After (Compound Config)

BackgroundGeolocation.ready(Config(
  geolocation: GeoConfig(
    desiredAccuracy: Config.DESIRED_ACCURACY_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,
  ),
));

🗺️ Mapping Table: Flat → Compound

Flat Key	Compound Group	Compound Property	Example
`desiredAccuracy`	`geolocation`	`desiredAccuracy`	`geolocation: GeoConfig(desiredAccuracy: ...)`
`distanceFilter`	`geolocation`	`distanceFilter`
`stopOnTerminate`	`app`	`stopOnTerminate`	`app: AppConfig(stopOnTerminate: ...)`
`startOnBoot`	`app`	`startOnBoot`
`url`	`http`	`url`	`http: HttpConfig(url: ...)`
`headers`	`http`	`headers`
`logLevel`	`logger`	`logLevel`	`logger: LoggerConfig(logLevel: ...)`
`debug`	`logger`	`debug`
...	...	...

See the full mapping table below for all properties.

🧑‍💻 Migration Steps

Update your dependency:
Ensure you are using flutter_background_geolocation v5.0.0 or later.

Import new config classes:

import 'package:flutter_background_geolocation/flutter_background_geolocation.dart';

Group related options:
- Move geolocation-related keys into GeoConfig
- Move HTTP-related keys into HttpConfig
- Move logging/debug keys into LoggerConfig
- Move app lifecycle keys into AppConfig
- Move activity-recognition keys into ActivityConfig
- Move persistence keys into PersistenceConfig
Replace flat keys:
- Instead of passing all options to Config(...) directly, pass the relevant compound config objects.
- Remove any duplicate or conflicting flat keys.
Check for breaking changes:
- Some keys may have been renamed, moved, or refactored.
- See Breaking Changes below.

📝 Example Migration

Flat Config (Old)

BackgroundGeolocation.ready(Config(
  desiredAccuracy: Config.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  stopOnTerminate: false,
  startOnBoot: true,
  url: "https://my.server.com/locations",
  headers: { "Authorization": "Bearer TOKEN" },
  logLevel: Config.LOG_LEVEL_DEBUG,
  debug: true,
  autoSync: true,
  batchSync: false,
));

Compound Config (New)

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

🧩 Compound Config Groups

Group	Class Name	Description
`geolocation`	`GeoConfig`	Location and geofencing options
`app`	`AppConfig`	App lifecycle and scheduling
`http`	`HttpConfig`	HTTP sync, batching, headers, etc.
`logger`	`LoggerConfig`	Debug, log-level, log retention
`activity`	`ActivityConfig`	Activity recognition, stop detection
`persistence`	`PersistenceConfig`	Data storage, max days, max records

Each group is a separate Dart class. See API docs for details.

🛠️ Full Mapping Table

Flat Key	Compound Group	Compound Property	Notes
`desiredAccuracy`	`geolocation`	`desiredAccuracy`
`distanceFilter`	`geolocation`	`distanceFilter`
`stationaryRadius`	`geolocation`	`stationaryRadius`
`stopTimeout`	`geolocation`	`stopTimeout`
`stopAfterElapsedMinutes`	`geolocation`	`stopAfterElapsedMinutes`
`geofenceProximityRadius`	`geolocation`	`geofenceProximityRadius`
`geofenceInitialTriggerEntry`	`geolocation`	`geofenceInitialTriggerEntry`
`geofenceModeHighAccuracy`	`geolocation`	`geofenceModeHighAccuracy`
`pausesLocationUpdatesAutomatically`	`geolocation`	`pausesLocationUpdatesAutomatically`
`showsBackgroundLocationIndicator`	`geolocation`	`showsBackgroundLocationIndicator`
`activityType`	`geolocation`	`activityType`	iOS only
`locationAuthorizationAlert`	`geolocation`	`locationAuthorizationAlert`	iOS only
`maxMonitoredGeofences`	`geolocation`	`maxMonitoredGeofences`
`filter`	`geolocation`	`filter`	Advanced filtering
`stopOnTerminate`	`app`	`stopOnTerminate`
`startOnBoot`	`app`	`startOnBoot`
`enableHeadless`	`app`	`enableHeadless`	Android only
`heartbeatInterval`	`app`	`heartbeatInterval`
`schedule`	`app`	`schedule`
`scheduleUseAlarmManager`	`app`	`scheduleUseAlarmManager`	Android only
`notification`	`app`	`notification`	Android only
`backgroundPermissionRationale`	`app`	`backgroundPermissionRationale`	Android only
`preventSuspend`	`app`	`preventSuspend`	iOS only
`url`	`http`	`url`
`autoSync`	`http`	`autoSync`
`autoSyncThreshold`	`http`	`autoSyncThreshold`
`disableAutoSyncOnCellular`	`http`	`disableAutoSyncOnCellular`
`batchSync`	`http`	`batchSync`
`maxBatchSize`	`http`	`maxBatchSize`
`method`	`http`	`method`
`params`	`http`	`params`
`headers`	`http`	`headers`
`rootProperty`/`httpRootProperty`	`http`	`rootProperty`
`timeout`/`httpTimeout`	`http`	`timeout`
`debug`	`logger`	`debug`
`logLevel`	`logger`	`logLevel`	Now an enum: `LogLevel`
`logMaxDays`	`logger`	`logMaxDays`
`activityRecognitionInterval`	`activity`	`activityRecognitionInterval`	Android only
`minimumActivityRecognitionConfidence`	`activity`	`minimumActivityRecognitionConfidence`	Android only
`disableStopDetection`	`activity`	`disableStopDetection`
`stopOnStationary`	`activity`	`stopOnStationary`
`motionTriggerDelay`	`activity`	`motionTriggerDelay`	Android only
`triggerActivities`	`activity`	`triggerActivities`	Android only
`disableMotionActivityUpdates`	`activity`	`disableMotionActivityUpdates`	iOS only
`stopDetectionDelay`	`activity`	`stopDetectionDelay`	iOS only
`persistMode`	`persistence`	`persistMode`
`maxDaysToPersist`	`persistence`	`maxDaysToPersist`
`maxRecordsToPersist`	`persistence`	`maxRecordsToPersist`
`locationsOrderDirection`	`persistence`	`locationsOrderDirection`

Not all legacy keys are shown above. See API docs for full details.

⚠️ Breaking Changes

Some keys have new enum types:
- logLevel is now a LogLevel enum (e.g., LogLevel.info), but legacy integer values are still supported for backward compatibility. You may use either the new enum or the legacy integer type.
Some keys have moved to new groups:
- E.g., debug is now in LoggerConfig.
Legacy flat config remains supported but deprecated:
- Using the legacy flat config will show warnings at runtime, but will not result in an error. Migration to the new grouped config is recommended for future compatibility.

⚠️ New License Key Format

v5.0.0 introduces a new format for license keys. You can generate them in the Customer Dashboard. Both iOS and Android now require a license key:

🧪 Testing Your Migration

Run your app after migration.
Check for errors or warnings about missing or misplaced config keys.
Review logs to ensure config is applied as expected.
Consult the API docs for each config group if unsure.

🆘 Need Help?

See the API Reference for each config class.
Ask questions on GitHub Discussions or open an issue.

📚 Resources

🎉 Happy Migrating!

If you have suggestions for improving this guide, please open a PR or issue.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

5.0.0 beta #1595

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

5.0.0 beta #1595

Uh oh!

Uh oh!

christocracy Nov 26, 2025 Maintainer

🚀 Migration Guide: Flat Config → Compound Config

📢 Overview

Installation

⚙️ Compatibility

⏩ Why Compound Config?

🏗️ Old vs. New Config Structure

Before (Flat Config)

After (Compound Config)

🗺️ Mapping Table: Flat → Compound

🧑‍💻 Migration Steps

📝 Example Migration

Flat Config (Old)

Compound Config (New)

🧩 Compound Config Groups

🛠️ Full Mapping Table

⚠️ Breaking Changes

⚠️ New License Key Format

🧪 Testing Your Migration

🆘 Need Help?

📚 Resources

🎉 Happy Migrating!

Replies: 0 comments

christocracy
Nov 26, 2025
Maintainer