Config¶

class Config

Root configuration object passed to BackgroundGeolocation.ready and BackgroundGeolocation.setConfig.

Config groups all SDK options into typed sub-interfaces. Each key maps to a dedicated configuration area — set only the keys relevant to your use case.

Contents¶

Overview
Examples

Overview¶

Key	Type	Description
`geolocation`	GeoConfig	Accuracy, sampling, elasticity, stop-detection, permissions, and geofencing.
`activity`	ActivityConfig	Motion recognition, stop-detection triggers, and motion-trigger delay.
`http`	HttpConfig	Upload URL, sync cadence, batching, headers, and params.
`persistence`	PersistenceConfig	SQLite storage, TTL, record limits, and custom extras.
`app`	AppConfig	App lifecycle — background operation, boot behaviour, headless mode, and foreground notification.
`logger`	LoggerConfig	Debug logging, log level, and log retention.
`authorization`	AuthorizationConfig	JWT and SAS token management with automatic refresh.

The SDK persists its configuration across app launches. Call BackgroundGeolocation.ready once at startup — subsequent launches load the persisted config automatically. Use BackgroundGeolocation.setConfig to update individual keys at runtime without restarting.

Examples¶

final state = await BackgroundGeolocation.ready(Config(
  geolocation: GeoConfig(
    desiredAccuracy: DesiredAccuracy.high,
    distanceFilter: 20.0,
  ),
  http: HttpConfig(
    url: 'https://my.server.com/api/locations',
    autoSync: true,
  ),
  app: AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
  ),
));

final state = await BackgroundGeolocation.ready(Config(
  geolocation: GeoConfig(
    desiredAccuracy: DesiredAccuracy.high,
    distanceFilter: 20.0,
    stopTimeout: 5,
    stationaryRadius: 150.0,
  ),
  activity: ActivityConfig(
    disableStopDetection: false,
    motionTriggerDelay: 30000.0,
  ),
  http: HttpConfig(
    url: 'https://my.server.com/api/locations',
    method: 'POST',
    autoSync: true,
    headers: { Authorization: 'Bearer secret-token' },
    params: { user_id: 123 },
  ),
  persistence: PersistenceConfig(
    persistMode: PersistMode.all,
    maxDaysToPersist: 14,
    extras: { appVersion: '1.0.0' },
  ),
  app: AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
    enableHeadless: true,
  ),
  logger: LoggerConfig(
    debug: true,
    logLevel: LogLevel.verbose,
    logMaxDays: 3,
  ),
));
if (!state.enabled) {
  await BackgroundGeolocation.start();
}

// Update a subset of config at runtime.
await BackgroundGeolocation.setConfig(Config(
  http: HttpConfig( headers: { Authorization: 'Bearer new-token' } ),
  logger: LoggerConfig( logLevel: LogLevel.info ),
));

Minimal configuration¶

final state = await BackgroundGeolocation.ready(Config(
  geolocation: GeoConfig(
    desiredAccuracy: DesiredAccuracy.high,
    distanceFilter: 20.0,
  ),
  http: HttpConfig(
    url: 'https://my.server.com/api/locations',
    autoSync: true,
  ),
  app: AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
  ),
));

Full configuration¶

final state = await BackgroundGeolocation.ready(Config(
  geolocation: GeoConfig(
    desiredAccuracy: DesiredAccuracy.high,
    distanceFilter: 20.0,
    stopTimeout: 5,
    stationaryRadius: 150.0,
  ),
  activity: ActivityConfig(
    disableStopDetection: false,
    motionTriggerDelay: 30000.0,
  ),
  http: HttpConfig(
    url: 'https://my.server.com/api/locations',
    method: 'POST',
    autoSync: true,
    headers: { Authorization: 'Bearer secret-token' },
    params: { user_id: 123 },
  ),
  persistence: PersistenceConfig(
    persistMode: PersistMode.all,
    maxDaysToPersist: 14,
    extras: { appVersion: '1.0.0' },
  ),
  app: AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
    enableHeadless: true,
  ),
  logger: LoggerConfig(
    debug: true,
    logLevel: LogLevel.verbose,
    logMaxDays: 3,
  ),
));
if (!state.enabled) {
  await BackgroundGeolocation.start();
}

// Update a subset of config at runtime.
await BackgroundGeolocation.setConfig(Config(
  http: HttpConfig( headers: { Authorization: 'Bearer new-token' } ),
  logger: LoggerConfig( logLevel: LogLevel.info ),
));

Members¶

activity¶

ActivityConfig? activity

Motion recognition, stop-detection triggers, and motion-trigger delay. Access via BGGeo.instance.config.activity. See ActivityConfig.

app¶

AppConfig? app

App lifecycle, background operation, boot behaviour, headless mode, and foreground notification. Access via BGGeo.instance.app. See AppConfig.

authorization¶

Authorization? authorization

JWT and SAS token management with automatic refresh. Access via BGGeo.instance.authorization. See AuthorizationConfig.

geolocation¶

GeoConfig? geolocation

Accuracy, sampling, elasticity, stop-detection, permissions, and geofencing. Access via BGGeo.instance.config.geolocation. See GeoConfig.

http¶

HttpConfig? http

Upload URL, HTTP method, sync cadence, batching, headers, and params. Access via BGGeo.instance.config.http. See HttpConfig.

logger¶

LoggerConfig? logger

Debug logging, log level, and log retention. Access via BGGeo.instance.config.logger. See LoggerConfig.

persistence¶

PersistenceConfig? persistence

SQLite storage, TTL, record limits, and custom extras. Access via BGGeo.instance.config.persistence. See PersistenceConfig.

reset¶

bool? reset

Controls whether the SDK resets to factory defaults before applying this configuration. Defaults to true.

When true (the default), every call to BackgroundGeolocation.ready applies the supplied Config on top of fresh defaults. When false, the SDK applies the supplied Config only on the first install. On subsequent launches it ignores the Config argument entirely — the only way to change settings is via BackgroundGeolocation.setConfig.

Warning

During development, always leave reset: true (or omit it). Setting reset: false causes the SDK to ignore your Config after the first launch, so configuration changes made between development builds will not take effect.

transistorAuthorizationToken¶

TransistorAuthorizationToken? transistorAuthorizationToken

Convenience option that automatically configures the SDK to upload locations to the Transistor Software demo server at tracker.transistorsoft.com, or a local instance of background-geolocation-console.

Setting this option automatically sets HttpConfig.url and the required AuthorizationConfig values. See TransistorAuthorizationService for how to obtain a token.

TransistorAuthorizationToken token = await
  TransistorAuthorizationToken.findOrCreate('my-company-name', 'my-username');

BackgroundGeolocation.ready(Config(
  transistorAuthorizationToken: token
));

// Base url to Transistor Demo Server.
const String url = 'http://tracker.transistorsoft.com';

// Register for an authorization token from server.
TransistorAuthorizationToken token = await
  TransistorAuthorizationToken.findOrCreate('my-company-name', 'my-username');

BackgroundGeolocation.ready(Config(
  /// This convenience option sets [HttpConfig.url] to the Demo server and configures [Authorization].
  url: "$url/api/locations",
  authorization: Authorization(
    strategy: "JWT",
    accessToken: token.accessToken,
    refreshToken: token.refreshToken,
    refreshUrl: "$url/api/refresh_token",
    refreshPayload: {
      "refresh_token": "{refreshToken}"
    },
    expires: token.expires
  )
));