Documentation

Core Options

HTTP Posting

Native HTTP delivery works the same in Capacitor and React Native. The JavaScript wrapper configures it once, then URLSession on iOS and HttpURLConnection on Android post directly from the native layer.

await configure({
  distanceFilter: 15,
  desiredAccuracy: 'high',
  heartbeatInterval: 15,
  locationUpdateInterval: 5000,
  fastestLocationUpdateInterval: 2000,
  http: {
    url: 'https://api.example.com/locations',
    headers: { Authorization: 'Bearer <token>' },
    buffer: { maxSize: 1000 },
  },
});

HTTP POST Body

{
  "location": {
    "latitude": 52.2297,
    "longitude": 21.0122,
    "accuracy": 5.0,
    "speed": 1.2,
    "heading": 180.0,
    "altitude": 110.5,
    "timestamp": 1700000000000,
    "isMoving": true,
    "isMock": false
  }
}

HttpEvent

interface HttpEvent {
  statusCode: number;
  success: boolean;
  responseText: string;
  error?: string;
  bufferedCount?: number;
}

Offline Buffer & Retry

Failed POSTs are stored in SQLite when buffer.maxSizeis configured. Buffered locations flush automatically in FIFO order after the next successful request.

Adaptive Distance Filter

Use auto mode to target stable update intervals regardless of whether the user is walking, cycling, or driving.

distanceFilter: 'auto',
autoDistanceFilter: {
  targetInterval: 10,
  minDistance: 10,
  maxDistance: 500,
}

Notification (Android)

Android tracking runs as a foreground service. Customize the persistent notification text from the wrapper.

notification: {
  title: 'Background Location',
  text: 'Tracking your route',
}

Methods

Events

Register listeners via addListener(event, handler) and keep the returned Subscription so you can remove it later.

Location Object

interface Location {
  latitude: number;
  longitude: number;
  accuracy: number;
  speed: number;
  heading: number;
  altitude: number;
  timestamp: number;
  isMoving: boolean;
  isMock: boolean;
  effectiveDistanceFilter?: number;
}

Geofencing

Geofencing is available through the same API surface in both wrappers. Up to 20 regions can be active at once.

interface Geofence {
  identifier: string;
  latitude: number;
  longitude: number;
  radius: number;
  notifyOnEntry?: boolean;
  notifyOnExit?: boolean;
  notifyOnDwell?: boolean;
  dwellDelay?: number;
  extras?: Record<string, string>;
}

GeofenceEvent Interface

interface GeofenceEvent {
  identifier: string;
  action: 'enter' | 'exit' | 'dwell';
  location: Location | null;
  extras?: Record<string, string>;
  timestamp: number;
}

Error Codes

iOS

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to track your route.</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>Background location is needed for continuous tracking.</string>

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
</array>

{
  "expo": {
    "plugins": [
      [
        "@bglocation/react-native",
        {
          "licenseKey": "BGL1-eyJ...",
          "locationWhenInUsePermission": "We use your location to track your route.",
          "locationAlwaysPermission": "We use your location in the background for continuous tracking."
        }
      ]
    ]
  }
}

Android

ACCESS_FINE_LOCATION
ACCESS_COARSE_LOCATION
ACCESS_BACKGROUND_LOCATION
FOREGROUND_SERVICE
FOREGROUND_SERVICE_LOCATION
POST_NOTIFICATIONS

await requestPermissions({
  permissions: ['location'],
});

await requestPermissions({
  permissions: ['backgroundLocation'],
});

Trial Mode

• 30-minute sessions with automatic stop and an onTrialExpired event.
• 1-hour cooldown between trial sessions.
• Debug mode is forced on so you can inspect behavior before buying.

Adding a License Key

Expo users should configure the package plugin. Bare React Native apps can set the same value directly in native config.

{
  "expo": {
    "plugins": [
      [
        "@bglocation/react-native",
        {
          "licenseKey": "BGL1-eyJ..."
        }
      ]
    ]
  }
}

<!-- iOS Info.plist -->
<key>BGLocationLicenseKey</key>
<string>BGL1-eyJ...</string>

<!-- AndroidManifest.xml -->
<meta-data
  android:name="dev.bglocation.LICENSE_KEY"
  android:value="BGL1-eyJ..." />

How Validation Works

• RSA-2048 signed payloads are verified fully offline on-device.
• The license is bound to a bundle ID and can be used across the Capacitor and React Native wrappers for the same app identifier.
• The license itself is perpetual. One year of updates is included, then update access can be renewed.

License Status

const result = await configure({ ... });

// result.licenseMode: 'full' | 'trial'
// result.licenseUpdatesUntil?: string
// result.licenseUpdateExpired?: boolean
// result.licenseError?: string

Fleet / Delivery Tracking

Continuous tracking with native HTTP posting and automatic offline buffering.

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

await configure({
  distanceFilter: 'auto',
  autoDistanceFilter: {
    targetInterval: 10,
    minDistance: 10,
    maxDistance: 500,
  },
  desiredAccuracy: 'high',
  heartbeatInterval: 30,
  http: {
    url: 'https://api.fleet.com/vehicle/location',
    headers: { Authorization: 'Bearer <token>' },
    buffer: { maxSize: 2000 },
  },
});

addListener('onHttp', (event) => {
  if (!event.success) {
    console.warn('Buffered:', event.bufferedCount);
  }
});

await start();

Fitness / Running App

High-frequency tracking with in-memory processing for pace, route, and progress stats.

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

const route: Location[] = [];

await configure({
  distanceFilter: 5,
  desiredAccuracy: 'high',
  heartbeatInterval: 10,
  locationUpdateInterval: 3000,
});

addListener('onLocation', (location) => {
  route.push(location);
  updateMapPolyline(route);
});

await start();

Geofencing — Points of Interest

Register circular regions and react to enter, exit, and dwell transitions.

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

await configure({
  distanceFilter: 50,
  desiredAccuracy: 'balanced',
  heartbeatInterval: 60,
});

await addGeofence({
  identifier: 'office',
  latitude: 52.2297,
  longitude: 21.0122,
  radius: 100,
  notifyOnEntry: true,
  notifyOnExit: true,
});

addListener('onGeofence', (event) => {
  console.log(event.identifier, event.action);
});

await start();