Skip to content

@capgo/background-geolocation

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

Closed-app iOS delivery

Call GeofenceRelay.shared.start() from the iOS app delegate so a terminated app can still POST a region crossing when iOS relaunches it. Always location access is required for that relaunch.

Disk queue and retries

On iOS, transitions are queued on disk and sent in order. iOS retries on network loss, 5xx, 408, 429, or 401/403. That iOS queue keeps the newest 100 transitions, none older than seven days. Android retries through WorkManager and does not use this ordered queue or those limits.

clearGeofenceQueue()

Drop unsent native POSTs on sign-out or an account switch on the same url. The queue is also emptied when setupGeofencing is given a different url. On web there is no queue and the call resolves at once.

Event time

Optional GeofenceTransitionEvent.time is when the phone detected the crossing, in milliseconds since the epoch. Read this in your webhook, not the server clock, because a queued POST can arrive later.

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.

  • 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.
  • updateHeaders - Replace persisted HTTP headers used by native POST delivery.
  • clearGeofenceQueue - Drop geofence transitions queued for a native POST and not yet sent.
  • geofenceTransition listener - Receive enter and exit events while the app is active, including optional time.
  • geofenceError listener - Handle native monitoring errors without changing the transition event shape.
MethodDescription
startStreams accurate foreground or background location updates.
stopStops location updates.
openSettingsOpens the device’s location settings page. Useful for directing users to enable location services or adjust permissions.
setPlannedRoutePlays a native sound when the user deviates from a planned route.
setupGeofencingConfigures geofence defaults and optional native transition POST delivery.
addGeofenceStarts monitoring a circular geofence on iOS and Android.
removeGeofenceStops monitoring one geofence by identifier.
removeAllGeofencesStops monitoring all geofences registered by this plugin.
getMonitoredGeofencesReturns the identifiers currently monitored by the native layer.
updateHeadersReplaces persisted HTTP headers for native POST delivery. On iOS this also flushes the geofence queue. On Android it saves headers without starting queued WorkManager jobs.
clearGeofenceQueueDrops geofence transitions queued for a native POST and not yet sent. Resolves at once on web.
addListener('geofenceTransition', ...)Receives geofence enter and exit events while the app is alive. Events may include time.
addListener('geofenceError', ...)Receives native geofence monitoring errors while the app is alive.
getPluginVersionGet the native Capacitor plugin version.

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

Keep going from @capgo/background-geolocation

Section titled “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.