Background Location Tracking

Configure the tracking engine: distance filter, heartbeat interval, accuracy level, and understand their impact on battery.

Configuration Options

All options are passed to configure(). Subsequent calls merge with the previous configuration — pass only the fields you want to change.

Option	Type	Default	Description
`distanceFilter`	`number \| 'auto'`	15	Minimum distance in meters between location updates. Use 'auto' for speed-adaptive mode.
`desiredAccuracy`	`'high' \| 'balanced' \| 'low'`	'high'	Accuracy preset. 'high' uses GPS, 'balanced' uses Wi-Fi/cell, 'low' uses passive provider.
`heartbeatInterval`	`number`	15	Interval in seconds between heartbeat events. Fires even when stationary.
`locationUpdateInterval`	`number`	5000	Android-only: requested update interval in milliseconds.
`fastestLocationUpdateInterval`	`number`	2000	Android-only: fastest allowed update interval in milliseconds.

Distance Filter: Fixed vs Auto

Fixed Distance Filter

Set a constant minimum distance (e.g., 15 meters). The native location manager only delivers updates when the device has moved at least this far. Best when your required precision is constant regardless of speed.

distanceFilter: 15

Auto Distance Filter

The filter adjusts automatically based on the device's speed. Slower movement means smaller filter (more precision), faster movement means larger filter (less battery drain). Ideal for mixed-mode transport.

distanceFilter: 'auto',
autoDistanceFilter: {
  targetInterval: 10,
  minDistance: 10,
  maxDistance: 500,
}

Heartbeat Timer

The heartbeat fires at a fixed interval regardless of movement. Each heartbeat includes the last known location (or null if none acquired yet). Use heartbeats to:

Confirm the device is still alive and tracking
Detect stationary periods (no onLocation events between heartbeats)
Trigger server-side logic on a schedule independent of movement

Recommended Settings by Use Case

Use Case	Distance Filter	Heartbeat (s)	Accuracy	Notes
Fleet / Delivery	'auto' or 50–100	30–60	`'high'`	Adaptive filter adjusts to vehicle speed. HTTP posting with buffer recommended.
Fitness / Running	5–15	10–15	`'high'`	Low distance filter for accurate polyline. High battery drain acceptable.
General Tracking	15–30	15–30	`'high'`	Good balance of accuracy and battery life.
Geofence-Only	50–100	60	`'balanced'`	Location updates are secondary. Focus on geofence transitions.

Battery Impact

Background location tracking consumes battery. The most impactful settings are:

desiredAccuracy: 'high' — GPS hardware stays active. Highest battery drain but best accuracy.
Small distanceFilter — More frequent updates = more CPU wake-ups.
Short heartbeatInterval — Frequent timer fires keep the process active.
HTTP posting — Network I/O adds to power consumption, but native posting is more efficient than JS-side fetch calls.

Tip: Balance Accuracy and Battery

For most apps, distanceFilter: 'auto' with default settings provides the best trade-off. It automatically reduces updates when stationary and increases them during movement.

Complete Example

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

await BackgroundLocation.configure({
  distanceFilter: 15,           // meters (or 'auto')
  desiredAccuracy: 'high',      // GPS-level accuracy
  heartbeatInterval: 15,        // seconds
  locationUpdateInterval: 5000, // Android only: ms
  fastestLocationUpdateInterval: 2000,
});

BackgroundLocation.addListener('onLocation', (location) => {
  console.log(location.latitude, location.longitude);
  console.log('Moving:', location.isMoving, 'Speed:', location.speed);
});

BackgroundLocation.addListener('onHeartbeat', (event) => {
  console.log('Heartbeat at:', event.timestamp);
  if (event.location) {
    console.log('Last known:', event.location.latitude, event.location.longitude);
  }
});

await BackgroundLocation.start();