State¶

Read-only snapshot of the SDK's current runtime state.

const state = await BackgroundGeolocation.getState();
console.log("[state] enabled:", state.enabled, "trackingMode:", state.trackingMode);

Properties¶

Property	Type	Description
enabled	Boolean	Whether the SDK is currently tracking.
isMoving	Boolean	Whether the device is currently in motion.
trackingMode	TrackingMode	Current tracking mode: `LOCATION` or `GEOFENCE`.
odometer	Double	Distance travelled in metres since last reset.
schedulerEnabled	Boolean	Whether the scheduler is currently active.
didDeviceReboot	Boolean	Whether the device rebooted since the SDK was last running.

Members¶

activity¶

activity?:ActivityConfig;

Motion recognition, stop-detection triggers, and motion-trigger delay. See ActivityConfig.

app¶

app?:AppConfig;

App lifecycle — background operation, boot behaviour, headless mode, and foreground notification. See AppConfig.

authorization¶

authorization?:AuthorizationConfig;

JWT and SAS token management with automatic refresh. See AuthorizationConfig.

didDeviceReboot¶

didDeviceReboot: boolean;

true when the app was launched after a device reboot.

didLaunchInBackground¶

didLaunchInBackground: boolean;

iOS only true when the app was relaunched in the background by the OS — for example, due to a background fetch, geofence exit, or stationary geofence transition. On Android, background launch is handled by the Headless Task mechanism — this property does not apply.

enabled¶

enabled: boolean;

true when the SDK is actively tracking — i.e. BackgroundGeolocation.start or BackgroundGeolocation.startGeofences has been called and not yet stopped.

geolocation¶

geolocation?:GeoConfig;

Accuracy, sampling, elasticity, stop-detection, permissions, and geofencing. See GeoConfig.

http¶

http?:HttpConfig;

Upload URL, HTTP method, sync cadence, batching, headers, and params. See HttpConfig.

isFirstBoot¶

true on the very first launch after the app is installed.

isMoving¶

isMoving: boolean;

true when the SDK is in the moving state (location services active); false when stationary.

// Toggle the SDK's motion state from stationary to moving.
BackgroundGeolocation.onMotionChange((event) => {
  console.log('[onMotionChange] isMoving?', event.isMoving);
});

await BackgroundGeolocation.changePace(true);
// State.isMoving is now true.

logger¶

logger?:LoggerConfig;

Debug logging, log level, and log retention. See LoggerConfig.

odometer¶

odometer: number;

Accumulated distance traveled since the last odometer reset, in meters.

See also - odometerError - BackgroundGeolocation.setOdometer - BackgroundGeolocation.getOdometer

odometerError¶

odometerError: number;

Accumulated positional error in the odometer measurement, in meters.

Reflects noise introduced by low-accuracy location samples. Use LocationFilter.odometerAccuracyThreshold to filter out low-accuracy samples from odometer calculations.

persistence¶

persistence?:PersistenceConfig;

SQLite storage, TTL, record limits, and custom extras. See PersistenceConfig.

reset¶

reset?: boolean;

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.

schedulerEnabled¶

schedulerEnabled: boolean;

true when a AppConfig.schedule is configured and BackgroundGeolocation.startSchedule has been called. BackgroundGeolocation.stopSchedule sets this to false.

trackingMode¶

trackingMode:TrackingMode;

Current tracking mode.

Value	Mode	Description
`0`	Geofences	Geofence monitoring only — no active location tracking.
`1`	Location	Location tracking and geofence monitoring.

await BackgroundGeolocation.start();
let state = await BackgroundGeolocation.getState();
console.log('Tracking mode:', state.trackingMode);
// > 'Tracking mode: 1'

await BackgroundGeolocation.startGeofences();
state = await BackgroundGeolocation.getState();
console.log('Tracking mode:', state.trackingMode);
// > 'Tracking mode: 0'

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.

const token = await BackgroundGeolocation.findOrCreateTransistorAuthorizationToken(
  "my-company-name",
  "my-username"
);

BackgroundGeolocation.ready({
  transistorAuthorizationToken: token
});