Geofencing Guide

Geofence Interface

interface Geofence {
  identifier: string;              // unique ID
  latitude: number;
  longitude: number;
  radius: number;                  // meters (recommended min: 100m)
  notifyOnEntry?: boolean;         // default: true
  notifyOnExit?: boolean;          // default: true
  notifyOnDwell?: boolean;         // default: false
  dwellDelay?: number;             // seconds (default: 300)
  extras?: Record<string, string>; // custom metadata
}

Add a Geofence

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

// Add a single geofence
await BackgroundLocation.addGeofence({
  identifier: 'office-hq',
  latitude: 52.2297,
  longitude: 21.0122,
  radius: 150,
  notifyOnEntry: true,
  notifyOnExit: true,
  notifyOnDwell: true,
  dwellDelay: 300,
  extras: { name: 'Headquarters', type: 'office' },
});

Batch Add

Add multiple geofences in one call. This is atomic — if the total count would exceed 20, the entire batch is rejected.

// Add multiple geofences atomically (all-or-nothing)
await BackgroundLocation.addGeofences({
  geofences: [
    { identifier: 'store-1', latitude: 52.23, longitude: 21.01, radius: 100 },
    { identifier: 'store-2', latitude: 52.24, longitude: 21.02, radius: 100 },
    { identifier: 'store-3', latitude: 52.25, longitude: 21.03, radius: 100 },
  ],
});

Manage Geofences

// Remove a specific geofence
await BackgroundLocation.removeGeofence({ identifier: 'store-1' });

// Remove all geofences
await BackgroundLocation.removeAllGeofences();

// List currently registered geofences
const { geofences } = await BackgroundLocation.getGeofences();
console.log('Active geofences:', geofences.length);

Listen for Transitions

BackgroundLocation.addListener('onGeofence', (event) => {
  console.log(`Geofence ${event.identifier}: ${event.action}`);
  console.log('Location:', event.location?.latitude, event.location?.longitude);
  console.log('Extras:', event.extras);
  console.log('Timestamp:', new Date(event.timestamp).toISOString());
});

GeofenceEvent

interface GeofenceEvent {
  identifier: string;
  action: 'enter' | 'exit' | 'dwell';
  location: Location | null;
  extras?: Record<string, string>;
  timestamp: number;
}

Dwell Detection

Dwell events fire when the device stays inside a geofence region for at least dwellDelay seconds (default: 300s = 5 minutes).

• Set notifyOnDwell: true to enable.
• Dwell works on both iOS and Android platforms.
• If the app is terminated before the dwell timer fires, the event is emitted on next app launch.

20 Region Limit

Both iOS and Android limit the number of simultaneously active geofence regions to 20. The plugin enforces this limit and rejects addGeofence / addGeofences with GEOFENCE_LIMIT_EXCEEDED when the limit would be exceeded.

Extras Metadata

Attach custom key-value pairs to geofences via the extras field. Extras are returned in the GeofenceEvent payload when the region triggers. Values must be strings — stringify numbers or booleans before passing.

Methods Summary