react-native-background-geolocation

The react-native-background-geolocation SDK provides sophisticated background location-tracking and geofencing for iOS and Android. It uses motion-detection APIs (accelerometer, gyroscope, magnetometer) to intelligently manage battery life:

• Moving: Location recording starts automatically based on the configured distanceFilter (in metres).
• Stationary: Location services turn off automatically to conserve battery.

This is v5 of the SDK. Note that v4.x license keys are not compatible with v5. You must generate a new v5 key via the Customer Dashboard.

The react-native-background-geolocation plugin does not upload any information to third-party services by default. All recorded location data is uploaded exclusively to the host you specify using the Config.url option.

Data lifecycle management:

• Successful Uploads: When the plugin's HTTP service receives a success response (e.g., 200 OK) from your configured url, the plugin automatically destroys the locally persisted location in its SQLite database.
• Data Retention: Locally recorded locations that have not been successfully uploaded are automatically destroyed after the period defined by the maxDaysToPersist configuration option.

The repository provides two distinct example applications to help you understand the SDK's capabilities:

• HelloWorld Demo: A minimal, stripped-down demo focused on core concepts like starting/stopping tracking, manually controlling motion state, and requesting current location. It contains no map view or configuration UI.
• Advanced Demo: A full-featured demonstration showcasing live map visualization, real-time configuration editing, circular and polygon geofences, motion state management, and demo server integration.

When configuring your release build type in android/app/build.gradle, ensure shrinkResources is set to false to prevent issues with the plugin.

android {
    ...
    buildTypes {
        release {
            ...
            minifyEnabled enableProguardInReleaseBuilds
+           shrinkResources false
        }
    }
}

After modifying app.json or adding plugins, you must rebuild your app.

Local Development:

1. Run npx expo prebuild.
2. Run the app using npx expo run:android or npx expo run:ios.

Expo EAS: Run eas build --profile development (adjust profile as needed). You must build for both iOS and Android platforms.

npx expo prebuild
# Then run:
npx expo run:android
npx expo run:ios

# Or for EAS:
eas build --profile development

The HelloWorld Demo App is a minimal demonstration of the react-native-background-geolocation plugin. Use it to understand basic SDK usage, lifecycle control, and event handling.

Prerequisites

• Node.js (LTS recommended)
• React Native CLI environment
• Android Studio (for Android) or Xcode & CocoaPods (for iOS)

Installation Steps

1. Clone the repository:

   git clone https://github.com/transistorsoft/react-native-background-geolocation.git

2. Navigate to the HelloWorld directory:

   cd react-native-background-geolocation/example/HelloWorld

3. Install dependencies:

   npm install

Running the App

Android:

npx react-native run-android

iOS:

cd ios
pod install
cd ..
npx react-native run-ios

To visualize live tracking results in a browser, the Advanced Demo App requires registration with the demo tracking server at https://tracker.transistorsoft.com.

On first launch, you will be prompted to provide:

1. Organization
2. Username

Once registered, a tracker authorization token (JWT) is generated, and location data is posted to the server. You can view your live tracking at: https://tracker.transistorsoft.com/<your-organization>

⚠️ Note: This demo server is for testing and demonstration purposes only.

Add the react-native-background-geolocation and expo-gradle-ext-vars plugins to your app.json. You must provide your Android license key in the background geolocation plugin configuration and specify the googlePlayServicesLocationVersion in the gradle extension variables plugin.

{
  "expo": {
    "name": "your-app-name",
    "plugins": [
      [
        "react-native-background-geolocation", {
          "license": "YOUR ANDROID LICENSE KEY"
        }
      ],
      [
        "expo-gradle-ext-vars", {
          "googlePlayServicesLocationVersion": "21.1.0"
        }
      ]
    ]
  }
}

The plugin supports monitoring thousands of geofences by bypassing native platform limits (20 for iOS, 100 for Android). It achieves this by storing geofences in a local database and using a geospatial query to activate only those within a specific radius of the device's current location.

As the device moves, the plugin periodically (default: once per minute) queries for geofences in proximity to the latest recorded location.