Migration Guide

Migrating from @capacitor-community/background-geolocation or similar plugins to @bglocation/capacitor.

Migration Steps

Uninstall the old plugin

npm uninstall @capacitor-community/background-geolocation

Install @bglocation/capacitor

npm install @bglocation/capacitor
npx cap sync

Update imports

// Before
import { BackgroundGeolocation } from '@capacitor-community/background-geolocation';

// After
import { BackgroundLocation } from '@bglocation/capacitor';

Update configuration
Restructure your config options — see the mapping table below.

Replace watchers with event listeners

// Before
const watcherId = await BackgroundGeolocation.addWatcher(options, callback);

// After
BackgroundLocation.addListener('onLocation', (location) => { ... });
BackgroundLocation.addListener('onHeartbeat', (event) => { ... });

Sync native projects
```
npx cap sync
```
Test on a physical device
Background location must always be validated on real hardware.

API Mapping

Old API	New API	Notes
`BackgroundGeolocation.configure()`	`BackgroundLocation.configure()`	Options restructured — see config changes below
`BackgroundGeolocation.start()`	`BackgroundLocation.start()`	Same behavior
`BackgroundGeolocation.stop()`	`BackgroundLocation.stop()`	Same behavior
`BackgroundGeolocation.getCurrentLocation()`	`BackgroundLocation.getCurrentPosition()`	Renamed method
`BackgroundGeolocation.checkStatus()`	`BackgroundLocation.getState()`	Returns LocationState instead of status object
`addWatcher()`	`addListener('onLocation', …)`	Event-based instead of watcher pattern
`N/A`	`addGeofence() / addGeofences()`	New geofencing support
`N/A`	`getVersion()`	New version info
`N/A`	`checkBatteryOptimization()`	New Android battery check

Configuration Changes

Old Option	New Option	Notes
`interval / minInterval`	`locationUpdateInterval`	Unified interval name (Android)
`distanceFilter`	`distanceFilter`	Same, but now supports "auto" mode
`stationaryRadius`	`N/A`	Removed — use adaptive filter instead
`debug`	`debug / debugSounds`	Split into separate flags
`stopAfterTerminate`	`N/A`	Plugin always runs via native service
`startOnBoot`	`N/A`	Not supported — re-start manually
`N/A`	`http: { url, headers, buffer }`	New native HTTP posting
`N/A`	`autoDistanceFilter: { … }`	New adaptive filter config
`N/A`	`heartbeatInterval`	New heartbeat timer

What You Gain

Native HTTP Posting

Automatic POST with offline buffer and retry — no JS bridge needed.

Geofencing

Up to 20 circular regions with enter, exit, and dwell transitions.

Adaptive Distance Filter

Speed-based auto mode adjusts filter dynamically for optimal battery/accuracy.

Heartbeat Timer

Periodic callbacks even when stationary — know the device is alive.

React Native Support

Same native core powers both Capacitor and React Native wrappers.

Debug Mode

Verbose logs, system sounds, and JS debug events for faster diagnosis.