@bglocation/react-native

React Native module for continuous background location tracking on iOS and Android.

Part of the bglocation.dev ecosystem — identical API surface as @bglocation/capacitor.

Status

� Bridge complete — native bridges (iOS + Android) are fully wired to bglocation-native-core. All 14 API methods and 11 events are implemented. Not yet published to npm — pending manual device testing.

Features

• Continuous background GPS tracking (iOS + Android)
• Configurable distance filter (fixed or speed-adaptive auto mode)
• Heartbeat timer for stationary detection
• Native HTTP POST with offline SQLite buffer + retry
• Geofencing (up to 20 regions, enter/exit/dwell)
• RSA-2048-SHA256 license validation (perpetual + update gating)
• Trial mode (30 min + 1h cooldown)
• Battery optimization detection (Android)
• Approximate location detection (iOS 14+)
• Mock location detection (Android)
• Debug mode with verbose logging

Requirements

• React Native >= 0.76 (New Architecture / TurboModules)
• iOS >= 15.0
• Android API >= 26 (Android 8.0)

Installation

npm install @bglocation/react-native
# or
yarn add @bglocation/react-native

Expo (Dev Build / CNG)

Add the plugin to your app.json / app.config.js:

{
  "expo": {
    "plugins": [
      [
        "@bglocation/react-native",
        {
          "locationWhenInUsePermission": "This app uses your location to track your position.",
          "locationAlwaysPermission": "This app uses your location in the background to continuously track your position."
        }
      ]
    ]
  }
}

Then rebuild: npx expo prebuild --clean && npx expo run:ios

Note: This plugin requires native code and does not work in Expo Go.

Bare React Native — iOS

cd ios && pod install

Bare React Native — Android

No additional setup required — auto-linking handles everything.

Quick Start

import {
  configure,
  start,
  stop,
  addListener,
  requestPermissions,
} from '@bglocation/react-native';

// 1. Request permissions
await requestPermissions({ permissions: ['location'] });
await requestPermissions({ permissions: ['backgroundLocation'] });

// 2. Configure
const result = await configure({
  distanceFilter: 'auto',
  heartbeatInterval: 15,
  debug: true,
  http: {
    url: 'https://api.example.com/locations',
    headers: { Authorization: 'Bearer TOKEN' },
  },
});

console.log('License mode:', result.licenseMode);

// 3. Listen for events
const sub = addListener('onLocation', (location) => {
  console.log('Location:', location.latitude, location.longitude);
});

// 4. Start tracking
await start();

// 5. Stop tracking
await stop();
sub.remove();

API

The API is identical to @bglocation/capacitor. See the full API Reference.

Methods

| Method | Description | |--------|-------------| | checkPermissions() | Check current location permission status | | requestPermissions(options?) | Request location permissions | | configure(options) | Configure the location service + validate license | | start() | Start background tracking | | stop() | Stop background tracking | | getState() | Get current tracking state | | getCurrentPosition(options?) | One-shot location request | | addGeofence(geofence) | Add a geofence region | | addGeofences(options) | Batch add geofences (atomic) | | removeGeofence(options) | Remove a geofence by identifier | | removeAllGeofences() | Remove all geofences | | getGeofences() | Get registered geofences | | checkBatteryOptimization() | Check battery optimization state | | requestBatteryOptimization() | Open battery optimization settings | | addListener(event, handler) | Subscribe to events | | removeAllListeners() | Remove all event listeners |

Events

| Event | Description | |-------|-------------| | onLocation | Location update | | onHeartbeat | Stationary heartbeat | | onProviderChange | GPS/Network provider change | | onHttp | HTTP POST response | | onDebug | Debug log message | | onBatteryWarning | Battery optimization warning (Android) | | onAccuracyWarning | Approximate location warning (iOS 14+) | | onMockLocation | Mock location detected (Android) | | onPermissionRationale | Permission rationale needed (Android 11+) | | onTrialExpired | Trial period expired | | onGeofence | Geofence transition (enter/exit/dwell) |

License

ELv2 (Elastic License v2)

Migration from Capacitor

Change the import and remove Capacitor-specific patterns:

- import { BackgroundLocation } from '@bglocation/capacitor';
+ import { configure, start, stop, addListener } from '@bglocation/react-native';

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

- const handle = await BackgroundLocation.addListener('onLocation', handler);
- handle.remove();
+ const sub = addListener('onLocation', handler);
+ sub.remove();

The configuration object, event payloads, and types are identical — only the import path and function-based API style differ.