Quick Start

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

1. Install

npm install @bglocation/react-native
npx expo prebuild

# Bare React Native (no Expo)
cd ios && pod install

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 {
  addListener,
  configure,
  requestPermissions,
  start,
  stop,
  removeAllListeners,
} from '@bglocation/react-native';

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

// 2. Configure tracking
const result = await 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
const locationSub = 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)
const heartbeatSub = addListener('onHeartbeat', (event) => {
  console.log('💓 Heartbeat:', event.location?.latitude, event.location?.longitude);
});

// 5. Start tracking
await start();

// 6. Stop tracking when done
// locationSub.remove();
// heartbeatSub.remove();
// await stop();
// 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 expo run:ios --device

# Android
npx expo run:android --device

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.