Background Geolocation

A Capacitor plugin for accurate background location tracking and native geofencing on iOS and Android. Use it to stream precise location updates, monitor circular geofence regions, react to enter/exit events in JavaScript, and POST geofence transitions natively while the WebView is suspended.

Features

• Accurate foreground and background geolocation without a paid license.
• Native geofencing on iOS and Android for circular regions.
• Enter and exit events through geofenceTransition while the app is alive.
• Native webhook delivery for geofence transitions when the WebView is suspended.
• A web fallback for development and browser-based testing.

This plugin's history

Interestingly enough, this plugin has a lot of history. The initial solution from Transistorsoft was a great piece of software, and I (HarelM) encourage using it if it fits your needs.
I tried it and understood that it prioritizes battery life over accuracy, which wasn't the right fit for my hiking app.
There was a very good fork maintained by mauron85 specifically for that use case, and I was happy to help maintain it.
But at some point, mauron85 stopped responding to messages on GitHub, and no one could continue maintaining it.
I hope mauron85 is safe and sound somewhere.

So I created a fork and started maintaining it here.
It served me well for over half a decade, but I felt it was hard to maintain due to all its history, features, and bug fixes.
I also felt like there was a barrier to introducing new features because of its complexity.

So I started exploring what it would take to reduce that complexity—at the same time, I was envious of how small @capacitor-community/background-geolocation is.
I took the best of both worlds: tried to reduce the codebase in the original Cordova plugin and add some robustness to the Capacitor plugin.

That's how I ended up maintaining this one.
I hope you'll enjoy it!

Plugin comparison

A short comparison between the three main background-geolocation plugins commonly used in Capacitor apps.

Notes:

• The Community plugin is lightweight and continues to work in the background, but it is known to be less accurate than the options below.
• This Cap-go plugin aims to provide accurate location fixes, reliable background operation, and native geofence enter/exit handling without requiring a paid license.
• Native geofence POST delivery is useful when iOS or Android wakes native code for a region transition but the Capacitor WebView is not running.
• Transistorsoft's plugin is a mature, accurate solution that also includes a broader HTTP uploader. It is a commercial product and requires a paid license for full use.

Usage

import { BackgroundGeolocation } from "@capgo/background-geolocation";

BackgroundGeolocation.start(
    {
        backgroundMessage: "Cancel to prevent battery drain.",
        backgroundTitle: "Tracking You.",
        requestPermissions: true,
        stale: false,
        distanceFilter: 50
    },
    (location, error) => {
        if (error) {
            if (error.code === "NOT_AUTHORIZED") {
                if (window.confirm(
                    "This app needs your location, " +
                    "but does not have permission.\n\n" +
                    "Open settings now?"
                )) {
                    // It can be useful to direct the user to their device's
                    // settings when location permissions have been denied. The
                    // plugin provides the 'openSettings' method to do exactly
                    // this.
                    BackgroundGeolocation.openSettings();
                }
            }
            return console.error(error);
        }
        return console.log(location);
    }
).then(() => {
    // When location updates are no longer needed, the plugin should be stopped by calling
    BackgroundGeolocation.stop();
});

// Set a planned route to get a notification sound when a new location arrives and it's not on the route:
        
BackgroundGeolocation.setPlannedRoute({soundFile: "assets/myFile.mp3", route: [[1,2], [3,4]], distance: 30 });

Native geofencing

Use native geofencing when you need lightweight location boundaries such as stores, job sites, delivery zones, campuses, or check-in areas. The plugin monitors geofences natively, emits JavaScript events while the app is active, and can send transition payloads directly to your backend while the WebView is suspended.

import { BackgroundGeolocation } from "@capgo/background-geolocation";

// Geofencing can notify JavaScript while the app is alive and can also POST
// transitions natively while the WebView is suspended.
await BackgroundGeolocation.setupGeofencing({
    url: "https://api.example.com/geofences",
    notifyOnEntry: true,
    notifyOnExit: true,
    payload: { userId: "123" }
});

await BackgroundGeolocation.addGeofence({
    identifier: "office",
    latitude: 37.33182,
    longitude: -122.03118,
    radius: 150
});

const handle = await BackgroundGeolocation.addListener(
    "geofenceTransition",
    (event) => console.log(event.identifier, event.transition)
);

await BackgroundGeolocation.removeGeofence({ identifier: "office" });
handle.remove();

Android background geofence permission

The plugin does not add ACCESS_BACKGROUND_LOCATION by default. Add it to your app manifest only when you need background geofencing or background location updates:

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Apps that only use foreground location can omit this permission.

// If you just want the current location, try something like this. The longer
// the timeout, the more accurate the guess will be. I wouldn't go below about 100ms.
function guessLocation(callback, timeout) {
    let last_location;
    BackgroundGeolocation.start(
        {
            requestPermissions: false,
            stale: true
        },
        (location) => {
            last_location = location || undefined;
        }
    ).then(() => {
        setTimeout(() => {
            callback(last_location);
            BackgroundGeolocation.stop();
        }, timeout);
    });
}

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/background-geolocation/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Installation

This plugin supports Capacitor v8:

bun add @capgo/background-geolocation
bunx cap update

iOS

Add the following keys to Info.plist.:

<dict>
  ...
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>We need to track your location</string>
  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>We need to track your location while your device is locked.</string>
  <key>UIBackgroundModes</key>
  <array>
    <string>location</string>
  </array>
  ...
</dict>

Android

Set the the android.useLegacyBridge option to true in your Capacitor configuration. This prevents location updates halting after 5 minutes in the background. See https://capacitorjs.com/docs/config and https://github.com/capacitor-community/background-geolocation/issues/89.

On Android 13+, the app needs the POST_NOTIFICATIONS runtime permission to show the persistent notification informing the user that their location is being used in the background. This runtime permission is requested after the location permission is granted.

For geofencing on Android 10+, the app also needs ACCESS_BACKGROUND_LOCATION. Android may require the user to grant this from system settings after foreground location is granted; use openSettings() if the permission remains denied.

If your app forwards location updates to a server in real time, be aware that after 5 minutes in the background Android will throttle HTTP requests initiated from the WebView. The solution is to use a native HTTP plugin such as CapacitorHttp. See https://github.com/capacitor-community/background-geolocation/issues/14.

Configuration specific to Android can be made in strings.xml:

<resources>
    <!--
        The channel name for the background notification. This will be visible
        when the user presses & holds the notification. It defaults to
        "Background Tracking".
    -->
    <string name="capacitor_background_geolocation_notification_channel_name">
        Background Tracking
    </string>

    <!--
        The icon to use for the background notification. Note the absence of a
        leading "@". It defaults to "mipmap/ic_launcher", the app's launch icon.

        If a raster image is used to generate the icon (as opposed to a vector
        image), it must have a transparent background. To make sure your image
        is compatible, select "Notification Icons" as the Icon Type when
        creating the image asset in Android Studio.

        An incompatible image asset will cause the notification to misbehave in
        a few telling ways, even if the icon appears correctly:

          - The notification may be dismissable by the user when it should not
            be.
          - Tapping the notification may open the settings, not the app.
          - The notification text may be incorrect.
    -->
    <string name="capacitor_background_geolocation_notification_icon">
        drawable/ic_tracking
    </string>

    <!--
        The color of the notification as a string parseable by
        android.graphics.Color.parseColor. Optional.
    -->
    <string name="capacitor_background_geolocation_notification_color">
        yellow
    </string>
</resources>

API

start(options: StartOptions, callback: (position?: Location | undefined, error?: CallbackError | undefined) => void) => Promise<void>

stop() => Promise<void>

openSettings() => Promise<void>

setPlannedRoute(options: SetPlannedRouteOptions) => Promise<void>

setupGeofencing(options: GeofenceSetupOptions) => Promise<void>

addGeofence(options: AddGeofenceOptions) => Promise<void>

removeGeofence(options: RemoveGeofenceOptions) => Promise<void>

removeAllGeofences() => Promise<void>

getMonitoredGeofences() => Promise<MonitoredGeofencesResult>

addListener(eventName: 'geofenceTransition', listenerFunc: (event: GeofenceTransitionEvent) => void) => Promise<PluginListenerHandle>

addListener(eventName: 'geofenceError', listenerFunc: (event: GeofenceErrorEvent) => void) => Promise<PluginListenerHandle>

getPluginVersion() => Promise<{ version: string; }>