API Reference

Complete TypeScript API exported by @bglocation/capacitor.

Methods

Method	Returns	Description
`getVersion()`	`Promise<VersionInfo>`	Get wrapper and native core version information.
`checkPermissions()`	`Promise<LocationPermissionStatus>`	Check current foreground and background permission state.
`requestPermissions(options?)`	`Promise<LocationPermissionStatus>`	Request foreground or background location permissions.
`configure(options)`	`Promise<ConfigureResult>`	Configure tracking before start(); partial updates are merged.
`start()`	`Promise<LocationState>`	Start background location tracking.
`stop()`	`Promise<LocationState>`	Stop background location tracking.
`getState()`	`Promise<LocationState>`	Read the current enabled/tracking state.
`getCurrentPosition(options?)`	`Promise<Location>`	Request a single location update.
`addGeofence(geofence)`	`Promise<void>`	Register one geofence region.
`addGeofences({ geofences })`	`Promise<void>`	Register multiple geofences atomically.
`removeGeofence({ identifier })`	`Promise<void>`	Remove a geofence by identifier.
`removeAllGeofences()`	`Promise<void>`	Clear all geofences.
`getGeofences()`	`Promise<{ geofences: Geofence[] }>`	Return the currently registered geofences.
`checkBatteryOptimization()`	`Promise<BatteryWarningEvent>`	Inspect Android battery optimization state.
`requestBatteryOptimization()`	`Promise<BatteryWarningEvent>`	Open Android battery optimization settings.
`removeAllListeners()`	`Promise<void>`	Remove all active event listeners.

Events

Event	Payload	Description
`onLocation`	`Location`	Location update based on distanceFilter.
`onHeartbeat`	`HeartbeatEvent`	Periodic heartbeat, even when stationary.
`onProviderChange`	`ProviderChangeEvent`	GPS/network provider status changed.
`onHttp`	`HttpEvent`	Native HTTP POST result.
`onDebug`	`DebugEvent`	Debug log message when debug mode is enabled.
`onBatteryWarning`	`BatteryWarningEvent`	Battery optimization warning on Android.
`onAccuracyWarning`	`AccuracyWarningEvent`	Approximate location warning on iOS 14+.
`onMockLocation`	`MockLocationEvent`	Mock location detected on Android.
`onPermissionRationale`	`PermissionRationaleEvent`	Show a custom rationale before background permission.
`onTrialExpired`	`TrialExpiredEvent`	Trial session ended and tracking stopped automatically.
`onGeofence`	`GeofenceEvent`	Geofence transition: enter, exit, or dwell.

Interfaces

Location

interface Location {
  latitude: number;
  longitude: number;
  accuracy: number;
  speed: number;
  heading: number;
  altitude: number;
  timestamp: number;
  isMoving: boolean;
  isMock: boolean;
  effectiveDistanceFilter?: number;
}

LocationConfig

interface LocationConfig {
  distanceFilter?: number | 'auto';
  desiredAccuracy?: 'high' | 'balanced' | 'low';
  heartbeatInterval?: number;            // seconds (default: 15)
  locationUpdateInterval?: number;       // ms, Android minimum interval
  debug?: boolean;
  debugSounds?: boolean;
  autoDistanceFilter?: AutoDistanceFilterConfig;
  http?: HttpConfig;
  notification?: NotificationConfig;     // Android foreground notification
}

HttpConfig

interface HttpConfig {
  url: string;
  method?: 'POST';
  headers?: Record<string, string>;
  buffer?: {
    maxSize?: number;                   // default: 1000
  };
}

Geofence

interface Geofence {
  identifier: string;
  latitude: number;
  longitude: number;
  radius: number;                        // meters
  notifyOnEntry?: boolean;
  notifyOnExit?: boolean;
  notifyOnDwell?: boolean;
  dwellDelay?: number;                   // seconds
  extras?: Record<string, string>;
}

GeofenceEvent

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

ConfigureResult

interface ConfigureResult {
  licenseMode: 'full' | 'trial';
  distanceFilterMode: 'fixed' | 'auto';
  licenseUpdatesUntil?: string;
  licenseUpdateExpired?: boolean;
  licenseError?: string;
}

HeartbeatEvent

interface HeartbeatEvent {
  location: Location | null;
  timestamp: number;
}

HttpEvent

interface HttpEvent {
  success: boolean;
  statusCode: number;
  error?: string;
  bufferedCount?: number;
  timestamp: number;
}

Error Codes

Code	Description
`NOT_CONFIGURED`	configure() must be called before this method.
`GEOFENCE_LIMIT_EXCEEDED`	Maximum of 20 geofence regions reached.
`GEOFENCE_ERROR`	Native geofence registration failed.
`UNSUPPORTED`	Operation not supported on the current platform.
`TRIAL_COOLDOWN`	Trial cooldown period is active.
`PERMISSION_DENIED`	Required location permissions not granted.