Skip to content
BGeo SDK

BGeo SDK

BGeo is a background-geolocation SDK for React Native. It keeps tracking across app backgrounding, kill, and reboot, uploads locations natively (no JS in the hot path), and adapts GPS use to motion to save battery.

  • iOS & Android, React Native New Architecture — implemented as a TurboModule (a React Native New Architecture native module).
  • Native offline upload — a durable queue drains to your server with batching, backoff, and optional JWT refresh; survives process death.
  • Motion-based tracking — Kalman smoothing, activity recognition, a stationary geofence/region wake, elastic distance filter.
  • Closed engine, open bridge — the engine ships as a prebuilt BGeoCore.xcframework (iOS) + bgeo-android AAR (Android) behind an open TypeScript + native bridge you can read end to end. Requires a license key in release builds.

The SDK’s own source repo ships a full example app under example/ — a React Native dev tool with a map screen (live tracked route, geofence creation by long-press), a settings screen for tuning Config at runtime, and a log console for on-device diagnostics. Screenshots throughout these docs are taken from it.

The example app's map screen on iOS and Android, each showing a tracked route recorded during a walk, the status chip, and the collected-coordinates count.

Philosophy

BGeo is designed around one idea: configure once, then get out of the way.

  • Call ready(config) once, at every app launch. It’s not a one-time setup call — it’s meant to run on every cold start, every time. The config you pass merges over whatever was persisted natively from the previous session (or the SDK’s defaults, on first run), so a launch that doesn’t call ready() at all still keeps tracking with its last known configuration.
  • The API is event-driven, not poll-driven. Subscribe to onLocation and onMotionChange once and let the engine push updates to you — there’s no location loop to manage in JS.
  • Tracking and upload run natively and survive JS death. Once start() has been called, the native engine keeps filtering, persisting, and uploading locations whether your app is backgrounded, killed by the OS, or not yet relaunched since a reboot. JS is a subscriber to what’s happening, not the thing making it happen.

Architecture

BGeo is an open TypeScript + native bridge around a closed, prebuilt engine: the JS API, event plumbing, and native bridge code are readable source; the location-filtering, motion-classification, persistence, and HTTP upload logic ship as compiled binaries (BGeoCore.xcframework on iOS, a bgeo-android AAR on Android). You get full visibility into how your app talks to the SDK, without needing to vendor or rebuild the tracking engine itself.

New Architecture only

BGeo is a TurboModule — it requires the React Native New Architecture (the default since RN 0.76) and has no Old Architecture (bridge) build. See Compatibility for the full version matrix.

Where to go next

Getting Started

How it works

  • Tracking lifecycle — how the SDK tracks across foreground, background, kill, and reboot.
  • Data pipeline — how a location moves from fix to filter to queue to your server.

Guides

API Reference