Examples

Fleet / Delivery Tracking

Continuous tracking with adaptive distance filter, native HTTP posting, and automatic offline buffering. Ideal for logistics and delivery apps.

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. Low distance filter for detailed route polylines.

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. Great for location-based notifications and triggered actions.

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();

Attendance / Check-In System

Combine geofencing with HTTP posting for automatic workplace check-in and check-out. Uses geofence extras to attach metadata like building and floor.

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

await BackgroundLocation.configure({
  distanceFilter: 100,
  desiredAccuracy: 'balanced',
  heartbeatInterval: 120,
  http: {
    url: 'https://api.company.com/attendance/checkin',
    headers: { Authorization: 'Bearer <token>' },
  },
});

// Register workplace geofence
await BackgroundLocation.addGeofence({
  identifier: 'headquarters',
  latitude: 52.2297,
  longitude: 21.0122,
  radius: 150,
  notifyOnEntry: true,
  notifyOnExit: true,
  extras: { building: 'HQ', floor: '3' },
});

BackgroundLocation.addListener('onGeofence', (event) => {
  if (event.action === 'enter') {
    recordCheckIn(event.identifier, event.extras);
  } else if (event.action === 'exit') {
    recordCheckOut(event.identifier, event.extras);
  }
});

await BackgroundLocation.start();

Recommended Configuration by Use Case