react-native-bg-geo

An original, New-Architecture background-geolocation library scaffold for iOS + Android. Every subsystem has a home in the codebase. Core paths (location capture, SQLite queue, HTTP upload with lock/unlock, motion switching) are implemented; tuning-heavy parts are marked TODO — that's where the ongoing work lives (see "Status").

Your own implementation built on the public platform APIs (FusedLocationProvider / CoreLocation, WorkManager, Room/SQLite). Not derived from any commercial SDK's source.

Install into a demo app

# demo app must have New Architecture enabled
npm install ../react-native-bg-geo
cd ios && RCT_NEW_ARCH_ENABLED=1 pod install && cd ..
npx react-native run-android   # or run-ios

New Arch on: newArchEnabled=true in android/gradle.properties + the pod install above.

iOS Info.plist (demo app) — COMPLETE set

<key>NSLocationWhenInUseUsageDescription</key><string>...</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key><string>...</string>
<key>NSLocationAlwaysUsageDescription</key><string>...</string>
<key>NSMotionUsageDescription</key><string>...</string>   <!-- required: CMMotionActivityManager -->
<key>UIBackgroundModes</key>
<array><string>location</string><string>fetch</string><string>processing</string></array>
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array><string>com.bggeo.sync</string><string>com.bggeo.heartbeat</string></array>

Permissions are handled SDK-side

The app never requests anything itself — call requestPermission() and the SDK drives the whole flow: Android FINE → ACTIVITY_RECOGNITION → POST_NOTIFICATIONS → BACKGROUND_LOCATION (Settings deep-link on API 30+); iOS WhenInUse → Always + Motion. Resolves 0=denied, 3=when-in-use, 4=always. Android: the library manifest declares permissions + the FGS location type. The demo app must still request runtime permission (FINE, then BACKGROUND) at run time.

Usage

import BackgroundGeolocation from 'react-native-bg-geo';

BackgroundGeolocation.onLocation(loc => console.log('[location]', loc));
BackgroundGeolocation.onHttp(r => console.log('[http]', r.status, r.success));

await BackgroundGeolocation.requestPermission();
await BackgroundGeolocation.ready({
  geolocation: { desiredAccuracy: -1, distanceFilter: 10 },
  http: { url: 'https://your.server.com/locations', autoSync: true, batchSync: false,
          headers: { Authorization: 'Bearer <token>' }, params: { device_id: 'demo-1' } },
  persistence: { maxDaysToPersist: 7, extras: { app: 'demo' } },
  app: { stopOnTerminate: false, startOnBoot: true, foregroundService: true },
});
await BackgroundGeolocation.start();

HTTP wire format (single mode)

{ "device_id": "demo-1",
  "location": { "uuid": "...", "timestamp": "...", "coords": { }, "is_moving": true } }

A record is deleted from the queue ONLY on a 2xx; any other status unlocks it for retry.

Status

Implemented (testable end-to-end on device): location capture + odometer + distance filter (both platforms); SQLite queue with lock/unlock + delete-on-2xx; HTTP single & batch upload with params/headers/auto-sync (Android WorkManager, iOS URLSession); foreground service (Android) / background modes (iOS); basic motion-based accuracy switching; main event bridge.

Stubbed (TODO in code): getCurrentPosition/watchPosition; multi-step FINE->BACKGROUND permission flow; geofence proximity re-loading beyond OS limit, DWELL, polygons; headless / terminated-app JS execution; scheduler + heartbeat; template rendering; battery/OEM survival tuning; Kalman/accuracy filter pipeline; stationary stop-detection.

Build notes

NativeBgGeoSpec (Android) and NativeBgGeoSpecJSI/BgGeoSpec (iOS) are produced by RN codegen from src/NativeBgGeo.ts on first build — IDE "missing symbol" warnings before a build are expected. Android needs apply plugin: 'com.facebook.react' (already in gradle).