BackgroundGeolocation¶

Primary SDK API — the single entry point for all geolocation, geofencing, HTTP sync, and configuration operations.

Contents¶

Overview
Lifecycle
Configuration
Events
Examples

Overview¶

The SDK operates around a motion-based state machine: it tracks aggressively while the device is moving and pauses location services when stationary, delivering high-quality background tracking with minimal battery impact.

Area	Key methods
Lifecycle	`ready`, `start`, `stop`, `setConfig`, `reset`
Location	`getCurrentPosition`, `watchPosition`, `getOdometer`
Geofencing	`addGeofence`, `startGeofences`, `onGeofence`
Events	`onLocation`, `onMotionChange`, `onHttp`, `onProviderChange`
Persistence	`getLocations`, `getCount`, `sync`, `destroyLocations`
Background tasks	`startBackgroundTask`, `stopBackgroundTask`

Lifecycle¶

Think of the SDK like a stereo receiver:

Wiring the speakers — Register event listeners (onLocation, onGeofence, etc.) before calling ready. The SDK buffers events until ready resolves, so listeners registered afterward may miss them. You do not need to remove listeners when you call stop — the SDK simply stops emitting events when it isn't running.
Plugging in the power cord — ready initializes the SDK, restores persisted state, and applies your configuration. Call it once per launch, before any method that acquires a location or requests permissions. Your config is not applied until ready resolves.
The power button — start and stop begin and halt location tracking. The SDK persists its enabled state across launches. If the app is terminated while tracking is active, the next call to ready will automatically resume tracking — you do not need to call start again.

Always call ready on every launch — no exceptions. The SDK buffers all events from the moment the app starts, and holds them until ready is called. If your app launches and never calls ready, the SDK sits silently waiting: no events fire, no locations are recorded, no uploads are attempted. It does not matter whether tracking was already active from a previous session — ready is the signal that tells the SDK your app is alive and listening. This is why the method is named ready.

Calling methods before ready resolves is perfectly fine, provided they do not request a location or trigger a permission dialog. Methods that only read from the SDK's SQLite database are safe — for example getState, getLocations, getGeofences, removeGeofences. Avoid start, requestPermission, getCurrentPosition, and watchPosition until after ready resolves. The SDK defaults apply until your config arrives — calling a permission-sensitive method too early will use those defaults, not your configured values.

Configuration¶

The SDK uses a compound-configuration model. Options are grouped into typed sub-interfaces (GeoConfig, HttpConfig, AppConfig, etc.) passed as a single Config object. All SDK constants are available as strongly-typed enum namespaces on the default export:

Events¶

Each onX method returns a Subscription that must be removed when no longer needed:

Examples¶

Events¶

onActivityChange¶

Subscribe to motion-activity changes.

Fires each time the activity-recognition system reports a new activity (still, on_foot, in_vehicle, on_bicycle, running).

Android¶

MotionActivityEvent.confidence always reports 100.

activitychange

onAuthorization¶

Subscribe to Config.authorization events.

Fires when AuthorizationConfig.refreshUrl responds, either successfully or not. On success, AuthorizationEvent.success is true and AuthorizationEvent.response contains the decoded JSON response. On failure, AuthorizationEvent.error contains the error message.

authorization

onConnectivityChange¶

Subscribe to network connectivity changes.

Fires when the device's network connectivity transitions between connected and disconnected. By default, the SDK also fires this event at start time with the current connectivity state. When connectivity is restored and the SDK has queued locations, it automatically initiates an upload to HttpConfig.url.

connectivitychange

onEnabledChange¶

Subscribe to changes in plugin State.enabled.

Fires when State.enabled changes. Calling start or stop triggers this event.

enabledchange

onGeofence¶

Subscribe to geofence transition events.

Fires when any monitored geofence crossing occurs.

See also - 📘 Geofencing Guide

geofence

onGeofencesChange¶

Subscribe to changes in the set of actively monitored geofences.

Fires when the SDK's active geofence set changes. The SDK can monitor any number of geofences in its database — even thousands — despite native platform limits (20 for iOS; 100 for Android). It achieves this with a geospatial query that activates only the geofences nearest to the device's current location (see GeoConfig.geofenceProximityRadius). When the device is moving, the query runs periodically and the active set may change — that change triggers this event.

See also - 📘 Geofencing Guide

geofenceschange

onHeartbeat¶

Subscribe to periodic heartbeat events.

Fires at each AppConfig.heartbeatInterval while the device is in the stationary state. On iOS, AppConfig.preventSuspend must also be true to receive heartbeats in the background.

Note

The Location provided by the HeartbeatEvent is only the last-known location — the heartbeat does not engage location services. To fetch a fresh location inside your callback, call getCurrentPosition.

heartbeat

onHttp¶

Subscribe to HTTP responses from your server HttpConfig.url.

See also - HTTP Guide

http

onLocation¶

Subscribe to location events.

Every location recorded by the SDK is delivered to your callback, including locations from onMotionChange, getCurrentPosition, and watchPosition.

Error Codes¶

If the native location API fails, the error callback receives a LocationError code.

Note

During onMotionChange and getCurrentPosition, the SDK requests multiple location samples to find the most accurate fix. These intermediate samples are not persisted, but are delivered to this callback with Location.sample set to true. Filter out sample locations before manually posting to your server.

location

onMotionChange¶

Subscribe to motion-change events.

Fires each time the device transitions between the moving and stationary states.

Warning

When a motion-change event fires, HttpConfig.autoSyncThreshold is ignored — all queued locations are uploaded immediately. The SDK flushes eagerly before going dormant (moving→stationary) and immediately after waking up (stationary→moving).

See also - GeoConfig.stopTimeout

motionchange

onNotificationAction¶

Android only Subscribe to button-click actions on the Android foreground-service notification.

Fires when the user taps a button defined in a custom NotificationConfig.layout.

onPowerSaveChange¶

Subscribe to OS power-saving mode changes.

Fires when the operating system's power-saving mode is enabled or disabled. Power-saving mode can throttle background services such as GPS and HTTP uploads.

See also - isPowerSaveMode

iOS¶

Power Saving mode is enabled manually in Settings → Battery or via an automatic OS prompt.

Android¶

Battery Saver is enabled manually in Settings → Battery → Battery Saver or automatically when the battery drops below a configured threshold.

powersavechange

onProviderChange¶

Subscribe to location-services authorization changes.

Fires whenever the state of the device's location-services authorization changes (e.g. GPS enabled, WiFi-only, permission revoked). The SDK also fires this event immediately after ready completes, so you always receive the current authorization state on each app launch.

See also - getProviderState

providerchange

onSchedule¶

Subscribe to AppConfig.schedule events.

Fires each time a schedule event activates or deactivates tracking. Check state.enabled in your callback to determine whether tracking was started or stopped.

schedule

Methods¶

changePace¶

Manually toggle the SDK's motion state between stationary and moving.

Passing true immediately engages location services and begins tracking, bypassing stationary monitoring. Passing false turns off location services and returns the SDK to the stationary state.

Use this in workout-style apps where you want explicit start/stop control independent of the device's motion sensors.

destroyTransistorAuthorizationToken¶

Destroy a Transistor authorization token.

See TransistorAuthorizationService for more information.

findOrCreateTransistorAuthorizationToken¶

Find or create a Transistor authorization token.

See TransistorAuthorizationService for more information.

getCurrentPosition¶

Retrieve the current Location.

Instructs the SDK to fetch a single location at maximum power and accuracy. The location is persisted to SQLite and posted to HttpConfig.url just like any other recorded location. If an error occurs, the promise rejects with a LocationError.

Options¶

See CurrentPositionRequest.

Error Codes¶

See LocationError.

Note

The SDK requests multiple location samples internally to find the best fix. All intermediate samples are delivered to onLocation with Location.sample set to true. Filter these out if you are manually posting locations to your server.

getDeviceInfo¶

Returns device information.

getOdometer¶

Retrieve the current odometer reading in meters.

The SDK continuously accumulates distance traveled between recorded locations.

Warning

Odometer accuracy depends on location accuracy. Noisy or inaccurate locations introduce error into accumulated distance. Use LocationFilter.odometerAccuracyThreshold to filter low-accuracy samples from odometer calculations.

See also - LocationFilter.odometerAccuracyThreshold - resetOdometer / setOdometer

getState¶

Return the current State of the SDK, including all Config parameters.

ready¶

Signal to the SDK that your app is launched and ready, supplying the default Config.

Call ready exactly once per app launch, before calling start. The SDK applies your configuration, restores persisted state, and prepares for tracking. On subsequent launches after first install, it loads the persisted configuration and merges your supplied Config on top. See Config.reset for finer control over this behaviour.

Warning

Call ready once per app launch from your application root — not inside a component or behind a UI action. On iOS, the OS can relaunch your app in the background when the device starts moving; if ready is not called in that path, tracking will not resume.

See also - Config.reset - setConfig

registerHeadlessTask¶

Android only Registers a headless-task callback for Android background events when the app has been terminated with AppConfig.stopOnTerminate:false.

The callback receives a HeadlessEvent with a name (event name) and params (event data).

Warning

You must call registerHeadlessTask in your application root file (e.g. index.js), not inside a component or behind a UI action.

Warning

Your function must be declared async. Await all work inside it — the headless task is automatically terminated after the last line executes.

Note

Javascript headless callbacks are not supported by Cordova or Capacitor.

Debugging¶

While implementing your headless task, observe Android logs via:

$ adb logcat *:S TSLocationManager:V ReactNativeJS:V

See also - 📘 Android Headless Mode - AppConfig.enableHeadless

removeListeners¶

Remove all event listeners.

Calls Subscription.remove on all active subscriptions.

reset¶

Reset the SDK configuration to documented default values.

If an optional Config is provided, it is applied after the reset.

resetOdometer¶

Reset the odometer to 0.

Internally performs a getCurrentPosition to record the exact location where the odometer was reset. Equivalent to .setOdometer(0).

setConfig¶

Update the SDK's Config at runtime.

The supplied Config is merged into the current configuration and applied immediately. Use this after ready has been called to change settings dynamically.

setOdometer¶

Set the odometer to an arbitrary value.

Internally performs a getCurrentPosition to record the exact location where the odometer was set.

start¶

Enable location and geofence tracking.

This is the SDK's power ON switch. The SDK enters its stationary state, acquires an initial location, then turns off location services until motion is detected. On Android, the Activity Recognition System monitors for motion; on iOS, a stationary geofence is created around the current location.

Note

If a AppConfig.schedule is configured, start overrides the schedule and begins tracking immediately.

See also - stop - startGeofences

startGeofences¶

Switch to geofences-only tracking mode.

In this mode no active location tracking occurs — only geofences are monitored. Use the usual stop method to exit geofences-only mode.

start and startGeofences are mutually exclusive — call one or the other, never both. start enables full tracking: location recording and geofence monitoring run together. startGeofences enables geofence monitoring only, with no continuous location recording. Calling start while already in geofences-only mode (or vice versa) switches modes; there is no need to call stop first.

See also - stop - 📘 Geofencing Guide

startSchedule¶

Activate the configured AppConfig.schedule.

Initiates the schedule defined in AppConfig.schedule. The SDK automatically starts or stops tracking according to the schedule. To halt scheduled tracking, call stopSchedule.

See also - AppConfig.schedule - stopSchedule

stop¶

Disable location and geofence monitoring.

This is the SDK's power OFF switch.

Note

If a AppConfig.schedule is configured, stop does not halt the scheduler. Call stopSchedule explicitly if you also want to stop scheduled tracking (for example, on user logout).

stopSchedule¶

Halt scheduled tracking.

Warning

stopSchedule does not call stop if the SDK is currently tracking. Call stop explicitly if you also want to end the current tracking session.

See also - startSchedule

watchPosition¶

Start a continuous stream of location updates.

Each location is persisted to SQLite (when the SDK is State.enabled) and posted to HttpConfig.url if HTTP is configured. Returns a Subscription that must be retained to halt the stream.

Warning

watchPosition is designed for foreground use only — not for long-term background monitoring. The SDK's motion-based tracking model does not require it.

iOS¶

watchPosition continues running in the background, preventing iOS from suspending your app. Remove the subscription in your app's suspend handler to avoid draining the battery.

Geofencing¶

addGeofence¶

Add a Geofence to be monitored by the native geofencing API.

Note

If a geofence with the same Geofence.identifier already exists, it is deleted before the new one is inserted. When adding multiple geofences, addGeofences is approximately 10× faster.

See also - 📘 Geofencing Guide

addGeofences¶

Add a list of Geofence to be monitored by the native geofencing API.

Note

If any geofence already exists with a matching Geofence.identifier, it is deleted before the new one is inserted.

See also - 📘 Geofencing Guide - addGeofence

geofenceExists¶

Determine whether a geofence with the given identifier exists in the SDK's database.

See also - 📘 Geofencing Guide

getGeofence¶

Fetch a single Geofence by identifier from the SDK's database.

See also - 📘 Geofencing Guide

getGeofences¶

Fetch all Geofence records from the SDK's database.

Returns an empty array if no geofences are stored.

See also - 📘 Geofencing Guide

removeGeofence¶

Remove the Geofence with the given Geofence.identifier.

See also - 📘 Geofencing Guide

removeGeofences¶

Remove all monitored Geofence records, or a specific subset by identifier.

See also - 📘 Geofencing Guide

Data Management¶

destroyLocation¶

Remove a single location by Location.uuid.

destroyLocations¶

Remove all records from the SDK's SQLite database.

getCount¶

Retrieve the count of all locations currently stored in the SDK's SQLite database.

getLocations¶

Retrieve all Location records stored in the SDK's SQLite database.

sync¶

Manually upload all queued locations to HttpConfig.url.

Initiates a POST of all records in the SQLite database to your configured HttpConfig.url. Records that receive a 200 OK response are deleted from the database. If HttpConfig.batchSync is true, all locations are sent in a single request; otherwise one request is made per location. If no HTTP service is configured, all records are deleted from the database.

See also - HTTP Guide

Authorization¶

getProviderState¶

Retrieve the current location-services authorization state.

See also - onProviderChange to subscribe to future authorization changes.

requestPermission¶

Manually request location permission using the configured GeoConfig.locationAuthorizationRequest.

Resolves successfully if either WhenInUse or Always is granted, regardless of the requested level. Rejects if the user denies.

If permission is already granted, resolves immediately. If iOS has already shown the authorization dialog and the current grant does not match the configured request, the SDK presents an alert offering to direct the user to your app's Settings page.

Note

The SDK automatically requests permission when you call start, startGeofences, or getCurrentPosition. You do not need to call this method in typical use.

See also - GeoConfig.locationAuthorizationRequest - GeoConfig.disableLocationAuthorizationAlert - GeoConfig.locationAuthorizationAlert - AppConfig.backgroundPermissionRationale (Android) - requestTemporaryFullAccuracy (iOS 14+)

requestTemporaryFullAccuracy¶

Request temporary full-accuracy location authorization. [iOS 14+]

iOS 14 allows users to grant only reduced location accuracy. This method presents the system dialog (requestTemporaryFullAccuracyAuthorization) requesting full accuracy for the lifetime of the current app session.

Configuration — Info.plist¶

Add the Privacy - Location Temporary Usage Description Dictionary key to your Info.plist:

The dictionary keys (e.g. Delivery) are passed as purposeKey. The corresponding value is the message shown to the user explaining the purpose of your request.

The dialog fails to present if: - The Info.plist entry for purposeKey is missing. - The app is already authorized for full accuracy. - The app is in the background.

Note

On Android and iOS versions below 14, this method returns AccuracyAuthorization.Full immediately without presenting a dialog.

Background Tasks¶

startBackgroundTask¶

Signal to the OS that you need to perform a long-running task.

The OS keeps the app running in the background until you signal completion with stopBackgroundTask. Your callback receives a taskId which you must pass to stopBackgroundTask when finished — always call it, even if an error occurs, to avoid hanging the background task.

iOS¶

Uses beginBackgroundTaskWithExpirationHandler. iOS provides exactly 180 seconds of background time. The SDK automatically stops the task before the OS force-kills the app.

✅-[BackgroundTaskManager createBackgroundTask] 1
✅-[BackgroundTaskManager stopBackgroundTask:]_block_invoke 1 OF (1)

Android¶

Uses WorkManager. The SDK imposes a 3-minute limit before automatically force-killing the task.

 I TSLocationManager: [c.t.l.u.BackgroundTaskManager onStartJob] ⏳ startBackgroundTask: 6
 I TSLocationManager: [c.t.l.u.BackgroundTaskManager$Task stop] ⏳ stopBackgroundTask: 6

stopBackgroundTask¶

Signal completion of a startBackgroundTask to the OS.

The OS may now suspend the app if appropriate.

Logging¶

playSound¶

Play a system sound.

iOS¶

Provide a numeric SystemSoundID.

Android¶

Provide a sound name string.

setLogLevel¶

Sets the LoggerConfig.logLevel.

Device¶

getSensors¶

Returns the availability of motion sensors: accelerometer, gyroscope, and magnetometer.

These sensors power the motion activity-recognition system. When any sensor is absent (particularly on low-end Android devices), motion recognition performance degrades significantly.

isPowerSaveMode¶

Returns the current state of the operating system's power-saving mode.

Power-saving mode can throttle background services such as GPS and HTTP uploads.

See also - onPowerSaveChange to subscribe to future changes.

iOS¶

Power Saving mode is enabled manually in Settings → Battery or via an automatic OS prompt.

Android¶

Battery Saver is enabled manually in Settings → Battery → Battery Saver or automatically when the battery drops below a configured threshold.

Properties¶

AccuracyAuthorization¶

Enum namespace indicating whether the user granted full or reduced location accuracy. [iOS 14+]

Used by ProviderChangeEvent.accuracyAuthorization and requestTemporaryFullAccuracy.

ActivityType¶

iOS only Enum namespace specifying the type of user activity (AutomotiveNavigation, Fitness, OtherNavigation, etc).

Used by GeoConfig.activityType.

AuthorizationStatus¶

Enum namespace representing the OS-level authorization state for location services (Denied, Restricted, Always, WhenInUse).

Returned from requestPermission() and onProviderChange.

AuthorizationStrategy¶

Enum namespace defining how the HTTP service performs authorization.

Includes basic, JWT, and custom strategies. Used by AuthorizationConfig.strategy.

DesiredAccuracy¶

Enum namespace controlling the native location engine's target accuracy.

Higher accuracy consumes more battery. Used by GeoConfig.desiredAccuracy.

Event¶

Enum namespace of all event names emitted by the SDK (location, geofence, motionchange, heartbeat, etc).

HttpMethod¶

Enum namespace defining the HTTP method used for location uploads (POST, PUT, etc).

Used by HttpConfig.method.

KalmanProfile¶

Enum namespace selecting a preset Kalman filter tuning profile (aggressive, moderate, or relaxed smoothing).

Used by LocationFilter.kalmanProfile.

LocationFilterPolicy¶

Enum namespace selecting the filtering engine policy for noise-reduction and smoothing.

Used by LocationFilter.policy.

LocationRequest¶

iOS only Enum namespace defining the type of location permission request (Always, WhenInUse, or Any). Used by GeoConfig.locationAuthorizationRequest.

LogLevel¶

Enum namespace controlling verbosity of the SDK logger.

Used by LoggerConfig.logLevel. Values range from silent (Off) to extremely verbose (Verbose).

NotificationPriority¶

Android only Enum namespace controlling Android foreground-service notification priority and icon placement (top, bottom, hidden).

Used by NotificationConfig.priority.

PersistMode¶

Enum namespace controlling which records the SDK persists to SQLite: locations only, geofences only, both, or none.

Used by PersistenceConfig.persistMode.

TriggerActivity¶

Enum namespace defining which physical motion activities can trigger motion-detection transitions (still → moving).

Used by ActivityConfig.triggerActivities.

app¶

App API — background-task and power-save utilities.

authorization¶

Authorization API — request and monitor location permissions.

config¶

Config API — read and update the SDK configuration.

deviceSettings¶

DeviceSettings API

geofences¶

Access to the GeofenceManager — add, remove, and query geofences.

val bgGeo = BGGeo.instance
bgGeo.geofences.add(geofence)

logger¶

Logger API

sensors¶

Sensors API — query the device motion hardware.

state¶

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

store¶

DataStore API — query, upload, and destroy persisted location records.