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.
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.| 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. |
updateHeaders | Replaces 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. |
clearGeofenceQueue | Drops 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. |
getPluginVersion | Get the native Capacitor plugin version. |
This reference is synced from src/definitions.ts in capacitor-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.