Documentation

Core Options

HTTP Posting

Native HTTP delivery works the same in Capacitor and React Native. The JavaScript wrapper configures it once, then URLSession on iOS and HttpURLConnection on Android post directly from the native layer.

await BackgroundLocation.configure({
  distanceFilter: 15,
  desiredAccuracy: 'high',
  heartbeatInterval: 15,
  locationUpdateInterval: 5000,
  fastestLocationUpdateInterval: 2000,
  http: {
    url: 'https://api.example.com/locations',
    headers: { Authorization: 'Bearer <token>' },
    buffer: { maxSize: 1000 },
  },
});

HTTP POST Body

{
  "location": {
    "latitude": 52.2297,
    "longitude": 21.0122,
    "accuracy": 5.0,
    "speed": 1.2,
    "heading": 180.0,
    "altitude": 110.5,
    "timestamp": 1700000000000,
    "isMoving": true,
    "isMock": false
  }
}

HttpEvent

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

Offline Buffer & Retry

Failed POSTs are stored in SQLite when buffer.maxSizeis configured. Buffered locations flush automatically in FIFO order after the next successful request.

Adaptive Distance Filter

Use auto mode to target stable update intervals regardless of whether the user is walking, cycling, or driving.

distanceFilter: 'auto',
autoDistanceFilter: {
  targetInterval: 10,
  minDistance: 10,
  maxDistance: 500,
}

Notification (Android)

Android tracking runs as a foreground service. Customize the persistent notification text from the wrapper.

notification: {
  title: 'Background Location',
  text: 'Tracking your route',
}

Methods

Events

Register listeners via BackgroundLocation.addListener(event, handler).

Location Object

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

Geofencing

Geofencing is available through the same API surface in both wrappers. Up to 20 regions can be active at once.

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

GeofenceEvent Interface

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

Error Codes

iOS

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to track your route.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Background location is needed for continuous tracking.</string>

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

Android

ACCESS_FINE_LOCATION
ACCESS_COARSE_LOCATION
ACCESS_BACKGROUND_LOCATION
FOREGROUND_SERVICE
FOREGROUND_SERVICE_LOCATION
POST_NOTIFICATIONS

await BackgroundLocation.requestPermissions({
  permissions: ['location'],
});

await BackgroundLocation.requestPermissions({
  permissions: ['backgroundLocation'],
});

Trial Mode

• 30-minute sessions with automatic stop and an onTrialExpired event.
• 1-hour cooldown between trial sessions.
• Debug mode is forced on so you can inspect behavior before buying.

Adding a License Key

Place the key in capacitor.config.ts and rerun sync.

// capacitor.config.ts
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.yourcompany.app',
  plugins: {
    BackgroundLocation: {
      licenseKey: 'BGL1-eyJ...',
    },
  },
};

export default config;

How Validation Works

• RSA-2048 signed payloads are verified fully offline on-device.
• The license is bound to a bundle ID and can be used across the Capacitor and React Native wrappers for the same app identifier.
• The license itself is perpetual. One year of updates is included, then update access can be renewed.

License Status

const result = await BackgroundLocation.configure({ ... });

// result.licenseMode: 'full' | 'trial'
// result.licenseUpdatesUntil?: string
// result.licenseUpdateExpired?: boolean
// result.licenseError?: string

Fleet / Delivery Tracking

Continuous tracking with native HTTP posting and automatic offline buffering.

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

await BackgroundLocation.configure({
  distanceFilter: 'auto',
  autoDistanceFilter: {
    targetInterval: 10,
    minDistance: 10,
    maxDistance: 500,
  },
  desiredAccuracy: 'high',
  heartbeatInterval: 30,
  http: {
    url: 'https://api.fleet.com/vehicle/location',
    headers: { Authorization: 'Bearer <token>' },
    buffer: { maxSize: 2000 },
  },
});

BackgroundLocation.addListener('onHttp', (event) => {
  if (!event.success) {
    console.warn('Buffered:', event.bufferedCount);
  }
});

await BackgroundLocation.start();

Fitness / Running App

High-frequency tracking with in-memory processing for pace, route, and progress stats.

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

const route: Location[] = [];

await BackgroundLocation.configure({
  distanceFilter: 5,
  desiredAccuracy: 'high',
  heartbeatInterval: 10,
  locationUpdateInterval: 3000,
});

BackgroundLocation.addListener('onLocation', (location) => {
  route.push(location);
  updateMapPolyline(route);
});

await BackgroundLocation.start();

Geofencing — Points of Interest

Register circular regions and react to enter, exit, and dwell transitions.

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

await BackgroundLocation.configure({
  distanceFilter: 50,
  desiredAccuracy: 'balanced',
  heartbeatInterval: 60,
});

await BackgroundLocation.addGeofence({
  identifier: 'office',
  latitude: 52.2297,
  longitude: 21.0122,
  radius: 100,
  notifyOnEntry: true,
  notifyOnExit: true,
});

BackgroundLocation.addListener('onGeofence', (event) => {
  console.log(event.identifier, event.action);
});

await BackgroundLocation.start();