Quick Start

Go from zero to working background location tracking in 5 minutes. Copy the full snippet below into your Capacitor app.

1. Install

npm install @bglocation/capacitor
npx cap sync

2. Complete Working Example

This is a complete, copy-paste-ready snippet. No license key required — the plugin runs in trial mode (30 minutes of full functionality, then 1-hour cooldown).

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

// 1. Request permissions (Android: foreground first, then background)
await BackgroundLocation.requestPermissions({ permissions: ['location'] });
await BackgroundLocation.requestPermissions({ permissions: ['backgroundLocation'] });

// 2. Configure tracking
const result = await BackgroundLocation.configure({
  distanceFilter: 15,
  desiredAccuracy: 'high',
  heartbeatInterval: 15,
  locationUpdateInterval: 5000,
  debug: true,
});

console.log('License mode:', result.licenseMode); // 'trial' or 'full'

// 3. Listen for location updates
BackgroundLocation.addListener('onLocation', (location) => {
  console.log(`📍 ${location.latitude}, ${location.longitude}`);
  console.log(`   accuracy: ${location.accuracy}m, speed: ${location.speed}m/s`);
});

// 4. Listen for heartbeats (fires even when stationary)
BackgroundLocation.addListener('onHeartbeat', (event) => {
  console.log('💓 Heartbeat:', event.location?.latitude, event.location?.longitude);
});

// 5. Start tracking
await BackgroundLocation.start();

// 6. Stop tracking when done
// await BackgroundLocation.stop();
// await BackgroundLocation.removeAllListeners();

3. Run on Device

Important: Test on a Physical Device

Background location tracking requires a real device. Simulators do not reliably generate background location updates or test native background execution.

# iOS
npx cap run ios --target <device-id>

# Android
npx cap run android --target <device-id>

What's Next?

Configure tracking — Fine-tune distance filter, accuracy, and heartbeat in the Background Tracking guide.
Send data to your server — Enable native HTTP posting in the HTTP Posting guide.
Set up geofences — Monitor circular regions in the Geofencing guide.
Add your license key — Remove trial restrictions in the Licensing guide.