@capgo/background-geolocation

Accurate background location tracking, native geofence enter/exit events, and transition webhooks for Capacitor apps.

Overview

Use @capgo/background-geolocation when your Capacitor app needs precise location updates in the foreground or background, native circular geofences on iOS and Android, and backend delivery for geofence transitions when the WebView is suspended.

Core Capabilities

start - Stream accurate foreground or background location updates.
stop - Stop active location tracking cleanly.
openSettings - Send users to native location settings when permissions need attention.
setPlannedRoute - Play a native sound when the user deviates from a planned route.
setupGeofencing - Configure native geofence defaults and optional transition webhook delivery.
addGeofence - Monitor a circular iOS or Android geofence region by identifier.
removeGeofence / removeAllGeofences - Stop monitoring one or all registered geofences.
getMonitoredGeofences - List region identifiers currently monitored by the native layer.
geofenceTransition listener - Receive enter and exit events while the app is active.
geofenceError listener - Handle native monitoring errors without changing the transition event shape.

Public API

Method	Description
`start`	Streams accurate foreground or background location updates.
`stop`	Stops location updates.
`openSettings`	Opens the device’s location settings page. Useful for directing users to enable location services or adjust permissions.
`setPlannedRoute`	Plays a native sound when the user deviates from a planned route.
`setupGeofencing`	Configures geofence defaults and optional native transition POST delivery.
`addGeofence`	Starts monitoring a circular geofence on iOS and Android.
`removeGeofence`	Stops monitoring one geofence by identifier.
`removeAllGeofences`	Stops monitoring all geofences registered by this plugin.
`getMonitoredGeofences`	Returns the identifiers currently monitored by the native layer.
`addListener('geofenceTransition', ...)`	Receives geofence enter and exit events while the app is alive.
`addListener('geofenceError', ...)`	Receives native geofence monitoring errors while the app is alive.
`getPluginVersion`	Get the native Capacitor plugin version.

Source Of Truth

This reference is synced from src/definitions.ts in capacitor-background-geolocation.

Keep going from @capgo/background-geolocation

If you are using @capgo/background-geolocation to plan native plugin work, connect it with Using @capgo/background-geolocation for the native capability in Using @capgo/background-geolocation, Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Plugins for the implementation detail in Adding or Updating Plugins, and Ionic Enterprise Plugin Alternatives for the product workflow in Ionic Enterprise Plugin Alternatives.